/1*****************************************************************************************************/
/**
* Allocate an AVFormatContext.
* avformat_free_context() can be used to free the context and everything
* allocated by the framework within it.
*/
/*为定义的AVFormatContext结构分配空间，使用avformat_free_context来释放*/
AVFormatContext *avformat_alloc_context(void);
/2*****************************************************************************************************/
/**
* Open an input stream and read the header. The codecs are not opened.
* The stream must be closed with avformat_close_input().
*
* @param ps Pointer to user-supplied AVFormatContext (allocated by avformat_alloc_context).
* May be a pointer to NULL, in which case an AVFormatContext is allocated by this
* function and written into ps.
* Note that a user-supplied AVFormatContext will be freed on failure.
* @param filename Name of the stream to open.
* @param fmt If non-NULL, this parameter forces a specific input format.
* Otherwise the format is autodetected.
* @param options A dictionary filled with AVFormatContext and demuxer-private options.
* On return this parameter will be destroyed and replaced with a dict containing
* options that were not found. May be NULL.
*
* @return 0 on success, a negative AVERROR on failure.
*
* @note If you want to use custom IO, preallocate the format context and set its pb field.
*/
/**
*打开输入流，并且读取文件头。并不会打开codec，使用avformat_close_input来关闭打开的流。
*@param ps：用户定义的AVFormatContext变量指针，如果为NULL，那么函数自动分配一个AVFormatContext变量，并通过ps返回。如果用户指定ps指针，那么需要手动释放
*@param filename：需要打开的输入流的名称
*@param fmt：非NULL时，该参数强制指定AVInputFormat变量，为NULL时，由函数自动检测
*@param options：由AVFormatContext和demuxer-private选项填充的字典项，函数返回时，本身会被销毁，返回没有找到的选项，如果没有找到的选项，则为NULL
*
*@return 0：成功，<0(AVERROR)：失败
*@note If you want to use custom IO, preallocate the format context and set its pb field.
*/
int avformat_open_input(AVFormatContext **ps, const char *filename, AVInputFormat *fmt, AVDictionary **options);
/3*****************************************************************************************************/
/**
* Close an opened input AVFormatContext. Free it and all its contents
* and set *s to NULL.
*/
/**
*关闭由avformat_open_input打开的ps，释放相关内存和内容，并设置指针指向NULL
*/
void avformat_close_input(AVFormatContext **s);
/4*****************************************************************************************************/
/**
* Read packets of a media file to get stream information. This
* is useful for file formats with no headers such as MPEG. This
* function also computes the real framerate in case of MPEG-2 repeat
* frame mode.
* The logical file position is not changed by this function;
* examined packets may be buffered for later processing.
*
* @param ic media file handle
* @param options If non-NULL, an ic.nb_streams long array of pointers to
* dictionaries, where i-th member contains options for
* codec corresponding to i-th stream.
* On return each dictionary will be filled with options that were not found.
* @return >=0 if OK, AVERROR_xxx on error
*
* @note this function isn't guaranteed to open all the codecs, so
* options being non-empty at return is a perfectly normal behavior.
*
* @todo Let the user decide somehow what information is needed so that
* we do not waste time getting stuff the user does not need.
*/
/**
*解析多媒体文件多个报文，获取流信息。对于没有头的文件，只能使用该函数来获取，比如MPEG格式的文件。该函数也可以计算MPEG2重复帧模式下的实际帧率。
*函数不会改变文件内部的数据的逻辑位置；解析过的数据会被存储起来，以备他用。
*
*@param ic：媒体文件句柄AVFormatContext指针，通常是avformat_open_input函数的返回值
*@param options：非空时，该参数为一个指针数组，元素指向dictionaries，数组长度为ic.nb_streams。i-th成员包含了流的解码器的选项。返回时，包含没有找到的选项
*
*@return 0：成功，<0(AVERROR_xxx)：失败
*@note：该函数不保证打开所有codecs，所以当options返回为非空时，是完全正常的
*@todo：让用户来决定需要获取的信息，我们没有必要浪费时间来填充用户不需要的信息
*/
int avformat_find_stream_info(AVFormatContext *ic, AVDictionary **options);
/5*****************************************************************************************************/
/**
* Print detailed information about the input or output format, such as
* duration, bitrate, streams, container, programs, metadata, side data,
* codec and time base.
*
* @param ic the context to analyze
* @param index index of the stream to dump information about
* @param url the URL to print, such as source or destination file
* @param is_output Select whether the specified context is an input(0) or output(1)
*/
/**
*打印输入/输出格式的详细信息，例如：duration(时长), bitrate(码率), streams(流数目), container(容器), programs(节目), metadata(元数据),
*side data(边界数据), codec(编解码器) and time base(时基).
*
* @param ic：媒体文件句柄AVFormatContext指针，通常是avformat_open_input/avformat_find_stream_info函数的返回值
* @param index：指定打印流的索引
* @param url：指定需要打印的文件路劲
* @param is_output：指定该内容是输入还是输出
*/
void av_dump_format(AVFormatContext *ic,int index,const char *url,int is_output);
/6*****************************************************************************************************/
/**
* Get a dictionary entry with matching key.
*
* The returned entry key or value must not be changed, or it will
* cause undefined behavior.
*
* To iterate through all the dictionary entries, you can set the matching key
* to the null string "" and set the AV_DICT_IGNORE_SUFFIX flag.
*
* @param prev Set to the previous matching element to find the next.
* If set to NULL the first matching element is returned.
* @param key matching key
* @param flags a collection of AV_DICT_* flags controlling how the entry is retrieved
* @return found entry or NULL in case no matching entry was found in the dictionary
*/
/**
*视频的原数据（metadata）信息可以通过AVDictionary获取。元数据存储在AVDictionaryEntry结构体中，该函数可以返回一个匹配key的字典项，
*
*返回的字典项不能被更改，否则会产生不可预料的行为
*循环访问所有字典项时，可以设置需要匹配的key为空字符串""，并且设置AV_DICT_IGNORE_SUFFIX标志
*
*@param m：字典首项，通常为AVFormatContext->metadata
*@param prev: 前一次匹配上的字典项，用于寻找下一行。如果设置为NULL，返回第一个匹配上的项
*@param key：匹配的key，例如：rotate
*@param flags：AV_DICT_*系列标志的集合，控制字典项获取的方式
*@return：返回找到的项，没有找到项时，返回NULL
*/
AVDictionaryEntry *av_dict_get(const AVDictionary *m, const char *key,const AVDictionaryEntry *prev, int flags);
/7*****************************************************************************************************/
/**
* Get side information from stream.
*
* @param stream stream
* @param type desired side information type
* @param size pointer for side information size to store (optional)
* @return pointer to data if present or NULL otherwise
*/
/**
*获取流的边界信息
*
*@param stream：流，通常为AVFormatContext->streams[i]
*@param type：需要获取的边界信息类型，Ex：AV_PKT_DATA_DISPLAYMATRIX：
/**This side data contains a 3x3 transformation matrix(变换矩阵) describing an affine transformation(仿射变换) that
* needs to be applied to the decoded video frames for correct presentation.显示变换矩阵指定了一个仿射变换，可以用于视频帧来纠正显示
*/
*@param size：存储获取边界信息的指针(可选)
*@return 返回数据指针或NULL
*/
uint8_t *av_stream_get_side_data(AVStream *stream,enum AVPacketSideDataType type, int *size);
/8*****************************************************************************************************/
/**
* The display transformation matrix specifies an affine transformation that
* should be applied to video frames for correct presentation. It is compatible
* with the matrices stored in the ISO/IEC 14496-12 container format.
*
* The data is a 3x3 matrix represented as a 9-element array:
*
* | a b u |
* (a, b, u, c, d, v, x, y, w) -> | c d v |
* | x y w |
*
* All numbers are stored in native endianness, as 16.16 fixed-point values,
* except for u, v and w, which are stored as 2.30 fixed-point values.
*
* The transformation maps a point (p, q) in the source (pre-transformation)
* frame to the point (p', q') in the destination (post-transformation) frame as
* follows:
* | a b u |
* (p, q, 1) . | c d v | = z * (p', q', 1)
* | x y w |
*
* The transformation can also be more explicitly written in components as
* follows:
* p' = (a * p + c * q + x) / z;
* q' = (b * p + d * q + y) / z;
* z = u * p + v * q + w
*/
/**
* Extract the rotation component of the transformation matrix.
*
* @param matrix the transformation matrix
* @return the angle (in degrees) by which the transformation rotates the frame
* counterclockwise. The angle will be in range [-180.0, 180.0],
* or NaN if the matrix is singular.
*
* @note floating point numbers are inherently inexact, so callers are
* recommended to round the return value to nearest integer before use.
*/
/**
*显示变换矩阵指定了一个仿射变换，可以用于视频帧来纠正显示。与ISO/IEC 14496-12规定的矩阵格式兼容
*9元素数组用来表示这个3x3矩阵：
*
* | a b u |
* (a, b, u, c, d, v, x, y, w) -> | c d v |
* | x y w |
*所有数据按照原始字节顺序存储，uvw按照2.30定点值存储，其他的按照16.16定点值存储
*
*源帧(预转换帧)里面的点(p, q)映射到目的帧(转换帧)里的(p', q')点，转换公式如下：
* | a b u |
* (p, q, 1) . | c d v | = z * (p', q', 1)
* | x y w |
*转换可以明确按照构成标示出来：
* zp' = (a * p + c * q + x);
* zq' = (b * p + d * q + y);
* z = u * p + v * q + w
===>
* p' = (a * p + c * q + x) / z;
* q' = (b * p + d * q + y) / z;
* z = u * p + v * q + w
*/
/**
* 提取转换矩阵的旋转组件
*
* @param matrix：转换矩阵
* @return：转换按照逆时针方向转动帧的角度，角度范围[-180.0, 180.0]，如果是单一矩阵，值为NAN
*
* @note：返回值为浮点数时，由于内在的不精确，需要调用者来取浮点数附近的整数值。
*/
double av_display_rotation_get(const int32_t matrix[9]);
/9*****************************************************************************************************/
/**
* Parse the string in numstr and return its value as a double. If
* the string is empty, contains only whitespaces, or does not contain
* an initial substring that has the expected syntax for a
* floating-point number, no conversion is performed. In this case,
* returns a value of zero and the value returned in tail is the value
* of numstr.
*
* @param numstr a string representing a number, may contain one of
* the International System number postfixes, for example 'K', 'M',
* 'G'. If 'i' is appended after the postfix, powers of 2 are used
* instead of powers of 10. The 'B' postfix multiplies the value for
* 8, and can be appended after another postfix or used alone. This
* allows using for example 'KB', 'MiB', 'G' and 'B' as postfix.
* @param tail if non-NULL puts here the pointer to the char next
* after the last parsed character
*/
/**
*解析字符串numstr，并返回一个double型的数据。如果字符串为空，或只包含一个空格，或不包含一个合法的初始浮点数字串，此时将不被转换。
*这种情况下，返回值为0，tail指针指向的值为输入的numstr
*
*@param numstr：一个代表数字的字符串，例如：'1.0'，可以包含一些内部后缀，例如'K','M','G'
*i：2的幂，而不是10的幂
*B：x8，可以独立使用，也可以和其他后缀一起使用
*例如：KB、MiB、G、B
*@param tail：如果非NULL，指向最后被解析的字符串的下一个字符
*/
double av_strtod(const char *numstr, char **tail);
/10*****************************************************************************************************/
/*计算a * bq / cq，来把时间a戳从一个时基bq调整到另外一个时基cq*/
int64_t av_rescale_q(int64_t a, AVRational bq, AVRational cq)
/**
* Return number of bytes per sample.
*
* @param sample_fmt the sample format
* @return number of bytes per sample or zero if unknown for the given
* sample format
*/
int av_get_bytes_per_sample(enum AVSampleFormat sample_fmt);
/11*****************************************************************************************************/
/**
* Allocate SwrContext if needed and set/reset common parameters.
*
* This function does not require s to be allocated with swr_alloc(). On the
* other hand, swr_alloc() can use swr_alloc_set_opts() to set the parameters
* on the allocated context.
*
* @param s existing Swr context if available, or NULL if not
* @param out_ch_layout output channel layout (AV_CH_LAYOUT_*)
* @param out_sample_fmt output sample format (AV_SAMPLE_FMT_*).
* @param out_sample_rate output sample rate (frequency in Hz)
* @param in_ch_layout input channel layout (AV_CH_LAYOUT_*)
* @param in_sample_fmt input sample format (AV_SAMPLE_FMT_*).
* @param in_sample_rate input sample rate (frequency in Hz)
* @param log_offset logging level offset
* @param log_ctx parent logging context, can be NULL
*
* @see swr_init(), swr_free()
* @return NULL on error, allocated context otherwise
*/
/**
*分配SwrContext变量空间，初始化通用参数
*
*该函数不需要swr_alloc()函数来为SwrContext变量分配空间。如果swr_alloc()分配好之后，可以使用该函数来设置变量参数
*
* @param s：已经分配好的SwrContext变量空间或者为NULL，由函数自己分配
* @param out_ch_layout：输出通道布局(AV_CH_LAYOUT_*)，一般由av_get_default_channel_layout函数来获取
* @param out_sample_fmt：输出采样位数(AV_SAMPLE_FMT_*).
* @param out_sample_rate：输出采样率(frequency in Hz)
* @param in_ch_layout：输入通道布局(AV_CH_LAYOUT_*)，一般由av_get_default_channel_layout函数来获取
* @param in_sample_fmt：输入采样位数(AV_SAMPLE_FMT_*).
* @param in_sample_rate：输入采样率(frequency in Hz)
* @param log_offset：日志级别偏移
* @param log_ctx：父日志上下文，可以为NULL
*
* @see swr_init(), swr_free()
* @return NULL on error, allocated context otherwise，如果传入的s为空，此时返回值为SwrContext变量空间，需要调用swr_init来初始化
*/
struct SwrContext *swr_alloc_set_opts(struct SwrContext *s,
int64_t out_ch_layout, enum AVSampleFormat out_sample_fmt, int out_sample_rate,
int64_t in_ch_layout, enum AVSampleFormat in_sample_fmt, int in_sample_rate,
int log_offset, void *log_ctx);
/12*****************************************************************************************************/
/**
* Free the given SwrContext and set the pointer to NULL.
*
* @param[in] s a pointer to a pointer to Swr context
*/
/**
*释放输入的SwrContext并且设置指针的值为NULL.
*
* @param[in] s：指向SwrContext结构的指针
*/
void swr_free(struct SwrContext **s);
/13*****************************************************************************************************/
/**
* Allocate SwrContext.
*
* If you use this function you will need to set the parameters (manually or
* with swr_alloc_set_opts()) before calling swr_init().
*
* @see swr_alloc_set_opts(), swr_init(), swr_free()
* @return NULL on error, allocated context otherwise
*/
/**
*分配SwrContext变量空间.
*
*如果使用该函数，需要在调用swr_init()之前手动调用swr_alloc_set_opts函数来设置参数
*
* @see swr_alloc_set_opts(), swr_init(), swr_free()
* @return NULL on error, allocated context otherwise
*/
struct SwrContext *swr_alloc(void);
/14*****************************************************************************************************/
/**
* Initialize context after user parameters have been set.
* @note The context must be configured using the AVOption API.
*
* @see av_opt_set_int()
* @see av_opt_set_dict()
*
* @param[in,out] s Swr context to initialize
* @return AVERROR error code in case of failure.
*/
/**
*用户设置SwrContext参数之后(一般调用swr_alloc_set_opts)，此时调用该函数初始化SwrContext.
* @note The context must be configured using the AVOption API.
*
* @see av_opt_set_int()
* @see av_opt_set_dict()
*
* @param[in,out] s Swr context to initialize
* @return AVERROR error code in case of failure.
*/
int swr_init(struct SwrContext *s);
/14*****************************************************************************************************/
/** Convert audio.
*
* in and in_count can be set to 0 to flush the last few samples out at the
* end.
*
* If more input is provided than output space, then the input will be buffered.
* You can avoid this buffering by using swr_get_out_samples() to retrieve an
* upper bound on the required number of output samples for the given number of
* input samples. Conversion will run directly without copying whenever possible.
*
* @param s allocated Swr context, with parameters set
* @param out output buffers, only the first one need be set in case of packed audio
* @param out_count amount of space available for output in samples per channel
* @param in input buffers, only the first one need to be set in case of packed audio
* @param in_count number of input samples available in one channel
*
* @return number of samples output per channel, negative value on error
*/
/**音频转换
*
*在最后可以通过设置in和in_count为0来一次性输出剩下少许的样本
*
*如果设置输入的数量大于输出数量，此时输入将被缓存。为了避免输入被缓存，可以通过调用swr_get_out_samples()来获取输入样本数所需要的输出样本上限数。
*如果可能，转换直接运行，并不会拷贝。
*
* @param s：SwrContext变量空间，该变量的参数已经被设置
* @param output buffers, only the first one need be set in case of packed audio
* @param out_count amount of space available for output in samples per channel
* @param in input buffers, only the first one need to be set in case of packed audio
* @param in_count number of input samples available in one channel
*
* @return number of samples output per channel, negative value on error
*/
int swr_convert(struct SwrContext *s, uint8_t **out, int out_count,
const uint8_t **in , int in_count);
/15*****************************************************************************************************/
/**
*使用codec id查找一个已经注册的decoder
*
* @param id AVCodecID of the requested decoder
* @return A decoder if one was found, NULL otherwise.
*/
AVCodec *avcodec_find_decoder(enum AVCodecID id);
/16*****************************************************************************************************/
/**
* Initialize the AVCodecContext to use the given AVCodec. Prior to using this
* function the context has to be allocated with avcodec_alloc_context3().
*
* The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
* avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
* retrieving a codec.
*
* @warning This function is not thread safe!
*
* @note Always call this function before using decoding routines (such as
* @ref avcodec_decode_video2()).
*
* @code
* avcodec_register_all();
* av_dict_set(&opts, "b", "2.5M", 0);
* codec = avcodec_find_decoder(AV_CODEC_ID_H264);
* if (!codec)
* exit(1);
*
* context = avcodec_alloc_context3(codec);
*
* if (avcodec_open2(context, codec, opts) < 0)
* exit(1);
* @endcode
*
* @param avctx The context to initialize.
* @param codec The codec to open this context for. If a non-NULL codec has been
* previously passed to avcodec_alloc_context3() or
* avcodec_get_context_defaults3() for this context, then this
* parameter MUST be either NULL or equal to the previously passed
* codec.
* @param options A dictionary filled with AVCodecContext and codec-private options.
* On return this object will be filled with options that were not found.
*
* @return zero on success, a negative value on error
* @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
* av_dict_set(), av_opt_find().
*/
/**
*使用指定的AVCodec初始化AVCodecContext. 使用该方法之前，需要使用avcodec_alloc_context3()分配AVCodecContext
*
*使用avcodec_find_decoder_by_name() avcodec_find_encoder_by_name() avcodec_find_decoder() avcodec_find_encoder()来获取codec
*
* @warning 该函数线程非安全，需要调用者自己来保护
*
* @note 解码之前(例如:调用avcodec_decode_video2)必须先调用该函数
*
* @code
* avcodec_register_all();/*注册所有编解码器*/
* av_dict_set(&opts, "b", "2.5M", 0);/*设置字典项*/
* codec = avcodec_find_decoder(AV_CODEC_ID_H264);/*根据编解码器ID查找编解码器*/
* if (!codec)
* exit(1);
*
* context = avcodec_alloc_context3(codec);/*分配AVCodecContext变量空间*/
*
* if (avcodec_open2(context, codec, opts) < 0)/*初始化获取的AVCodecContext空间*/
* exit(1);
* @endcode
*
* @param avctx：待初始化的AVCodecContext变量
* @param codec：为codec打开的AVCodecContext，如果已经使用avcodec_alloc_context3()或者avcodec_get_context_defaults3()获取到了一个非NULL的codec
* 那么该参数必须要么为NULL，要么为之前传递给avcodec_alloc_context3()或者avcodec_get_context_defaults3()的codec参数
* @param options：由AVCodecContext and codec-private options填充的字典项。函数返回时，会被没有找到的选项填充
*
* @return 0：成功，<0失败
* @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
* av_dict_set(), av_opt_find().
*/
int avcodec_open2(AVCodecContext *avctx, const AVCodec *codec, AVDictionary **options);
/17*****************************************************************************************************/
/**
* Close a given AVCodecContext and free all the data associated with it
* (but not the AVCodecContext itself).
*
* Calling this function on an AVCodecContext that hasn't been opened will free
* the codec-specific data allocated in avcodec_alloc_context3() /
* avcodec_get_context_defaults3() with a non-NULL codec. Subsequent calls will
* do nothing.
*/
/**
*关闭传入的AVCodecContext，并且释放相关的所有数据，但不释放本身
*
*当AVCodecContext打开失败时，此时需要释放由avcodec_alloc_context3() or avcodec_get_context_defaults3()分配的AVCodecContext，那么就调用该函数
*/
int avcodec_close(AVCodecContext *avctx);
/18*****************************************************************************************************/
/**
* Allocate an AVFrame and set its fields to default values. The resulting
* struct must be freed using av_frame_free().
*
* @return An AVFrame filled with default values or NULL on failure.
*
* @note this only allocates the AVFrame itself, not the data buffers. Those
* must be allocated through other means, e.g. with av_frame_get_buffer() or
* manually.
*/
/**
*分配一个AVFrame空间，并付初值。释放时，必须使用av_frame_free().
*
* @return：成功时，返回分配并初始化的一个AVFrame空间，失败时，返回为NULL.
*
* @note：该函数只分配AVFrame变量本身占用的空间，而不是数据buffer空间，其他的空间需要使用其他的方式来分配。例如：使用av_frame_get_buffer()自动获取，或者手动malloc
*/
AVFrame *av_frame_alloc(void);
/19*****************************************************************************************************/
/**
* Free the frame and any dynamically allocated objects in it,
* e.g. extended_data. If the frame is reference counted, it will be
* unreferenced first.
*
* @param frame frame to be freed. The pointer will be set to NULL.
*/
/**
*释放帧存和帧存里面动态分配的变量空间
* e.g. extended_data. If the frame is reference counted, it will be unreferenced first.
*
* @param frame frame to be freed. The pointer will be set to NULL.
*/
void av_frame_free(AVFrame **frame);
/20*****************************************************************************************************/
/**
* Return default channel layout for a given number of channels.
*/
/**
*返回一个输入通道数目的通道默认布局
*/
int64_t av_get_default_channel_layout(int nb_channels);
/21*****************************************************************************************************/
/**
* Unreference all the buffers referenced by frame and reset the frame fields.
*/
/**
*解除帧引用的所有buffer的引用，并且复位帧的字段。
*/
void av_frame_unref(AVFrame *frame);
/22*****************************************************************************************************/
/**
* Decode the audio frame of size avpkt->size from avpkt->data into frame.
*
* Some decoders may support multiple frames in a single AVPacket. Such
* decoders would then just decode the first frame and the return value would be
* less than the packet size. In this case, avcodec_decode_audio4 has to be
* called again with an AVPacket containing the remaining data in order to
* decode the second frame, etc... Even if no frames are returned, the packet
* needs to be fed to the decoder with remaining data until it is completely
* consumed or an error occurs.
*
* Some decoders (those marked with CODEC_CAP_DELAY) have a delay between input
* and output. This means that for some packets they will not immediately
* produce decoded output and need to be flushed at the end of decoding to get
* all the decoded data. Flushing is done by calling this function with packets
* with avpkt->data set to NULL and avpkt->size set to 0 until it stops
* returning samples. It is safe to flush even those decoders that are not
* marked with CODEC_CAP_DELAY, then no samples will be returned.
*
* @warning The input buffer, avpkt->data must be FF_INPUT_BUFFER_PADDING_SIZE
* larger than the actual read bytes because some optimized bitstream
* readers read 32 or 64 bits at once and could read over the end.
*
* @note The AVCodecContext MUST have been opened with @ref avcodec_open2()
* before packets may be fed to the decoder.
*
* @param avctx the codec context
* @param[out] frame The AVFrame in which to store decoded audio samples.
* The decoder will allocate a buffer for the decoded frame by
* calling the AVCodecContext.get_buffer2() callback.
* When AVCodecContext.refcounted_frames is set to 1, the frame is
* reference counted and the returned reference belongs to the
* caller. The caller must release the frame using av_frame_unref()
* when the frame is no longer needed. The caller may safely write
* to the frame if av_frame_is_writable() returns 1.
* When AVCodecContext.refcounted_frames is set to 0, the returned
* reference belongs to the decoder and is valid only until the
* next call to this function or until closing or flushing the
* decoder. The caller may not write to it.
* @param[out] got_frame_ptr Zero if no frame could be decoded, otherwise it is
* non-zero. Note that this field being set to zero
* does not mean that an error has occurred. For
* decoders with CODEC_CAP_DELAY set, no given decode
* call is guaranteed to produce a frame.
* @param[in] avpkt The input AVPacket containing the input buffer.
* At least avpkt->data and avpkt->size should be set. Some
* decoders might also require additional fields to be set.
* @return A negative error code is returned if an error occurred during
* decoding, otherwise the number of bytes consumed from the input
* AVPacket is returned.
*/
/**
*从avpkt->data获取avpkt->size的音频帧，解码，并存储在frame参数指定的帧存中.
*
*一些解码器可能支持单一AVPacket里面包含多个帧。这类解码器先会解码第一帧，且返回的尺寸肯定小于packert大小。
*这种情况下，该函数不得不被循环调用，来解码AVPacket里面剩下的数据帧。即使剩下的数据不包含有效帧，也要这么做，直到AVPacket的数据全部被消耗掉或者返回error，
*
*一些解码器(包括那些含有CODEC_CAP_DELAY标记的)在输入和输出之前有一些延时。这意味着，输入的packet不会立即输出解码之后的数据，需要在全部解码完成之后，来获取解码的所有数据。
*解码完成后，循环调用该函数来获取数据，此时avpkt->data设置为NULL，avpkt->size设置为0，直到不返回样本，则意味着获取完成。
*即使对那些没有被CODEC_CAP_DELAY标记的解码器，flush也是安全的，此时将不会返回样本。
*
* @warning：avpkt->data必须大于实际读取数据字节数FF_INPUT_BUFFER_PADDING_SIZE，因为一些优化的bitstream reader会一次性读取32或者64个bit，这样可能会超出有效数据区域
*
* @note：packets输入解码器之前，必须先使用avcodec_open2来打开AVCodecContext。
*
* @param avctx：the codec context
* @param[out] frame：用于存储解码之后的音频样本数据。
* 解码器通过调用AVCodecContext.get_buffer2()回调来为解码后的帧分配空间。
* 当AVCodecContext.refcounted_frames为1时，该帧引用被计数，引用属于调用者。当帧不再需要时，调用者只能通过av_frame_unref()来释放引用。
* 如果av_frame_is_writable()返回1，调用者可以安全的写入frame。
* 当AVCodecContext.refcounted_frames为0时，引用属于解码器，有效期直至下一次调用该函数或者关闭或者flush编码器。此阶段调用者不能写入frame。
* @param[out] got_frame_ptr：如果没有帧被解码，此时值为0，否则非0。可以通过获取该值，来判断是否解码帧。需要注意的是，如果该值为0，并不表明发生了错误。
* 如果解码器设置了CODEC_CAP_DELAY标志，解码调用不能保证解码帧。
* @param[in] avpkt：需要解码的数据帧packet，至少avpkt->data and avpkt->size被设置，一些编码器可能需要设置其他字段.
* @return A negative error code is returned if an error occurred during
* decoding, otherwise the number of bytes consumed from the input
* AVPacket is returned.
*/
int avcodec_decode_audio4(AVCodecContext *avctx, AVFrame *frame, int *got_frame_ptr, const AVPacket *avpkt);
/23*****************************************************************************************************/
/**
* Get the required buffer size for the given audio parameters.
*
* @param[out] linesize calculated linesize, may be NULL
* @param nb_channels the number of channels
* @param nb_samples the number of samples in a single channel
* @param sample_fmt the sample format
* @param align buffer size alignment (0 = default, 1 = no alignment)
* @return required buffer size, or negative error code on failure
*/
/**
*根据输入的音频参数来获取需要的buffer尺寸.
*
* @param[out] linesize：计算得到的linesize，行大小，可以为NULL
* @param nb_channels：通道数目
* @param nb_samples：单一通道的样本数
* @param sample_fmt：采样位数
* @param align：buffer对齐 (0 = default, 1 = no alignment)
* @return：需要的buffer尺寸，<0：失败
*/
int av_samples_get_buffer_size(int *linesize, int nb_channels, int nb_samples,
enum AVSampleFormat sample_fmt, int align);
/24*****************************************************************************************************/
/**
* Free a packet.
*
* @param pkt packet to free
*/
/**
*释放分配的packet.
*
* @param pkt packet to free
*/
void av_free_packet(AVPacket *pkt);
/25*****************************************************************************************************/
/**
* Seek to the keyframe at timestamp.
* 'timestamp' in 'stream_index'.
*
* @param s media file handle
* @param stream_index If stream_index is (-1), a default
* stream is selected, and timestamp is automatically converted
* from AV_TIME_BASE units to the stream specific time_base.
* @param timestamp Timestamp in AVStream.time_base units
* or, if no stream is specified, in AV_TIME_BASE units.
* @param flags flags which select direction and seeking mode
* @return >= 0 on success
*/
/**
*Seek到索引为stream_index的stream的timestamp处的关键帧
* 'timestamp' in 'stream_index'.
*
* @param s media file handle
* @param stream_index：如果为-1，使用默认的stream，并且timestamp自动从AV_TIME_BASE时基转换到流指定的时基上
* @param timestamp：基于AVStream.time_base时基的时间戳，如果没有指定，就是基于AV_TIME_BASE的时间戳
* @param flags：方向和模式的选择标识
* @return >= 0 on success
*/
int av_seek_frame(AVFormatContext *s, int stream_index, int64_t timestamp,
int flags);
/26*****************************************************************************************************/
/**
* Seek to timestamp ts.
* Seeking will be done so that the point from which all active streams
* can be presented successfully will be closest to ts and within min/max_ts.
* Active streams are all streams that have AVStream.discard < AVDISCARD_ALL.
*
* If flags contain AVSEEK_FLAG_BYTE, then all timestamps are in bytes and
* are the file position (this may not be supported by all demuxers).
* If flags contain AVSEEK_FLAG_FRAME, then all timestamps are in frames
* in the stream with stream_index (this may not be supported by all demuxers).
* Otherwise all timestamps are in units of the stream selected by stream_index
* or if stream_index is -1, in AV_TIME_BASE units.
* If flags contain AVSEEK_FLAG_ANY, then non-keyframes are treated as
* keyframes (this may not be supported by all demuxers).
* If flags contain AVSEEK_FLAG_BACKWARD, it is ignored.
*
* @param s media file handle
* @param stream_index index of the stream which is used as time base reference
* @param min_ts smallest acceptable timestamp
* @param ts target timestamp
* @param max_ts largest acceptable timestamp
* @param flags flags
* @return >=0 on success, error code otherwise
*
* @note This is part of the new seek API which is still under construction.
* Thus do not use this yet. It may change at any time, do not expect
* ABI compatibility yet!
*/
/**
*Seek到时间戳ts处.
*Seek完成之后，有效流的点将会趋近与ts，并且在min/max_ts区间内。
*流的AVStream.discard < AVDISCARD_ALL均为有效流，有效流都可以成功显示.
*
*如果标识包含AVSEEK_FLAG_BYTE(seeking based on position in bytes)，所有时间戳单位都是字节，且用于文件位置定位(不是所有的解复用器都支持)。
*如果标识包含AVSEEK_FLAG_FRAME(seeking based on frame number)，在含有stream_index的流中，所有时间戳都是帧(不是所有的解复用器都支持)。另外，所有时间戳都是以stream_index指定流的时基为标准，如果stream_index为-1，则默认时基为AV_TIME_BASE
*如果标识包含AVSEEK_FLAG_ANY(seek to any frame, even non-keyframes)，non-keyframes为关键帧(不是所有的解复用器都支持)
*如果标识包含AVSEEK_FLAG_BACKWARD(seek backward)，it is ignored.
*
* @param s media file handle
* @param stream_index：流的索引，该流的时基用作基准时基
* @param min_ts：最小可接受的时间戳
* @param ts：目标时间戳
* @param max_ts：最大可接受时间戳
* @param flags flags
* @return >=0 on success, error code otherwise
*
* @note 该函数是正在建设中的seek API的一部分，尽量不要使用。可能随时改变，还不要期望ABI兼容
*/
int avformat_seek_file(AVFormatContext *s, int stream_index, int64_t min_ts, int64_t ts, int64_t max_ts, int flags);
/27*****************************************************************************************************/
/**
* Return the next frame of a stream.
* This function returns what is stored in the file, and does not validate
* that what is there are valid frames for the decoder. It will split what is
* stored in the file into frames and return one for each call. It will not
* omit invalid data between valid frames so as to give the decoder the maximum
* information possible for decoding.
*
* If pkt->buf is NULL, then the packet is valid until the next
* av_read_frame() or until avformat_close_input(). Otherwise the packet
* is valid indefinitely. In both cases the packet must be freed with
* av_free_packet when it is no longer needed. For video, the packet contains
* exactly one frame. For audio, it contains an integer number of frames if each
* frame has a known fixed size (e.g. PCM or ADPCM data). If the audio frames
* have a variable size (e.g. MPEG audio), then it contains one frame.
*
* pkt->pts, pkt->dts and pkt->duration are always set to correct
* values in AVStream.time_base units (and guessed if the format cannot
* provide them). pkt->pts can be AV_NOPTS_VALUE if the video format
* has B-frames, so it is better to rely on pkt->dts if you do not
* decompress the payload.
*
* @return 0 if OK, < 0 on error or end of file
*/
/**
*返回流中的下一帧。
*该函数返回文件中存储的内容，并且不会验证数据是否有效。函数会将文件分割成帧，并且每次调用一次返回一帧。为了给解码器提供更多的信息来解码，也不会忽略无效帧。
*
*如果pkt->buf为NULL，直到下一次av_read_frame()或者avformat_close_input()，packet有效。另外packet不确定是否有效。
*当packet无效时，必须使用av_free_packet()来释放。对于视频来说，packet只包含一帧。对于音频来说，如果帧大小固定，packet包含整数个帧(例如：PCM or ADPCM)；如果帧大小可变，则只包含一帧(例如：MPEG)。
*
*pkt->pts, pkt->dts and pkt->duration总是被设置，用于基于AVStream.time_base来更正数据(总是假设格式不能提供pts、dts、duration)
*这样即使流没有提供pts、dts、duration，我们也可以按照提供的pts、dts、duration来进行解码
*如果视频格式有B帧，pkt->pts可以为AV_NOPTS_VALUE。所以如果不解压负载，最好依赖pkt-dts
*
* @return 0 if OK, < 0 on error or end of file
*/
int av_read_frame(AVFormatContext *s, AVPacket *pkt);
阅读(1290) | 评论(0) | 转发(0) |
