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