BASS_Encode_GetACMFormat

Presents the user with a list of available ACM codec output formats to choose from (or suggests one).

DWORD BASS_Encode_GetACMFormat(
    DWORD handle,
    void *form,
    DWORD formlen,
    char *title,
    DWORD flags
);

Parameters

handle

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

form

Format buffer.

formlen

Size of the format buffer. If this is 0, then a suggested format buffer length is returned.

title

Window title for the selector... NULL = "Choose the output format".

flags

A combination of these flags.

BASS_ACM_DEFAULT	Use the format buffer (form) contents as the default choice in the selector.
BASS_ACM_RATE	Only include formats with the same sample rate as the source.
BASS_ACM_CHANS	Only include formats with the same number of channels (mono/stereo) as the source.
BASS_ACM_SUGGEST	Suggest a format without letting the user choose.
BASS_UNICODE	title is Unicode (UTF-16).

The HIWORD - use MAKELONG(flags,format) - can be used to restrict the choice to a particular format tag (eg. WAVE_FORMAT_ADPCM). This is required with BASS_ACM_SUGGEST, and is optional otherwise.

Return value

If successful, the user-selected (or suggested) format details are put in the form buffer and the length of the format details is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code. If formlen is 0, then the suggested format buffer size is returned.

Error codes

BASS_ERROR_HANDLE	handle is not valid.
BASS_ERROR_NOTAVAIL	There are no codecs available that will accept the channel's format.
BASS_ERROR_ACM_CANCEL	The user pressed the "cancel" button.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

Unless the BASS_ACM_SUGGEST flag is specified, the user is presented with a list of available ACM codecs to choose from, given the sample format of the channel. The details of the chosen codec's output are returned in the form buffer, which can then be used with BASS_Encode_StartACM or BASS_Encode_StartACMFile to begin encoding.

The form buffer contents are actually a WAVEFORMATEX structure, and if writing the encoder output to a WAVE file, would be the format chunk ("fmt ") of the file.

Platform-specific

This function is only available on Windows.

Example

Let the user choose a codec, and setup an encoder on a channel using it.

DWORD formlen=BASS_Encode_GetACMFormat(0, NULL, 0, (char*)NULL, 0); // get suggested format buffer size
void *form=malloc(formlen); // allocate the format buffer
if (BASS_Encode_GetACMFormat(channel, form, formlen, (char*)NULL, 0)) // let the user choose a codec
    BASS_Encode_StartACMFile(channel, form, 0, "acm.wav"); // begin encoding using the codec
free(form); // free the format buffer

Without letting the user choose, setup an MP3 encoder on a channel.

DWORD formlen=BASS_Encode_GetACMFormat(0, NULL, 0, (char*)NULL, 0); // get suggested format buffer size
void *form=malloc(formlen); // allocate the format buffer
if (BASS_Encode_GetACMFormat(channel, form, formlen, (char*)NULL,
    MAKELONG(BASS_ACM_SUGGEST|BASS_ACM_RATE|BASS_ACM_CHANS, WAVE_FORMAT_MPEGLAYER3)) // get the format details
    BASS_Encode_StartACMFile(channel, form, BASS_ENCODE_NOHEAD, "acm.mp3"); // begin encoding without a WAVE header
free(form); // free the format buffer