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