FFMPEG 之 AVUtility 2

AVUtility 库提供了很多通用的函数， 这篇介绍AVUtility 库中AVFrame, AVOption, AVDictionary,Audio 相关，error code,log 相关等相关API。

1 AVFrame

     AVPacket 与 AVFrame 两个结构体，一个存放解码前的数据，一个存放解码后的数据。 两个结构体对应的API 函数也差不多。 

AVFrame * av_frame_alloc (void) ；//这申请的是AVFrame 本身结构体的空间，frame data 并没有申请， 可通过av_frame_get_buffer()去申请。另外对于解码等操作，frame data的空间解码库会给申请好， 无需使用者操作。

函数名	作用
const char * av_get_colorspace_name (enum AVColorSpace val)	获取颜色空间的名称
AVFrame * av_frame_alloc (void)	分配一个avframe，并将其字段设置为默认值
void av_frame_free (AVFrame **frame)	释放框架和其中任何动态分配的对象
int av_frame_ref (AVFrame *dst, const AVFrame *src)	为源框架描述的数据建立新的引用
AVFrame * av_frame_clone (const AVFrame *src)	为源框架描述的数据建立新的引用
void av_frame_unref (AVFrame *frame)	取消引用帧引用的所有缓冲区，并重置帧字段
void av_frame_move_ref (AVFrame *dst, AVFrame *src)	将src中包含的所有内容移动到dst并重置src
int av_frame_get_buffer (AVFrame *frame, int align)	为音频或视频数据分配新的缓冲区
int av_frame_is_writable (AVFrame *frame)	检查帧数据是否可写
int av_frame_make_writable (AVFrame *frame)	确保帧数据是可写的，尽可能避免数据复制
int av_frame_copy (AVFrame *dst, const AVFrame *src)	将帧数据从src复制到dst
int av_frame_copy_props (AVFrame *dst, const AVFrame *src)	仅将“元数据”字段从src复制到dst。
AVBufferRef * av_frame_get_plane_buffer (AVFrame *frame, int plane)	获取存储给定数据平面的缓冲区引用
AVFrameSideData * av_frame_new_side_data (AVFrame *frame, enum AVFrameSideDataType type, int size)	向帧添加新的边数据
AVFrameSideData * av_frame_new_side_data_from_buf (AVFrame *frame, enum AVFrameSideDataType type, AVBufferRef *buf)	获取存储给定数据平面的缓冲区引用
AVFrameSideData * av_frame_get_side_data (const AVFrame *frame, enum AVFrameSideDataType type)
void av_frame_remove_side_data (AVFrame *frame, enum AVFrameSideDataType type)	如果框架中存在所提供类型的边数据，请将其释放并从框架中移除
int av_frame_apply_cropping (AVFrame *frame, int flags)	根据给定视频avframe的裁剪_左/裁剪_上/裁剪_右/裁剪_下字段对其进行裁剪。
const char * av_frame_side_data_name (enum AVFrameSideDataType type)

2 AVOption

   avoptions提供了一个通用参数设置方法， 我们可以通过它去设置任何结构体参数。 AVFormatContext结构体第一个成员就是AVClass, 而AVClass 里面有AVOption 成员，这就是为av_opt_xxx 系列函数准备的。我们可以通过av_opt_set_xxx， 去设置AVFormatContext 成员。其他向AVCodecContext , AVSwResample 等等结构体，里面都有avclass 成员。 具体实现原理请参考：https://blog.csdn.net/leixiaohua1020/article/details/44279329

函数名	作用
int av_opt_show2 (void *obj, void *av_log_obj, int req_flags, int rej_flags)	显示obj选项。
void av_opt_set_defaults (void *s)	将所有选项字段的值设置为默认值
void av_opt_set_defaults2 (void *s, int mask, int flags)	将所有选项字段的值设置为默认值
int av_set_options_string (void *ctx, const char *opts, const char *key_val_sep, const char *pairs_sep)	解析opts中的键/值对列表。
int av_opt_set_from_string (void *ctx, const char *opts, const char *const *shorthand, const char *key_val_sep, const char *pairs_sep)	解析opts中的键值对列表
void av_opt_free (void *obj)	释放obj中所有已分配的对象
int av_opt_flag_is_set (void *obj, const char *field_name, const char *flag_name)	检查标志字段中是否设置了特定标志。
int av_opt_set_dict (void *obj, struct AVDictionary **options)	设置对象上给定dict的所有选项。
int av_opt_set_dict2 (void *obj, struct AVDictionary **options, int search_flags)	设置对象上给定dict的所有选项。
int av_opt_get_key_value (const char **ropts, const char *key_val_sep, const char *pairs_sep, unsigned flags, char **rkey, char **rval)	从字符串的开头提取键值对
const AVOption * av_opt_find (void *obj, const char *name, const char *unit, int opt_flags, int search_flags)	在objec中寻找选项
const AVOption * av_opt_find2 (void *obj, const char *name, const char *unit, int opt_flags, int search_flags, void **target_obj)	在对象中寻找选项
const AVOption * av_opt_next (const void *obj, const AVOption *prev)	遍历属于obj的所有avoptions
void * av_opt_child_next (void *obj, void *prev)	遍历obj的启用avoptions的子级
const AVClass * av_opt_child_class_next (const AVClass *parent, const AVClass *prev)	遍历obj的启用avoptions的子级
void * av_opt_ptr (const AVClass *avclass, void *obj, const char *name)	迭代obj的启用avoptions的子级
void av_opt_freep_ranges (AVOptionRanges **ranges)	释放avoptionranges结构并将其设置为null
int av_opt_query_ranges (AVOptionRanges **, void *obj, const char *key, int flags)	获取给定选项的允许范围列表
int av_opt_copy (void *dest, const void *src)	将选项从src对象复制到目标对象
int av_opt_query_ranges_default (AVOptionRanges **, void *obj, const char *key, int flags)	获取给定选项的默认允许范围列表
int av_opt_is_set_to_default (void *obj, const AVOption *o)	检查给定选项是否设置为默认值
int av_opt_is_set_to_default_by_name (void *obj, const char *name, int search_flags)	检查给定选项是否设置为默认值。
int av_opt_serialize (void *obj, int opt_flags, int flags, char **buffer, const char key_val_sep, const char pairs_sep)	序列化对象的选项。

 

3 AVDictionary

key:value 形式，一个key 里面，存着一个value， 可以记录info信息。

函数名	作用
AVDictionaryEntry * av_dict_get (const AVDictionary *m, const char *key, const AVDictionaryEntry *prev, int flags)	获取带有匹配关键字的词典条目
int av_dict_count (const AVDictionary *m)	获取字典中的条目数
int av_dict_set (AVDictionary **pm, const char *key, const char *value, int flags)	在*pm中设置给定条目，覆盖现有条目
int av_dict_set_int (AVDictionary **pm, const char *key, int64_t value, int flags)	av_dict_set的便捷包装器，用于将值转换为字符串并存储
int av_dict_parse_string (AVDictionary **pm, const char *str, const char *key_val_sep, cons	解析键/值对列表，并将解析后的条目添加到字典中
int av_dict_copy (AVDictionary **dst, const AVDictionary *src, int flags)	将条目从一个avdictionary结构复制到另一个
void av_dict_free (AVDictionary **m)	释放为avdictionary结构分配的所有内存以及所有键和值
int av_dict_get_string (const AVDictionary *m, char **buffer, const char key_val_sep, const char pairs_sep)	以字符串形式获取词典条目

 

4 AVAudioFifo

audio 相关的数据结构。

函数原型	作用
void          av_audio_fifo_free (AVAudioFifo *af)	free AVAudioFifo
AVAudioFifo *           av_audio_fifo_alloc (enum AVSampleFormat sample_fmt, int channels, int nb_samples)	alloc AVAudioFifo
int   av_audio_fifo_write (AVAudioFifo *af, void **data, int nb_samples)	将数据写入avaudiofifo。
int   av_audio_fifo_peek (AVAudioFifo *af, void **data, int nb_samples)	从avaudiofifo中查看数据。
int   av_audio_fifo_read (AVAudioFifo *af, void **data, int nb_samples)	从avaudiofifo读取数据
int   av_audio_fifo_drain (AVAudioFifo *af, int nb_samples)	从avaudiofifo中丢弃数据。

 

5 Audio channel

函数原型	作用
uint64_t           av_get_channel_layout (const char *name)	返回与name匹配的频道布局id，如果未找到匹配项，则返回0。
void          av_get_channel_layout_string (char *buf, int buf_size, int nb_channels, uint64_t channel_layout)	返回频道布局的描述。
int   av_get_channel_layout_nb_channels (uint64_t channel_layout)	返回频道布局中的频道数量
int64_t    av_get_default_channel_layout (int nb_channels)	返回给定数量通道的默认通道布局
int   av_get_standard_channel_layout (unsigned index, uint64_t *layout, const char **name)	获取标准通道布局的值和名称

6  AVSampleFormat

函数原型	作用
const char *    av_get_sample_fmt_name (enum AVSampleFormat sample_fmt)	返回sample_fmt的名称，如果sample_fmt无法识别，则返回null
enum AVSampleFormat           av_get_sample_fmt (const char *name)	返回对应于名称的样本格式，或错误时返回av_sample_fmt_none。
enum AVSampleFormat          av_get_packed_sample_fmt (enum AVSampleFormat sample_fmt)	获取给定样本格式的打包替代形式
int   av_get_bytes_per_sample (enum AVSampleFormat sample_fmt)	返回每个样本的字节数
int  av_sample_fmt_is_planar (enum AVSampleFormat sample_fmt)	检查样本格式是否为planar 格式
int  av_samples_get_buffer_size (int *linesize, int nb_channels, int nb_samples, enum AVSampleFormat sample_fmt, int align)	获取给定音频参数所需的缓冲区大小

7 sample 操作

av_samples_fill_arrays() 经常用， 比如在转换audio 时， 可通过这支API 去alloc  audio 的data 空间

函数原型	作用
int  av_samples_fill_arrays (uint8_t **audio_data, int *linesize, const uint8_t *buf, int nb_channels, int nb_samples, enum AVSampleFormat sample_fmt, int align)	使用sample format sample_fmt填充样本的平面数据指针和行尺寸。
int   av_samples_alloc (uint8_t **audio_data, int *linesize, int nb_channels, int nb_samples, enum AVSampleFormat sample_fmt, int align)	为nb_samples样本分配一个样本缓冲区，并相应地填充数据指针和行大小
int   av_samples_alloc_array_and_samples (uint8_t ***audio_data, int *linesize, int nb_channels, int nb_samples, enum AVSampleFormat sample_fmt, int align)	分配数据指针数组，为nb_samples样本分配样本缓冲区，并相应地填充数据指针和行大小
int   av_samples_copy (uint8_t **dst, uint8_t *const *src, int dst_offset, int src_offset, int nb_samples, int nb_channels, enum AVSampleFormat sample_fmt)	将样品从src复制到dst。
int   av_samples_set_silence (uint8_t **audio_data, int offset, int nb_samples, int nb_channels, enum AVSampleFormat sample_fmt)	用静音填充音频缓冲区

8 error code & log 

 av_strerror() 可以将err code 转换成具体的文字描述。

FFMPEG 默认的log 等级是AV_LOG_INFO， 如需提高log 等级可用av_log_set_level（）。ffmpeg 默认将log 打印到console, 如果想将log 打印到文件，可以通过av_log_set_callback() 将log 输出到指定的callback 函数，然后输出到具体文件中。

关于FFMPEG log 还有很多细节, 这点可以参考博客： https://blog.csdn.net/leixiaohua1020/article/details/44243155

函数原型	作用
int   av_strerror (int errnum, char *errbuf, size_t errbuf_size)	将错误代码errnum的描述放在errbuf中
static char *   av_make_error_string (char *errbuf, size_t errbuf_size, int errnum)	用包含对应于错误代码errnum的错误字符串的字符串填充提供的缓冲区
void  av_log (void *avcl, int level, const char *fmt,...)	如果级别小于或等于当前av_log_level，则向日志发送指定的消息
void  av_vlog (void *avcl, int level, const char *fmt, va_list vl)	如果级别小于或等于当前av_log_level，则向日志发送指定的消息
int   av_log_get_level (void)	获取当前日志级别
void          av_log_set_level (int level)	设置日志级别
void          av_log_set_callback (void(*callback)(void *, int, const char *, va_list))	设置日志回调