ao_sample_format

declared in "ao/ao.h";

This structure describes the format of audio samples.

typedef struct { int bits; /* bits per sample */ int rate; /* samples per second (in a single channel) */ int channels; /* number of audio channels */ int byte_format; /* Byte ordering in sample, see constants below */ char *matrix; /* channel input matrix */ } ao_sample_format;

Relevant Struct Members

byte_format

Specifies the ordering of the sample bytes. The value of this member is ignored when samples have only 8 bits. Use the following constants:

• AO_FMT_LITTLE - Samples are in little-endian order.
• AO_FMT_BIG - Samples are in big-endian order.
• AO_FMT_NATIVE - Samples are in the native ordering of the computer.

matrix

Specifies the mapping of input channels to intended speaker/ouput location (or NULL to specify no mapping). The matrix is specified as a comma seperated list of channel locations equal to the number and in the order of the input channels. The channel mnemonics are as follows:

• L - Left speaker, located forward and to the left of the listener.
• R - Right speaker, located forward and to the right of the listener.
• C - Center speaker, located directly forward of the listener between the Left and Right speakers.
• M - Monophonic, a virtual speaker for single-channel output.
• CL - Left of Center speaker (used in some Widescreen formats), located forward of the listener between the Center and Left speakers. Alternatively referred to as 'Left Center'.
• CR - Right of Center speaker (used in some Widescreen formats), located forward of the listener between the Center and Right speakers. Alternatively referred to as 'Right Center'.
• BL - Back Left speaker, located behind and to the left of the listener. Alternatively called 'Left Surround' (primarily by Apple) or 'Surround Rear Left' (primarily by Dolby).
• BR - Back Right speaker, located behind and to the right of the listener. Alternatively called 'Right Surround' (primarily by Apple) or 'Surround Rear Right' (primarily by Dolby).
• BC - Back Center speaker, located directly behind the listener. Alternatively called 'Center Surround' (primarily by Apple) or 'Surround Rear Center' (primarily by Dolby).
• SL - Side Left speaker, located directly to the listener's left side. The Side Left speaker is also referred to as 'Left Surround Direct' (primarily by Apple) or 'Surround Left' (primarily by Dolby)
• SR - Side Right speaker, located directly to the listener's right side. The Side Right speaker is also referred to as 'Right Surround Direct' (primarily by Apple) or 'Surround Right' (primarily by Dolby)
• LFE - Low Frequency Effect (subwoofer) channel. This is channel is usually lowpassed and meant only for bass, though in some recent formats it is a discrete, full-range channel. Microsoft calls this the 'Low Frequency' channel.
• A1, A2, A3, A4 - 'auxiliary' channels, not mapped to a location. Intended for driver-specific use.
• X - Unused/Invalid channel, to be dropped in the driver and not output to any speaker.

Note that the 'surround' speakers referred to in other systems can be either the side or back speakers depending on vendor. For example, Apple calls the back speakers 'surround' and the side speakers 'direct surround'. Dolby calls the back speakers 'surround rear' and the side speakers 'surround', resulting in a direct naming conflict. For this reason, libao explicitly refers to speakers as 'back' and 'side' rather than 'surround'.

Common examples of channel orderings:

• "L,R" - Stereo ordering in virtually all file formats
• "L,R,BL,BR" - Quadraphonic ordering for most file formats
• "L,R,C,LFE,BR,BL" - channel order of a 5.1 WAV or FLAC file
• "L,R,C,LFE,BR,BL,SL,SR" - channel order of a 7.1 WAV or FLAC file
• "L,C,R,BR,BL,LFE" - channel order of a six channel (5.1) Vorbis I file
• "L,C,R,BR,BL,SL,SR,LFE" - channel order of an eight channel (7.1) Vorbis file
• "L,CL,C,R,RC,BC" - channel order of a six channel AIFF[-C] file

Channel mappings for most formats are usually not tied to a single channel matrix (there are a few exceptions like Vorbis I, where the number of channels always maps to a specific order); the above examples cannot be blindly applied to a given file type and number of channels. The mapping must usually be read or intuited from the input.