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 * @addtogroup lavc_core
37 * @{
38 */
39
40/**
41 * This struct describes the properties of an encoded stream.
42 *
43 * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must
44 * be allocated with avcodec_parameters_alloc() and freed with
45 * avcodec_parameters_free().
46 */
47typedef struct AVCodecParameters {
48 /**
49 * General type of the encoded data.
50 */
51 enum AVMediaType codec_type;
52 /**
53 * Specific type of the encoded data (the codec used).
54 */
55 enum AVCodecID codec_id;
56 /**
57 * Additional information about the codec (corresponds to the AVI FOURCC).
58 */
59 uint32_t codec_tag;
60
61 /**
62 * Extra binary data needed for initializing the decoder, codec-dependent.
63 *
64 * Must be allocated with av_malloc() and will be freed by
65 * avcodec_parameters_free(). The allocated size of extradata must be at
66 * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding
67 * bytes zeroed.
68 */
69 uint8_t *extradata;
70 /**
71 * Size of the extradata content in bytes.
72 */
73 int extradata_size;
74
75 /**
76 * Additional data associated with the entire stream.
77 *
78 * Should be allocated with av_packet_side_data_new() or
79 * av_packet_side_data_add(), and will be freed by avcodec_parameters_free().
80 */
81 AVPacketSideData *coded_side_data;
82
83 /**
84 * Amount of entries in @ref coded_side_data.
85 */
86 int nb_coded_side_data;
87
88 /**
89 * - video: the pixel format, the value corresponds to enum AVPixelFormat.
90 * - audio: the sample format, the value corresponds to enum AVSampleFormat.
91 */
92 int format;
93
94 /**
95 * The average bitrate of the encoded data (in bits per second).
96 */
97 int64_t bit_rate;
98
99 /**
100 * The number of bits per sample in the codedwords.
101 *
102 * This is basically the bitrate per sample. It is mandatory for a bunch of
103 * formats to actually decode them. It's the number of bits for one sample in
104 * the actual coded bitstream.
105 *
106 * This could be for example 4 for ADPCM
107 * For PCM formats this matches bits_per_raw_sample
108 * Can be 0
109 */
110 int bits_per_coded_sample;
111
112 /**
113 * This is the number of valid bits in each output sample. If the
114 * sample format has more bits, the least significant bits are additional
115 * padding bits, which are always 0. Use right shifts to reduce the sample
116 * to its actual size. For example, audio formats with 24 bit samples will
117 * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32.
118 * To get the original sample use "(int32_t)sample >> 8"."
119 *
120 * For ADPCM this might be 12 or 16 or similar
121 * Can be 0
122 */
123 int bits_per_raw_sample;
124
125 /**
126 * Codec-specific bitstream restrictions that the stream conforms to.
127 */
128 int profile;
129 int level;
130
131 /**
132 * Video only. The dimensions of the video frame in pixels.
133 */
134 int width;
135 int height;
136
137 /**
138 * Video only. The aspect ratio (width / height) which a single pixel
139 * should have when displayed.
140 *
141 * When the aspect ratio is unknown / undefined, the numerator should be
142 * set to 0 (the denominator may have any value).
143 */
144 AVRational sample_aspect_ratio;
145
146 /**
147 * Video only. Number of frames per second, for streams with constant frame
148 * durations. Should be set to { 0, 1 } when some frames have differing
149 * durations or if the value is not known.
150 *
151 * @note This field correponds to values that are stored in codec-level
152 * headers and is typically overridden by container/transport-layer
153 * timestamps, when available. It should thus be used only as a last resort,
154 * when no higher-level timing information is available.
155 */
156 AVRational framerate;
157
158 /**
159 * Video only. The order of the fields in interlaced video.
160 */
161 enum AVFieldOrder field_order;
162
163 /**
164 * Video only. Additional colorspace characteristics.
165 */
166 enum AVColorRange color_range;
167 enum AVColorPrimaries color_primaries;
168 enum AVColorTransferCharacteristic color_trc;
169 enum AVColorSpace color_space;
170 enum AVChromaLocation chroma_location;
171
172 /**
173 * Video only. Number of delayed frames.
174 */
175 int video_delay;
176
177 /**
178 * Audio only. The channel layout and number of channels.
179 */
180 AVChannelLayout ch_layout;
181 /**
182 * Audio only. The number of audio samples per second.
183 */
184 int sample_rate;
185 /**
186 * Audio only. The number of bytes per coded audio frame, required by some
187 * formats.
188 *
189 * Corresponds to nBlockAlign in WAVEFORMATEX.
190 */
191 int block_align;
192 /**
193 * Audio only. Audio frame size, if known. Required by some formats to be static.
194 */
195 int frame_size;
196
197 /**
198 * Audio only. The amount of padding (in samples) inserted by the encoder at
199 * the beginning of the audio. I.e. this number of leading decoded samples
200 * must be discarded by the caller to get the original audio without leading
201 * padding.
202 */
203 int initial_padding;
204 /**
205 * Audio only. The amount of padding (in samples) appended by the encoder to
206 * the end of the audio. I.e. this number of decoded samples must be
207 * discarded by the caller from the end of the stream to get the original
208 * audio without any trailing padding.
209 */
210 int trailing_padding;
211 /**
212 * Audio only. Number of samples to skip after a discontinuity.
213 */
214 int seek_preroll;
215} AVCodecParameters;
216
217/**
218 * Allocate a new AVCodecParameters and set its fields to default values
219 * (unknown/invalid/0). The returned struct must be freed with
220 * avcodec_parameters_free().
221 */
222AVCodecParameters *avcodec_parameters_alloc(void);
223
224/**
225 * Free an AVCodecParameters instance and everything associated with it and
226 * write NULL to the supplied pointer.
227 */
228void avcodec_parameters_free(AVCodecParameters **par);
229
230/**
231 * Copy the contents of src to dst. Any allocated fields in dst are freed and
232 * replaced with newly allocated duplicates of the corresponding fields in src.
233 *
234 * @return >= 0 on success, a negative AVERROR code on failure.
235 */
236int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
237
238/**
239 * This function is the same as av_get_audio_frame_duration(), except it works
240 * with AVCodecParameters instead of an AVCodecContext.
241 */
242int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes);
243
244/**
245 * @}
246 */
247
248#endif // AVCODEC_CODEC_PAR_H
249