Module Avutil.Options

The options of FFmpeg objects: listing the options a kind of object declares, and reading the value of an option on a live object. Options are set when an object is created, through an opts table.

type t

The description of the options of one kind of FFmpeg object (a codec, a format, a filter): an FFmpeg option class, or no class at all. The libraries built on this one return these values; they are valid for the life of the process.

type flag = [
  1. | `Encoding_param
  2. | `Decoding_param
  3. | `Audio_param
  4. | `Video_param
  5. | `Subtitle_param
  6. | `Export
  7. | `Readonly
  8. | `Bsf_param
  9. | `Runtime_param
  10. | `Filtering_param
  11. | `Deprecated
  12. | `Child_consts
]

The flags FFmpeg sets on an option, each the AV_OPT_FLAG_* constant of the same name. The `X_param ones say what the option applies to: encoding, decoding, audio, video, subtitles, bitstream filters, filters.

  • `Export: meant for exporting values to the caller.
  • `Readonly: can be read and not set.
  • `Runtime_param: can be set by the user at run time.
  • `Child_consts: the named constants of the option can also reside in child objects.
type 'a entry = {
  1. default : 'a option;
  2. min : 'a option;
  3. max : 'a option;
  4. values : (string * 'a) list;
}

What FFmpeg declares about the value of an option.

  • default: the default value. None when the option declares none, when the declared one names no value (FFmpeg's "none" format, a negative boolean default, a text that is not a valid channel layout), and for every array option.
  • min, max: the smallest and the largest value accepted. Present for the numeric kinds only; for the 64-bit integer kinds a bound beyond the 64-bit range is that range's limit.
  • values: the named values the option accepts, as (name, value) in FFmpeg's order. Filled for the integer, floating-point and boolean kinds; empty for the others and for array options.
type ground = [
  1. | `Flags of int64 entry
  2. | `Int of int entry
  3. | `Int64 of int64 entry
  4. | `Float of float entry
  5. | `Double of float entry
  6. | `String of string entry
  7. | `Rational of rational entry
  8. | `Binary of string entry
  9. | `Dict of string entry
  10. | `UInt64 of int64 entry
  11. | `Image_size of string entry
  12. | `Pixel_fmt of Pixel_format.t entry
  13. | `Sample_fmt of Sample_format.t entry
  14. | `Video_rate of string entry
  15. | `Duration of int64 entry
  16. | `Color of string entry
  17. | `Channel_layout of Channel_layout.t entry
  18. | `Bool of bool entry
]

The type of a non-array option, each case the FFmpeg option type of the same name, with what FFmpeg declares about its value.

  • `Flags: a bit mask; the named values are its bits.
  • `Rational: FFmpeg declares the default and the bounds as floating-point numbers; each is given as the nearest rational.
  • `UInt64: an unsigned 64-bit value carried in a signed int64.
  • The cases that carry a string entry give their default as the text FFmpeg declares: `Binary, `Dict, `Image_size, `Video_rate and `Color are not parsed.
type spec = [
  1. | ground
  2. | `Array of ground
]

The type of an option: a ground type, or `Array of the type of its elements. The entry of an array option has neither default nor named values.

type opt = {
  1. name : string;
  2. help : string option;
  3. flags : flag list;
  4. spec : spec;
}

One option.

  • help: FFmpeg's help text, None when it is absent or empty.
  • flags: the flags set on the option, in ascending order of bit value.
val opts : t -> opt list

opts c lists the options of the class c and, recursively, of its child classes: the options of c in FFmpeg's order, then those of each child class in FFmpeg's order of child classes.

An option whose FFmpeg type has no case in ground is left out, so the call succeeds whatever the installed FFmpeg declares. FFmpeg's named constants are not options of their own: they appear in the values of the option they belong to. A value with no class gives [].

type obj

An object that carries options, inside a value of one of the libraries built on this one (a container, a codec context, a filter), which creates it. It keeps that owner alive, and reads through it are checked against the state of the owner.

type 'a getter = ?search_children:bool -> name:string -> obj -> 'a

The type of the readers below. get ~name obj returns the current value of the option name of obj. There is no setter on a live object.

Every string or layout returned is a copy. When the owner of obj has a use lock, the read takes it shared, for the time of the read.

  • parameter search_children

    With true, the option is also looked up in the child objects of obj. Default: false.

  • parameter name

    The option name, as the name field of opt gives it.

  • raises Error

    with `Option_not_found when the object has no option name; with another FFmpeg error when FFmpeg cannot give the value in the type asked; with `Failure "Container closed!" when the owner of obj is closed, and `Failure "Object in use!" when another operation is changing the owner at that moment.

val get_string : string getter

The value of the option as text, as FFmpeg renders it.

val get_int : int getter

The value of an integer option.

  • raises Error

    with `Failure when it is outside the range of int.

val get_int64 : int64 getter

The value of an integer option, as 64 bits.

val get_float : float getter

The value of the option as a float.

val get_rational : rational getter

The value of the option as a rational.

val get_image_size : (int * int) getter

The value of an image-size option, as (width, height) in pixels.

val get_pixel_fmt : Pixel_format.t getter

The value of a pixel-format option.

  • raises Error

    with `Failure when it is a format this build has no constructor for.

val get_sample_fmt : Sample_format.t getter

The value of a sample-format option.

  • raises Error

    with `Failure when it is a format this build has no constructor for.

val get_video_rate : rational getter

The value of a video-rate option, in frames per second as a rational.

val get_channel_layout : Channel_layout.t getter

The value of a channel-layout option, as an independent copy.

val get_dictionary : (string * string) list getter

The value of a dictionary option, as (key, value) pairs in the dictionary's order.