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

handleThe channel handle... a HSTREAM, HMUSIC, or HRECORD.
formFormat buffer.
formlenSize of the format buffer. If this is 0, then a suggested format buffer length is returned.
titleWindow title for the selector... NULL = "Choose the output format".
flagsA combination of these flags.
BASS_ACM_DEFAULTUse the format buffer (form) contents as the default choice in the selector.
BASS_ACM_RATEOnly include formats with the same sample rate as the source.
BASS_ACM_CHANSOnly include formats with the same number of channels (mono/stereo) as the source.
BASS_ACM_SUGGESTSuggest a format without letting the user choose.
BASS_UNICODEtitle 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_HANDLEhandle is not valid.
BASS_ERROR_NOTAVAILThere are no codecs available that will accept the channel's format.
BASS_ERROR_ACM_CANCELThe user pressed the "cancel" button.
BASS_ERROR_UNKNOWNSome 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 and Windows CE.

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

See also

BASS_Encode_StartACM, BASS_Encode_StartACMFile