FFmpeg  1.2.12
Modules | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
AVOptions
Data Structures

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.
file  avcodec.h
 external API header

Data Structures

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_SEARCH_CHILDREN   0x0001
 Search in possible children of the given object first.
#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.
#define AV_OPT_SEARCH_CHILDREN   0x0001
 Search in possible children of the given object first.
#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.
#define AV_OPT_SEARCH_CHILDREN   0x0001
 Search in possible children of the given object first.
#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.

Typedefs

typedef struct AVOption AVOption
 AVOption.
typedef struct AVOptionRange AVOptionRange
 A single allowed range of values, or a single allowed value.
typedef struct AVOptionRanges AVOptionRanges
 List of AVOptionRange structs.
typedef struct AVOption AVOption
 AVOption.
typedef struct AVOptionRange AVOptionRange
 A single allowed range of values, or a single allowed value.
typedef struct AVOptionRanges AVOptionRanges
 List of AVOptionRange structs.
typedef struct AVOption AVOption
 AVOption.
typedef struct AVOptionRange AVOptionRange
 A single allowed range of values, or a single allowed value.
typedef struct AVOptionRanges AVOptionRanges
 List of AVOptionRange structs.

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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
  FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE,
  FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY,
  FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
  AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64,
  FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL,
  FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'),
  AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT,
  FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING,
  FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128
}
enum  { AV_OPT_FLAG_IMPLICIT_KEY = 1 }
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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
  FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE,
  FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY,
  FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
  AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64,
  FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL,
  FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'),
  AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT,
  FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING,
  FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128
}
enum  { AV_OPT_FLAG_IMPLICIT_KEY = 1 }
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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'),
  FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE,
  FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY,
  FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'), AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'),
  AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT, FF_OPT_TYPE_INT64,
  FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING, FF_OPT_TYPE_RATIONAL,
  FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128, 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, AV_OPT_TYPE_IMAGE_SIZE = MKBETAG('S','I','Z','E'),
  AV_OPT_TYPE_PIXEL_FMT = MKBETAG('P','F','M','T'), AV_OPT_TYPE_SAMPLE_FMT = MKBETAG('S','F','M','T'), FF_OPT_TYPE_FLAGS = 0, FF_OPT_TYPE_INT,
  FF_OPT_TYPE_INT64, FF_OPT_TYPE_DOUBLE, FF_OPT_TYPE_FLOAT, FF_OPT_TYPE_STRING,
  FF_OPT_TYPE_RATIONAL, FF_OPT_TYPE_BINARY, FF_OPT_TYPE_CONST = 128
}
enum  { AV_OPT_FLAG_IMPLICIT_KEY = 1 }

Functions

attribute_deprecated const
AVOption
av_find_opt (void *obj, const char *name, const char *unit, int mask, int flags)
 Look for an option in obj.
attribute_deprecated int av_set_string3 (void *obj, const char *name, const char *val, int alloc, const AVOption **o_out)
 Set the field of obj with the given name to value.
attribute_deprecated const
AVOption
av_set_double (void *obj, const char *name, double n)
attribute_deprecated const
AVOption
av_set_q (void *obj, const char *name, AVRational n)
attribute_deprecated const
AVOption
av_set_int (void *obj, const char *name, int64_t n)
double av_get_double (void *obj, const char *name, const AVOption **o_out)
AVRational av_get_q (void *obj, const char *name, const AVOption **o_out)
int64_t av_get_int (void *obj, const char *name, const AVOption **o_out)
attribute_deprecated const char * av_get_string (void *obj, const char *name, const AVOption **o_out, char *buf, int buf_len)
attribute_deprecated const
AVOption
av_next_option (void *obj, const AVOption *last)
int av_opt_show2 (void *obj, void *av_log_obj, int req_flags, int rej_flags)
 Show the obj options.
void av_opt_set_defaults (void *s)
 Set the values of all AVOption fields to their default values.
attribute_deprecated 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)
 Parse the key/value pairs list in 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)
 Parse the key-value pairs list in opts.
void av_opt_free (void *obj)
 Free all string and binary options in obj.
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.
int av_opt_set_dict (void *obj, struct AVDictionary **options)
 Set all the options from a given dictionary on an object.
int av_opt_get_key_value (const char **ropts, const char *key_val_sep, const char *pairs_sep, unsigned flags, char **rkey, char **rval)
 Extract a key-value pair from the beginning of a string.
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.
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.
const AVOptionav_opt_next (void *obj, const AVOption *prev)
 Iterate over all AVOptions belonging to obj.
voidav_opt_child_next (void *obj, void *prev)
 Iterate over AVOptions-enabled children of obj.
const AVClassav_opt_child_class_next (const AVClass *parent, const AVClass *prev)
 Iterate over potential AVOptions-enabled children of parent.
voidav_opt_ptr (const AVClass *avclass, void *obj, const char *name)
 Gets a pointer to the requested field in a struct.
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.

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 {
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() 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_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 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_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.

Disable warnings about deprecated features This is useful for sections of code kept for backward compatibility and scheduled for removal.

Mark a variable as used and prevent the compiler from optimizing it away. This is useful for variables accessed only from inline assembler without the compiler being aware.

Audio Sample Formats

The data described by the sample format is always in native-endian order. Sample values can be expressed by native C types, hence the lack of a signed 24-bit sample format even though it is a common raw audio data format.
The floating-point formats are based on full volume being in the range [-1.0, 1.0]. Any values outside this range are beyond full volume level.
The data layout as used in av_samples_fill_arrays() and elsewhere in FFmpeg (such as AVFrame in libavcodec) is as follows:

For planar sample formats, each audio channel is in a separate data plane, and linesize is the buffer size, in bytes, for a single plane. All data planes must be the same size. For packed sample formats, only the first data plane is used, and samples for each channel are interleaved. In this case, linesize is the buffer size, in bytes, for the 1 plane.

< unsigned 8 bits

< signed 16 bits

< signed 32 bits

< float

< double

< unsigned 8 bits, planar

< signed 16 bits, planar

< signed 32 bits, planar

< float, planar

< double, planar

< Number of sample formats. DO NOT USE if linking dynamically

Return the name of sample_fmt, or NULL if sample_fmt is not recognized.

Return a sample format corresponding to name, or AV_SAMPLE_FMT_NONE on error.

Return the planar<->packed alternative form of the given sample format, or AV_SAMPLE_FMT_NONE on error. If the passed sample_fmt is already in the requested planar/packed format, the format returned is the same as the input.

Get the packed alternative form of the given sample format.

If the passed sample_fmt is already in packed format, the format returned is the same as the input.

Returns
the packed alternative form of the given sample format or AV_SAMPLE_FMT_NONE on error.

Get the planar alternative form of the given sample format.

If the passed sample_fmt is already in planar format, the format returned is the same as the input.

Returns
the planar alternative form of the given sample format or AV_SAMPLE_FMT_NONE on error.

Generate a string corresponding to the sample format with sample_fmt, or a header if sample_fmt is negative.

Parameters
bufthe buffer where to write the string
buf_sizethe size of buf
sample_fmtthe number of the sample format to print the corresponding info string, or a negative value to print the corresponding header.
Returns
the pointer to the filled buffer or NULL if sample_fmt is unknown or in case of other errors
Deprecated:
Use av_get_bytes_per_sample() instead.

Return number of bytes per sample.

Parameters
sample_fmtthe sample format
Returns
number of bytes per sample or zero if unknown for the given sample format

Check if the sample format is planar.

Parameters
sample_fmtthe sample format to inspect
Returns
1 if the sample format is planar, 0 if it is interleaved

Get the required buffer size for the given audio parameters.

Parameters
[out]linesizecalculated linesize, may be NULL
nb_channelsthe number of channels
nb_samplesthe number of samples in a single channel
sample_fmtthe sample format
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
required buffer size, or negative error code on failure

Fill plane data pointers and linesize for samples with sample format sample_fmt.

The audio_data array is filled with the pointers to the samples data planes: for planar, set the start point of each channel's data within the buffer, for packed, set the start point of the entire buffer only.

The value pointed to by linesize is set to the aligned size of each channel's data buffer for planar layout, or to the aligned size of the buffer for all channels for packed layout.

The buffer in buf must be big enough to contain all the samples (use av_samples_get_buffer_size() to compute its minimum size), otherwise the audio_data pointers will point to invalid data.

See Also
enum AVSampleFormat The documentation for AVSampleFormat describes the data layout.
Parameters
[out]audio_dataarray to be filled with the pointer for each channel
[out]linesizecalculated linesize, may be NULL
bufthe pointer to a buffer containing the samples
nb_channelsthe number of channels
nb_samplesthe number of samples in a single channel
sample_fmtthe sample format
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
>=0 on success or a negative error code on failure
Todo:
return minimum size in bytes required for the buffer in case of success at the next bump

Allocate a samples buffer for nb_samples samples, and fill data pointers and linesize accordingly. The allocated samples buffer can be freed by using av_freep(&audio_data[0]) Allocated data will be initialized to silence.

See Also
enum AVSampleFormat The documentation for AVSampleFormat describes the data layout.
Parameters
[out]audio_dataarray to be filled with the pointer for each channel
[out]linesizealigned size for audio buffer(s), may be NULL
nb_channelsnumber of audio channels
nb_samplesnumber of samples per channel
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
>=0 on success or a negative error code on failure
Todo:
return the size of the allocated buffer in case of success at the next bump
See Also
av_samples_fill_arrays()

Copy samples from src to dst.

Parameters
dstdestination array of pointers to data planes
srcsource array of pointers to data planes
dst_offsetoffset in samples at which the data will be written to dst
src_offsetoffset in samples at which the data will be read from src
nb_samplesnumber of samples to be copied
nb_channelsnumber of audio channels
sample_fmtaudio sample format

Fill an audio buffer with silence.

Parameters
audio_dataarray of pointers to data planes
offsetoffset in samples at which to start filling
nb_samplesnumber of samples to fill
nb_channelsnumber of audio channels
sample_fmtaudio sample format

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 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 {
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() 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_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 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_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.

Disable warnings about deprecated features This is useful for sections of code kept for backward compatibility and scheduled for removal.

Mark a variable as used and prevent the compiler from optimizing it away. This is useful for variables accessed only from inline assembler without the compiler being aware.

Audio Sample Formats

The data described by the sample format is always in native-endian order. Sample values can be expressed by native C types, hence the lack of a signed 24-bit sample format even though it is a common raw audio data format.
The floating-point formats are based on full volume being in the range [-1.0, 1.0]. Any values outside this range are beyond full volume level.
The data layout as used in av_samples_fill_arrays() and elsewhere in FFmpeg (such as AVFrame in libavcodec) is as follows:

For planar sample formats, each audio channel is in a separate data plane, and linesize is the buffer size, in bytes, for a single plane. All data planes must be the same size. For packed sample formats, only the first data plane is used, and samples for each channel are interleaved. In this case, linesize is the buffer size, in bytes, for the 1 plane.

< unsigned 8 bits

< signed 16 bits

< signed 32 bits

< float

< double

< unsigned 8 bits, planar

< signed 16 bits, planar

< signed 32 bits, planar

< float, planar

< double, planar

< Number of sample formats. DO NOT USE if linking dynamically

Return the name of sample_fmt, or NULL if sample_fmt is not recognized.

Return a sample format corresponding to name, or AV_SAMPLE_FMT_NONE on error.

Return the planar<->packed alternative form of the given sample format, or AV_SAMPLE_FMT_NONE on error. If the passed sample_fmt is already in the requested planar/packed format, the format returned is the same as the input.

Get the packed alternative form of the given sample format.

If the passed sample_fmt is already in packed format, the format returned is the same as the input.

Returns
the packed alternative form of the given sample format or AV_SAMPLE_FMT_NONE on error.

Get the planar alternative form of the given sample format.

If the passed sample_fmt is already in planar format, the format returned is the same as the input.

Returns
the planar alternative form of the given sample format or AV_SAMPLE_FMT_NONE on error.

Generate a string corresponding to the sample format with sample_fmt, or a header if sample_fmt is negative.

Parameters
bufthe buffer where to write the string
buf_sizethe size of buf
sample_fmtthe number of the sample format to print the corresponding info string, or a negative value to print the corresponding header.
Returns
the pointer to the filled buffer or NULL if sample_fmt is unknown or in case of other errors
Deprecated:
Use av_get_bytes_per_sample() instead.

Return number of bytes per sample.

Parameters
sample_fmtthe sample format
Returns
number of bytes per sample or zero if unknown for the given sample format

Check if the sample format is planar.

Parameters
sample_fmtthe sample format to inspect
Returns
1 if the sample format is planar, 0 if it is interleaved

Get the required buffer size for the given audio parameters.

Parameters
[out]linesizecalculated linesize, may be NULL
nb_channelsthe number of channels
nb_samplesthe number of samples in a single channel
sample_fmtthe sample format
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
required buffer size, or negative error code on failure

Fill plane data pointers and linesize for samples with sample format sample_fmt.

The audio_data array is filled with the pointers to the samples data planes: for planar, set the start point of each channel's data within the buffer, for packed, set the start point of the entire buffer only.

The value pointed to by linesize is set to the aligned size of each channel's data buffer for planar layout, or to the aligned size of the buffer for all channels for packed layout.

The buffer in buf must be big enough to contain all the samples (use av_samples_get_buffer_size() to compute its minimum size), otherwise the audio_data pointers will point to invalid data.

See Also
enum AVSampleFormat The documentation for AVSampleFormat describes the data layout.
Parameters
[out]audio_dataarray to be filled with the pointer for each channel
[out]linesizecalculated linesize, may be NULL
bufthe pointer to a buffer containing the samples
nb_channelsthe number of channels
nb_samplesthe number of samples in a single channel
sample_fmtthe sample format
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
>=0 on success or a negative error code on failure
Todo:
return minimum size in bytes required for the buffer in case of success at the next bump

Allocate a samples buffer for nb_samples samples, and fill data pointers and linesize accordingly. The allocated samples buffer can be freed by using av_freep(&audio_data[0]) Allocated data will be initialized to silence.

See Also
enum AVSampleFormat The documentation for AVSampleFormat describes the data layout.
Parameters
[out]audio_dataarray to be filled with the pointer for each channel
[out]linesizealigned size for audio buffer(s), may be NULL
nb_channelsnumber of audio channels
nb_samplesnumber of samples per channel
alignbuffer size alignment (0 = default, 1 = no alignment)
Returns
>=0 on success or a negative error code on failure
Todo:
return the size of the allocated buffer in case of success at the next bump
See Also
av_samples_fill_arrays()

Copy samples from src to dst.

Parameters
dstdestination array of pointers to data planes
srcsource array of pointers to data planes
dst_offsetoffset in samples at which the data will be written to dst
src_offsetoffset in samples at which the data will be read from src
nb_samplesnumber of samples to be copied
nb_channelsnumber of audio channels
sample_fmtaudio sample format

Fill an audio buffer with silence.

Parameters
audio_dataarray of pointers to data planes
offsetoffset in samples at which to start filling
nb_samplesnumber of samples to fill
nb_channelsnumber of audio channels
sample_fmtaudio sample format

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 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 {
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() 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_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 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_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 536 of file opt.h.

Referenced by av_get_string(), av_opt_find2(), av_probe_input_buffer(), ff_rtp_chain_mux_open(), and opt_default().

#define AV_OPT_SEARCH_CHILDREN   0x0001

Search in possible children of the given object first.

Definition at line 536 of file opt.h.

#define AV_OPT_SEARCH_CHILDREN   0x0001

Search in possible children of the given object first.

Definition at line 536 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 544 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 544 of file opt.h.

Referenced by av_opt_find2(), av_opt_ptr(), filter_codec_opts(), init(), open_input_file(), opt_default(), and opt_list().

#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 544 of file opt.h.

Typedef Documentation

typedef struct AVOption AVOption
typedef struct AVOption AVOption
typedef struct AVOption AVOption
typedef struct AVOptionRange AVOptionRange

A single allowed range of values, or a single allowed value.

typedef struct AVOptionRange AVOptionRange

A single allowed range of values, or a single allowed value.

typedef struct AVOptionRange AVOptionRange

A single allowed range of values, or a single allowed value.

List of AVOptionRange structs.

List of AVOptionRange structs.

List of AVOptionRange structs.

Enumeration Type Documentation

anonymous enum
Enumerator:
AV_OPT_FLAG_IMPLICIT_KEY 

Accept to parse a value without a key; the key will then be returned as NULL.

Definition at line 503 of file opt.h.

anonymous enum
Enumerator:
AV_OPT_FLAG_IMPLICIT_KEY 

Accept to parse a value without a key; the key will then be returned as NULL.

Definition at line 503 of file opt.h.

anonymous enum
Enumerator:
AV_OPT_FLAG_IMPLICIT_KEY 

Accept to parse a value without a key; the key will then be returned as NULL.

Definition at line 503 of file opt.h.

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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 

Definition at line 220 of file opt.h.

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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 

Definition at line 220 of file opt.h.

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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 
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 
AV_OPT_TYPE_IMAGE_SIZE 

offset must point to two consecutive integers

AV_OPT_TYPE_PIXEL_FMT 
AV_OPT_TYPE_SAMPLE_FMT 
FF_OPT_TYPE_FLAGS 
FF_OPT_TYPE_INT 
FF_OPT_TYPE_INT64 
FF_OPT_TYPE_DOUBLE 
FF_OPT_TYPE_FLOAT 
FF_OPT_TYPE_STRING 
FF_OPT_TYPE_RATIONAL 
FF_OPT_TYPE_BINARY 

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

FF_OPT_TYPE_CONST 

Definition at line 220 of file opt.h.

Function Documentation

attribute_deprecated const AVOption * av_find_opt ( void obj,
const char *  name,
const char *  unit,
int  mask,
int  flags 
)

Look for an option in obj.

Look only for the options which have the flags set as specified in mask and flags (that is, for which it is the case that opt->flags & mask == flags).

Parameters
[in]obja pointer to a struct whose first element is a pointer to an AVClass
[in]namethe name of the option to look for
[in]unitthe unit of the option to look for, or any if NULL
Returns
a pointer to the option found, or NULL if no option has been found
Deprecated:
use av_opt_find.

Look only for the options which have the flags set as specified in mask and flags (that is, for which it is the case that opt->flags & mask == flags).

Parameters
[in]obja pointer to a struct whose first element is a pointer to an AVClass
[in]namethe name of the option to look for
[in]unitthe unit of the option to look for, or any if NULL
Returns
a pointer to the option found, or NULL if no option has been found
Deprecated:
use av_opt_find.

Look only for the options which have the flags set as specified in mask and flags (that is, for which it is the case that opt->flags & mask == flags).

Parameters
[in]obja pointer to a struct whose first element is a pointer to an AVClass
[in]namethe name of the option to look for
[in]unitthe unit of the option to look for, or any if NULL
Returns
a pointer to the option found, or NULL if no option has been found
Deprecated:
use av_opt_find.

Definition at line 44 of file opt.c.

double av_get_double ( void obj,
const char *  name,
const AVOption **  o_out 
)

Definition at line 605 of file opt.c.

int64_t av_get_int ( void obj,
const char *  name,
const AVOption **  o_out 
)

Definition at line 630 of file opt.c.

Referenced by config_output(), and query_formats().

AVRational av_get_q ( void obj,
const char *  name,
const AVOption **  o_out 
)

Definition at line 616 of file opt.c.

attribute_deprecated const char * av_get_string ( void obj,
const char *  name,
const AVOption **  o_out,
char *  buf,
int  buf_len 
)
Parameters
bufa buffer which is used for returning non string values as strings, can be NULL
buf_lenallocated length in bytes of buf

Definition at line 494 of file opt.c.

attribute_deprecated const AVOption * av_next_option ( void obj,
const AVOption last 
)

Definition at line 57 of file opt.c.

Referenced by av_find_opt(), print_option(), and show_opts().

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 1200 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 1192 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 1145 of file opt.c.

Referenced by av_get_string(), av_opt_flag_is_set(), av_opt_query_ranges_default(), av_set_double(), av_set_int(), av_set_q(), av_set_string3(), ffserver_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 1151 of file opt.c.

Referenced by av_opt_find(), av_opt_find2(), av_opt_get(), av_opt_get_image_size(), av_opt_ptr(), av_opt_set(), av_opt_set_bin(), av_opt_set_image_size(), get_format(), get_number(), set_format(), 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 728 of file opt.c.

Referenced by ff_rtp_get_payload_type().

void av_opt_free ( void obj)
void av_opt_freep_ranges ( AVOptionRanges **  ranges)

Free an AVOptionRanges struct and set it to NULL.

Definition at line 1289 of file opt.c.

Referenced by opt_list().

int av_opt_get_key_value ( const char **  ropts,
const char *  key_val_sep,
const char *  pairs_sep,
unsigned  flags,
char **  rkey,
char **  rval 
)

Extract a key-value pair from the beginning of a string.

Parameters
roptspointer to the options string, will be updated to point to the rest of the string (one of the pairs_sep or the final NUL)
key_val_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
flagsflags; see the AV_OPT_FLAG_* values below
rkeyparsed key; must be freed using av_free()
rvalparsed value; must be freed using av_free()
Returns
>=0 for success, or a negative value corresponding to an AVERROR code in case of error; in particular: AVERROR(EINVAL) if no key is present

Definition at line 1042 of file opt.c.

Referenced by av_opt_set_from_string(), init_report(), and parse_slave_options().

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 63 of file opt.c.

Referenced by av_next_option(), av_opt_find2(), av_opt_free(), av_opt_set_defaults2(), opt_list(), and show_stream().

void * av_opt_ptr ( const AVClass avclass,
void obj,
const char *  name 
)

Gets a pointer to the requested field in a struct.

This function allows accessing a struct even when its fields are moved or renamed since the application making the access has been compiled,

Returns
a pointer to the field, it can be cast to the correct type and read or written to.

Definition at line 1207 of file opt.c.

Referenced by decode_video().

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

The result must be freed with av_opt_freep_ranges.

Returns
>= 0 on success, a negative errro code otherwise

Definition at line 1215 of file opt.c.

Referenced by opt_list().

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

The result must be freed with av_opt_free_ranges.

Returns
>= 0 on success, a negative errro code otherwise

Definition at line 1229 of file opt.c.

Referenced by av_opt_query_ranges().

void av_opt_set_defaults ( void s)
attribute_deprecated void av_opt_set_defaults2 ( void s,
int  mask,
int  flags 
)

Definition at line 879 of file opt.c.

Referenced by av_opt_set_defaults(), and avcodec_get_context_defaults3().

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

Set all the options from a given dictionary on an object.

Parameters
obja struct whose first element is a pointer to AVClass
optionsoptions to process. This dictionary will be freed and replaced by a new one containing all options not found in obj. Of course this new dictionary needs to be freed by caller with av_dict_free().
Returns
0 on success, a negative AVERROR if some option was found in obj, but could not be set.
See Also
av_dict_copy()

Definition at line 1124 of file opt.c.

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

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

Parse the key-value pairs list in opts.

For each key=value pair found, set the value of the corresponding option in ctx.

Parameters
ctxthe AVClass object to set options on
optsthe options string, key-value pairs separated by a delimiter
shorthanda NULL-terminated array of options names for shorthand notation: if the first field in opts has no key part, the key is taken from the first element of shorthand; then again for the second, etc., until either opts is finished, shorthand is finished or a named option is found; after that, all options must be named
key_val_sepa 0-terminated list of characters used to separate key from value, for example '='
pairs_sepa 0-terminated list of characters used to separate two pairs from each other, for example ':' or ','
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

Options names must use only the following characters: a-z A-Z 0-9 - . / _ Separators must use characters distinct from option names and from each other.

Definition at line 1064 of file opt.c.

Referenced by geq_init(), init(), and set_options().

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 861 of file opt.c.

Referenced by show_help_children().

attribute_deprecated const AVOption * av_set_double ( void obj,
const char *  name,
double  n 
)

Definition at line 350 of file opt.c.

attribute_deprecated const AVOption * av_set_int ( void obj,
const char *  name,
int64_t  n 
)

Definition at line 366 of file opt.c.

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
optsoptions string to parse, may be NULL
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 984 of file opt.c.

Referenced by channelmap_init(), init(), init_audio(), init_video(), join_init(), movie_common_init(), and writer_open().

attribute_deprecated const AVOption * av_set_q ( void obj,
const char *  name,
AVRational  n 
)

Definition at line 358 of file opt.c.

attribute_deprecated int av_set_string3 ( void obj,
const char *  name,
const char *  val,
int  alloc,
const AVOption **  o_out 
)

Set the field of obj with the given name to value.

Parameters
[in]objA struct whose first element is a pointer to an AVClass.
[in]namethe name of the field to set
[in]valThe value to set. If the field is not of a string type, then the given string is parsed. SI postfixes and some named scalars are supported. If the field is of a numeric type, it has to be a numeric or named scalar. Behavior with more than one scalar and +- infix operators is undefined. If the field is of a flags type, it has to be a sequence of numeric scalars or named flags separated by '+' or '-'. Prefixing a flag with '+' causes it to be set without affecting the other flags; similarly, '-' unsets a flag.
[out]o_outif non-NULL put here a pointer to the AVOption found
allocthis parameter is currently ignored
Returns
0 if the value has been set, or an AVERROR code in case of error: AVERROR_OPTION_NOT_FOUND if no matching option exists AVERROR(ERANGE) if the value is out of range AVERROR(EINVAL) if the value is not valid
Deprecated:
use av_opt_set()
Parameters
[in]objA struct whose first element is a pointer to an AVClass.
[in]namethe name of the field to set
[in]valThe value to set. If the field is not of a string type, then the given string is parsed. SI postfixes and some named scalars are supported. If the field is of a numeric type, it has to be a numeric or named scalar. Behavior with more than one scalar and +- infix operators is undefined. If the field is of a flags type, it has to be a sequence of numeric scalars or named flags separated by '+' or '-'. Prefixing a flag with '+' causes it to be set without affecting the other flags; similarly, '-' unsets a flag.
[out]o_outif non-NULL put here a pointer to the AVOption found
allocthis parameter is currently ignored
Returns
0 if the value has been set, or an AVERROR code in case of error: AVERROR_OPTION_NOT_FOUND if no matching option exists AVERROR(ERANGE) if the value is out of range AVERROR(EINVAL) if the value is not valid
Deprecated:
use av_opt_set()
Parameters
[in]objA struct whose first element is a pointer to an AVClass.
[in]namethe name of the field to set
[in]valThe value to set. If the field is not of a string type, then the given string is parsed. SI postfixes and some named scalars are supported. If the field is of a numeric type, it has to be a numeric or named scalar. Behavior with more than one scalar and +- infix operators is undefined. If the field is of a flags type, it has to be a sequence of numeric scalars or named flags separated by '+' or '-'. Prefixing a flag with '+' causes it to be set without affecting the other flags; similarly, '-' unsets a flag.
[out]o_outif non-NULL put here a pointer to the AVOption found
allocthis parameter is currently ignored
Returns
0 if the value has been set, or an AVERROR code in case of error: AVERROR_OPTION_NOT_FOUND if no matching option exists AVERROR(ERANGE) if the value is out of range AVERROR(EINVAL) if the value is not valid
Deprecated:
use av_opt_set()

Definition at line 243 of file opt.c.