BASS.NET API for the Un4seen BASS Audio Library

BassBASS_ChannelSetPosition Method (Int32, Int64, BASSMode)

BASS.NET API for the Un4seen BASS Audio Library
Sets the playback position of a sample, MOD music, or stream.

Namespace:  Un4seen.Bass
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

[DllImportAttribute("bass")]
public static bool BASS_ChannelSetPosition(
	int handle,
	long pos,
	BASSMode mode
)

Parameters

handle
Type: SystemInt32
The channel handle... a HCHANNEL, HSTREAM or HMUSIC.
pos
Type: SystemInt64
The position, in units determined by the mode.
mode
Type: Un4seen.BassBASSMode
How to set the position. One of the following (see BASSMode), with optional flags:
BASS_POS_BYTEThe position is in bytes, which will be rounded down to the nearest sample boundary.
BASS_POS_MUSIC_ORDERThe position is in orders and rows... use MakeLong(Int16, Int16). (HMUSIC only).
BASS_POS_OGGThe position is a bitstream number in an OGG file... 0 = first.
BASS_POS_ENDThe position is in bytes and is where the channel will end... 0 = normal end position. This will have no effect if it is beyond the channel's normal end position. If the channel is already at/beyond the position then it will end at its current position.
BASS_POS_LOOPThe position is in bytes and is where looping will start from (when looping is enabled). If this is at/beyond the end then the default loop position of 0 will be used instead.
BASS_POS_DECODETOFlag: Decode/render up to the position rather than seeking to it. This is useful for streams that are unseekable or that have inexact seeking, but it is generally slower than normal seeking and the requested position cannot be behind the current decoding position. This flag can only be used with the BASS_POS_BYTE mode.
BASS_POS_FLUSHFlag: Flush all output buffers (including FX) so that no remnant of the old position is heard after seeking. This is automatic on normal playback channels (not decoding channels) outside of a 'mixtime' SYNCPROC.
BASS_POS_INEXACTFlag: Allow inexact seeking. For speed, seeking may stop at the beginning of a block rather than partially processing the block to reach the requested position.
BASS_POS_RELATIVEFlag: The requested position is relative to the current position. pos is treated as signed in this case and can be negative.
BASS_POS_RESETFlag: Reset user file buffers. This allows a user file stream with the BASS_STREAM_BLOCK flag set to be reset, so that it is ready to process new data. This flag can only be used with the BASS_POS_BYTE mode, and pos must be 0.
BASS_POS_RELATIVEFlag: Allow inexact seeking. For speed, seeking may stop at the beginning of a block rather than partially processing the block to reach the requested position.
BASS_POS_RESETFlag: Reset user file buffers. This allows a user file stream with the BASS_STREAM_BLOCK flag set to be reset, so that it is ready to process new data. This flag can only be used with the BASS_POS_BYTE mode, and pos must be 0.
BASS_POS_SCANFlag: Scan the file to build a seek table up to the position, if it has not already been scanned. Scanning will continue from where it left off previously rather than restarting from the beginning of the file each time. This flag only applies to MP3/MP2/MP1 files and will be ignored with other file formats.
BASS_MUSIC_POSRESETFlag: Stop all notes. This flag is applied automatically if it has been set on the channel, eg. via BASS_ChannelFlags(Int32, BASSFlag, BASSFlag). (HMUSIC).
BASS_MUSIC_POSRESETEXFlag: Stop all notes and reset bpm/etc. This flag is applied automatically if it has been set on the channel, eg. via BASS_ChannelFlags(Int32, BASSFlag, BASSFlag). (HMUSIC).
Other modes and flags may be supported by add-ons, see the documentation.

Return Value

Type: Boolean
If succesful, then is returned, else is returned. Use BASS_ErrorGetCode to get the error code.
Remarks

Setting the position of a MOD music in bytes (other than 0) requires that the BASS_MUSIC_PRESCAN flag was used in the BASS_MusicLoad(String, Int64, Int32, BASSFlag, Int32) call. When setting the position in orders/rows, the channel's byte position (as reported by BASS_ChannelGetPosition(Int32, BASSMode)) is reset to 0. This is because it's not possible to get the byte position of an order/row position - it's possible that a position may never be played in the normal cause of events, or it may be played multiple times.

When changing the position of a MOD music, and the BASS_MUSIC_POSRESET flag is active on the channel, 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 postion change, unless the seek position is 0 (the start), in which case they are also reset to the starting values (when using 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(BASSStreamSystem, BASSFlag, BASS_FILEPROCS, IntPtr) can be used again instead to create a new stream for the new data.

User streams (created with BASS_StreamCreate(Int32, Int32, BASSFlag, STREAMPROC, IntPtr)) 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. BASS_ChannelGetPosition(Int32, BASSMode) can be used to confirm what the new position actually is.

In some cases, particularly when the BASS_POS_INEXACT flag is used, the new position may not be what was requested. BASS_ChannelGetPosition(Int32, BASSMode) can be used to confirm what the new position actually is.

The BASS_POS_SCAN flag works the same way as the BASS_StreamCreateFile(String, Int64, Int64, BASSFlag) 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.

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not a valid channel.
BASS_ERROR_NOTFILEThe stream is not a file stream.
BASS_ERROR_POSITIONThe requested position is invalid, eg. beyond the end.
BASS_ERROR_NOTAVAILThe download has not yet reached the requested position.
BASS_ERROR_UNKNOWNSome other mystery problem!

Examples

Set the position of a stream channel to 10sec. and 200ms:
Bass.BASS_ChannelSetPosition(stream, Bass.BASS_ChannelSeconds2Bytes(stream, 10.20), BASSMode.BASS_POS_BYTE);
Set the position of a MOD music to row 20 of order 10:
Bass.BASS_ChannelSetPosition(music, Utils.MakeMusicPos(10,20), BASSMode.BASS_POS_MUSIC_ORDER );
Start playback of a MOD music from the beginning of the last order:
// get number of orders
int len = (int)Bass.BASS_ChannelGetLength(music, BASSMode.BASS_POS_MUSIC_ORDER);
// seek to last order
Bass.BASS_ChannelSetPosition(music, Utils.MakeMusicPos(len-1, 0), BASSMode.BASS_POS_MUSIC_ORDER);
Bass.BASS_ChannelPlay(music, false); // play
See Also

Reference