1/*
2 * Codec parameters public API
3 *
4 * This file is part of FFmpeg.
5 *
6 * FFmpeg is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * FFmpeg is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with FFmpeg; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19 */
20
21#ifndef AVCODEC_CODEC_PAR_H
22#define AVCODEC_CODEC_PAR_H
23
24#include <stdint.h>
25
26#include "libavutil/avutil.h"
27#include "libavutil/channel_layout.h"
28#include "libavutil/rational.h"
29#include "libavutil/pixfmt.h"
30
31#include "codec_id.h"
32#include "defs.h"
33#include "packet.h"
34
35/**
36 * @defgroup lavc_codec_params Codec parameters
37 * @ingroup lavc_core
38 * @{
39 */
40
41/**
42 * This struct describes the properties of an encoded stream.
43 *
44 * @note
45 * The `sizeof(AVCodecParameters)` is not a part of the public ABI,
46 * therefore this struct must be allocated with ::avcodec_parameters_alloc()
47 * and freed with ::avcodec_parameters_free().
48 */
49typedef struct AVCodecParameters {
50 /**
51 * General type of the encoded data.
52 */
53 enum AVMediaType codec_type;
54 /**
55 * Specific type of the encoded data (the codec used).
56 */
57 enum AVCodecID codec_id;
58 /**
59 * Additional information about the codec (corresponds to the AVI FOURCC).
60 */
61 uint32_t codec_tag;
62
63 /**
64 * Extra binary data needed for initializing the decoder, codec-dependent.
65 *
66 * Must be allocated with ::av_malloc() and will be freed by
67 * ::avcodec_parameters_free(). The allocated size of extradata must be at
68 * least #extradata_size + ::AV_INPUT_BUFFER_PADDING_SIZE, with the padding
69 * bytes zeroed.
70 */
71 uint8_t *extradata;
72 /**
73 * Size of the extradata content in bytes.
74 */
75 int extradata_size;
76
77 /**
78 * Additional data associated with the entire stream.
79 *
80 * Should be allocated with ::av_packet_side_data_new() or
81 * ::av_packet_side_data_add(), and will be freed by ::avcodec_parameters_free().
82 */
83 AVPacketSideData *coded_side_data;
84
85 /**
86 * Amount of entries in #coded_side_data.
87 */
88 int nb_coded_side_data;
89
90 /**
91 * - Video: the pixel format, the value corresponds to enum ::AVPixelFormat.
92 * - Audio: the sample format, the value corresponds to enum ::AVSampleFormat.
93 */
94 int format;
95
96 /**
97 * The average bitrate of the encoded data (in bits per second).
98 */
99 int64_t bit_rate;
100
101 /**
102 * The number of bits per sample in the codedwords.
103 *
104 * This is basically the bitrate per sample. It is mandatory for a bunch of
105 * formats to actually decode them. It's the number of bits for one sample in
106 * the actual coded bitstream.
107 *
108 * This could be, for example, 4, for ADPCM.
109 * For PCM formats this matches #bits_per_raw_sample.
110 *
111 * Can be 0.
112 */
113 int bits_per_coded_sample;
114
115 /**
116 * The number of valid bits in each output sample.
117 *
118 * If the sample format has more bits, the least significant bits are additional
119 * padding bits, which are always 0. Use right shifts to reduce the sample
120 * to its actual size.
121 *
122 * For example, audio formats with 24-bit samples will have #bits_per_raw_sample
123 * set to 24, and ::format set to ::AV_SAMPLE_FMT_S32. To get the original sample,
124 * use: `(int32_t)sample >> 8`.
125 *
126 * For ADPCM, this might be 12 or 16, or similar.
127 *
128 * Can be 0.
129 */
130 int bits_per_raw_sample;
131
132 /**
133 * Codec-specific bitstream restrictions that the stream conforms to.
134 */
135 int profile;
136 int level;
137
138 /**
139 * The width of the video frame in pixels.
140 *
141 * Video only.
142 */
143 int width;
144
145 /**
146 * The height of the video frame in pixels.
147 *
148 * Video only.
149 */
150 int height;
151
152 /**
153 * The aspect ratio (width/height) which a single pixel
154 * should have when displayed.
155 *
156 * When the aspect ratio is unknown or undefined, the numerator should be
157 * set to 0 (the denominator may have any value).
158 *
159 * Video only.
160 */
161 AVRational sample_aspect_ratio;
162
163 /**
164 * Number of frames per second, for streams with constant frame
165 * durations. Should be set to `{ 0, 1 }` when some frames have differing
166 * durations or if the value is not known.
167 *
168 * @note This field corresponds to values that are stored in codec-level
169 * headers and is typically overridden by container/transport-layer
170 * timestamps, when available. It should thus be used only as a last resort,
171 * when no higher-level timing information is available.
172 *
173 * Video only.
174 */
175 AVRational framerate;
176
177 /**
178 * The order of the fields in interlaced video.
179 *
180 * Video only.
181 */
182 enum AVFieldOrder field_order;
183
184 /**
185 * Additional colorspace characteristics.
186 *
187 * Video only.
188 */
189 enum AVColorRange color_range;
190 enum AVColorPrimaries color_primaries;
191 enum AVColorTransferCharacteristic color_trc;
192 enum AVColorSpace color_space;
193 enum AVChromaLocation chroma_location;
194
195 /**
196 * Number of delayed frames.
197 *
198 * Video only.
199 */
200 int video_delay;
201
202 /**
203 * The channel layout and number of channels.
204 *
205 * Audio only.
206 */
207 AVChannelLayout ch_layout;
208 /**
209 * The number of audio samples per second.
210 *
211 * Audio only.
212 */
213 int sample_rate;
214 /**
215 * The number of bytes per coded audio frame, required by some formats.
216 *
217 * Audio only.
218 *
219 * Corresponds to nBlockAlign in WAVEFORMATEX.
220 */
221 int block_align;
222 /**
223 * Audio frame size, if known. Required by some formats to be static.
224 *
225 * Audio only.
226 */
227 int frame_size;
228
229 /**
230 * Number of padding audio samples at the start.
231 *
232 * The amount of padding (in samples) inserted by the encoder at
233 * the beginning of the audio. I.e. this number of leading decoded samples
234 * must be discarded to get the original audio without leading
235 * padding.
236 *
237 * Audio only.
238 */
239 int initial_padding;
240 /**
241 * Number of padding audio samples at the end.
242 *
243 * The amount of padding (in samples) appended by the encoder to
244 * the end of the audio. I.e. this number of decoded samples must be
245 * discarded from the end of the stream to get the original
246 * audio without any trailing padding.
247 *
248 * Audio only.
249 */
250 int trailing_padding;
251 /**
252 * Number of audio samples to skip after a discontinuity.
253 *
254 * Audio only.
255 */
256 int seek_preroll;
257
258 /**
259 * Video with alpha channel only. Alpha channel handling
260 */
261 enum AVAlphaMode alpha_mode;
262} AVCodecParameters;
263
264/**
265 * @relates AVCodecParameters
266 * @{
267 */
268
269/**
270 * Allocate a new AVCodecParameters and set its fields to default values
271 * (unknown/invalid/0). The returned struct must be freed with
272 * ::avcodec_parameters_free().
273 */
274AVCodecParameters *avcodec_parameters_alloc(void);
275
276/**
277 * Free an AVCodecParameters instance and everything associated with it and
278 * write `NULL` to the supplied pointer.
279 */
280void avcodec_parameters_free(AVCodecParameters **par);
281
282/**
283 * Copy the contents of \p src to \p dst. Any allocated fields in dst are freed and
284 * replaced with newly allocated duplicates of the corresponding fields in src.
285 *
286 * @return >= 0 on success, a negative AVERROR code on failure.
287 */
288int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
289
290/**
291 * This function is the same as ::av_get_audio_frame_duration(), except it works
292 * with ::AVCodecParameters instead of an ::AVCodecContext.
293 */
294int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes);
295
296/** @} */
297
298/**
299 * @}
300 */
301
302#endif // AVCODEC_CODEC_PAR_H
303