How to add Triggers and Cue Points to a player
An useful feature for DJ applications is the ability to setup Triggers and/or Cue points that will generate one or more events when a predefined position is reached: the main difference between a trigger and a cue point is the fact that a trigger is identified though a unique identification number (for example 0, 1, 2, 1000, 2000, etc.) while a cue point is identified by a mnemonic string of characters containing a custom name (for example "intro start", "mainpart start", "refrain start", etc.): obviously you are free to define your own set of triggers and of cue points identifiers.
You can add as many Triggers and Cue Points you need to a given player using a set of predefined methods.
Each time you create a trigger using the TriggersAdd or TriggersAddPerc methods, you must provide a unique identification number that will be used in order to identify the trigger at a later time: each time a trigger is reached during playback, a TriggerReached event will be generated and you will be able to discriminate the specific trigger through its nTriggerID parameter: this parameter will match exactly the unique identification number assigned to the trigger when added through the TriggersAdd or TriggersAddPerc methods.
The total number of existing triggers can be obtained using the TriggersGetCount method; you can obtain/modify the position for an existing trigger, expressed in ScaleUnits, through the TriggersGetPos and TriggersSetPos methods or, if you are working with positions in floating point percentage, through the TriggersGetPosPerc and TriggersSetPosPerc methods.
Each time you create a cue point using the CuePointsAdd method, you must provide a mnemonic string of characters containing a custom name that will be used in order to identify the cue point at a later time: each time a cue point is reached during playback, a CuePointReached event is generated allowing to discriminate the specific cue point through its strCuePointName parameter: this parameter will match exactly the custom name assigned to the cue point when added through the CuePointsAdd method.
The total number of existing cue points can be obtained using the CuePointsGetCount method; you can obtain/modify the position for an existing cue point, expressed in milliseconds, through the CuePointsGetPos and CuePointsSetPos methods. The name of each cue point can be be obtained through the CuePointsGetName method.
A further feature available for cue points is the capability to save them inside a XML-based file through the CuePointsSaveToFile method and to retrieve them at a later time using the CuePointsLoadFromFile method: last but not least, each time a new sound is loaded, the control will automatically search for a XML file containing cue points for that specific file: if for example the loaded sound file should be named MySong.mp3, the corresponding XML file containing cue points should be named MySong.cue : when the control will find this specific XML file inside the same folder of the loaded sound it will automatically create the list of cue points.
The XML file, which should always have extension .cue, has a structure like the sample below:
<?xml version="1.0" ?>
<CuePoint PosMs="1000" name="Silence end" />
<CuePoint PosMs="4200" name="Fading point" />
<CuePoint PosMs="18000" name="Silence start" />
As you can see, each cue point is identified by the name attribute and has a position expressed in milliseconds set into the PosMs attribute.
Existing cue points can be saved inside a memory stream, in the same XML format as seen for the .cue files, through the CuePointsSaveToMemoryStream method and retrieved at a later time through the CuePointsLoadFromMemoryStream method.
Cue points can be also managed when dealing with playlists formatted in PDJ format containing volume automation features; for details about using Volume Automation refer to the How to manage Volume Automation tutorial.
During playback, Triggers and Cue Points will not generate the related events TriggersReached and CuePointReached if the current playback position should be moved, through a call to the SeekSound or ForwardSound methods, to a position exceeding the one of the trigger/cue point itself.
A sample of use of Triggers in Visual C# and Visual Basic.NET can be found inside the following samples installed with the product's setup package:
A sample of use of Cue Points in Visual C# and Visual Basic.NET can be found inside the following samples installed with the product's setup package: