Tutorials > 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.

•

Triggers

A new trigger can be added through the TriggersAdd or TriggersAddPerc methods and removed at a later time using the TriggersRemove method.

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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_TRIGGER_REACHED and you will be able to discriminate the specific trigger through its nData1 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 single trigger can be enabled/disabled through the TriggersEnable method and its enabled/disabled state can be obtained through the TriggersIsEnabled method.

•	Cue Points

A new cue point can be added through the CuePointsAdd method and removed at a later time using the CuePointsRemove method.

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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED allowing to discriminate the specific cue point through contents of the pBufferUnicode 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.

Each single cue point can be enabled/disabled through the CuePointsEnable method and its enabled/disabled state can be obtained through the CuePointsIsEnabled 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" ?>

</CuePoints>

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.

The CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_CUE_POINTS_LOADED each time a file containing cue points is loaded into the player, automatically or through a call to the CuePointsLoadFromFile 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.

IMPORTANT NOTE ABOUT POSITIONING OF TRIGGERS AND CUE POINTS: Positioning of triggers and cue points, added through the TriggersAdd and CuePointsAdd methods whose position is expressed in milliseconds, is always referred to the original duration of the loaded sound, meaning that their position won't be automatically moved when tempo and/or playback rate changes and will always refer to the position inside the song as it should be played at its original speed. This means that if you should improve tempo percentage through the Effects.PlaybackTempoSet method, determining a shorter duration of the song, the cue point or trigger could be never reached if the updated song duration should be shorter respect to the position were the cue point or trigger was originally set. The only entity that could avoid this issue would be triggers added through the TriggersAddPerc method which, being based upon a positioning expressed in percentage, won't be affected by changes of the song's duration.

As a final note, positioning expressed in percentage is not supported for cue points. In case you should need to have cue points that would automatically update their positioning after using the the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods, you would have to apply a proportion that would allow repositioning the cue point through the CuePointsSetPos method; see the VB example below where tempo is updated after moving a trackbar control:

Private Sub trackBarTempo1_Scroll(ByVal sender As Object, ByVal e As System.EventArgs) Handles trackBarTempo1.Scroll

' change tempo using value set into the trackbar control: this will change the duration of the loaded sound

AudioDjStudio1.Effects.PlaybackTempoSet (Player_1, trackBarTempo1.Value)

' obtain updated duration after tempo change

Dim nUpdatedDuration As Double = 0

AudioDjStudio1.SoundDurationGet(Player_1, nUpdatedDuration, true)

' obtain original duration as available before applying tempo change

Dim nOriginalDuration as Int32 = 0

AudioDjStudio1.GetSoundOriginalDuration(Player_1, nOriginalDuration, false)

' imagine that our cue points was originally positioned at an offset of 5 seconds (5000 ms) from the end of the file

Dim nOffsetOriginalSpeed as Int32 = 5000

' recalculate the offset through a proportion

Dim nOffsetUpdatedSpeed as Int32 = (nOffsetOriginalSpeed * nUpdatedDuration) / nOriginalDuration

' reposition the cue point based upon the updated song duration and offset

AudioDjStudio1.CuePointsSetPos (Player_1, "CuePoint name", nUpdatedDuration - nOffsetUpdatedSpeed)

End Sub

During playback, Triggers and Cue Points will not generate the related events 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:

- Triggers

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:

- CuePoints