Loading...
Searching...
No Matches
AVOptions
libavutil » Data Structures

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

## Topics

| 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.
#define | AV_OPT_FLAG_DECODING_PARAM (1 << 1)
| A generic parameter which can be set by the user for demuxing or decoding.
#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.
#define | AV_OPT_FLAG_READONLY (1 << 7)
| The option may not be set through the AVOptions API, only read.
#define | AV_OPT_FLAG_BSF_PARAM (1 << 8)
| A generic parameter which can be set by the user for bit stream filtering.
#define | AV_OPT_FLAG_RUNTIME_PARAM (1 << 15)
| A generic parameter which can be set by the user at runtime.
#define | AV_OPT_FLAG_FILTERING_PARAM (1 << 16)
| A generic parameter which can be set by the user for filtering.
#define | AV_OPT_FLAG_DEPRECATED (1 << 17)
| Set if option is deprecated, users should refer to AVOption.help text for more information.
#define | AV_OPT_FLAG_CHILD_CONSTS (1 << 18)
| Set if option constants can also reside in child objects.

## 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.
int | av_opt_query_ranges (AVOptionRanges **, void *obj, const char *key, int flags)
| Get a list of allowed ranges for the given option.
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.

## 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;
} test_struct;
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),
AV_OPT_TYPE_STRING },
{ "test_bin", "This is a test option of binary type.", offsetof(test_struct, bin_opt),
AV_OPT_TYPE_BINARY },
{ NULL },
};
static const AVClass test_class = {
.class_name = "test class",
.item_name = av_default_item_name,
.option = test_options,
.version = LIBAVUTIL_VERSION_INT,
};
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_TYPE_INT
@ AV_OPT_TYPE_INT
Underlying C type is int.
Definition opt.h:259
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_default_item_name
const char * av_default_item_name(void *ctx)
Return the context name.
LIBAVUTIL_VERSION_INT
#define LIBAVUTIL_VERSION_INT
Definition version.h:85
AVClass
Describe the class of an AVClass context structure.
Definition log.h:76
AVOption
AVOption.
Definition opt.h:429

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;
av_opt_set_defaults(ret);
return ret;
}
void free_test_struct(test_struct **foo)
{
av_opt_free(*foo);
av_freep(foo);
}
av_freep
void av_freep(void *ptr)
Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family,...
av_mallocz
void * av_mallocz(size_t size) av_malloc_attrib
Allocate a memory block with alignment suitable for all memory accesses (including vectors if availab...
av_opt_free
void av_opt_free(void *obj)
Free all allocated objects in obj.
av_opt_set_defaults
void av_opt_set_defaults(void *s)
Set the values of all AVOption fields to their default values.

## 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,
.version = LIBAVUTIL_VERSION_INT,
};
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;
}
AV_OPT_TYPE_FLAGS
@ AV_OPT_TYPE_FLAGS
Underlying C type is unsigned int.
Definition opt.h:255

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" },
AV_OPT_TYPE_CONST
@ AV_OPT_TYPE_CONST
Special option type for declaring named constants.
Definition opt.h:299

# 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

enum 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.

## 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

  flags | is 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 components returned on success, a negative error code otherwise

## 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

  flags | is 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 components returned on success, a negative error code otherwise