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

handle

The channel handle... a HMUSIC, HSTREAM or HRECORD.

type

The type of sync (see the table below). The following flags may also be used.

BASS_SYNC_MIXTIME	Call 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_ONETIME	Call the sync only once, and then remove it from the channel.

param

The sync parameter. Depends on the sync type... see the table below.

proc

The callback function.

user

User instance data to pass to the callback function.

Sync types, with param and SYNCPROC data definitions.

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_END	Sync 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 : 1 = the sync is triggered by a backward jump in a MOD music, otherwise not used.
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_MUSICFX	Sync 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_MUSICINST	Sync 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_MUSICPOS	Sync 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_CHANGE	Sync 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_POS	Sync when a channel reaches a position. param : position in bytes (automatically rounded down to nearest sample). data : not used.
BASS_SYNC_SETPOS	Sync 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_HANDLE	handle is not a valid channel.
BASS_ERROR_ILLTYPE	An illegal type was specified.
BASS_ERROR_ILLPARAM	An 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 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.

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)
{
    char *meta=BASS_ChannelGetTags(channel, BASS_TAG_META); // get metadata
    meta=strstr(meta, "StreamTitle='"); // look for title
    if (meta) { // found it, copy it...
        strcpy(title, meta+13);
        strchr(title, ';')[-1]=0;
    }
}
...
BASS_ChannelSetSync(stream, BASS_SYNC_META, 0, MyMetaSyncProc, 0); // set the meta sync

BASS