BASS.NET API for the Un4seen BASS Audio Library

BassBASS_ChannelSetSync Method

BASS.NET API for the Un4seen BASS Audio Library
Sets up a synchronizer on a MOD music, stream or recording channel.

Namespace:  Un4seen.Bass
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax
Copy
[DllImportAttribute("bass")]
public static int BASS_ChannelSetSync(
	int handle,
	BASSSync type,
	long param,
	SYNCPROC proc,
	IntPtr user
)

Parameters

handle
Type: SystemInt32
The channel handle... a HMUSIC, HSTREAM or HRECORD.
type
Type: Un4seen.BassBASSSync
The type of sync (see the table below or BASSSync), you may also use these flags:
BASS_SYNC_ONETIMECall the sync only once, and then remove it from the channel.
BASS_SYNC_MIXTIMECall the sync function when the sync occurs during decoding/mixing, instead of delaying the call until the sync is actually heard. This is automatically applied with decoding channels, as they can not be played/heard.
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(Int32) or BASS_StreamFree(Int32) or BASS_MusicFree(Int32) on the same channel handle.
param
Type: SystemInt64
The sync parameters, depends on the sync type... see the table below.
proc
Type: Un4seen.BassSYNCPROC
The callback function which should be invoked with the sync.
user
Type: SystemIntPtr
User instance data to pass to the callback function.

Return Value

Type: Int32
If succesful, then the new synchronizer's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.
Remarks
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(BASS_INFO).

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. 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(String, Int64, Int32, BASSFlag, Int32) or BASS_ChannelFlags(Int32, BASSFlag, BASSFlag)), 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 (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. This sync is also triggered when a new logical-bitstream begins in a chained OGG stream (multiple streams are strung one-after-another), in which case the metadata is the updated OGG tags. (see example below)

param : not used.

data : not used - the updated metadata is available from BASS_ChannelGetTags(Int32, BASSTag) (BASS_TAG_META)

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),

param : 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(Int32, BASSTag).

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

param : not used.

data : the type of slide completed (one of the BASS_SLIDE_xxx values).

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.

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(Int32, Int32). 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(Int32, Int64, BASSMode) in the callback. A MIXTIME sync can also be used to add or remove DSP/FX at specific points, or change a HMUSIC channel's flags or attributes (see BASS_ChannelFlags(Int32, BASSFlag, BASSFlag)). 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.

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

Examples
Set a sync to get notified when the channel reaches the end:
Copy
private SYNCPROC _mySync;
...
_mySync = new SYNCPROC(EndSync);
Bass.BASS_ChannelSetSync(_stream, BASSSync.BASS_SYNC_END | BASSSync.BASS_SYNC_MIXTIME, 
                         0, _mySync, IntPtr.Zero);
...
private void EndSync(int handle, int channel, int data, IntPtr user)
{
  // the 'channel' has ended - jump to the beginning
  Bass.BASS_ChannelSetPosition(channel, 0L);
}
Process metadata received from an internet stream:
Copy
private SYNCPROC _mySync;
...
int stream = Bass.BASS_StreamCreateURL(url, 0, BASSFlag.BASS_DEFAULT, null, 0);
// set a sync to get notified on stream title updates
_mySync = new SYNCPROC(MetaSync);
Bass.BASS_ChannelSetSync(stream, BASSSync.BASS_SYNC_META, 0, _mySync, IntPtr.Zero);
Bass.BASS_ChannelPlay(stream, false);
...
private void MetaSync(int handle, int channel, int data, IntPtr user)
{
  // BASS_SYNC_META is triggered
  string[] tags = Bass.BASS_ChannelGetTagsMETA(channel);
  foreach (string tag in tags)
    Console.WriteLine(tag);
}
See Also

Reference

Bass Class
Un4seen.Bass Namespace