Sets the playback position of a sample, MOD music, or stream.
BOOL BASS_ChannelSetPosition( DWORD handle, QWORD pos, DWORD mode );
|handle||The channel handle... a HCHANNEL, HSTREAM or HMUSIC.|
|pos||The position, in units determined by the mode.|
|mode||How to set the position. One of the following, with optional flags.|
|BASS_ERROR_HANDLE||handle is not a valid channel.|
|BASS_ERROR_NOTFILE||The stream is not a file stream.|
|BASS_ERROR_POSITION||The requested position is invalid, eg. it is beyond the end or the download has not yet reached it.|
|BASS_ERROR_NOTAVAIL||The requested mode is not available. Invalid flags are ignored and do not result in this error.|
|BASS_ERROR_UNKNOWN||Some other mystery problem!|
When setting the position of a MOD music, and the BASS_MUSIC_POSRESET flag is active, all notes that were playing before the position changed will be stopped. Otherwise, the notes will continue playing until they are stopped in the MOD music. When setting the position in bytes, the BPM, speed and global volume are updated to what they would normally be at the new position. Otherwise they are left as they were prior to the position change, unless the seek position is 0 (the start), in which case they are also reset to the starting values (with the BASS_MUSIC_POSRESET flag). When the BASS_MUSIC_POSRESETEX flag is active, the BPM, speed and global volume are reset with every seek.
For MP3/MP2/MP1 streams, unless the file is scanned via the BASS_POS_SCAN flag or the BASS_STREAM_PRESCAN flag at stream creation, seeking will be approximate but generally still quite accurate. Besides scanning, exact seeking can also be achieved with the BASS_POS_DECODETO flag.
Seeking in internet file (and "buffered" user file) streams is possible once the download has reached the requested position, so long as the file is not being streamed in blocks (BASS_STREAM_BLOCK flag).
The BASS_POS_RESET flag can be used to reset/flush a buffered user file stream, so that new data can be processed, but it may not be supported by some decoders. When it is not supported, BASS_StreamCreateFileUser can be used again instead to create a new stream for the new data.
User streams (created with BASS_StreamCreate) are not seekable, but it is possible to reset a user stream (including its buffer contents) by setting its position to byte 0.
The BASS_POS_DECODETO flag can be used to seek forwards in streams that are not normally seekable, like custom streams or internet streams that are using the BASS_STREAM_BLOCK flag, but it will only go as far as what is currently available; it will not wait for more data to be downloaded, for example.
In some cases, particularly when the BASS_POS_INEXACT flag is used, the new position may not be what was requested. BASS_ChannelGetPosition can be used to confirm what the new position actually is.
The BASS_POS_SCAN flag works the same way as the BASS_StreamCreateFile BASS_STREAM_PRESCAN flag, and can be used to delay the scanning until after the stream has been created. When a position beyond the end is requested, the call will fail (BASS_ERROR_POSITION error code) but the seek table and exact length will have been scanned. When a file has been scanned, all seeking (even without the BASS_POS_SCAN flag) within the scanned part of it will use the scanned infomation.
BASS_ChannelSetPosition(channel, 1000000, BASS_POS_BYTE);
Set the position of a MOD music to row 20 of order 10, and stop all currently playing notes.
BASS_ChannelSetPosition(music, MAKELONG(10, 20), BASS_POS_MUSIC_ORDER | BASS_MUSIC_POSRESET);