Copyright © 2005-2018 MultiMedia Soft

OnPlayersEvents event

Previous pageReturn to chapter overviewNext page

Remarks

 

Occurs when an event related to a player occurs.

 

This event replaces the usage of the CallbackForPlayersEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

 

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

 

 

Syntax

 

[Visual Basic 6]

Private Sub DjStudioApi_OnPlayersEvents ( _

ByVal nEvent as enumPlayerEvents, _

ByVal nPlayerIndex as Int16, _

ByVal nData1 as Int32, _

ByVal nData2 as Int32, _

ByVal fData3 as Single, _

ByVal pBufferUnicode as IntPtr, _

ByVal nBufferLength as Int32 _

)

 

where "DjStudioApi" is declared in Visual Basic 6 code as:

 

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj


 

 

Event Data

 

Parameter

Description

 

 

nEvent

Event reported by the player.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_SOUND_DONE

0

Occurs when a song has been performed completely.

 

Involved data parameters: none.

EV_SOUND_PLAYING

1

Occurs when a song starts playing.

 

Involved data parameters: none.

EV_SOUND_PAUSED

2

Occurs when a song is paused.

 

Involved data parameters: none.

EV_SOUND_STOPPED

3

Occurs when a song is stopped.

 

Involved data parameters: none.

EV_SOUND_LOADED

4

Occurs when a song is loaded in memory from a file.

 

Involved data parameters:

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

EV_SOUND_SYNC_LOADED

5

Occurs when a song or video clip has been loaded in memory from a file after a call to the LoadSoundSync, LoadSoundFromMemorySync, LoadEncryptedSoundSync, LoadEncryptedSoundFromMemorySync or VideoPlayer.LoadSync methods.

 

Involved data parameters:

nData1: The result of the loading operation. See the LastError property for details about the returned result code.

EV_META_CHANGED

6

Occurs, during an Internet stream playback, when the Shoutcast metadata of the playing stream is changed from the provider.

After catching this event it will be possible retrieving the new strings of metadata through the GetTagString method.

 

Involved data parameters: none.

EV_DOWNLOAD_COMPLETE

7

Occurs when an Internet stream (usually a file) has been downloaded completely.

Involved data parameters: none.

EV_DOWNLOAD_BUFFERING

8

Occurs when an Internet stream doesn't have enough data for playback and starts buffering new data and also when there are enough buffered data for resuming the stalled playback.

 

Involved data parameters:

nData1: The buffering status.

EV_DOWNLOAD_PERC

9

Occurs during the download of an Internet stream to inform about buffering percentage.

 

Involved data parameters:

nData1: Number representing the download percentage.

EV_STREAM_CONNECTING

10

Occurs when the player starts the connection to an Internet stream.

 

Involved data parameters: none.

EV_STREAM_LOADED

11

Occurs when the player has buffered enough data from an Internet stream in order to start playback. In case the Internet stream should have been successfully loaded from a playlist, this event would be fired immediately before the EV_STREAM_LOADED_FROM_INET_PLS event (see below).

 

Involved data parameters:

nData1: The stream loading result.

EV_STREAM_LOADED_FROM_INET_PLS

12

Occurs after the player has tried to load an Internet stream taken from a playlist stored inside a web server.

 

Involved data parameters:

nData1: The stream loading result.

nData2: The zero-based index of the item.

pBufferUnicode: String containing the URL of the Internet stream.

EV_PLAYLIST_DONE

13

Occurs when a playlist has been performed completely.

 

Involved data parameters: none.

EV_PLAYLIST_SOUND_LOADED

14

Occurs when a song included inside a playlist is loaded in memory from a file.

Involved data parameters:

 

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

pBufferUnicode: String containing a custom tag associated to this item.

EV_PLAYLIST_SOUND_LOAD_FAILED

15

Occurs when the loading of a playlist's song fails.

 

Involved data parameters:

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

EV_PLAYLIST_STREAM_LOADED

16

Occurs when a playlist Internet stream item has been loaded.

 

Involved data parameters:

nData1: The zero based-index of the loaded item: in case of failure in loading the stream taken from the playlist this parameter would be set to -1.

EV_SOUND_CLOSED

17

Occurs when a song is closed and discarded from memory.

 

Involved data parameters: none.

EV_SERVER_CLOSED

18

Occurs when the Internet connection drops or when the remote stream server closes the streaming channel during the buffering of an Internet stream: this last situation could happen when using a slow dial-up connection (56 Kbits or slower).

 

Involved data parameters: none.

EV_DURATION_CHANGED

19

Occurs after a successful call to the Effects.PlaybackTempoSet and Effects.PlaybackRateSet methods to notify that the original sound duration has been altered.

 

Involved data parameters:

fData3: The updated sound duration expressed in seconds.

EV_VUMETER

20

Occurs whenever there is a change on the VU-Meter peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own VU-Meter graphical representation.

This event is fired only if you have created the VUMeter object though a call to the VUMeter.Create method.

 

Involved data parameters:

nData1: Number representing the peak value for the left channel: can assume values from 0 (no sound) to 32767 (max volume).

nData2: Number representing the peak value for the right channel: can assume values from 0 (no sound) to 32767 (max volume).

EV_SPECTRUM_CHANGE

21

Occurs whenever there is a change on the Spectrum peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own Spectrum graphical representation; after receiving this event, in order to obtain the Spectrum values to render graphically, you need to perform a call to the Spectrum.GetTable method.

This event is fired only if you have previously created the Spectrum object though a call to the Spectrum.Create method.

 

Involved data parameters: none.

EV_BPM_AVAILABLE

22

Occurs when a song BPM has been detected.

 

Involved data parameters:

fData3: The detected song BPM.

EV_FADING_VOLUME_CHANGED

23

During a cross-fading, performed by the embedded Automatic Fader, or during a volume sliding operation, performed through call to the StreamVolumeSlide or StreamVolumeSlideEx methods, allows to know in real time the volume of a certain player: this event is generated every 15 milliseconds and not for any single/minimal change of the volume level.

This event is also generated during a fading session performed after a call to the PlaySound method and after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

 

Involved data parameters:

fData3: The player's current volume.

EV_FADING_POINT_REACHED

24

Occurs when the playback of the song that will fade-out reaches the Fader.FadeStartFromEnd position

 

Involved data parameters: none.

EV_FADEIN_STARTED

25

Occurs when the song fading-in starts playing

This event is also generated at the start of a fade-in session performed after a call to the PlaySound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

 

Involved data parameters: none.

EV_FADEIN_COMPLETED

26

Occurs when the fade-in is completed.

This event is also generated at the end of a fade-in session performed after a call to the PlaySound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

 

Involved data parameters: none.

EV_FADEOUT_STARTED

27

Occurs when the song fading-out starts lowering its volume.

This event is also generated at the start of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

 

Involved data parameters: none.

EV_FADEOUT_COMPLETED

28

Occurs when the fade-out is completed.

This event is also generated at the end of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

 

Involved data parameters: none.

EV_TRIGGER_REACHED

29

Occurs when the song playback reaches an existing trigger position.

During playback this event is not generated 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 itself.

 

Involved data parameters:

nData1: Number representing the trigger identifier.

EV_SILENCE_AVAIL

30

Occurs when the control has completed the detection of silent portions at the start and end of a loaded song.

Silence detection is performed automatically if the SilenceDetectionOnPlayerLoadAutoSet method has been previously called or on-demand after a call to the SilenceDetectionOnPlayerRequest method.

 

Involved data parameters:

nData1: Number representing the position in milliseconds where the sound level is higher than the initial threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.

nData2: Number representing the position in milliseconds where the sound level is lower than the final threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.

EV_WAVE_ANALYSIS_START

31

Occurs when the analysis of a sound's waveform begins. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

 

Involved data parameters: none.

EV_WAVE_ANALYSIS_PERC

32

Occurs during the analysis of a sound's waveform in order to notify the container application about the analysis advancement. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

 

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis.

EV_WAVE_ANALYSIS_DONE

33

Occurs when the analysis of a sound's waveform has been completed or aborted. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

 

Involved data parameters:

nData1: Number representing the amount of peaks detected during the sound's analysis.

fData3: Floating point number representing the duration in milliseconds of each detected peak.

EV_RANGE_LOOP_DONE

34

Occurs when a loop of a sound range playback, started through a call to the PlaySoundRangeLoop or the VideoPlayer.PlayRangeWithLoop methods, has been completed.

 

Involved data parameters:

nData1: Number representing the amount of loops that must be still performed.

EV_WAV_EXPORT_START

35

Occurs when the export of the loaded song into a file in WAV format begins. The exporting session is started through a previous call to the RequestSoundExportToWav method.

 

Involved data parameters: none.

EV_WAV_EXPORT_PERC

36

Occurs during an exporting session of the loaded sound into a file in WAV format in order to notify the container application about the exporting advancement. The exporting session is started through a previous call to the RequestSoundExportToWav method.

 

Involved data parameters:

nData1: Number representing the percentage of advancement for the current exporting session.

EV_WAV_EXPORT_COMPLETE

37

Occurs at the end of an exporting session of the loaded sound into a file in WAV format. The exporting session is started through a previous call to the RequestSoundExportToWav method.

 

Involved data parameters:

nData1: Number representing the total size, expressed in bytes, of the exported WAV file..

EV_EQUALIZER_LOADED

38

Occurs when settings of an equalizer file are applied to a sound.

 

Involved data parameters: none.

EV_CUE_POINTS_LOADED

39

Occurs when a file containing cue points have been loaded into the player.

 

Involved data parameters: none.

EV_BEATS_AVAILABLE

40

Occurs when the offline beats detection is completed. Offline beats detection can be started through a previous call to the BeatsDetectRequest method.

 

Involved data parameters:

nData1: Number of beats detected.

EV_BEAT_DETECTED

41

Occurs when a beat is detected during a playback session of the loaded sound. Real-time beats detection can be enabled/disabled through a previous call to the BeatsDetectEnableRT method.

 

Involved data parameters:

nData1: Beat's position expressed in milliseconds.

EV_PLAYLIST_LOAD_STARTED

42

Occurs when the synchronized loading of a playlist starts. A synchronized loading is started through a call to the PlayListLoadSync method.

 

Involved data parameters: none.

EV_PLAYLIST_LOAD_PERC

43

Occurs during the synchronized loading of a playlist. A synchronized loading is started through a call to the PlayListLoadSync method.

 

Involved data parameters:

nData1: Number representing the percentage of advancement for the loading session.

EV_PLAYLIST_LOAD_DONE

44

Occurs when the synchronized loading of a playlist is completed. A synchronized loading is started through a call to the PlayListLoadSync method.

 

Involved data parameters: none.

EV_CUE_POINT_REACHED

45

Occurs when an existing cue point is reached during playback.

During playback this event is not generated 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 cue point itself.

 

Involved data parameters:

nData1: Number representing the position, expressed in milliseconds, of the cue point.

pBufferUnicode: String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.

EV_VOLUME_POINT_REACHED

46

Occurs when a volume automation point is reached during playback.

 

Involved data parameters:

fData3: Number representing the position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property.

pBufferUnicode: String containing the friendly name of the volume point as defined when the volume point was added through the VolumeAutomation.PointAdd method.

EV_VOLUME_AUTOMATION_LOADED

47

Occurs when a volume automation procedure is loaded from a VDJ file.

The VDJ file could have been loaded manually through the VolumeAutomation.Load method or automatically if a VDJ file having the same filename of the loaded sound should be found inside the same directory: if for example the loaded sound file should be named MySong.mp3, the corresponding searched VDJ file would be named MySong.vdj

 

Involved data parameters: none.

EV_LYRICS_AVAIL

48

Occurs when a previous request to the SoundLyricsRequest method is completed.

 

Involved data parameters:

nData1: The result of the lyrics search operation. See the LastError property for details about the returned result code. If the result is enumErrorCodes.ERR_NOERROR, lyrics text can be retrieved through the SoundLyricsGet method.

EV_SOUND_STALLED

49

Occurs when a queued stream, created through the StreamQueueCreate method and fed through the StreamQueuePushData method, doesn't have PCM data to play.

 

Involved data parameters: none.

EV_AUDIO_EXTRACT_START

50

Occurs at the beginning of the extraction of the audio track from a video file. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

 

Involved data parameters: none.

EV_AUDIO_EXTRACT_PERC

51

Occurs during the extraction of the audio track from a video file to notify about the advancement. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract

 

Involved data parameters:

nData1: Number representing the current percentage of the audio extraction.

EV_AUDIO_EXTRACT_DONE

52

Occurs during the extraction of the audio track from a video file to notify about the advancement. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

 

Involved data parameters:

nData1: Boolean flag that warns when the extracted audio track, that was originally requested to be stored in memory, has been put into a temporary file due to missing memory space. If the original request was to store the extracted audio track inside a temporary file, this flag can be ignored.

nData2: Result of the audio extraction: see the LastError property for details about the specific error code.

EV_VOLUME_SLIDE_COMPLETED

53

Occurs during the extraction of the audio track from a video file to notify about the advancement. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

 

Involved data parameters: none.

EV_PLAYER_DISCONNECTED

54

Occurs when the output device connected to a certain player is disconnected from the system: this may happen when using USB devices; with this event you can be informed that the player cannot continue playback on the output device and that a new device should be used.

 

Involved data parameters: none.

EV_OUTPUT_DEVICE_CHANGED

55

Occurs when the output device (sound card) has been changed through a successful call to the StreamOutputDeviceSet method.

 

Involved data parameters:

nData1: Number representing the zero-based index of the new output device for the given player.

EV_SILENCE_DETECTION

56

Occurs during playback of a sound stream having realtime silence detection enabled through the SilenceDetectionRealTimeEnable method.

 

Involved data parameters:

nData1: Boolean value specifying detection of silent data or of audible data.

nData2: Number representing the position inside the sound stream, expressed in milliseconds, where the silence threshold was crossed.

EV_VST_PARAM_CHANGED

57

Occurs when a parameter of the VST has been changed through its editor.

 

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number representing the zero-based index of the changed parameter.

fData3: Number representing the updated parameter value.

EV_VST_EDITOR_RESIZED

58

Occurs when the editor of the VST effect is resized.

 

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number containing the updated size of the VST. The updated width is stored inside the lower 16 bits of the parameter while the updated height is stored inside the higher 16 bits of the parameter.

EV_LRC_FILE_AVAILABLE

59

Occurs when a lyrics LRC file is found and loaded.

 

Involved data parameters:

nData1: Boolean value specifying if the LRC file is in enhanced format.

EV_LRC_ADVANCETIME_FULL_LINE

60

Occurs when it's time to display, with a certain advance set through the LrcNotifTimingsSet method, a full line of text of the loaded lyrics LRC file.

 

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_FULL_LINE

61

Occurs when it's time to display in real-time a full line of text of the loaded lyrics LRC file. Timing can be fine tuned through the LrcNotifTimingsSet method.

 

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_PORTION_LINE

62

Occurs when it's time to display in real-time a portion of line of text of the loaded lyrics LRC file in Enhanced format. Timing can be fine tuned through the LrcNotifTimingsSet method.

 

Involved data parameters:

nData1: Number representing the zero based-index of the Line Enhanced Time Tag

nData2: Position, expressed in milliseconds, within the song of the Enhanced Time Tag

fData3: Duration, expressed in milliseconds, of the Enhanced Time Tag

pBufferUnicode: String containing the full line of text of the Enhanced Time Tag

EV_WAVEFORM_CHANGE

63

Occurs during playback whenever there is a change on the waveform peak values displayed on an object of the Waveform class.

nPlayerIndex

Zero-based index of the player reporting the event

nData1

First 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData2

Second 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

fData3

Third floating point value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

pBufferUnicode

Pointer to a buffer containing a string of Unicode characters related to the event; its value and meaning depends upon the specific event received: see the table above for possible values. Below a couple of snippets that show how to convert the buffer contents, passed when  the callback is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED, into a .NET string through marshaling:

 

Visual Basic .NET

 

Imports System.Runtime.InteropServices

 

Dim strCuePointName As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strCuePointName = strCuePointName.Trim()

 

 

Visual C#

 

using System.Runtime.InteropServices;

 

string strCuePointName = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strCuePointName = strCuePointName.Trim();

 

 

Visual C++ with MFC (Unmanaged)

 

CString strCuePointName;

strCuePointName.Format (L"Reached Cue Point with name %s on player %d", pBufferUnicode, nPlayerIndex);

 

 

Visual Basic 6

 

Dim strCuePointName As String

strCuePointName = StrFromPtr(pBufferUnicode, nBufferLength)

 

 

nBufferLength

The length in characters of the buffer above