Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
Loading...
Searching...
No Matches
channel_tables.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_tables.h
10//! @brief Channel tables.
11
12#ifndef ROC_AUDIO_CHANNEL_TABLES_H_
13#define ROC_AUDIO_CHANNEL_TABLES_H_
14
16#include "roc_audio/sample.h"
17
18namespace roc {
19namespace audio {
20
21//! Defines string name for channel position.
23 //! Channel name.
24 const char* name;
25
26 //! Channel position (numeric identifier).
28};
29
30//! Defines string name for pre-defined channel mask.
32 //! Mask name.
33 const char* name;
34
35 //! Bitmask of enabled channels.
37};
38
39//! Defines multiplication coefficient for a pair of channels.
41 //! Index of output channel.
43
44 //! Index of input channel.
46
47 //! Multiplication coefficient.
48 //! @remarks
49 //! output channel is a sum of input channels multiplied
50 //! by corresponding coefficients.
52};
53
54//! Defines multiplication matrix for two channel masks.
55//!
56//! Instead of defining the whole matrix, it defines a list of pairs of
57//! output and input channel numbers and corresponding coefficients.
58//!
59//! Such representation allows more compact definition in the source
60//! code. The actual matrix is built by channel mapper at runtime.
62 //! Table name.
63 const char* name;
64
65 //! Channel mask of input stream.
67 //! Channel mask of output stream.
69
70 //! Transformation rules.
71 //! Rules are used to fill channel mapping matrix.
73};
74
75//! Defines ordered list of channels.
77 //! Order name.
78 const char* name;
79
80 //! Order identifier.
82
83 //! List of channels.
84 //! Last channel is equal to ChanPos_Max.
86};
87
88//! Defines mapping between channel position and its name.
90
91//! Defines mapping between channel mask and its name.
92extern const ChannelMaskName ChanMaskNames[17];
93
94//! Defines mapping of channel order identifier to list of channel positions
95//! in corresponding order.
96//!
97//! When channel order is applied, the list of channels is filtered, and only
98//! channels present in channel mask are kept. The resulting filtered list
99//! defines how channels are placed in memory.
100//!
101//! This allows us to define single list that for multiple channel masks.
102//! For example, ITU/SMPTE defines order for each channel mask (5.x, 7.x),
103//! but we define only one list ChanOrder_Smpte, and after filtering it
104//! becomes suitable for each of the masks.
105//!
106//! The opposite is also true: if some channel is missing from the order's
107//! list, it is considered unsupported by the order and is zeroized.
108//!
109//! Links:
110//! https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2102-0-201701-I!!PDF-E.pdf
112
113//! Defines list of mappings between all supported surround channel mask pairs.
114//!
115//! Channel mapper will search for appropriate mapping in this list,
116//! based on input and output channel masks.
117//!
118//! These tables define downmixing coefficients for mapping between different
119//! surround channel sets. They are used for both downmixing and upmixing.
120//!
121//! Mappings should be ordered from smaller to larger masks, because channel mapper
122//! will use the very first pair that covers both output and input masks.
123//!
124//! Only downmixing mappings are defined. Upmixing mappings are derived
125//! automatically from them.
126//!
127//! Technically, some of the mappings are actually partially downmixing, and
128//! partially upmixing, for example mapping from 6.x to 5.1.x downmixes some
129//! channels and upmixes others. However, for convenience, we still call it
130//! "downmixing" because we consider 6.x to be a "larger" channel set than 5.x.
131//!
132//! For groups of similar layouts, when possible, mappings are defined only for
133//! the most complete layout, and are automatically reused for the rest. For example,
134//! mappings for 5.1.2 may be automatically used for 5.1 and 5.0.
135//!
136//! These tables were originally based on the following documents
137//! (and then extended to cover more combinations):
138//! - ITU-R BS.775-1, ANNEX 4
139//! - A/52, Digital Audio Compression (AC-3) (E-AC-3) Standard, sections 6.1.12 and 7.8
140//!
141//! Useful links:
142//! https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.775-1-199407-S!!PDF-E.pdf
143//! https://prdatsc.wpenginepowered.com/wp-content/uploads/2021/04/A52-2018.pdf
144//! https://www.audiokinetic.com/en/library/edge/?source=Help&id=downmix_tables
145//! https://trac.ffmpeg.org/wiki/AudioChannelManipulation
146//! https://superuser.com/questions/852400
147extern const ChannelMapTable ChanMapTables[71];
148
149} // namespace audio
150} // namespace roc
151
152#endif // ROC_AUDIO_CHANNEL_TABLES_H_
Channel layout, order, and positions.
const ChannelMaskName ChanMaskNames[17]
Defines mapping between channel mask and its name.
ChannelPosition
Surround channel position.
@ ChanPos_Max
Maximum value of enum.
float sample_t
Raw audio sample.
Definition sample.h:22
const ChannelPositionName ChanPositionNames[ChanPos_Max]
Defines mapping between channel position and its name.
const ChannelOrderTable ChanOrderTables[ChanOrder_Max]
Defines mapping of channel order identifier to list of channel positions in corresponding order.
const ChannelMapTable ChanMapTables[71]
Defines list of mappings between all supported surround channel mask pairs.
uint32_t ChannelMask
Channel mask.
ChannelOrder
Surround channel order.
@ ChanOrder_Max
Maximum value of enum.
Root namespace.
Audio sample.
Defines multiplication coefficient for a pair of channels.
ChannelPosition in_ch
Index of input channel.
sample_t coeff
Multiplication coefficient.
ChannelPosition out_ch
Index of output channel.
Defines multiplication matrix for two channel masks.
const char * name
Table name.
ChannelMask out_mask
Channel mask of output stream.
ChannelMask in_mask
Channel mask of input stream.
ChannelMapRule rules[32]
Transformation rules. Rules are used to fill channel mapping matrix.
Defines string name for pre-defined channel mask.
ChannelMask mask
Bitmask of enabled channels.
const char * name
Mask name.
Defines ordered list of channels.
const char * name
Order name.
ChannelPosition chans[ChanPos_Max+1]
List of channels. Last channel is equal to ChanPos_Max.
ChannelOrder order
Order identifier.
Defines string name for channel position.
const char * name
Channel name.
ChannelPosition pos
Channel position (numeric identifier).