codec_par.h (7728B)
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 */ 47 typedef 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 corresponds 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 */ 222 AVCodecParameters *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 */ 228 void 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 */ 236 int 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 */ 242 int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes); 243 244 /** 245 * @} 246 */ 247 248 #endif // AVCODEC_CODEC_PAR_H