BASS_Encode_StartCA


Sets up an encoder on a channel, using a CoreAudio codec and sending the output to a user defined function.

HENCODE BASS_Encode_StartCA(
    DWORD handle,
    DWORD ftype,
    DWORD atype,
    DWORD flags,
    DWORD bitrate,
    ENCODEPROCEX *proc,
    void *user
);

Parameters

handleThe channel handle... a HSTREAM, HMUSIC, or HRECORD.
ftypeFile format identifier.
atypeAudio data format identifier.
flagsA combination of these flags.
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 before encoding. 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_MONOConvert to mono before encoding.
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 queud more quickly than the encoder can process it, that could result in lost data.
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 queuing is enabled, any remaining queued data will be sent to the encoder before it is freed.
bitrateThe bitrate in bits per second... 0 = the codec's default bitrate.
procCallback function to receive the encoded data.
userUser 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_HANDLEhandle is not valid.
BASS_ERROR_FILEFORMftype is not valid.
BASS_ERROR_CODECatype is not valid or supported with ftype.
BASS_ERROR_NOTAVAILbitrate is not supported by the codec.
BASS_ERROR_FORMATThe channel's sample format is not supported by the codec.
BASS_ERROR_UNKNOWNSome other mystery problem!

Remarks

This function allows CoreAudio codecs to be used for encoding. A list of standard file and audio data format identifiers is available from Apple, here. The available file and audio data identifiers, as well as other information, can be retreived via the Audio File Services and Audio Format Services APIs, eg. the kAudioFileGlobalInfo_WritableTypes and kAudioFormatProperty_EncodeFormatIDs properties.

Internally, the sending of sample data to the encoder is implemented via a DSP callback on the channel. That means when you play the channel (or call BASS_ChannelGetData if it's a decoding channel), the sample data will be sent to the encoder at the same time. The encoding is performed in the DSP callback; there isn't a separate process doing the encoding, as when using an external encoder via BASS_Encode_Start.

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 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_StartCAFile can be used to have the encoder output sent to a file instead of a callback function.

Platform-specific

This function is only available on OSX and iOS.

See also

BASS_Encode_CastInit, BASS_Encode_GetACMFormat, BASS_Encode_IsActive, BASS_Encode_ServerInit, BASS_Encode_SetPaused, BASS_Encode_Start, BASS_Encode_StartCAFile, BASS_Encode_Stop, BASS_Encode_Write, ENCODEPROCEX callback, BASS_CONFIG_ENCODE_PRIORITY