Avfilter (ffmpeg-avfilter.Avfilter)

type config

A filter graph. It is used in two phases.

init creates it in the configuring phase: attach creates filter instances in it, link connects their pads and parse adds the filters and links of a textual description. launch then configures the graph and returns its endpoints: the functions that push frames into its buffer sources and pull frames from its buffer sinks. Once the graph is launched, attach, link, parse and launch raise Error (`Failure _). process_command works in both phases.

A failed parse or launch leaves the graph failed: every operation on it, and on a filter, pad, input or output that belongs to it, then raises Error (`Failure "Object failed!"). A program that needs the graph again builds a new one.

The value owns the native graph and its filter instances. They are released when the graph and every attached filter, attached pad, input, output and sink context obtained from it have been collected.

Under concurrent use, an operation that conflicts with one running on the same graph raises Error (`Failure "Object in use!") at once; it does not wait. The sink accessors run together with one another. Every other operation, pushing and pulling included, runs alone: pushing to a source while another thread pulls from a sink of the same graph makes one of the two raise.

type ground_arg = [

| `String of string
| `Int of int
| `Int64 of int64
| `Float of float
| `Rational of Avutil.rational

]

The value of a filter option. It is rendered to text for FFmpeg: `String s is s verbatim, `Int and `Int64 are in decimal, `Float is a decimal text that FFmpeg reads back to the same value and `Rational {num; den} is num/den.

Nothing is quoted or escaped. A string that contains a colon, an equal sign, a single quote, a backslash or the array separator is written by the caller in FFmpeg's option-string syntax.

type valued_arg = [

| ground_arg
| `Array of ground_arg list

]

The value of a filter option: a single value, or `Array values for an array-typed option. The elements of an array are rendered in list order and joined with the separator get_array_separator returns for the filter and the option.

type args = [

| `Flag of string
| `Pair of string * valued_arg

]

One argument of a filter. `Pair (key, value) is rendered as key=value. `Flag s is rendered as s alone: a value with no key, which FFmpeg binds to the options of the filter in their declaration order and rejects when it follows a `Pair.

type ('a, 'b) av = {

audio : 'a;
video : 'b;

}

An audio part and a video part.

type ('a, 'b) io = {

inputs : 'a;
outputs : 'b;

}

An input part and an output part.

type ('a, 'b, 'c) pad

A pad of a filter. 'a is [ `Unattached ] for a pad of a filter of the registry and [ `Attached ] for a pad of a filter instance of a graph. 'b is the media type, [ `Audio ] or [ `Video ]. 'c is the direction, [ `Input ] or [ `Output ].

An attached pad keeps its graph alive.

type ('a, 'b) pads =
  (('a, [ `Audio ], 'b) pad list, ('a, [ `Video ], 'b) pad list) av

The pads of one direction of a filter, split by media type, each list in ascending pad order. A pad that is neither audio nor video is in neither list.

type flag = [

| `Dynamic_inputs
| `Dynamic_outputs
| `Slice_threads
| `Support_timeline_generic
| `Support_timeline_internal

]

A property FFmpeg declares for a filter.

`Dynamic_inputs: the filter may add input pads when it is initialised, depending on its arguments.
`Dynamic_outputs: the filter may add output pads when it is initialised, depending on its arguments.
`Slice_threads: the filter supports multithreading by splitting frames into parts processed concurrently.
`Support_timeline_generic: the filter supports FFmpeg's generic enable expression option. While the expression is false, frames pass through unchanged.
`Support_timeline_internal: as `Support_timeline_generic, with the filter itself handling the frames while the expression is false.

type 'a filter = {

name : string;
description : string;
options : Avutil.Options.t;
flags : flag list;
io : (('a, [ `Input ]) pads, ('a, [ `Output ]) pads) io;

}

A filter. A [ `Unattached ] filter comes from the registry (filters, find, abuffer and the like) and describes a filter FFmpeg provides. A [ `Attached ] filter comes from attach and designates one instance of that filter in a graph, which it keeps alive.

An operation that takes an attached filter finds the instance through the pads of io. It raises Error (`Failure _) when the record has no attached pad and when its pads belong to several instances.

name: the name of the filter, not of an instance.
description: FFmpeg's description, the empty string when it gives none.
options: the options of the filter, for inspection through Avutil.Options. Their values are set through the args of attach.
io: the static pads of an unattached filter, the actual pads of an attached one.

type 'a input = [ `Frame of 'a Avutil.frame | `Flush ] -> unit

The function that feeds one buffer source of a launched graph.

`Frame frame gives the frame to the source. The source takes a reference of its own: the caller's frame is unchanged and stays usable.

`Flush marks the end of the stream on that source. A flushed source accepts no further frame: `Frame _ then raises Error `Eof.

Each call releases the OCaml runtime lock while FFmpeg works. It raises Avutil.Error when FFmpeg reports a failure.

type 'a context

A buffer sink of a launched graph, as read by the accessors below. It keeps the graph alive. The accessors raise Error (`Failure "Object failed!") on a failed graph and Error (`Failure "Object in use!") while another thread changes the graph, pushes to it or pulls from it.

type 'a output = {

context : 'a context;
handler : unit -> 'a Avutil.frame;

}

One buffer sink of a launched graph.

context: the sink, for the accessors.
handler: handler () returns the next frame the sink has ready. Each call returns a new frame value; the frame data is not copied.

It raises Error `Eagain when no frame is ready yet. It raises Error `Eof once the sink is drained after the end of the stream was marked with `Flush. Both are part of normal operation. Any other FFmpeg failure raises Avutil.Error.

Each call releases the OCaml runtime lock while FFmpeg works.

type 'a entries = (string * 'a) list

Endpoints by filter instance name, in the order the instances were created in the graph.

type inputs = ([ `Audio ] input entries, [ `Video ] input entries) av

The buffer sources of a launched graph.

type outputs = ([ `Audio ] output entries, [ `Video ] output entries) av

The buffer sinks of a launched graph.

type t = (inputs, outputs) io

The endpoints of a launched graph, as returned by launch.

val time_base : _ context -> Avutil.rational

The time base of the sink: the unit of the timestamps of the frames it delivers.

val frame_rate : [ `Video ] context -> Avutil.rational

The frame rate of the sink.

val width : [ `Video ] context -> int

The width of the frames of the sink, in pixels.

val height : [ `Video ] context -> int

The height of the frames of the sink, in pixels.

val pixel_aspect : [ `Video ] context -> Avutil.rational option

The sample aspect ratio of the frames of the sink. None when it is unknown, which FFmpeg reports as a ratio of numerator 0.

val pixel_format : [ `Video ] context -> Avutil.Pixel_format.t

The pixel format of the frames of the sink.

raises Avutil.Error
with `Failure _ when the format is one this build of the bindings has no constructor for.

val channels : [ `Audio ] context -> int

The number of channels of the frames of the sink.

val channel_layout : [ `Audio ] context -> Avutil.Channel_layout.t

The channel layout of the frames of the sink, as an independent copy.

raises Avutil.Error
when FFmpeg fails to give the layout.

val sample_rate : [ `Audio ] context -> int

The sample rate of the frames of the sink, in Hz.

val sample_format : [ `Audio ] context -> Avutil.Sample_format.t

The sample format of the frames of the sink.

raises Avutil.Error
with `Failure _ when the format is one this build of the bindings has no constructor for.

val set_frame_size : [ `Audio ] context -> int -> unit

set_frame_size sink size makes the sink deliver frames of exactly size samples per channel, except the last one. It excludes every other operation on the graph while it runs.

raises Avutil.Error
with `Failure _ when size is below 1.

val get_array_separator : filter_name:string -> option_name:string -> char

The character that separates the elements of an array-typed option of a filter: the separator the option declares, and ',' when it declares none. filter_name is the name of a filter FFmpeg registers, the four buffer filters included; option_name is the name of one of its options. attach calls it to render an `Array argument.

raises Avutil.Error
with `Failure _ when FFmpeg has no filter of that name, when the filter has no option of that name and when the option is not array-typed.

exception Exists

Raised by attach when the graph already has a filter instance of the requested name.

val filters : [ `Unattached ] filter list

Every filter FFmpeg registers except the four buffer filters below, sorted by name in ascending byte order. The list is computed once, when the module is loaded.

val find : string -> [ `Unattached ] filter

find name is the element of filters of that name. The four buffer filters are reached through abuffer, buffer, abuffersink and buffersink, not through find.

raises Not_found
when filters has no filter of that name.

val find_opt : string -> [ `Unattached ] filter option

As find, with None when filters has no filter of that name.

val abuffer : [ `Unattached ] filter

The audio buffer source: the filter through which a program feeds audio frames to a graph. Each of its instances gives one entry of inputs.audio in the result of launch.

val buffer : [ `Unattached ] filter

The video buffer source: the filter through which a program feeds video frames to a graph. Each of its instances gives one entry of inputs.video in the result of launch.

val abuffersink : [ `Unattached ] filter

The audio buffer sink: the filter from which a program takes the audio frames a graph produces. Each of its instances gives one entry of outputs.audio in the result of launch.

val buffersink : [ `Unattached ] filter

The video buffer sink: the filter from which a program takes the video frames a graph produces. Each of its instances gives one entry of outputs.video in the result of launch.

val pad_name : (_, _, _) pad -> string

The name of the pad, the empty string when FFmpeg gives none.

val filter_name : (_, _, _) pad -> string

The name of the filter the pad belongs to: the filter, not the instance.

val init : unit -> config

A new, empty graph in the configuring phase. Every option of the graph keeps FFmpeg's default.

val attach : 
  ?args:args list ->
  name:string ->
  [ `Unattached ] filter ->
  config ->
  [ `Attached ] filter

attach ?args ~name filter graph creates an instance of filter in graph and initialises it. The options of a filter are set here and nowhere else.

The result has the name, description, options and flags of filter, and the actual pads of the instance in io. Their number can differ from the pads of filter: some filters create pads when they are initialised.

The call releases the OCaml runtime lock while FFmpeg creates the instance. When it raises, the graph is unchanged.

parameter args
The arguments of the instance, none by default. They are rendered in list order and joined with colons into the option string FFmpeg parses; see args and ground_arg.

parameter name
The name of the instance, unique in the graph. It is the key of the instance in the result of launch when filter is a buffer source or sink.

raises Exists
when the graph already has an instance of that name, whether attach or parse created it.

raises Avutil.Error
with `Filter_not_found when FFmpeg has no filter of the name of filter; with the FFmpeg error when FFmpeg rejects the arguments, an unknown option among them, or fails to create the instance; with `Failure _ when the graph is launched and when an `Array argument names an option get_array_separator rejects.

val link : 
  ([ `Attached ], 'a, [ `Output ]) pad ->
  ([ `Attached ], 'a, [ `Input ]) pad ->
  unit

link output input connects an output pad of a filter instance to an input pad of another. Both pads have the same media type and belong to the same graph, which is in the configuring phase.

raises Avutil.Error
with `Failure _ when the pads belong to different graphs and when the graph is launched; with the FFmpeg error when FFmpeg refuses the link, for instance because a pad is already linked.

type command_flag = [

| `Fast

]

A flag of process_command. With `Fast, FFmpeg executes the command only when it is fast for the filter to do so.

val process_command : 
  ?flags:command_flag list ->
  cmd:string ->
  ?arg:string ->
  [ `Attached ] filter ->
  string

process_command ?flags ~cmd ?arg filter sends the command cmd with the argument arg to one filter instance and returns the answer the filter writes, cut at a fixed length. It works before and after launch, and is the one way to control a filter of a running graph.

The call releases the OCaml runtime lock and excludes every other operation on the graph while it runs.

parameter flags
None by default.

parameter arg
The empty string by default.

raises Avutil.Error
with the FFmpeg error when the command fails; with `Failure _ when filter has no attached pad.

type ('a, 'b, 'c) parse_node = {

node_name : string;
node_args : args list option;
node_pad : ('a, 'b, 'c) pad;

}

An open end of a graph description given to parse, and the pad it is connected to.

node_name: the label of the open end in the description.
node_args: ignored.
node_pad: the pad of an attached filter the open end is linked to.

type ('a, 'b) parse_av =
  (('a, [ `Audio ], 'b) parse_node list, ('a, [ `Video ], 'b) parse_node list)
    av

Nodes split by media type.

type 'a parse_io = (('a, [ `Input ]) parse_av, ('a, [ `Output ]) parse_av) io

The open ends of a graph description, named as in FFmpeg's API, from the point of view of the description.

inputs holds input pads of attached filters, typically the input of a sink: the open outputs of the description with that label are linked to them. outputs holds output pads of attached filters, typically the output of a source: they feed the open inputs of the description with that label.

val parse : [ `Attached ] parse_io -> string -> config -> unit

parse nodes description graph adds the filters and links of description, a graph description in FFmpeg's filtergraph syntax, to graph, and connects the open ends of the description to the pads of nodes.

The filters the description creates belong to the graph and no [ `Attached ] filter value is returned for them. Their instance names count for Exists. The buffer sources and sinks among them are endpoints in the result of launch.

The call releases the OCaml runtime lock while FFmpeg parses.

raises Avutil.Error
with `Failure _, before anything is parsed, when a pad of nodes belongs to another graph and when the graph is launched; with the FFmpeg error when parsing fails. A parsing failure leaves the graph failed: FFmpeg frees every filter of it, those created before the call included.

val launch : config -> t

launch graph configures the graph, which enters the running phase, and returns its endpoints.

The result lists every buffer source and every buffer sink of the graph by instance name, whichever of attach and parse created it, in the order the instances were created. inputs holds one input function per buffer source and outputs one output per buffer sink.

Frames are then pushed with the input functions and pulled with the output handlers. A typical loop pushes a frame, then pulls from every sink until it raises Error `Eagain. At the end of the stream it pushes `Flush to every source and pulls until Error `Eof.

The call releases the OCaml runtime lock while FFmpeg configures the graph.

raises Avutil.Error
with the FFmpeg error when the configuration fails, which leaves the graph failed; with `Failure _ when the graph is already launched.

module Utils : sig ... end

An audio converter built on a private filter graph: it re-frames audio to a fixed frame size and, optionally, converts it to another sample rate, channel layout and sample format.