AVOptions provide a generic system to declare options on arbitrary structs ("objects"). More...

Modules

 Evaluating option strings
 This group of functions can be used to evaluate option strings and get numbers out of them.
 
 Option setting functions
 Those functions set the field of obj with the given name to value.
 
 Option getting functions
 Those functions get a value of the option with the given name from an object.
 

Files

file  avformat.h
 Main libavformat public API header.
 

Data Structures

struct  AVOption
 AVOption. More...
 

Macros

#define AV_OPT_SEARCH_CHILDREN   0x0001
 Search in possible children of the given object first. More...
 
#define AV_OPT_SEARCH_FAKE_OBJ   0x0002
 The obj passed to av_opt_find() is fake – only a double pointer to AVClass instead of a required pointer to a struct containing AVClass. More...
 

Typedefs

typedef struct AVOption AVOption
 AVOption. More...
 

Enumerations

enum  AVOptionType {
  AV_OPT_TYPE_FLAGS, AV_OPT_TYPE_INT, AV_OPT_TYPE_INT64, AV_OPT_TYPE_DOUBLE,
  AV_OPT_TYPE_FLOAT, AV_OPT_TYPE_STRING, AV_OPT_TYPE_RATIONAL, AV_OPT_TYPE_BINARY,
  AV_OPT_TYPE_CONST = 128
}
 

Functions

int av_opt_show2 (void *obj, void *av_log_obj, int req_flags, int rej_flags)
 Show the obj options. More...
 
void av_opt_set_defaults (void *s)
 Set the values of all AVOption fields to their default values. More...
 
int av_set_options_string (void *ctx, const char *opts, const char *key_val_sep, const char *pairs_sep)
 Parse the key/value pairs list in opts. More...
 
void av_opt_free (void *obj)
 Free all string and binary options in obj. More...
 
int av_opt_flag_is_set (void *obj, const char *field_name, const char *flag_name)
 Check whether a particular flag is set in a flags field. More...
 
int av_opt_set_dict (void *obj, struct AVDictionary **options)
 
const AVOptionav_opt_find (void *obj, const char *name, const char *unit, int opt_flags, int search_flags)
 Look for an option in an object. More...
 
const AVOptionav_opt_find2 (void *obj, const char *name, const char *unit, int opt_flags, int search_flags, void **target_obj)
 Look for an option in an object. More...
 
const AVOptionav_opt_next (void *obj, const AVOption *prev)
 Iterate over all AVOptions belonging to obj. More...
 
voidav_opt_child_next (void *obj, void *prev)
 Iterate over AVOptions-enabled children of obj. More...
 
const AVClassav_opt_child_class_next (const AVClass *parent, const AVClass *prev)
 Iterate over potential AVOptions-enabled children of parent. More...
 

Detailed Description

AVOptions provide a generic system to declare options on arbitrary structs ("objects").

An option can have a help text, a type and a range of possible values. Options may then be enumerated, read and written to.

Implementing AVOptions

This section describes how to add AVOptions capabilities to a struct.

All AVOptions-related information is stored in an AVClass. Therefore the first member of the struct must be a pointer to an AVClass describing it. The option field of the AVClass must be set to a NULL-terminated static array of AVOptions. Each AVOption must have a non-empty name, a type, a default value and for number-type AVOptions also a range of allowed values. It must also declare an offset in bytes from the start of the struct, where the field associated with this AVOption is located. Other fields in the AVOption struct should also be set when applicable, but are not required.

The following example illustrates an AVOptions-enabled struct:

typedef struct test_struct {
AVClass *class;
int int_opt;
char *str_opt;
uint8_t *bin_opt;
int bin_len;
} test_struct;
static const AVOption options[] = {
{ "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
{ "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
{ "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
{ NULL },
};
static const AVClass test_class = {
.class_name = "test class",
.item_name = av_default_item_name,
.option = options,
};

Next, when allocating your struct, you must ensure that the AVClass pointer is set to the correct value. Then, av_opt_set_defaults() must be called to initialize defaults. After that the struct is ready to be used with the AVOptions API.

When cleaning up, you may use the av_opt_free() function to automatically free all the allocated string and binary options.

Continuing with the above example:

test_struct *alloc_test_struct(void)
{
test_struct *ret = av_malloc(sizeof(*ret));
ret->class = &test_class;
return ret;
}
void free_test_struct(test_struct **foo)
{
av_opt_free(*foo);
av_freep(foo);
}

Nesting

It may happen that an AVOptions-enabled struct contains another AVOptions-enabled struct as a member (e.g. AVCodecContext in libavcodec exports generic options, while its priv_data field exports codec-specific options). In such a case, it is possible to set up the parent struct to export a child's options. To do that, simply implement AVClass.child_next() and AVClass.child_class_next() in the parent struct's AVClass. Assuming that the test_struct from above now also contains a child_struct field:

typedef struct child_struct {
AVClass *class;
int flags_opt;
} child_struct;
static const AVOption child_opts[] = {
{ "test_flags", "This is a test option of flags type.",
offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
{ NULL },
};
static const AVClass child_class = {
.class_name = "child class",
.item_name = av_default_item_name,
.option = child_opts,
};
void *child_next(void *obj, void *prev)
{
test_struct *t = obj;
if (!prev && t->child_struct)
return t->child_struct;
return NULL
}
const AVClass child_class_next(const AVClass *prev)
{
return prev ? NULL : &child_class;
}

Putting child_next() and child_class_next() as defined above into test_class will now make child_struct's options accessible through test_struct (again, proper setup as described above needs to be done on child_struct right after it is created).

From the above example it might not be clear why both child_next() and child_class_next() are needed. The distinction is that child_next() iterates over actually existing objects, while child_class_next() iterates over all possible child classes. E.g. if an AVCodecContext was initialized to use a codec which has private options, then its child_next() will return AVCodecContext.priv_data and finish iterating. OTOH child_class_next() on AVCodecContext.av_class will iterate over all available codecs with private options.

Named constants

It is possible to create named constants for options. Simply set the unit field of the option the constants should apply to to a string and create the constants themselves as options of type AV_OPT_TYPE_CONST with their unit field set to the same string. Their default_val field should contain the value of the named constant. For example, to add some named constants for the test_flags option above, put the following into the child_opts array:

{ "test_flags", "This is a test option of flags type.",
offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
{ "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" },

Using AVOptions

This section deals with accessing options in an AVOptions-enabled struct. Such structs in Libav are e.g. AVCodecContext in libavcodec or AVFormatContext in libavformat.

Examining AVOptions

The basic functions for examining options are av_opt_next(), which iterates over all options defined for one object, and av_opt_find(), which searches for an option with the given name.

The situation is more complicated with nesting. An AVOptions-enabled struct may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag to av_opt_find() will make the function search children recursively.

For enumerating there are basically two cases. The first is when you want to get all options that may potentially exist on the struct and its children (e.g. when constructing documentation). In that case you should call av_opt_child_class_next() recursively on the parent struct's AVClass. The second case is when you have an already initialized struct with all its children and you want to get all options that can be actually written or read from it. In that case you should call av_opt_child_next() recursively (and av_opt_next() on each result).

Reading and writing AVOptions

When setting options, you often have a string read directly from the user. In such a case, simply passing it to av_opt_set() is enough. For non-string type options, av_opt_set() will parse the string according to the option type.

Similarly av_opt_get() will read any option type and convert it to a string which will be returned. Do not forget that the string is allocated, so you have to free it with av_free().

In some cases it may be more convenient to put all options into an AVDictionary and call av_opt_set_dict() on it. A specific case of this are the format/codec open functions in lavf/lavc which take a dictionary filled with option as a parameter. This allows to set some options that cannot be set otherwise, since e.g. the input file format is not known before the file is actually opened.

Describe the class of an AVClass context structure. That is an arbitrary struct of which the first field is a pointer to an AVClass struct (e.g. AVCodecContext, AVFormatContext etc.).

The name of the class; usually it is the same name as the context structure type to which the AVClass is associated.

A pointer to a function which returns the name of a context instance ctx associated with the class.

a pointer to the first option specified in the class if any or NULL

See Also
av_set_default_options()

LIBAVUTIL_VERSION with which this structure was created. This is used to allow fields to be added without requiring major version bumps everywhere.

Offset in the structure where log_level_offset is stored. 0 means there is no such variable

Offset in the structure where a pointer to the parent context for logging is stored. For example a decoder could pass its AVCodecContext to eval as such a parent context, which an av_log() implementation could then leverage to display the parent context. The offset can be NULL.

Return next AVOptions-enabled child or NULL

Return an AVClass corresponding to the next potential AVOptions-enabled child.

The difference between child_next and this is that child_next iterates over already existing objects, while child_class_next iterates over all possible children.

Something went really wrong and we will crash now.

Something went wrong and recovery is not possible. For example, no header was found for a format which depends on headers or an illegal combination of parameters is used.

Something went wrong and cannot losslessly be recovered. However, not all future data is affected.

Something somehow does not look correct. This may or may not lead to problems. An example would be the use of '-vstrict -2'.

Stuff which is only useful for libav* developers.

Send the specified message to the log if the level is less than or equal to the current av_log_level. By default, all logging messages are sent to stderr. This behavior can be altered by setting a different av_vlog callback function.

Parameters
avclA pointer to an arbitrary struct of which the first field is a pointer to an AVClass struct.
levelThe importance level of the message, lower values signifying higher importance.
fmtThe format string (printf-compatible) that specifies how subsequent arguments are converted to output.
See Also
av_vlog

av_dlog macros Useful to print debug messages that shouldn't get compiled in normally.

Skip repeated messages, this requires the user app to use av_log() instead of (f)printf as the 2 would otherwise interfere and lead to "Last message repeated x times" messages below (f)printf messages with some bad luck. Also to receive the last, "last repeated" line if any, the user app must call av_log(NULL, AV_LOG_QUIET, ""); at the end

AVOptions provide a generic system to declare options on arbitrary structs ("objects"). An option can have a help text, a type and a range of possible values. Options may then be enumerated, read and written to.

Implementing AVOptions

This section describes how to add AVOptions capabilities to a struct.

All AVOptions-related information is stored in an AVClass. Therefore the first member of the struct must be a pointer to an AVClass describing it. The option field of the AVClass must be set to a NULL-terminated static array of AVOptions. Each AVOption must have a non-empty name, a type, a default value and for number-type AVOptions also a range of allowed values. It must also declare an offset in bytes from the start of the struct, where the field associated with this AVOption is located. Other fields in the AVOption struct should also be set when applicable, but are not required.

The following example illustrates an AVOptions-enabled struct:

typedef struct test_struct {
AVClass *class;
int int_opt;
char *str_opt;
uint8_t *bin_opt;
int bin_len;
} test_struct;
static const AVOption options[] = {
{ "test_int", "This is a test option of int type.", offsetof(test_struct, int_opt),
AV_OPT_TYPE_INT, { .i64 = -1 }, INT_MIN, INT_MAX },
{ "test_str", "This is a test option of string type.", offsetof(test_struct, str_opt),
{ "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
{ NULL },
};
static const AVClass test_class = {
.class_name = "test class",
.item_name = av_default_item_name,
.option = options,
};

Next, when allocating your struct, you must ensure that the AVClass pointer is set to the correct value. Then, av_opt_set_defaults() must be called to initialize defaults. After that the struct is ready to be used with the AVOptions API.

When cleaning up, you may use the av_opt_free() function to automatically free all the allocated string and binary options.

Continuing with the above example:

test_struct *alloc_test_struct(void)
{
test_struct *ret = av_malloc(sizeof(*ret));
ret->class = &test_class;
return ret;
}
void free_test_struct(test_struct **foo)
{
av_opt_free(*foo);
av_freep(foo);
}

Nesting

It may happen that an AVOptions-enabled struct contains another AVOptions-enabled struct as a member (e.g. AVCodecContext in libavcodec exports generic options, while its priv_data field exports codec-specific options). In such a case, it is possible to set up the parent struct to export a child's options. To do that, simply implement AVClass.child_next() and AVClass.child_class_next() in the parent struct's AVClass. Assuming that the test_struct from above now also contains a child_struct field:

typedef struct child_struct {
AVClass *class;
int flags_opt;
} child_struct;
static const AVOption child_opts[] = {
{ "test_flags", "This is a test option of flags type.",
offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX },
{ NULL },
};
static const AVClass child_class = {
.class_name = "child class",
.item_name = av_default_item_name,
.option = child_opts,
};
void *child_next(void *obj, void *prev)
{
test_struct *t = obj;
if (!prev && t->child_struct)
return t->child_struct;
return NULL
}
const AVClass child_class_next(const AVClass *prev)
{
return prev ? NULL : &child_class;
}

Putting child_next() and child_class_next() as defined above into test_class will now make child_struct's options accessible through test_struct (again, proper setup as described above needs to be done on child_struct right after it is created).

From the above example it might not be clear why both child_next() and child_class_next() are needed. The distinction is that child_next() iterates over actually existing objects, while child_class_next() iterates over all possible child classes. E.g. if an AVCodecContext was initialized to use a codec which has private options, then its child_next() will return AVCodecContext.priv_data and finish iterating. OTOH child_class_next() on AVCodecContext.av_class will iterate over all available codecs with private options.

Named constants

It is possible to create named constants for options. Simply set the unit field of the option the constants should apply to to a string and create the constants themselves as options of type AV_OPT_TYPE_CONST with their unit field set to the same string. Their default_val field should contain the value of the named constant. For example, to add some named constants for the test_flags option above, put the following into the child_opts array:

{ "test_flags", "This is a test option of flags type.",
offsetof(child_struct, flags_opt), AV_OPT_TYPE_FLAGS, { .i64 = 0 }, INT_MIN, INT_MAX, "test_unit" },
{ "flag1", "This is a flag with value 16", 0, AV_OPT_TYPE_CONST, { .i64 = 16 }, 0, 0, "test_unit" },

Using AVOptions

This section deals with accessing options in an AVOptions-enabled struct. Such structs in Libav are e.g. AVCodecContext in libavcodec or AVFormatContext in libavformat.

Examining AVOptions

The basic functions for examining options are av_opt_next(), which iterates over all options defined for one object, and av_opt_find(), which searches for an option with the given name.

The situation is more complicated with nesting. An AVOptions-enabled struct may have AVOptions-enabled children. Passing the AV_OPT_SEARCH_CHILDREN flag to av_opt_find() will make the function search children recursively.

For enumerating there are basically two cases. The first is when you want to get all options that may potentially exist on the struct and its children (e.g. when constructing documentation). In that case you should call av_opt_child_class_next() recursively on the parent struct's AVClass. The second case is when you have an already initialized struct with all its children and you want to get all options that can be actually written or read from it. In that case you should call av_opt_child_next() recursively (and av_opt_next() on each result).

Reading and writing AVOptions

When setting options, you often have a string read directly from the user. In such a case, simply passing it to av_opt_set() is enough. For non-string type options, av_opt_set() will parse the string according to the option type.

Similarly av_opt_get() will read any option type and convert it to a string which will be returned. Do not forget that the string is allocated, so you have to free it with av_free().

In some cases it may be more convenient to put all options into an AVDictionary and call av_opt_set_dict() on it. A specific case of this are the format/codec open functions in lavf/lavc which take a dictionary filled with option as a parameter. This allows to set some options that cannot be set otherwise, since e.g. the input file format is not known before the file is actually opened.

Macro Definition Documentation

#define AV_OPT_SEARCH_CHILDREN   0x0001

Search in possible children of the given object first.

Definition at line 371 of file opt.h.

#define AV_OPT_SEARCH_FAKE_OBJ   0x0002

The obj passed to av_opt_find() is fake – only a double pointer to AVClass instead of a required pointer to a struct containing AVClass.

This is useful for searching for options without needing to allocate the corresponding object.

Definition at line 380 of file opt.h.

Typedef Documentation

typedef struct AVOption AVOption

Enumeration Type Documentation

Enumerator
AV_OPT_TYPE_FLAGS 
AV_OPT_TYPE_INT 
AV_OPT_TYPE_INT64 
AV_OPT_TYPE_DOUBLE 
AV_OPT_TYPE_FLOAT 
AV_OPT_TYPE_STRING 
AV_OPT_TYPE_RATIONAL 
AV_OPT_TYPE_BINARY 

offset must point to a pointer immediately followed by an int for the length

AV_OPT_TYPE_CONST 

Definition at line 218 of file opt.h.

Function Documentation

const AVClass* av_opt_child_class_next ( const AVClass parent,
const AVClass prev 
)

Iterate over potential AVOptions-enabled children of parent.

Parameters
prevresult of a previous call to this function or NULL
Returns
AVClass corresponding to next potential child or NULL

Definition at line 686 of file opt.c.

Referenced by av_opt_find2(), and show_help_children().

void* av_opt_child_next ( void obj,
void prev 
)

Iterate over AVOptions-enabled children of obj.

Parameters
prevresult of a previous call to this function or NULL
Returns
next AVOptions-enabled child or NULL

Definition at line 678 of file opt.c.

Referenced by av_opt_find2().

const AVOption* av_opt_find ( void obj,
const char *  name,
const char *  unit,
int  opt_flags,
int  search_flags 
)

Look for an option in an object.

Consider only options which have all the specified flags set.

Parameters
[in]objA pointer to a struct whose first element is a pointer to an AVClass. Alternatively a double pointer to an AVClass, if AV_OPT_SEARCH_FAKE_OBJ search flag is set.
[in]nameThe name of the option to look for.
[in]unitWhen searching for named constants, name of the unit it belongs to.
opt_flagsFind only options with all the specified flags set (AV_OPT_FLAG).
search_flagsA combination of AV_OPT_SEARCH_*.
Returns
A pointer to the option found, or NULL if no option was found.
Note
Options found with AV_OPT_SEARCH_CHILDREN flag may not be settable directly with av_set_string3(). Use special calls which take an options AVDictionary (e.g. avformat_open_input()) to set options found with this flag.

Definition at line 636 of file opt.c.

Referenced by av_opt_flag_is_set(), avserver_opt_default(), filter_codec_opts(), init(), open_input_file(), opt_default(), and set_string_number().

const AVOption* av_opt_find2 ( void obj,
const char *  name,
const char *  unit,
int  opt_flags,
int  search_flags,
void **  target_obj 
)

Look for an option in an object.

Consider only options which have all the specified flags set.

Parameters
[in]objA pointer to a struct whose first element is a pointer to an AVClass. Alternatively a double pointer to an AVClass, if AV_OPT_SEARCH_FAKE_OBJ search flag is set.
[in]nameThe name of the option to look for.
[in]unitWhen searching for named constants, name of the unit it belongs to.
opt_flagsFind only options with all the specified flags set (AV_OPT_FLAG).
search_flagsA combination of AV_OPT_SEARCH_*.
[out]target_objif non-NULL, an object to which the option belongs will be written here. It may be different from obj if AV_OPT_SEARCH_CHILDREN is present in search_flags. This parameter is ignored if search_flags contain AV_OPT_SEARCH_FAKE_OBJ.
Returns
A pointer to the option found, or NULL if no option was found.

Definition at line 642 of file opt.c.

Referenced by av_opt_find(), av_opt_find2(), av_opt_get(), av_opt_set(), av_opt_set_bin(), get_number(), and set_number().

int av_opt_flag_is_set ( void obj,
const char *  field_name,
const char *  flag_name 
)

Check whether a particular flag is set in a flags field.

Parameters
field_namethe name of the flag field option
flag_namethe name of the flag to check
Returns
non-zero if the flag is set, zero if the flag isn't set, isn't of the right type, or the flags field doesn't exist.

Definition at line 411 of file opt.c.

Referenced by ff_rtp_get_payload_type().

void av_opt_free ( void obj)

Free all string and binary options in obj.

Definition at line 607 of file opt.c.

Referenced by av_write_trailer(), avcodec_close(), avformat_free_context(), avresample_free(), channelmap_init(), ffurl_close(), init(), init_audio(), and join_init().

const AVOption* av_opt_next ( void obj,
const AVOption prev 
)

Iterate over all AVOptions belonging to obj.

Parameters
objan AVOptions-enabled struct or a double pointer to an AVClass describing it.
prevresult of the previous call to av_opt_next() on this object or NULL
Returns
next AVOption or NULL

Definition at line 37 of file opt.c.

Referenced by av_opt_find2(), av_opt_free(), av_opt_set_defaults(), and opt_list().

void av_opt_set_defaults ( void s)

Set the values of all AVOption fields to their default values.

Parameters
san AVOption-enabled struct (its first member must be a pointer to AVClass)

Definition at line 505 of file opt.c.

Referenced by avcodec_get_context_defaults3(), avcodec_open2(), avformat_get_context_defaults(), avformat_open_input(), avresample_alloc_context(), channelmap_init(), init(), init_audio(), init_common(), init_muxer(), join_init(), sws_alloc_context(), and url_alloc_for_protocol().

int av_opt_set_dict ( void obj,
struct AVDictionary **  options 
)

Definition at line 615 of file opt.c.

Referenced by avcodec_open2(), avformat_open_input(), ffurl_open(), and init_muxer().

int av_opt_show2 ( void obj,
void av_log_obj,
int  req_flags,
int  rej_flags 
)

Show the obj options.

Parameters
req_flagsrequested flags for the options to show. Show only the options for which it is opt->flags & req_flags.
rej_flagsrejected flags for the options to show. Show only the options for which it is !(opt->flags & req_flags).
av_log_objlog context to use for showing the options

Definition at line 493 of file opt.c.

Referenced by show_help_children().

int av_set_options_string ( void ctx,
const char *  opts,
const char *  key_val_sep,
const char *  pairs_sep 
)

Parse the key/value pairs list in opts.

For each key/value pair found, stores the value in the field in ctx that is named like the key. ctx must be an AVClass context, storing is done using AVOptions.

Parameters
key_val_sepa 0-terminated list of characters used to separate key from value
pairs_sepa 0-terminated list of characters used to separate two pairs from each other
Returns
the number of successfully set key/value pairs, or a negative value corresponding to an AVERROR code in case of error: AVERROR(EINVAL) if opts cannot be parsed, the error code issued by av_set_string3() if a key/value pair cannot be set

Definition at line 587 of file opt.c.

Referenced by channelmap_init(), init(), init_audio(), init_common(), and join_init().