BASS_Encode_StartPCM

Sets up a PCM encoder on a channel, sending the output to a user defined function.

HENCODE BASS_Encode_StartPCM(
    DWORD handle,
    DWORD flags,
    ENCODEPROCEX *proc,
    void *user
);

Parameters

handle

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

flags

A combination of these flags.

BASS_ENCODE_NOHEAD	Do not write any headers.
BASS_ENCODE_AIFF	Write an AIFF header instead of a WAVE header. This flag is ignored if the BASS_ENCODE_NOHEAD is used.
BASS_ENCODE_RF64	Write an RF64 header instead of a standard RIFF header, allowing more than 4GB of sample data. This flag is ignored if the BASS_ENCODE_NOHEAD or BASS_ENCODE_AIFF flags are used.
BASS_ENCODE_WFEXT	Write the sample format information in WAVEFORMATEXTENSIBLE form instead of WAVEFORMATEX form. This flag is ignored if the BASS_ENCODE_NOHEAD or BASS_ENCODE_AIFF flags are used.
BASS_ENCODE_BIGEND	Write big-endian sample data, else little-endian. This flag is ignored unless the BASS_ENCODE_NOHEAD flag is used.
BASS_ENCODE_FP_8BIT, BASS_ENCODE_FP_16BIT, BASS_ENCODE_FP_24BIT, BASS_ENCODE_FP_32BIT	Convert floating-point sample data to 8/16/24/32 bit integer. These flags are ignored if the channel is not floating-point and the BASS_CONFIG_FLOATDSP option is not enabled.
BASS_ENCODE_FP_AUTO	Convert floating-point sample data back to the channel's format (8/16 bit integer) if the data is only floating-point due to the BASS_CONFIG_FLOATDSP option being enabled.
BASS_ENCODE_DITHER	Apply dither (TPDF) when converting floating-point sample data to integer.
BASS_ENCODE_QUEUE	Queue data to write asynchronously. This prevents the data source (DSP system or BASS_Encode_Write call) getting blocked by the writing, and can improve performance through multithreading, but if data is queued more quickly than the encoder can process it then that could result in lost data.
BASS_ENCODE_QUEUE_WAIT	This is the same as BASS_ENCODE_QUEUE except that it will wait for space in the queue rather than drop data (so the data source may get blocked).
BASS_ENCODE_LIMIT	Limit the processing rate to real-time speed, by introducing a delay when the rate is too high. With BASS 2.4.6 or above, this flag is ignored when the encoder is fed in a playback buffer update cycle (including BASS_Update and BASS_ChannelUpdate calls), to avoid possibly causing playback buffer underruns.
BASS_ENCODE_PAUSE	Start the encoder in a paused state.
BASS_ENCODE_AUTOFREE	Automatically free the encoder when the source channel is freed. If it has queued data, the encoder will be freed asynchronously once that has been processed.

proc

Optional callback function to receive the encoded data... NULL = no callback.

user

User instance data to pass to the callback function.

Return value

The encoder handle is returned if the encoder is successfully started, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_HANDLE	handle is not valid.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

Standard RIFF files are limited to 4GB in size, and the encoder will automatically stop at that point (except when it is feeding a server via BASS_Encode_ServerInit). That size limit can be overcome by writing an RF64 file instead with the BASS_ENCODE_RF64 flag, or a headerless raw PCM file with the BASS_ENCODE_NOHEAD flag. When writing an RF64 file, a standard RIFF header will still be written initially, which will only be replaced by an RF64 header at the end if the file size has exceeded the standard limit.

Internally, the sending of sample data to the encoder is implemented via a DSP callback on the channel. That means when the channel is played (or BASS_ChannelGetData is called if it is a decoding channel), the sample data will be sent to the encoder at the same time. It also means that if the BASS_CONFIG_FLOATDSP option is enabled, the sample data will be 32-bit floating-point, and one of the BASS_ENCODE_FP flags will be required if the encoder does not support floating-point sample data. The BASS_CONFIG_FLOATDSP setting should not be changed while encoding is in progress.

By default, the encoder DSP has a priority setting of -1000, which determines where in the DSP chain the encoding is performed. That can be changed via the BASS_CONFIG_ENCODE_PRIORITY config option.

Besides the automatic DSP system, data can also be manually fed to the encoder via the BASS_Encode_Write function. Both methods can be used together, but in general, the "automatic" system ought to be paused when using the "manual" system, via the BASS_ENCODE_PAUSE flag or the BASS_Encode_SetPaused function. Data fed to the encoder manually does not go through the source channel's DSP chain, so any DSP/FX set on the channel will not be applied to the data.

When queued encoding is enabled via the BASS_ENCODE_QUEUE flag, the DSP system or BASS_Encode_Write call will just buffer the data, and the data will then be fed to the encoder by another thread. The maximum amount of queued data is determined by the BASS_CONFIG_ENCODE_QUEUE config option. If the limit is exceeded then data will be lost; BASS_Encode_SetNotify can be used to get notified of that. The amount of data that is currently queued, as well as the queue limit and how much data has been lost, is available from BASS_Encode_GetCount.

BASS_Encode_IsActive can be used to check that the encoder is still running. When done encoding, use BASS_Encode_Stop or BASS_Encode_StopEx to close the encoder.

Multiple encoders can be set on a channel. For convenience, most of the encoder functions will accept either an encoder handle or a channel handle. When a channel handle is used, the function is applied to all encoders that are set on that channel.

BASS_Encode_StartPCMFile can be used to have the encoder output sent to a file instead of a callback function.

BASS_Encode_StartPCM

Parameters

Return value

Error codes

Remarks

See also