ffmpeg/libavcodec/codec_par.h

/*
 * Codec parameters public API
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef AVCODEC_CODEC_PAR_H
#define AVCODEC_CODEC_PAR_H

#include <stdint.h>

#include "libavutil/avutil.h"
#include "libavutil/channel_layout.h"
#include "libavutil/rational.h"
#include "libavutil/pixfmt.h"

#include "codec_id.h"
#include "defs.h"
#include "packet.h"

/**
 * @defgroup lavc_codec_params Codec parameters
 * @ingroup lavc_core
 * @{
 */

/**
 * This struct describes the properties of an encoded stream.
 *
 * @note
 * The `sizeof(AVCodecParameters)` is not a part of the public ABI,
 * therefore this struct must be allocated with ::avcodec_parameters_alloc()
 * and freed with ::avcodec_parameters_free().
 */
typedef struct AVCodecParameters {
    /**
     * General type of the encoded data.
     */
    enum AVMediaType codec_type;
    /**
     * Specific type of the encoded data (the codec used).
     */
    enum AVCodecID   codec_id;
    /**
     * Additional information about the codec (corresponds to the AVI FOURCC).
     */
    uint32_t         codec_tag;

    /**
     * Extra binary data needed for initializing the decoder, codec-dependent.
     *
     * Must be allocated with ::av_malloc() and will be freed by
     * ::avcodec_parameters_free(). The allocated size of extradata must be at
     * least #extradata_size + ::AV_INPUT_BUFFER_PADDING_SIZE, with the padding
     * bytes zeroed.
     */
    uint8_t *extradata;
    /**
     * Size of the extradata content in bytes.
     */
    int      extradata_size;

    /**
     * Additional data associated with the entire stream.
     *
     * Should be allocated with ::av_packet_side_data_new() or
     * ::av_packet_side_data_add(), and will be freed by ::avcodec_parameters_free().
     */
    AVPacketSideData *coded_side_data;

    /**
     * Amount of entries in #coded_side_data.
     */
    int nb_coded_side_data;

    /**
     * - Video: the pixel format, the value corresponds to enum ::AVPixelFormat.
     * - Audio: the sample format, the value corresponds to enum ::AVSampleFormat.
     */
    int format;

    /**
     * The average bitrate of the encoded data (in bits per second).
     */
    int64_t bit_rate;

    /**
     * The number of bits per sample in the codedwords.
     *
     * This is basically the bitrate per sample. It is mandatory for a bunch of
     * formats to actually decode them. It's the number of bits for one sample in
     * the actual coded bitstream.
     *
     * This could be, for example, 4, for ADPCM.
     * For PCM formats this matches #bits_per_raw_sample.
     *
     * Can be 0.
     */
    int bits_per_coded_sample;

    /**
     * The number of valid bits in each output sample.
     *
     * If the sample format has more bits, the least significant bits are additional
     * padding bits, which are always 0. Use right shifts to reduce the sample
     * to its actual size.
     *
     * For example, audio formats with 24-bit samples will have #bits_per_raw_sample
     * set to 24, and ::format set to ::AV_SAMPLE_FMT_S32. To get the original sample,
     * use: `(int32_t)sample >> 8`.
     *
     * For ADPCM, this might be 12 or 16, or similar.
     *
     * Can be 0.
     */
    int bits_per_raw_sample;

    /**
     * Codec-specific bitstream restrictions that the stream conforms to.
     */
    int profile;
    int level;

    /**
     * The width of the video frame in pixels.
     *
     * Video only.
     */
    int width;

    /**
     * The height of the video frame in pixels.
     *
     * Video only.
     */
    int height;

    /**
     * The aspect ratio (width/height) which a single pixel
     * should have when displayed.
     *
     * When the aspect ratio is unknown or undefined, the numerator should be
     * set to 0 (the denominator may have any value).
     *
     * Video only.
     */
    AVRational sample_aspect_ratio;

    /**
     * Number of frames per second, for streams with constant frame
     * durations. Should be set to `{ 0, 1 }` when some frames have differing
     * durations or if the value is not known.
     *
     * @note This field corresponds to values that are stored in codec-level
     * headers and is typically overridden by container/transport-layer
     * timestamps, when available. It should thus be used only as a last resort,
     * when no higher-level timing information is available.
     *
     * Video only.
     */
    AVRational framerate;

    /**
     * The order of the fields in interlaced video.
     *
     * Video only.
     */
    enum AVFieldOrder                  field_order;

    /**
     * Additional colorspace characteristics.
     *
     * Video only.
     */
    enum AVColorRange                  color_range;
    enum AVColorPrimaries              color_primaries;
    enum AVColorTransferCharacteristic color_trc;
    enum AVColorSpace                  color_space;
    enum AVChromaLocation              chroma_location;

    /**
     * Number of delayed frames.
     *
     * Video only.
     */
    int video_delay;

    /**
     * The channel layout and number of channels.
     *
     * Audio only.
     */
    AVChannelLayout ch_layout;
    /**
     * The number of audio samples per second.
     *
     * Audio only.
     */
    int      sample_rate;
    /**
     * The number of bytes per coded audio frame, required by some formats.
     *
     * Audio only.
     *
     * Corresponds to nBlockAlign in WAVEFORMATEX.
     */
    int      block_align;
    /**
     * Audio frame size, if known. Required by some formats to be static.
     *
     * Audio only.
     */
    int      frame_size;

    /**
     * Number of padding audio samples at the start.
     *
     * The amount of padding (in samples) inserted by the encoder at
     * the beginning of the audio. I.e. this number of leading decoded samples
     * must be discarded to get the original audio without leading
     * padding.
     *
     * Audio only.
     */
    int initial_padding;
    /**
     * Number of padding audio samples at the end.
     *
     * The amount of padding (in samples) appended by the encoder to
     * the end of the audio. I.e. this number of decoded samples must be
     * discarded from the end of the stream to get the original
     * audio without any trailing padding.
     *
     * Audio only.
     */
    int trailing_padding;
    /**
     * Number of audio samples to skip after a discontinuity.
     *
     * Audio only.
     */
    int seek_preroll;

    /**
     * Video with alpha channel only. Alpha channel handling
     */
    enum AVAlphaMode alpha_mode;
} AVCodecParameters;

/**
 * @relates AVCodecParameters
 * @{
 */

/**
 * Allocate a new AVCodecParameters and set its fields to default values
 * (unknown/invalid/0). The returned struct must be freed with
 * ::avcodec_parameters_free().
 */
AVCodecParameters *avcodec_parameters_alloc(void);

/**
 * Free an AVCodecParameters instance and everything associated with it and
 * write `NULL` to the supplied pointer.
 */
void avcodec_parameters_free(AVCodecParameters **par);

/**
 * Copy the contents of \p src to \p dst. Any allocated fields in dst are freed and
 * replaced with newly allocated duplicates of the corresponding fields in src.
 *
 * @return >= 0 on success, a negative AVERROR code on failure.
 */
int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);

/**
 * This function is the same as ::av_get_audio_frame_duration(), except it works
 * with ::AVCodecParameters instead of an ::AVCodecContext.
 */
int av_get_audio_frame_duration2(AVCodecParameters *par, int frame_bytes);

/** @} */

/**
 * @}
 */

#endif // AVCODEC_CODEC_PAR_H