sound/designs/channel-mapping-api.rst

2 ALSA PCM channel-mapping API
10 The channel mapping API allows user to query the possible channel maps
11 and the current channel map, also optionally to modify the channel map
12 of the current stream.
14 A channel map is an array of position for each PCM channel.
15 Typically, a stereo PCM stream has a channel map of
17 while a 4.0 surround PCM stream has a channel map of
20 The problem, so far, was that we had no standard channel map
21 explicitly, and applications had no way to know which channel
29 was no way to specify this because of lack of channel map
30 specification.  These are the main motivations for the new channel
37 Actually, "the channel mapping API" doesn't introduce anything new in
38 the kernel/user-space ABI perspective.  It uses only the existing
42 providing the channel mapping information and configuration.  This
46 * name = "Playback Channel Map" or "Capture Channel Map"
54 allow user to change the channel map dynamically.
57 ---
59 The TLV operation gives the list of available channel
60 maps.  A list item of a channel map is usually a TLV of
61 ``type data-bytes ch0 ch1 ch2...``
63 bytes (not the numbers) of channel values, and the rest are the
64 position value for each channel.
68 The ``_FIXED`` type is for a channel map with the fixed channel position
69 while the latter two are for flexible channel positions. ``_VAR`` type is
70 for a channel map where all channels are freely swappable and ``_PAIRED``
71 type is where pair-wise channels are swappable.  For example, when you
72 have {FL/FR/RL/RR} channel map, ``_PAIRED`` type would allow you to swap
78 The available channel position values are defined in ``sound/asound.h``,
83   /* channel positions */
88 	/* this follows the alsa-lib mixer channel value + 3 */
118 When a PCM stream can provide more than one channel map, you can
119 provide multiple channel maps in a TLV container type.  The TLV data
129 The channel position is provided in LSB 16bits.  The upper bits are
137 ``SNDRV_CHMAP_PHASE_INVERSE`` indicates the channel is phase inverted,
141 When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values
142 don't follow the standard definition above but driver-specific.
145 --------------
147 The control read operation is for providing the current channel map of
149 containing the position of each channel.
151 When this is performed before the number of the channel is specified
156 ---------------
159 change the channel configuration on the fly, such as HDMI.  User needs
160 to pass an integer value containing the valid channel positions for