FFmpeg
channel_layout.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
3  * Copyright (c) 2008 Peter Ross
4  *
5  * This file is part of FFmpeg.
6  *
7  * FFmpeg is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2.1 of the License, or (at your option) any later version.
11  *
12  * FFmpeg is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with FFmpeg; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20  */
21 
22 #ifndef AVUTIL_CHANNEL_LAYOUT_H
23 #define AVUTIL_CHANNEL_LAYOUT_H
24 
25 #include <stdint.h>
26 
27 /**
28  * @file
29  * audio channel layout utility functions
30  */
31 
32 /**
33  * @addtogroup lavu_audio
34  * @{
35  */
36 
37 /**
38  * @defgroup channel_masks Audio channel masks
39  *
40  * A channel layout is a 64-bits integer with a bit set for every channel.
41  * The number of bits set must be equal to the number of channels.
42  * The value 0 means that the channel layout is not known.
43  * @note this data structure is not powerful enough to handle channels
44  * combinations that have the same channel multiple times, such as
45  * dual-mono.
46  *
47  * @{
48  */
49 #define AV_CH_FRONT_LEFT 0x00000001
50 #define AV_CH_FRONT_RIGHT 0x00000002
51 #define AV_CH_FRONT_CENTER 0x00000004
52 #define AV_CH_LOW_FREQUENCY 0x00000008
53 #define AV_CH_BACK_LEFT 0x00000010
54 #define AV_CH_BACK_RIGHT 0x00000020
55 #define AV_CH_FRONT_LEFT_OF_CENTER 0x00000040
56 #define AV_CH_FRONT_RIGHT_OF_CENTER 0x00000080
57 #define AV_CH_BACK_CENTER 0x00000100
58 #define AV_CH_SIDE_LEFT 0x00000200
59 #define AV_CH_SIDE_RIGHT 0x00000400
60 #define AV_CH_TOP_CENTER 0x00000800
61 #define AV_CH_TOP_FRONT_LEFT 0x00001000
62 #define AV_CH_TOP_FRONT_CENTER 0x00002000
63 #define AV_CH_TOP_FRONT_RIGHT 0x00004000
64 #define AV_CH_TOP_BACK_LEFT 0x00008000
65 #define AV_CH_TOP_BACK_CENTER 0x00010000
66 #define AV_CH_TOP_BACK_RIGHT 0x00020000
67 #define AV_CH_STEREO_LEFT 0x20000000 ///< Stereo downmix.
68 #define AV_CH_STEREO_RIGHT 0x40000000 ///< See AV_CH_STEREO_LEFT.
69 #define AV_CH_WIDE_LEFT 0x0000000080000000ULL
70 #define AV_CH_WIDE_RIGHT 0x0000000100000000ULL
71 #define AV_CH_SURROUND_DIRECT_LEFT 0x0000000200000000ULL
72 #define AV_CH_SURROUND_DIRECT_RIGHT 0x0000000400000000ULL
73 #define AV_CH_LOW_FREQUENCY_2 0x0000000800000000ULL
74 
75 /** Channel mask value used for AVCodecContext.request_channel_layout
76  to indicate that the user requests the channel order of the decoder output
77  to be the native codec channel order. */
78 #define AV_CH_LAYOUT_NATIVE 0x8000000000000000ULL
79 
80 /**
81  * @}
82  * @defgroup channel_mask_c Audio channel layouts
83  * @{
84  * */
85 #define AV_CH_LAYOUT_MONO (AV_CH_FRONT_CENTER)
86 #define AV_CH_LAYOUT_STEREO (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT)
87 #define AV_CH_LAYOUT_2POINT1 (AV_CH_LAYOUT_STEREO|AV_CH_LOW_FREQUENCY)
88 #define AV_CH_LAYOUT_2_1 (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER)
89 #define AV_CH_LAYOUT_SURROUND (AV_CH_LAYOUT_STEREO|AV_CH_FRONT_CENTER)
90 #define AV_CH_LAYOUT_3POINT1 (AV_CH_LAYOUT_SURROUND|AV_CH_LOW_FREQUENCY)
91 #define AV_CH_LAYOUT_4POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_CENTER)
92 #define AV_CH_LAYOUT_4POINT1 (AV_CH_LAYOUT_4POINT0|AV_CH_LOW_FREQUENCY)
93 #define AV_CH_LAYOUT_2_2 (AV_CH_LAYOUT_STEREO|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
94 #define AV_CH_LAYOUT_QUAD (AV_CH_LAYOUT_STEREO|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
95 #define AV_CH_LAYOUT_5POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
96 #define AV_CH_LAYOUT_5POINT1 (AV_CH_LAYOUT_5POINT0|AV_CH_LOW_FREQUENCY)
97 #define AV_CH_LAYOUT_5POINT0_BACK (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
98 #define AV_CH_LAYOUT_5POINT1_BACK (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_LOW_FREQUENCY)
99 #define AV_CH_LAYOUT_6POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_CENTER)
100 #define AV_CH_LAYOUT_6POINT0_FRONT (AV_CH_LAYOUT_2_2|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
101 #define AV_CH_LAYOUT_HEXAGONAL (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_BACK_CENTER)
102 #define AV_CH_LAYOUT_6POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_CENTER)
103 #define AV_CH_LAYOUT_6POINT1_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_BACK_CENTER)
104 #define AV_CH_LAYOUT_6POINT1_FRONT (AV_CH_LAYOUT_6POINT0_FRONT|AV_CH_LOW_FREQUENCY)
105 #define AV_CH_LAYOUT_7POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
106 #define AV_CH_LAYOUT_7POINT0_FRONT (AV_CH_LAYOUT_5POINT0|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
107 #define AV_CH_LAYOUT_7POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
108 #define AV_CH_LAYOUT_7POINT1_WIDE (AV_CH_LAYOUT_5POINT1|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
109 #define AV_CH_LAYOUT_7POINT1_WIDE_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
110 #define AV_CH_LAYOUT_OCTAGONAL (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_CENTER|AV_CH_BACK_RIGHT)
111 #define AV_CH_LAYOUT_HEXADECAGONAL (AV_CH_LAYOUT_OCTAGONAL|AV_CH_WIDE_LEFT|AV_CH_WIDE_RIGHT|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT|AV_CH_TOP_BACK_CENTER|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
112 #define AV_CH_LAYOUT_STEREO_DOWNMIX (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT)
113 
114 enum AVMatrixEncoding {
115  AV_MATRIX_ENCODING_NONE,
116  AV_MATRIX_ENCODING_DOLBY,
117  AV_MATRIX_ENCODING_DPLII,
118  AV_MATRIX_ENCODING_DPLIIX,
119  AV_MATRIX_ENCODING_DPLIIZ,
120  AV_MATRIX_ENCODING_DOLBYEX,
121  AV_MATRIX_ENCODING_DOLBYHEADPHONE,
122  AV_MATRIX_ENCODING_NB
123 };
124 
125 /**
126  * Return a channel layout id that matches name, or 0 if no match is found.
127  *
128  * name can be one or several of the following notations,
129  * separated by '+' or '|':
130  * - the name of an usual channel layout (mono, stereo, 4.0, quad, 5.0,
131  * 5.0(side), 5.1, 5.1(side), 7.1, 7.1(wide), downmix);
132  * - the name of a single channel (FL, FR, FC, LFE, BL, BR, FLC, FRC, BC,
133  * SL, SR, TC, TFL, TFC, TFR, TBL, TBC, TBR, DL, DR);
134  * - a number of channels, in decimal, followed by 'c', yielding
135  * the default channel layout for that number of channels (@see
136  * av_get_default_channel_layout);
137  * - a channel layout mask, in hexadecimal starting with "0x" (see the
138  * AV_CH_* macros).
139  *
140  * Example: "stereo+FC" = "2c+FC" = "2c+1c" = "0x7"
141  */
142 uint64_t av_get_channel_layout(const char *name);
143 
144 /**
145  * Return a channel layout and the number of channels based on the specified name.
146  *
147  * This function is similar to (@see av_get_channel_layout), but can also parse
148  * unknown channel layout specifications.
149  *
150  * @param[in] name channel layout specification string
151  * @param[out] channel_layout parsed channel layout (0 if unknown)
152  * @param[out] nb_channels number of channels
153  *
154  * @return 0 on success, AVERROR(EINVAL) if the parsing fails.
155  */
156 int av_get_extended_channel_layout(const char *name, uint64_t* channel_layout, int* nb_channels);
157 
158 /**
159  * Return a description of a channel layout.
160  * If nb_channels is <= 0, it is guessed from the channel_layout.
161  *
162  * @param buf put here the string containing the channel layout
163  * @param buf_size size in bytes of the buffer
164  */
165 void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, uint64_t channel_layout);
166 
167 struct AVBPrint;
168 /**
169  * Append a description of a channel layout to a bprint buffer.
170  */
171 void av_bprint_channel_layout(struct AVBPrint *bp, int nb_channels, uint64_t channel_layout);
172 
173 /**
174  * Return the number of channels in the channel layout.
175  */
176 int av_get_channel_layout_nb_channels(uint64_t channel_layout);
177 
178 /**
179  * Return default channel layout for a given number of channels.
180  */
181 int64_t av_get_default_channel_layout(int nb_channels);
182 
183 /**
184  * Get the index of a channel in channel_layout.
185  *
186  * @param channel a channel layout describing exactly one channel which must be
187  * present in channel_layout.
188  *
189  * @return index of channel in channel_layout on success, a negative AVERROR
190  * on error.
191  */
192 int av_get_channel_layout_channel_index(uint64_t channel_layout,
193  uint64_t channel);
194 
195 /**
196  * Get the channel with the given index in channel_layout.
197  */
198 uint64_t av_channel_layout_extract_channel(uint64_t channel_layout, int index);
199 
200 /**
201  * Get the name of a given channel.
202  *
203  * @return channel name on success, NULL on error.
204  */
205 const char *av_get_channel_name(uint64_t channel);
206 
207 /**
208  * Get the description of a given channel.
209  *
210  * @param channel a channel layout with a single channel
211  * @return channel description on success, NULL on error
212  */
213 const char *av_get_channel_description(uint64_t channel);
214 
215 /**
216  * Get the value and name of a standard channel layout.
217  *
218  * @param[in] index index in an internal list, starting at 0
219  * @param[out] layout channel layout mask
220  * @param[out] name name of the layout
221  * @return 0 if the layout exists,
222  * <0 if index is beyond the limits
223  */
224 int av_get_standard_channel_layout(unsigned index, uint64_t *layout,
225  const char **name);
226 
227 /**
228  * @}
229  * @}
230  */
231 
232 #endif /* AVUTIL_CHANNEL_LAYOUT_H */
av_get_channel_layout_string
void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, uint64_t channel_layout)
Return a description of a channel layout.
Definition: channel_layout.c:211
name
const char * name
Definition: avisynth_c.h:867
av_get_channel_layout
uint64_t av_get_channel_layout(const char *name)
Return a channel layout id that matches name, or 0 if no match is found.
Definition: channel_layout.c:139
buf
void * buf
Definition: avisynth_c.h:766
AV_MATRIX_ENCODING_DOLBY
@ AV_MATRIX_ENCODING_DOLBY
Definition: channel_layout.h:116
AV_MATRIX_ENCODING_NB
@ AV_MATRIX_ENCODING_NB
Definition: channel_layout.h:122
av_bprint_channel_layout
void av_bprint_channel_layout(struct AVBPrint *bp, int nb_channels, uint64_t channel_layout)
Append a description of a channel layout to a bprint buffer.
Definition: channel_layout.c:177
av_get_channel_name
const char * av_get_channel_name(uint64_t channel)
Get the name of a given channel.
Definition: channel_layout.c:243
AV_MATRIX_ENCODING_DPLIIX
@ AV_MATRIX_ENCODING_DPLIIX
Definition: channel_layout.h:118
AVMatrixEncoding
AVMatrixEncoding
Definition: channel_layout.h:114
AV_MATRIX_ENCODING_DOLBYHEADPHONE
@ AV_MATRIX_ENCODING_DOLBYHEADPHONE
Definition: channel_layout.h:121
av_get_standard_channel_layout
int av_get_standard_channel_layout(unsigned index, uint64_t *layout, const char **name)
Get the value and name of a standard channel layout.
Definition: channel_layout.c:279
index
int index
Definition: gxfenc.c:89
av_get_channel_layout_nb_channels
int av_get_channel_layout_nb_channels(uint64_t channel_layout)
Return the number of channels in the channel layout.
Definition: channel_layout.c:220
AV_MATRIX_ENCODING_NONE
@ AV_MATRIX_ENCODING_NONE
Definition: channel_layout.h:115
layout
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel layout
Definition: filter_design.txt:18
av_channel_layout_extract_channel
uint64_t av_channel_layout_extract_channel(uint64_t channel_layout, int index)
Get the channel with the given index in channel_layout.
Definition: channel_layout.c:265
av_get_channel_layout_channel_index
int av_get_channel_layout_channel_index(uint64_t channel_layout, uint64_t channel)
Get the index of a channel in channel_layout.
Definition: channel_layout.c:233
av_get_channel_description
const char * av_get_channel_description(uint64_t channel)
Get the description of a given channel.
Definition: channel_layout.c:254
AV_MATRIX_ENCODING_DOLBYEX
@ AV_MATRIX_ENCODING_DOLBYEX
Definition: channel_layout.h:120
av_get_extended_channel_layout
int av_get_extended_channel_layout(const char *name, uint64_t *channel_layout, int *nb_channels)
Return a channel layout and the number of channels based on the specified name.
Definition: channel_layout.c:155
av_get_default_channel_layout
int64_t av_get_default_channel_layout(int nb_channels)
Return default channel layout for a given number of channels.
Definition: channel_layout.c:225
AV_MATRIX_ENCODING_DPLIIZ
@ AV_MATRIX_ENCODING_DPLIIZ
Definition: channel_layout.h:119
channel
channel
Definition: ebur128.h:39
AV_MATRIX_ENCODING_DPLII
@ AV_MATRIX_ENCODING_DPLII
Definition: channel_layout.h:117
nb_channels
int nb_channels
Definition: channel_layout.c:76
Generated on Wed Aug 24 2022 21:27:27 for FFmpeg by   doxygen 1.8.17