Sets up a user-provided encoder on a channel.
HENCODE BASS_Encode_StartUser(
DWORD handle,
char *filename,
DWORD flags,
ENCODERPROC *proc,
void *user
);
| handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD. | ||||||||||||||||
| filename | Output filename... NULL = no output file. | ||||||||||||||||
| flags | A combination of these flags.
| ||||||||||||||||
| proc | Callback function to receive the sample data and return the encoded data. | ||||||||||||||||
| user | User instance data to pass to the callback function. |
| BASS_ERROR_HANDLE | handle is not valid. |
| BASS_ERROR_CREATE | The file could not be created. |
| BASS_ERROR_MEM | There is insufficient memory. |
| BASS_ERROR_UNKNOWN | Some other mystery problem! |
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 buffer will grow as needed to hold the queued data, up to a limit specified by the BASS_CONFIG_ENCODE_QUEUE config option. If the limit is exceeded (or there is no free memory), data will be lost; BASS_Encode_SetNotify can be used to be notified of that occurrence. 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.
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.