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 #define AV_CH_TOP_SIDE_LEFT 0x0000001000000000ULL
75 #define AV_CH_TOP_SIDE_RIGHT 0x0000002000000000ULL
76 #define AV_CH_BOTTOM_FRONT_CENTER 0x0000004000000000ULL
77 #define AV_CH_BOTTOM_FRONT_LEFT 0x0000008000000000ULL
78 #define AV_CH_BOTTOM_FRONT_RIGHT 0x0000010000000000ULL
79 
80 /** Channel mask value used for AVCodecContext.request_channel_layout
81  to indicate that the user requests the channel order of the decoder output
82  to be the native codec channel order. */
83 #define AV_CH_LAYOUT_NATIVE 0x8000000000000000ULL
84 
85 /**
86  * @}
87  * @defgroup channel_mask_c Audio channel layouts
88  * @{
89  * */
90 #define AV_CH_LAYOUT_MONO (AV_CH_FRONT_CENTER)
91 #define AV_CH_LAYOUT_STEREO (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT)
92 #define AV_CH_LAYOUT_2POINT1 (AV_CH_LAYOUT_STEREO|AV_CH_LOW_FREQUENCY)
93 #define AV_CH_LAYOUT_2_1 (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER)
94 #define AV_CH_LAYOUT_SURROUND (AV_CH_LAYOUT_STEREO|AV_CH_FRONT_CENTER)
95 #define AV_CH_LAYOUT_3POINT1 (AV_CH_LAYOUT_SURROUND|AV_CH_LOW_FREQUENCY)
96 #define AV_CH_LAYOUT_4POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_CENTER)
97 #define AV_CH_LAYOUT_4POINT1 (AV_CH_LAYOUT_4POINT0|AV_CH_LOW_FREQUENCY)
98 #define AV_CH_LAYOUT_2_2 (AV_CH_LAYOUT_STEREO|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
99 #define AV_CH_LAYOUT_QUAD (AV_CH_LAYOUT_STEREO|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
100 #define AV_CH_LAYOUT_5POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
101 #define AV_CH_LAYOUT_5POINT1 (AV_CH_LAYOUT_5POINT0|AV_CH_LOW_FREQUENCY)
102 #define AV_CH_LAYOUT_5POINT0_BACK (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
103 #define AV_CH_LAYOUT_5POINT1_BACK (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_LOW_FREQUENCY)
104 #define AV_CH_LAYOUT_6POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_CENTER)
105 #define AV_CH_LAYOUT_6POINT0_FRONT (AV_CH_LAYOUT_2_2|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
106 #define AV_CH_LAYOUT_HEXAGONAL (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_BACK_CENTER)
107 #define AV_CH_LAYOUT_6POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_CENTER)
108 #define AV_CH_LAYOUT_6POINT1_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_BACK_CENTER)
109 #define AV_CH_LAYOUT_6POINT1_FRONT (AV_CH_LAYOUT_6POINT0_FRONT|AV_CH_LOW_FREQUENCY)
110 #define AV_CH_LAYOUT_7POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
111 #define AV_CH_LAYOUT_7POINT0_FRONT (AV_CH_LAYOUT_5POINT0|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
112 #define AV_CH_LAYOUT_7POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
113 #define AV_CH_LAYOUT_7POINT1_WIDE (AV_CH_LAYOUT_5POINT1|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
114 #define AV_CH_LAYOUT_7POINT1_WIDE_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
115 #define AV_CH_LAYOUT_OCTAGONAL (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_CENTER|AV_CH_BACK_RIGHT)
116 #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)
117 #define AV_CH_LAYOUT_STEREO_DOWNMIX (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT)
118 #define AV_CH_LAYOUT_22POINT2 (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER|AV_CH_BACK_CENTER|AV_CH_LOW_FREQUENCY_2|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_CENTER|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT|AV_CH_TOP_SIDE_LEFT|AV_CH_TOP_SIDE_RIGHT|AV_CH_TOP_BACK_CENTER|AV_CH_BOTTOM_FRONT_CENTER|AV_CH_BOTTOM_FRONT_LEFT|AV_CH_BOTTOM_FRONT_RIGHT)
119 
120 enum AVMatrixEncoding {
121  AV_MATRIX_ENCODING_NONE,
122  AV_MATRIX_ENCODING_DOLBY,
123  AV_MATRIX_ENCODING_DPLII,
124  AV_MATRIX_ENCODING_DPLIIX,
125  AV_MATRIX_ENCODING_DPLIIZ,
126  AV_MATRIX_ENCODING_DOLBYEX,
127  AV_MATRIX_ENCODING_DOLBYHEADPHONE,
128  AV_MATRIX_ENCODING_NB
129 };
130 
131 /**
132  * Return a channel layout id that matches name, or 0 if no match is found.
133  *
134  * name can be one or several of the following notations,
135  * separated by '+' or '|':
136  * - the name of an usual channel layout (mono, stereo, 4.0, quad, 5.0,
137  * 5.0(side), 5.1, 5.1(side), 7.1, 7.1(wide), downmix);
138  * - the name of a single channel (FL, FR, FC, LFE, BL, BR, FLC, FRC, BC,
139  * SL, SR, TC, TFL, TFC, TFR, TBL, TBC, TBR, DL, DR);
140  * - a number of channels, in decimal, followed by 'c', yielding
141  * the default channel layout for that number of channels (@see
142  * av_get_default_channel_layout);
143  * - a channel layout mask, in hexadecimal starting with "0x" (see the
144  * AV_CH_* macros).
145  *
146  * Example: "stereo+FC" = "2c+FC" = "2c+1c" = "0x7"
147  */
148 uint64_t av_get_channel_layout(const char *name);
149 
150 /**
151  * Return a channel layout and the number of channels based on the specified name.
152  *
153  * This function is similar to (@see av_get_channel_layout), but can also parse
154  * unknown channel layout specifications.
155  *
156  * @param[in] name channel layout specification string
157  * @param[out] channel_layout parsed channel layout (0 if unknown)
158  * @param[out] nb_channels number of channels
159  *
160  * @return 0 on success, AVERROR(EINVAL) if the parsing fails.
161  */
162 int av_get_extended_channel_layout(const char *name, uint64_t* channel_layout, int* nb_channels);
163 
164 /**
165  * Return a description of a channel layout.
166  * If nb_channels is <= 0, it is guessed from the channel_layout.
167  *
168  * @param buf put here the string containing the channel layout
169  * @param buf_size size in bytes of the buffer
170  */
171 void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, uint64_t channel_layout);
172 
173 struct AVBPrint;
174 /**
175  * Append a description of a channel layout to a bprint buffer.
176  */
177 void av_bprint_channel_layout(struct AVBPrint *bp, int nb_channels, uint64_t channel_layout);
178 
179 /**
180  * Return the number of channels in the channel layout.
181  */
182 int av_get_channel_layout_nb_channels(uint64_t channel_layout);
183 
184 /**
185  * Return default channel layout for a given number of channels.
186  */
187 int64_t av_get_default_channel_layout(int nb_channels);
188 
189 /**
190  * Get the index of a channel in channel_layout.
191  *
192  * @param channel a channel layout describing exactly one channel which must be
193  * present in channel_layout.
194  *
195  * @return index of channel in channel_layout on success, a negative AVERROR
196  * on error.
197  */
198 int av_get_channel_layout_channel_index(uint64_t channel_layout,
199  uint64_t channel);
200 
201 /**
202  * Get the channel with the given index in channel_layout.
203  */
204 uint64_t av_channel_layout_extract_channel(uint64_t channel_layout, int index);
205 
206 /**
207  * Get the name of a given channel.
208  *
209  * @return channel name on success, NULL on error.
210  */
211 const char *av_get_channel_name(uint64_t channel);
212 
213 /**
214  * Get the description of a given channel.
215  *
216  * @param channel a channel layout with a single channel
217  * @return channel description on success, NULL on error
218  */
219 const char *av_get_channel_description(uint64_t channel);
220 
221 /**
222  * Get the value and name of a standard channel layout.
223  *
224  * @param[in] index index in an internal list, starting at 0
225  * @param[out] layout channel layout mask
226  * @param[out] name name of the layout
227  * @return 0 if the layout exists,
228  * <0 if index is beyond the limits
229  */
230 int av_get_standard_channel_layout(unsigned index, uint64_t *layout,
231  const char **name);
232 
233 /**
234  * @}
235  * @}
236  */
237 
238 #endif /* AVUTIL_CHANNEL_LAYOUT_H */
name
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf default minimum maximum flags name is the option name
Definition: writing_filters.txt:88
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:217
index
fg index
Definition: ffmpeg_filter.c:167
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:145
AV_MATRIX_ENCODING_DOLBY
@ AV_MATRIX_ENCODING_DOLBY
Definition: channel_layout.h:122
AV_MATRIX_ENCODING_NB
@ AV_MATRIX_ENCODING_NB
Definition: channel_layout.h:128
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:183
av_get_channel_name
const char * av_get_channel_name(uint64_t channel)
Get the name of a given channel.
Definition: channel_layout.c:249
AV_MATRIX_ENCODING_DPLIIX
@ AV_MATRIX_ENCODING_DPLIIX
Definition: channel_layout.h:124
AVMatrixEncoding
AVMatrixEncoding
Definition: channel_layout.h:120
AV_MATRIX_ENCODING_DOLBYHEADPHONE
@ AV_MATRIX_ENCODING_DOLBYHEADPHONE
Definition: channel_layout.h:127
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:285
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:226
AV_MATRIX_ENCODING_NONE
@ AV_MATRIX_ENCODING_NONE
Definition: channel_layout.h:121
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:271
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:239
av_get_channel_description
const char * av_get_channel_description(uint64_t channel)
Get the description of a given channel.
Definition: channel_layout.c:260
AV_MATRIX_ENCODING_DOLBYEX
@ AV_MATRIX_ENCODING_DOLBYEX
Definition: channel_layout.h:126
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:161
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:231
AV_MATRIX_ENCODING_DPLIIZ
@ AV_MATRIX_ENCODING_DPLIIZ
Definition: channel_layout.h:125
channel
channel
Definition: ebur128.h:39
AV_MATRIX_ENCODING_DPLII
@ AV_MATRIX_ENCODING_DPLII
Definition: channel_layout.h:123
nb_channels
int nb_channels
Definition: channel_layout.c:81
Generated on Wed Aug 24 2022 21:38:29 for FFmpeg by   doxygen 1.8.17