Avutil (ffmpeg-avutil.Avutil)

type input

type output

input and output are phantom parameters that mark a value as reading or as writing: the "line" of a container or a format. This library only declares them; the libraries built on it give them their meaning.

type 'a container

A container opened for reading or for writing, 'a being input or output. This library only declares the type; the libraries built on it create and consume its values.

type audio = [

| `Audio

]

Phantom parameter of values that carry audio.

type video = [

| `Video

]

Phantom parameter of values that carry video.

type subtitle = [

| `Subtitle

]

Phantom parameter of values that carry subtitles.

type media_type = [

| `Unknown
| `Video
| `Audio
| `Data
| `Subtitle
| `Attachment

]

The media types FFmpeg knows, as a variant generated from FFmpeg's headers at build time.

type ('line, 'media) format

A container format, 'line being input or output and 'media one of audio, video and subtitle. This library only declares the type; the libraries built on it create and consume its values.

type version = {

major : int;
minor : int;
micro : int;

}

A library version number.

val version : version

The version of the libavutil library loaded at run time, read once when this module is loaded. It may differ from the version of the headers the bindings were compiled against.

val version_string : version -> string

version_string v is major.minor.micro in decimal, such as "60.8.100".

module Display_matrix : sig ... end

The display matrix: the 3x3 transformation a container or a decoder attaches to a video for it to be shown upright, as libavutil/display.h defines it.

type cropping = {

top : int;
bottom : int;
left : int;
right : int;

}

The number of pixels to discard from each border of a picture.

module Frame_side_data : sig ... end

Side data of frames: the kinds FFmpeg defines, raw entries and their typed content.

module Frame : sig ... end

Frames: the properties common to audio and video frames.

type 'media frame = 'media Frame.t

Shorthand for Frame.t.

type error = [

| `Bsf_not_found
| `Decoder_not_found
| `Demuxer_not_found
| `Encoder_not_found
| `Eof
| `Exit
| `Filter_not_found
| `Invalid_data
| `Muxer_not_found
| `Option_not_found
| `Patch_welcome
| `Protocol_not_found
| `Stream_not_found
| `Bug
| `Eagain
| `Unknown
| `Experimental
| `Other of int
| `Failure of string

]

The failures the bindings report. The cases up to `Experimental each stand for one FFmpeg error code; the `X_not_found ones say that FFmpeg has no component, option or stream of the kind named.

`Eof: end of file or of stream.
`Exit: an immediate exit was requested; the operation should not be restarted.
`Invalid_data: FFmpeg found invalid data in its input.
`Option_not_found: an option name the object does not have, as raised by the getters of Options.
`Patch_welcome: FFmpeg does not implement the feature.
`Bug: FFmpeg reports an internal bug.
`Eagain: the operation cannot proceed for the moment (the C EAGAIN).
`Unknown: an unknown error, typically from an external library.
`Experimental: FFmpeg flags the requested feature as experimental.
`Other code: any other FFmpeg error, with its raw, negative code. FFmpeg's AVERROR_EXTERNAL and the errors that wrap a system errno other than EAGAIN arrive this way.
`Failure msg: a condition the bindings detect themselves: an invalid argument, a value FFmpeg returns that the bindings have no constructor for, a handle in the wrong state. msg is for a human reader. Three messages are fixed: "Container closed!" for a closed handle, "Object failed!" for a failed one and "Object in use!" for a handle another operation is using at that moment.

exception Error of error

The exception that carries the failures of all the FFmpeg bindings, this library and the ones built on it.

A negative code returned by an FFmpeg call raises it with the matching case of error, and a condition the bindings detect themselves raises Error (`Failure msg). Besides it, the lookups documented as such raise Not_found.

An uncaught Error e prints as Avutil.Error(...) with the text of string_of_error e between the parentheses.

val string_of_error : error -> string

string_of_error e describes e for a human reader. For `Failure msg it is msg. For every other case it is the text FFmpeg gives for the corresponding error code.

val expr_parse_and_eval : string -> float

expr_parse_and_eval s evaluates the arithmetic expression s with FFmpeg's expression evaluator and returns its value. The expression may use the evaluator's built-in constants and functions; it has no variable and no user function.

raises Error
when s does not parse or does not evaluate. Nothing is written to the log.

type data =
  (int, Stdlib.Bigarray.int8_unsigned_elt, Stdlib.Bigarray.c_layout)
    Stdlib.Bigarray.Array1.t

A buffer of bytes.

val create_data : int -> data

create_data len returns a fresh buffer of len bytes, managed by the OCaml runtime like any bigarray. Its content is unspecified.

raises Error
with `Failure when len is negative.

type rational = {

num : int;
den : int;

}

A rational number num/den, as FFmpeg uses for time bases, frame rates and aspect ratios. Each field must fit a C int when the value is given to FFmpeg; a function that receives one outside that range raises Error with `Failure.

val string_of_rational : rational -> string

string_of_rational r is num/den in decimal, such as "1/25".

val qp2lambda : int

FFmpeg's FF_QP2LAMBDA: the factor that converts a quantiser value (QP) to the lambda unit of encoder quality settings. Read once when this module is loaded.

module Time_format : sig ... end

Units of time.

val time_base : unit -> rational

FFmpeg's internal time base, AV_TIME_BASE_Q: { num = 1; den = 1000000 }, that is microseconds.

module Log : sig ... end

FFmpeg's log: its level, and the capture of its messages by an OCaml function. Both are state of the whole process.

module Channel_layout : sig ... end

Channel layouts: how many audio channels, which ones and in which order.

module Sample_format : sig ... end

Audio sample formats.

module Color_space : sig ... end

Colour spaces (the matrix between YUV and RGB).

module Color_range : sig ... end

Colour ranges (limited or full). The functions behave as those of Color_space.

module Color_primaries : sig ... end

Colour primaries. The functions behave as those of Color_space.

module Color_trc : sig ... end

Colour transfer characteristics. The functions behave as those of Color_space.

module Chroma_location : sig ... end

Locations of the chroma samples. The functions behave as those of Color_space.

module Pixel_format : sig ... end

Pixel formats.

module Audio : sig ... end

Audio frames. The timestamps and the metadata are in Frame; the samples are read and written through the resampling library.

module Video : sig ... end

Video frames. The timestamps and the metadata are in Frame.

module Subtitle : sig ... end

Subtitles.

module Options : sig ... end

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 value = [

| `String of string
| `Int of int
| `Int64 of int64
| `Float of float

]

The value of an option given to FFmpeg. FFmpeg receives it as text: a string as it is, an integer in decimal, a float in a decimal form that FFmpeg parses back to the same value.

type opts = (string, value) Stdlib.Hashtbl.t

A table of options, from option name to value, as the ?opts argument of the operations that create or open an FFmpeg object.

Such an operation hands the entries to FFmpeg and, when it succeeds, removes from the table every entry FFmpeg consumed: the keys still in the table afterwards are the options FFmpeg did not recognise. A caller checks for mistyped names by looking at what is left. When the operation raises, the table is untouched. HwContext.create_device_context is the one operation that never changes its table.

A key bound several times in the table counts once, with its most recent binding. Names and string values end at their first NUL byte.

val string_of_opts : opts -> string

string_of_opts t renders the table as key=value items joined by commas, such as "b=128000,preset=fast". The order of the items is unspecified and nothing is escaped, so the text is meant for display.

val filter_opts : string array -> opts -> unit

filter_opts unused t removes from t, in place, every key that is not an element of unused: t keeps only the options listed as unused.

module HwContext : sig ... end

Hardware acceleration: devices, and pools of frames on a device.