BASS_Encode_StartLimit

Sets up an encoder on a channel, and limits the amount of sample data that is fed to it. 

HENCODE BASS_Encode_StartLimit(
    DWORD handle,
    char *cmdline,
    DWORD flags,
    ENCODEPROC *proc,
    void *user,
    DWORD limit
);

Parameters

handleThe channel handle... a HSTREAM, HMUSIC, or HRECORD. 0 = no channel for pre-encoded data.
cmdlineThe encoder command-line, including the executable filename and any options.
flagsA combination of these flags.
BASS_ENCODE_NOHEADDo not send any headers to the encoder. If this flag is used then the sample format must be passed to the encoder some other way, eg. via the command-line.
BASS_ENCODE_AIFFSend an AIFF header to the encoder instead of a WAVE header. This flag is ignored if the BASS_ENCODE_NOHEAD flag is used.
BASS_ENCODE_RF64Send an RF64 header to the encoder 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_WFEXTSend the sample format information to the encoder 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_BIGENDSend big-endian sample data to the encoder, 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. If the encoder does not support 32-bit floating-point sample data, one of these flags can be used to have the sample data converted to integer before it is fed to the encoder. These flags are ignored if the channel is not floating-point and the BASS_CONFIG_FLOATDSP option is not enabled.
BASS_ENCODE_FP_AUTOConvert 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_DITHERApply dither (TPDF) when converting floating-point sample data to integer
BASS_ENCODE_QUEUEQueue data to feed the encoder asynchronously. This prevents the data source (DSP system or BASS_Encode_Write call) getting blocked by the encoder, but if data is queued more quickly than the encoder can process it then that could result in lost data.
BASS_ENCODE_QUEUE_WAITThis 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_LIMITLimit the encoding 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. Except for in those instances, this flag is applied automatically when the encoder is feeding a Shoutcast or Icecast server.
BASS_ENCODE_CAST_NOLIMITDon't limit the encoding rate to real-time speed when feeding a Shoutcast or Icecast server. This flag overrides the BASS_ENCODE_LIMIT flag.
BASS_ENCODE_PAUSEStart the encoder in a paused state.
BASS_ENCODE_AUTOFREEAutomatically 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.
BASS_ENCODE_TERMINATETerminate the encoder's process immediately when stopping. This overrides the BASS_CONFIG_ENCODE_TERMINATE setting. If the encoder is writing a file, it may result in an incomplete file.
BASS_UNICODEcmdline is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.
procOptional 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.
userUser instance data to pass to the callback function.
limitThe number of bytes of sample data to encode... 0 = unlimited. If the BASS_ENCODE_FP flags are used, the limit is applied after the effect of that, ie. the limit is based on the file's sample format rather than the source's.

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_HANDLEhandle is not valid.
BASS_ERROR_FILEOPENThe encoder could not be started. Check that the executable exists.
BASS_ERROR_CREATEThe PCM file could not be created.
BASS_ERROR_NOTAVAILExternal encoders are not supported.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

This function is identical to BASS_Encode_Start, with the additional ability to limit the amount of sample data that is fed to the encoder. This can be useful in situations where the encoder needs to know in advance how much data it will be receiving, but the BASS_ENCODE_NOHEAD flag should not be used then because the length is communicated via the header. BASS_Encode_SetNotify can be used to get notified when the limit is hit.

Example

Start encoding a channel to an MP3 file (output.mp3) using LAME with the standard preset settings, limiting it to 1000000 bytes of sample data. 
BASS_Encode_StartLimit(channel, "lame --preset standard - output.mp3", BASS_ENCODE_FP_24BIT, NULL, NULL, 1000000);
BASS_ChannelPlay(channel, 0); // start the channel playing & encoding

See also

BASS_Encode_AddChunk, BASS_Encode_CastInit, BASS_Encode_IsActive, BASS_Encode_SetNotify, BASS_Encode_SetPaused, BASS_Encode_Start, BASS_Encode_Stop, BASS_Encode_Write, ENCODEPROC callback, BASS_CONFIG_ENCODE_PRIORITY