BASS_ChannelSetSync

Sets up a synchronizer on a MOD music, stream or recording channel. 

HSYNC BASS_ChannelSetSync(
    DWORD handle,
    DWORD type,
    QWORD param,
    SYNCPROC *proc,
    void *user
);

Parameters

handleThe channel handle... a HMUSIC, HSTREAM or HRECORD.
typeThe type of sync (see the table below). The following flags may also be used.
BASS_SYNC_MIXTIMECall the sync function immediately when the sync is triggered, instead of delaying the call until the sync event is actually heard. This is automatic with some sync types (see table below), and always with decoding and recording channels, as they cannot be played/heard.
BASS_SYNC_ONETIMECall the sync only once and then remove it from the channel.
BASS_SYNC_THREADCall the sync asynchronously in the dedicated sync thread. This only affects mixtime syncs (except BASS_SYNC_FREE syncs) and allows the callback function to safely call BASS_ChannelFree or BASS_StreamFree or BASS_MusicFree on the same channel handle.
paramThe sync parameter. Depends on the sync type... see the table below.
procThe callback function.
userUser instance data to pass to the callback function.

Sync types, with param and SYNCPROC data definitions.

BASS_SYNC_DEV_FAIL
mixtime only		Sync when the channel's device stops unexpectedly (eg. if it is disconnected/disabled). When this happens, it will not be possible to resume a recording but it may be possible to resume playback via BASS_Start once the device becomes available again.
param : not used. data : not used.
BASS_SYNC_DEV_FORMAT
mixtime only		Sync when the sample format (sample rate and/or channel count) of the channel's device changes. The new format is available from BASS_GetInfo or BASS_RecordGetInfo.
param : not used. data : not used.
BASS_SYNC_DOWNLOAD
mixtime only		Sync when downloading of an internet (or "buffered" user file) stream is done.
param : not used. data : not used.
BASS_SYNC_ENDSync when a channel reaches the end, including when looping. Note that some MOD musics never reach the end; they may jump to another position first. If the BASS_MUSIC_STOPBACK flag is used with a MOD music (through BASS_MusicLoad or BASS_ChannelFlags) then this sync will also be called when a backward jump effect is played.
param : not used. data : 0 = the normal end position, 1 = a backward jump in a MOD music, 2 = the BASS_POS_END position, 3 = the end of a tail (BASS_ATTRIB_TAIL).
BASS_SYNC_FREE
mixtime only		Sync when a channel is freed. This can be useful when you need to release some resources associated with the channel. Note that you will not be able to use any BASS functions with the channel in the callback, as the channel will no longer exist.
param : not used. data : not used.
BASS_SYNC_META
mixtime only		Sync when metadata is received in a Shoutcast stream. The updated metadata is available from BASS_ChannelGetTags.
param : not used. data : not used.
BASS_SYNC_MUSICFXSync when the sync effect is used in a MOD music. The sync effect is E8x or Wxx for the XM/MTM/MOD formats, and S2x for the IT/S3M formats (where x = any value).
param : 0 = the position is passed to the callback (data : LOWORD = order, HIWORD = row), 1 = the value of x is passed to the callback (data : x value).
BASS_SYNC_MUSICINSTSync when an instrument (sample for the MOD/S3M/MTM formats) is played in a MOD music (not including retrigs).
param : LOWORD = instrument (1=first), HIWORD = note (0=c0...119=b9, -1=all). data : LOWORD = note, HIWORD = volume (0-64).
BASS_SYNC_MUSICPOSSync when a MOD music reaches an order.row position.
param : LOWORD = order (0=first, -1=all), HIWORD = row (0=first, -1=all). data : LOWORD = order, HIWORD = row.
BASS_SYNC_OGG_CHANGESync when a new logical bitstream begins in a chained OGG stream. Updated tags are available from BASS_ChannelGetTags.
param : not used. data : not used.
BASS_SYNC_POSSync when a channel reaches a position.
param : position in bytes (automatically rounded down to nearest sample). data : not used.
BASS_SYNC_SETPOSSync when a channel's position is set, including when looping/restarting.
param : not used. data : 0 = playback buffer is not flushed, 1 = playback buffer is flushed.
BASS_SYNC_SLIDE
mixtime only		Sync when an attribute slide has ended.
param : not used. data : the attribute that has finished sliding.
BASS_SYNC_STALL
mixtime only		Sync when playback of the channel is stalled/resumed.
param : not used. data : 0 = stalled, 1 = resumed.
other sync types may be supported by add-ons, see the documentation.

Return value

If successful, then the new synchronizer's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLEhandle is not a valid channel.
BASS_ERROR_ILLTYPEAn illegal type was specified.
BASS_ERROR_ILLPARAMAn illegal param was specified.

Remarks

Multiple synchronizers may be used per channel, and they can be set before and while playing. Equally, synchronizers can also be removed at any time, using BASS_ChannelRemoveSync. If the BASS_SYNC_ONETIME flag is used then the sync is automatically removed after its first occurrence.

The BASS_SYNC_MIXTIME flag (without BASS_SYNC_THREAD) can be used with BASS_SYNC_END or BASS_SYNC_POS/MUSICPOS syncs to implement custom looping, by using BASS_ChannelSetPosition in the callback. A mixtime sync can also be used to make DSP/FX changes at specific points, or change a HMUSIC channel's flags or attributes. The BASS_SYNC_MIXTIME flag can also be useful with a BASS_SYNC_SETPOS sync, to reset DSP states after seeking.

Several of the sync types are triggered in the process of rendering the channel's sample data; for example, BASS_SYNC_POS and BASS_SYNC_END syncs, when the rendering reaches the sync position or the end, respectively. Those sync types should be set before starting playback or pre-buffering (ie. before any rendering), to avoid missing any early sync events.

A channel does not need to be playing for its BASS_SYNC_DEV_FAIL and BASS_SYNC_DEV_FORMAT syncs to be triggered but the device does need to be active, which means it needs to be playing other channels or the BASS_CONFIG_DEV_NONSTOP option needs to be enabled.

With recording channels, BASS_SYNC_POS syncs are triggered just before the RECORDPROC receives the block of data containing the sync position.

Example

Do some processing until a MOD music reaches the 10th order. 
BOOL order10 = FALSE; // the order 10 flag
...
// the sync callback
void CALLBACK MySyncProc(HSYNC handle, DWORD channel, DWORD data, void *user)
{
    order10 = TRUE; // set the order 10 flag
}
...
BASS_ChannelSetSync(music, BASS_SYNC_MUSICPOS | BASS_SYNC_ONETIME, MAKELONG(10, 0), MySyncProc, 0); // set the one-time order 10 sync
while (!order10) {
    // order 10 has not arrived, so do some processing
}
// order 10 has arrived!

Process metadata received from a Shoutcast stream. 

char title[100] = ""; // the current stream title
...
// the sync callback
void CALLBACK MyMetaSyncProc(HSYNC handle, DWORD channel, DWORD data, void *user)
{
    const char *meta = BASS_ChannelGetTags(channel, BASS_TAG_META); // get metadata
    meta = strstr(meta, "StreamTitle='"); // look for title
    if (meta) { // found it, copy it...
        int a;
        meta += 13;
        for (a = 0; a < sizeof(title) - 1; a++) {
            if (meta[a] == ';' || !meta[a]) break;
            title[a] = meta[a];
        }
        title[a] = 0;
    }
}
...
BASS_ChannelSetSync(stream, BASS_SYNC_META, 0, MyMetaSyncProc, 0); // set the meta sync

See also

BASS_ChannelRemoveSync, SYNCPROC callback