FFmpeg
Modules | Data Structures | Macros | Enumerations | Functions

Modules

 AVOption (un)initialization and inspection.
 
 Setting and modifying option values
 
 Reading option values
 

Data Structures

struct  AVOptionArrayDef
 May be set as default_val for AV_OPT_TYPE_FLAG_ARRAY options. More...
 
struct  AVOption
 AVOption. More...
 
struct  AVOptionRange
 A single allowed range of values, or a single allowed value. More...
 
struct  AVOptionRanges
 List of AVOptionRange structs. More...
 

Macros

#define AV_OPT_FLAG_ENCODING_PARAM   (1 << 0)
 A generic parameter which can be set by the user for muxing or encoding. More...
 
#define AV_OPT_FLAG_DECODING_PARAM   (1 << 1)
 A generic parameter which can be set by the user for demuxing or decoding. More...
 
#define AV_OPT_FLAG_AUDIO_PARAM   (1 << 3)
 
#define AV_OPT_FLAG_VIDEO_PARAM   (1 << 4)
 
#define AV_OPT_FLAG_SUBTITLE_PARAM   (1 << 5)
 
#define AV_OPT_FLAG_EXPORT   (1 << 6)
 The option is intended for exporting values to the caller. More...
 
#define AV_OPT_FLAG_READONLY   (1 << 7)
 The option may not be set through the AVOptions API, only read. More...
 
#define AV_OPT_FLAG_BSF_PARAM   (1 << 8)
 A generic parameter which can be set by the user for bit stream filtering. More...
 
#define AV_OPT_FLAG_RUNTIME_PARAM   (1 << 15)
 A generic parameter which can be set by the user at runtime. More...
 
#define AV_OPT_FLAG_FILTERING_PARAM   (1 << 16)
 A generic parameter which can be set by the user for filtering. More...
 
#define AV_OPT_FLAG_DEPRECATED   (1 << 17)
 Set if option is deprecated, users should refer to AVOption.help text for more information. More...
 
#define AV_OPT_FLAG_CHILD_CONSTS   (1 << 18)
 Set if option constants can also reside in child objects. More...
 

Enumerations

enum  AVOptionType {
  AV_OPT_TYPE_FLAGS = 1, 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_DICT, AV_OPT_TYPE_UINT64, AV_OPT_TYPE_CONST, AV_OPT_TYPE_IMAGE_SIZE,
  AV_OPT_TYPE_PIXEL_FMT, AV_OPT_TYPE_SAMPLE_FMT, AV_OPT_TYPE_VIDEO_RATE, AV_OPT_TYPE_DURATION,
  AV_OPT_TYPE_COLOR, AV_OPT_TYPE_BOOL, AV_OPT_TYPE_CHLAYOUT, AV_OPT_TYPE_UINT,
  AV_OPT_TYPE_FLAG_ARRAY = (1 << 16)
}
 An option type determines: More...
 

Functions

void av_opt_freep_ranges (AVOptionRanges **ranges)
 Free an AVOptionRanges struct and set it to NULL. More...
 
int av_opt_query_ranges (AVOptionRanges **, void *obj, const char *key, int flags)
 Get a list of allowed ranges for the given option. More...
 
int av_opt_query_ranges_default (AVOptionRanges **, void *obj, const char *key, int flags)
 Get a default list of allowed ranges for the given option. 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.

There are two modes of access to members of AVOption and its child structs. One is called 'native access', and refers to access from the code that declares the AVOption in question. The other is 'foreign access', and refers to access from other code.

Certain struct members in this header are documented as 'native access only' or similar - it means that only the code that declared the AVOption in question is allowed to access the field. This allows us to extend the semantics of those fields without breaking API compatibility.

Scope of AVOptions

AVOptions is designed to support any set of multimedia configuration options that can be defined at compile-time. Although it is mainly used to expose FFmpeg options, you are welcome to adapt it to your own use case.

No single approach can ever fully solve the problem of configuration, but please submit a patch if you believe you have found a problem that is best solved by extending AVOptions.

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 should 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 {
const AVClass *class;
int int_opt;
char *str_opt;
uint8_t *bin_opt;
int bin_len;
static const AVOption test_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 = test_options,
};

Next, when allocating your struct, you must ensure that the AVClass pointer is set to the correct value. Then, av_opt_set_defaults() can 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_mallocz(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_iterate() 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_iterate(void **iter)
{
const AVClass *c = *iter ? NULL : &child_class;
*iter = (void*)(uintptr_t)c;
return c;
}

Putting child_next() and child_class_iterate() 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_iterate() are needed. The distinction is that child_next() iterates over actually existing objects, while child_class_iterate() 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_iterate() 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 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 FFmpeg 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_iterate() 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 makes it possible 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

◆ AV_OPT_FLAG_ENCODING_PARAM

#define AV_OPT_FLAG_ENCODING_PARAM   (1 << 0)

A generic parameter which can be set by the user for muxing or encoding.

Definition at line 352 of file opt.h.

◆ AV_OPT_FLAG_DECODING_PARAM

#define AV_OPT_FLAG_DECODING_PARAM   (1 << 1)

A generic parameter which can be set by the user for demuxing or decoding.

Definition at line 356 of file opt.h.

◆ AV_OPT_FLAG_AUDIO_PARAM

#define AV_OPT_FLAG_AUDIO_PARAM   (1 << 3)

Definition at line 357 of file opt.h.

◆ AV_OPT_FLAG_VIDEO_PARAM

#define AV_OPT_FLAG_VIDEO_PARAM   (1 << 4)

Definition at line 358 of file opt.h.

◆ AV_OPT_FLAG_SUBTITLE_PARAM

#define AV_OPT_FLAG_SUBTITLE_PARAM   (1 << 5)

Definition at line 359 of file opt.h.

◆ AV_OPT_FLAG_EXPORT

#define AV_OPT_FLAG_EXPORT   (1 << 6)

The option is intended for exporting values to the caller.

Definition at line 363 of file opt.h.

◆ AV_OPT_FLAG_READONLY

#define AV_OPT_FLAG_READONLY   (1 << 7)

The option may not be set through the AVOptions API, only read.

This flag only makes sense when AV_OPT_FLAG_EXPORT is also set.

Definition at line 368 of file opt.h.

◆ AV_OPT_FLAG_BSF_PARAM

#define AV_OPT_FLAG_BSF_PARAM   (1 << 8)

A generic parameter which can be set by the user for bit stream filtering.

Definition at line 372 of file opt.h.

◆ AV_OPT_FLAG_RUNTIME_PARAM

#define AV_OPT_FLAG_RUNTIME_PARAM   (1 << 15)

A generic parameter which can be set by the user at runtime.

Definition at line 377 of file opt.h.

◆ AV_OPT_FLAG_FILTERING_PARAM

#define AV_OPT_FLAG_FILTERING_PARAM   (1 << 16)

A generic parameter which can be set by the user for filtering.

Definition at line 381 of file opt.h.

◆ AV_OPT_FLAG_DEPRECATED

#define AV_OPT_FLAG_DEPRECATED   (1 << 17)

Set if option is deprecated, users should refer to AVOption.help text for more information.

Definition at line 386 of file opt.h.

◆ AV_OPT_FLAG_CHILD_CONSTS

#define AV_OPT_FLAG_CHILD_CONSTS   (1 << 18)

Set if option constants can also reside in child objects.

Definition at line 390 of file opt.h.

Enumeration Type Documentation

◆ AVOptionType

An option type determines:

  • for native access, the underlying C type of the field that an AVOption refers to;
  • for foreign access, the semantics of accessing the option through this API, e.g. which av_opt_get_*() and av_opt_set_*() functions can be called, or what format will av_opt_get()/av_opt_set() expect/produce.
Enumerator
AV_OPT_TYPE_FLAGS 

Underlying C type is unsigned int.

AV_OPT_TYPE_INT 

Underlying C type is int.

AV_OPT_TYPE_INT64 

Underlying C type is int64_t.

AV_OPT_TYPE_DOUBLE 

Underlying C type is double.

AV_OPT_TYPE_FLOAT 

Underlying C type is float.

AV_OPT_TYPE_STRING 

Underlying C type is a uint8_t* that is either NULL or points to a C string allocated with the av_malloc() family of functions.

AV_OPT_TYPE_RATIONAL 

Underlying C type is AVRational.

AV_OPT_TYPE_BINARY 

Underlying C type is a uint8_t* that is either NULL or points to an array allocated with the av_malloc() family of functions.

The pointer is immediately followed by an int containing the array length in bytes.

AV_OPT_TYPE_DICT 

Underlying C type is AVDictionary*.

AV_OPT_TYPE_UINT64 

Underlying C type is uint64_t.

AV_OPT_TYPE_CONST 

Special option type for declaring named constants.

Does not correspond to an actual field in the object, offset must be 0.

AV_OPT_TYPE_IMAGE_SIZE 

Underlying C type is two consecutive integers.

AV_OPT_TYPE_PIXEL_FMT 

Underlying C type is enum AVPixelFormat.

AV_OPT_TYPE_SAMPLE_FMT 

Underlying C type is enum AVSampleFormat.

AV_OPT_TYPE_VIDEO_RATE 

Underlying C type is AVRational.

AV_OPT_TYPE_DURATION 

Underlying C type is int64_t.

AV_OPT_TYPE_COLOR 

Underlying C type is uint8_t[4].

AV_OPT_TYPE_BOOL 

Underlying C type is int.

AV_OPT_TYPE_CHLAYOUT 

Underlying C type is AVChannelLayout.

AV_OPT_TYPE_UINT 

Underlying C type is unsigned int.

AV_OPT_TYPE_FLAG_ARRAY 

May be combined with another regular option type to declare an array option.

For array options, AVOption::offset should refer to a pointer corresponding to the option type. The pointer should be immediately followed by an unsigned int that will store the number of elements in the array.

Definition at line 251 of file opt.h.

Function Documentation

◆ av_opt_freep_ranges()

void av_opt_freep_ranges ( AVOptionRanges **  ranges)

Free an AVOptionRanges struct and set it to NULL.

Definition at line 2560 of file opt.c.

Referenced by opt_list().

◆ av_opt_query_ranges()

int av_opt_query_ranges ( AVOptionRanges **  ,
void *  obj,
const char *  key,
int  flags 
)

Get a list of allowed ranges for the given option.

The returned list may depend on other fields in obj like for example profile.

Parameters
flagsis a bitmask of flags, undefined flags should not be set and should be ignored AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component,
See also
AVOptionRanges

The result must be freed with av_opt_freep_ranges.

Returns
number of compontents returned on success, a negative errro code otherwise

Definition at line 2470 of file opt.c.

Referenced by opt_list().

◆ av_opt_query_ranges_default()

int av_opt_query_ranges_default ( AVOptionRanges **  ,
void *  obj,
const char *  key,
int  flags 
)

Get a default list of allowed ranges for the given option.

This list is constructed without using the AVClass.query_ranges() callback and can be used as fallback from within the callback.

Parameters
flagsis a bitmask of flags, undefined flags should not be set and should be ignored AV_OPT_SEARCH_FAKE_OBJ indicates that the obj is a double pointer to a AVClass instead of a full instance AV_OPT_MULTI_COMPONENT_RANGE indicates that function may return more than one component,
See also
AVOptionRanges

The result must be freed with av_opt_free_ranges.

Returns
number of compontents returned on success, a negative errro code otherwise

Definition at line 2488 of file opt.c.

Referenced by av_opt_query_ranges().

av_opt_set_defaults
void av_opt_set_defaults(void *s)
Set the values of all AVOption fields to their default values.
Definition: opt.c:1678
AVOption
AVOption.
Definition: opt.h:429
AV_OPT_TYPE_BINARY
@ AV_OPT_TYPE_BINARY
Underlying C type is a uint8_t* that is either NULL or points to an array allocated with the av_mallo...
Definition: opt.h:286
av_opt_free
void av_opt_free(void *obj)
Free all allocated objects in obj.
Definition: opt.c:1949
LIBAVUTIL_VERSION_INT
#define LIBAVUTIL_VERSION_INT
Definition: version.h:85
AVClass
Describe the class of an AVClass context structure.
Definition: log.h:75
NULL
#define NULL
Definition: coverity.c:32
child_class
static const AVClass child_class
Definition: opt.c:149
av_default_item_name
const char * av_default_item_name(void *ptr)
Return the context name.
Definition: log.c:237
c
Undefined Behavior In the C some operations are like signed integer dereferencing freed accessing outside allocated Undefined Behavior must not occur in a C it is not safe even if the output of undefined operations is unused The unsafety may seem nit picking but Optimizing compilers have in fact optimized code on the assumption that no undefined Behavior occurs Optimizing code based on wrong assumptions can and has in some cases lead to effects beyond the output of computations The signed integer overflow problem in speed critical code Code which is highly optimized and works with signed integers sometimes has the problem that often the output of the computation does not c
Definition: undefined.txt:32
child_class_iterate
static const AVClass * child_class_iterate(void **iter)
Definition: vf_scale.c:1020
av_mallocz
void * av_mallocz(size_t size)
Allocate a memory block with alignment suitable for all memory accesses (including vectors if availab...
Definition: mem.c:256
ret
ret
Definition: filter_design.txt:187
AVClass::class_name
const char * class_name
The name of the class; usually it is the same name as the context structure type to which the AVClass...
Definition: log.h:80
child_next
static void * child_next(void *obj, void *prev)
Definition: vf_scale.c:1034
AV_OPT_TYPE_INT
@ AV_OPT_TYPE_INT
Underlying C type is int.
Definition: opt.h:259
test_struct
static const TestStruct test_struct[]
Definition: audio_fifo.c:40
test_class
static const AVClass test_class
Definition: opt.c:164
av_freep
#define av_freep(p)
Definition: tableprint_vlc.h:34
AV_OPT_TYPE_FLAGS
@ AV_OPT_TYPE_FLAGS
Underlying C type is unsigned int.
Definition: opt.h:255
AV_OPT_TYPE_STRING
@ AV_OPT_TYPE_STRING
Underlying C type is a uint8_t* that is either NULL or points to a C string allocated with the av_mal...
Definition: opt.h:276
AV_OPT_TYPE_CONST
@ AV_OPT_TYPE_CONST
Special option type for declaring named constants.
Definition: opt.h:299
test_options
static const AVOption test_options[]
Definition: opt.c:89