Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
channel_defs.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2023 Roc Streaming authors
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 */
8
9//! @file roc_audio/channel_defs.h
10//! @brief Channel layout, order, and positions.
11
12#ifndef ROC_AUDIO_CHANNEL_DEFS_H_
13#define ROC_AUDIO_CHANNEL_DEFS_H_
14
15#include "roc_core/stddefs.h"
16
17namespace roc {
18namespace audio {
19
20//! Channel layout.
21//! Defines meaning of channels in ChannelSet.
22//! ChannelMapper uses channel layout to decide how to perform mapping.
24 //! Channel layout is not set.
25 //! @remarks
26 //! This is never valid and indicates that ChannelSet is not fully initialized.
28
29 //! Multi-channel mono / stereo / surround sound.
30 //! @remarks
31 //! The meaning of channel index is defined by ChannelPosition enum.
32 //! Channels are mapped according to their position in space, e.g. if
33 //! top-left channel is missing, it can be mixed from front-left and
34 //! side-left channels.
36
37 //! Multi-channel multi-track sound.
38 //! @remarks
39 //! There is no special meaning of channels, they are considered to be
40 //! independent tracks. Channels are mapped according to their numbers;
41 //! channel N is mapped to channel N and nothing else.
43};
44
45//! Surround channel order.
46//! @remarks
47//! Should be used with ChannelLayout_Surround.
48//! Defines order in which channels from ChannelSet are (de)serialized.
50 //! Channel order is not set.
51 //! @remarks
52 //! For ChanLayout_Surround, this is never valid and indicates that ChannelSet
53 //! is not fully initialized. For ChanLayout_Multitrack, in contrast, this is
54 //! the only valid value.
56
57 //! ITU/SMPTE channel order.
58 //! Order: FL, FR, FC, LFE, BL, BR, BC, SL, SR, TFL, TFR, TBL, TBR, TML, TMR.
59 //! @remarks
60 //! This order is actually a superset of what is defined by SMPTE, but when
61 //! fileterd by actual masks like 5.1 or 7.1, it produces orderings equal
62 //! to what is defined in the standard.
63 //! When used with masks 2.x - 5.x (but not 6.x), it is also compatible with
64 //! the channel order from AIFF-C, which is used by default in RTP/AVP, as
65 //! defined in RFC 3551.
67
68 //! ALSA channel order.
69 //! Order: FL, FR, BL, BR, FC, LFE, SL, SR, BC.
70 //! @remarks
71 //! This order is used by ALSA hardware devices.
72 //! ALSA supports only 9 channels.
74
75 //! Maximum value of enum.
77};
78
79//! Surround channel position.
80//! @remarks
81//! Should be used with ChannelLayout_Surround.
82//! Defines meaning of channel indicies for mono / stereo / surround sound.
83//! @note
84//! Despide mono, stereo, and 3.x technically are not surround layouts, in
85//! the code base they are considered a special case of surround.
87 //! @name Front speakers.
88 //! @remarks
89 //! Placed in the front of the user.
90 // @{
91 ChanPos_FrontLeft, //!< Front left (FL).
92 ChanPos_FrontCenter, //!< Front center (FC).
93 ChanPos_FrontRight, //!< Front right (FR).
94 // @}
95
96 //! @name Surround speakers.
97 //! @remarks
98 //! Placed on the sides of the user (in surround 7.x).
99 //! Also known as "mid" speakers.
100 // @{
101 ChanPos_SideLeft, //!< Side left (SL).
102 ChanPos_SideRight, //!< Side right (SR).
103 // @}
104
105 //! @name Back speakers.
106 //! @remarks
107 //! Placed behind the user.
108 //! Also known as "rear" speakers.
109 // @{
110 ChanPos_BackLeft, //!< Back left (BL).
111 ChanPos_BackCenter, //!< Back center (BC).
112 ChanPos_BackRight, //!< Back right (BR).
113 // @}
114
115 //! @name Top speakers.
116 //! @remarks
117 //! Placed above the user (in surround x.1.2 and x.1.4).
118 //! Also known as "height" or "overhead" speakers.
119 // @{
120 ChanPos_TopFrontLeft, //!< Top front left (TFL).
121 ChanPos_TopFrontRight, //!< Top front right (TFR).
122
123 ChanPos_TopMidLeft, //!< Top middle left (TML).
124 ChanPos_TopMidRight, //!< Top middle right (TMR).
125
126 ChanPos_TopBackLeft, //!< Top rear left (TBL).
127 ChanPos_TopBackRight, //!< Top rear right (TBR).
128 // @}
129
130 //! Low frequency speaker (LFE).
131 //! @remarks
132 //! Placed anywhere.
133 //! Also known as "subwoofer" or "SW" speaker.
135
136 //! Maximum value of enum.
139
140//! Channel mask.
141//! @remarks
142//! Used to construct short channel sets (up to 32 channels)
143//! for ChanLayout_Surround layout.
144typedef uint32_t ChannelMask;
145
146//! Mono.
147//! Mask: FC.
148//! @code
149//! +------------------+
150//! | FC |
151//! | user |
152//! +------------------+
153//! @endcode
154static const ChannelMask ChanMask_Surround_Mono = //
155 (1 << ChanPos_FrontCenter);
156
157//! Stereo.
158//! Mask: FL, FR.
159//! @code
160//! +------------------+
161//! | FL FR |
162//! | user |
163//! +------------------+
164//! @endcode
165static const ChannelMask ChanMask_Surround_Stereo =
167
168//! Stereo + subwoofer.
169//! Mask: FL, FR | LFE.
170//! +------------------+
171//! | FL FR |
172//! | user |
173//! | LFE |
174//! +------------------+
175//! @endcode
176static const ChannelMask ChanMask_Surround_2_1 = //
177 ChanMask_Surround_Stereo //
178 | (1 << ChanPos_LowFrequency);
179
180//! Three front channels.
181//! Mask: FL, FC, FR.
182//! @code
183//! +------------------+
184//! | FL FC FR |
185//! | user |
186//! +------------------+
187//! @endcode
188static const ChannelMask ChanMask_Surround_3_0 =
190
191//! Three front channels + subwoofer.
192//! Mask: FL, FC, FR | LFE.
193//! @code
194//! +------------------+
195//! | FL FC FR |
196//! | user |
197//! | LFE |
198//! +------------------+
199//! @endcode
200static const ChannelMask ChanMask_Surround_3_1 = //
201 ChanMask_Surround_3_0 //
202 | (1 << ChanPos_LowFrequency);
203
204//! Surround 4.0.
205//! Mask: FL, FR, BL, BR.
206//! @code
207//! +------------------+
208//! | FL FR |
209//! | user |
210//! | BL BR |
211//! +------------------+
212//! @endcode
213static const ChannelMask ChanMask_Surround_4_0 = //
214 (1 << ChanPos_FrontLeft) | (1 << ChanPos_FrontRight) //
215 | (1 << ChanPos_BackLeft) | (1 << ChanPos_BackRight);
216
217//! Surround 4.1.
218//! Mask: FL, FR, BL, BR | LFE.
219//! @code
220//! +------------------+
221//! | FL FR |
222//! | user |
223//! | LFE |
224//! | BL BR |
225//! +------------------+
226//! @endcode
227static const ChannelMask ChanMask_Surround_4_1 = //
228 ChanMask_Surround_4_0 //
229 | (1 << ChanPos_LowFrequency);
230
231//! Surround 5.0.
232//! Mask: FL, FC, FR, BL, BR.
233//! @code
234//! +------------------+
235//! | FL FC FR |
236//! | user |
237//! | BL BR |
238//! +------------------+
239//! @endcode
240static const ChannelMask ChanMask_Surround_5_0 = //
242 | (1 << ChanPos_BackLeft) | (1 << ChanPos_BackRight);
243
244//! Surround 5.1.
245//! Mask: FL, FC, FR, BL, BR | LFE.
246//! @code
247//! +------------------+
248//! | FL FC FR |
249//! | user |
250//! | LFE |
251//! | BL BR |
252//! +------------------+
253//! @endcode
254static const ChannelMask ChanMask_Surround_5_1 = //
255 ChanMask_Surround_5_0 //
256 | (1 << ChanPos_LowFrequency);
257
258//! Surround 5.1.2.
259//! Mask: FL, FC, FR, BL, BR | LFE | TML, TMR.
260//! @code
261//! +------------------+
262//! | FL FC FR |
263//! | |
264//! | TML user TMR |
265//! | LFE |
266//! | BL BR |
267//! +------------------+
268//! @endcode
269static const ChannelMask ChanMask_Surround_5_1_2 = //
270 ChanMask_Surround_5_0 //
271 | (1 << ChanPos_LowFrequency) //
272 | (1 << ChanPos_TopMidLeft) | (1 << ChanPos_TopMidRight);
273
274//! Surround 5.1.4.
275//! Mask: FL, FC, FR, BL, BR | LFE | TFL, TFR, TBL, TBR.
276//! @code
277//! +------------------+
278//! | FL FC FR |
279//! | TFL TFR |
280//! | user |
281//! | LFE |
282//! | TBL TBR |
283//! | BL BR |
284//! +------------------+
285//! @endcode
286static const ChannelMask ChanMask_Surround_5_1_4 = //
287 ChanMask_Surround_5_0 //
288 | (1 << ChanPos_LowFrequency) //
291
292//! Surround 6.0.
293//! Mask: FL, FC, FR, BL, BC, BR.
294//! @code
295//! +------------------+
296//! | FL FC FR |
297//! | user |
298//! | BL BC BR |
299//! +------------------+
300//! @endcode
301static const ChannelMask ChanMask_Surround_6_0 = //
303 | (1 << ChanPos_BackLeft) | (1 << ChanPos_BackCenter) | (1 << ChanPos_BackRight);
304
305//! Surround 6.1.
306//! Mask: FL, FC, FR, BL, BC, BR | LFE.
307//! @code
308//! +------------------+
309//! | FL FC FR |
310//! | user |
311//! | LFE |
312//! | BL BC BR |
313//! +------------------+
314//! @endcode
315static const ChannelMask ChanMask_Surround_6_1 = //
316 ChanMask_Surround_6_0 //
317 | (1 << ChanPos_LowFrequency);
318
319//! Surround 7.0.
320//! Mask: FL, FC, FR, SL, SR, BL, BR.
321//! @code
322//! +------------------+
323//! | FL FC FR |
324//! | SL user SR |
325//! | BL BR |
326//! +------------------+
327//! @endcode
328static const ChannelMask ChanMask_Surround_7_0 = //
330 | (1 << ChanPos_SideLeft) | (1 << ChanPos_SideRight) //
331 | (1 << ChanPos_BackLeft) | (1 << ChanPos_BackRight);
332
333//! Surround 7.1.
334//! Mask: FL, FC, FR, SL, SR, BL, BR | LFE.
335//! @code
336//! +------------------+
337//! | FL FC FR |
338//! | SL user SR |
339//! | LFE |
340//! | BL BR |
341//! +------------------+
342//! @endcode
343static const ChannelMask ChanMask_Surround_7_1 = //
344 ChanMask_Surround_7_0 //
345 | (1 << ChanPos_LowFrequency);
346
347//! Surround 7.1.2.
348//! Mask: FL, FC, FR, SL, SR, BL, BR | LFE | TML, TMR.
349//! @code
350//! +------------------+
351//! | FL FC FR |
352//! | |
353//! | TML TMR |
354//! | SL user SR |
355//! | LFE |
356//! | BL BR |
357//! +------------------+
358//! @endcode
359static const ChannelMask ChanMask_Surround_7_1_2 = //
360 ChanMask_Surround_7_0 //
361 | (1 << ChanPos_LowFrequency) //
362 | (1 << ChanPos_TopMidLeft) | (1 << ChanPos_TopMidRight);
363
364//! Surround 7.1.4.
365//! Mask: FL, FC, FR, SL, SR, BL, BR | LFE | TFL, TFR, TBL, TBR.
366//! @code
367//! +------------------+
368//! | FL FC FR |
369//! | TFL TFR |
370//! | SL user SR |
371//! | LFE |
372//! | TBL TBR |
373//! | BL BR |
374//! +------------------+
375//! @endcode
376static const ChannelMask ChanMask_Surround_7_1_4 = //
377 ChanMask_Surround_7_0 //
378 | (1 << ChanPos_LowFrequency) //
381
382//! Get string name of channel layout.
384
385//! Get string name of channel order.
387
388//! Get string name of channel position.
390
391} // namespace audio
392} // namespace roc
393
394#endif // ROC_AUDIO_CHANNEL_DEFS_H_
const char * channel_position_to_str(ChannelPosition)
Get string name of channel position.
ChannelPosition
Surround channel position.
Definition: channel_defs.h:86
@ ChanPos_SideLeft
Side left (SL).
Definition: channel_defs.h:101
@ ChanPos_Max
Maximum value of enum.
Definition: channel_defs.h:137
@ ChanPos_TopBackLeft
Top rear left (TBL).
Definition: channel_defs.h:126
@ ChanPos_FrontCenter
Front center (FC).
Definition: channel_defs.h:92
@ ChanPos_FrontLeft
Front left (FL).
Definition: channel_defs.h:91
@ ChanPos_LowFrequency
Low frequency speaker (LFE).
Definition: channel_defs.h:134
@ ChanPos_TopFrontLeft
Top front left (TFL).
Definition: channel_defs.h:120
@ ChanPos_FrontRight
Front right (FR).
Definition: channel_defs.h:93
@ ChanPos_BackRight
Back right (BR).
Definition: channel_defs.h:112
@ ChanPos_TopBackRight
Top rear right (TBR).
Definition: channel_defs.h:127
@ ChanPos_SideRight
Side right (SR).
Definition: channel_defs.h:102
@ ChanPos_BackLeft
Back left (BL).
Definition: channel_defs.h:110
@ ChanPos_TopMidRight
Top middle right (TMR).
Definition: channel_defs.h:124
@ ChanPos_BackCenter
Back center (BC).
Definition: channel_defs.h:111
@ ChanPos_TopMidLeft
Top middle left (TML).
Definition: channel_defs.h:123
@ ChanPos_TopFrontRight
Top front right (TFR).
Definition: channel_defs.h:121
ChannelLayout
Channel layout. Defines meaning of channels in ChannelSet. ChannelMapper uses channel layout to decid...
Definition: channel_defs.h:23
@ ChanLayout_Multitrack
Multi-channel multi-track sound.
Definition: channel_defs.h:42
@ ChanLayout_None
Channel layout is not set.
Definition: channel_defs.h:27
@ ChanLayout_Surround
Multi-channel mono / stereo / surround sound.
Definition: channel_defs.h:35
const char * channel_layout_to_str(ChannelLayout)
Get string name of channel layout.
uint32_t ChannelMask
Channel mask.
Definition: channel_defs.h:144
const char * channel_order_to_str(ChannelOrder)
Get string name of channel order.
ChannelOrder
Surround channel order.
Definition: channel_defs.h:49
@ ChanOrder_Max
Maximum value of enum.
Definition: channel_defs.h:76
@ ChanOrder_None
Channel order is not set.
Definition: channel_defs.h:55
@ ChanOrder_Smpte
ITU/SMPTE channel order. Order: FL, FR, FC, LFE, BL, BR, BC, SL, SR, TFL, TFR, TBL,...
Definition: channel_defs.h:66
@ ChanOrder_Alsa
ALSA channel order. Order: FL, FR, BL, BR, FC, LFE, SL, SR, BC.
Definition: channel_defs.h:73
Root namespace.
Commonly used types and functions.