BASS_Encode_Start
Sets up an encoder on a channel.
HENCODE BASS_Encode_Start(
DWORD handle,
char *cmdline,
DWORD flags,
ENCODEPROC *proc,
void *user
);
Parameters
| handle | The channel handle... a HSTREAM, HMUSIC, or HRECORD. | ||||||||||||||||||||||
| cmdline | The encoder command-line, including the executable filename and any options. Or the output filename if the BASS_ENCODE_PCM flag is used. | ||||||||||||||||||||||
| flags | A combination of these flags.
| ||||||||||||||||||||||
| proc | Optional callback function to receive the encoded data... NULL = no callback. To have the encoded data received by a callback function, the encoder needs to be told to output to STDOUT. | ||||||||||||||||||||||
| 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_FILEOPEN | The encoder could not be started. Check that the executable exists. |
| BASS_ERROR_CREATE | The PCM file could not be created. |
| BASS_ERROR_NOTAVAIL | External encoders are not supported. |
| BASS_ERROR_UNKNOWN | Some other mystery problem! |
Remarks
The encoder must be told (via the command-line) to expect input from STDIN, rather than a file. The command-line should also tell the encoder what filename to write its output to, unless you are using a callback function, in which case it should be told to write its output to STDOUT.No user interaction with the encoder is possible, so anything that would cause the encoder to require the user to press any keys should be avoided. For example, if the encoder asks whether to overwrite files, the encoder should be instructed to always overwrite (via the command-line), or the existing file should be deleted before starting the encoder.
Standard RIFF files are limited to a little over 4GB in size. When writing a WAV file, BASSenc will automatically stop at that point, so that the file is valid. That does not apply when sending data to an encoder though, as the encoder may (possibly via a command-line option) ignore the size restriction, but if it does not, it could mean that the encoder stops after a few hours (depending on the sample format). If longer encodings are needed, the BASS_ENCODE_NOHEAD flag can be used to omit the WAVE header, and the encoder informed of the sample format via the command-line instead. The 4GB size limit can also be overcome with the BASS_ENCODE_RF64 flag, but most encoders are unlikely to support RF64.
When writing an RF64 WAV 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. When an encoder is used, it is not possible to go back and change the header at the end, so the RF64 header is sent at the beginning in that case.
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.
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.
The returned handle is the encoder's process handle, which can be used to do things like change the encoder's priority (SetPriorityClass) and get its exit code (GetExitCodeProcess).
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.
Platform-specific
External encoders are not supported on iOS or Windows CE, so only plain PCM file writing with the BASS_ENCODE_PCM flag is possible on those platforms.Example
Start encoding a channel to an MP3 file (output.mp3) using LAME with the standard preset settings.BASS_Encode_Start(channel, "lame --alt-preset standard - output.mp3", 0, NULL, 0); BASS_ChannelPlay(channel, 0); // start the channel playing & encoding
Start writing a channel to a WAV file (output.wav).
BASS_Encode_Start(channel, "output.wav", BASS_ENCODE_PCM, NULL, 0); BASS_ChannelPlay(channel, 0); // start the channel playing & encoding