Module Avcodec

The version of the libavcodec library loaded at run time. It is read once, when this module is loaded.

A codec FFmpeg registers: the static description of one encoder or decoder implementation, such as "libmp3lame" or "h264".

'media is the media kind (audio, video, subtitle or [`Data]) and 'mode is encode or decode. Both are phantom parameters, and every function that returns a codec gives the parameters that match it.

A codec holds no stream state. It is valid for the life of the process and is immutable, so any number of threads may use one. A decoder or an encoder is the working instance built from a codec, see Audio.create_decoder, Audio.create_encoder, Video.create_decoder and Video.create_encoder.

Equality between two codec values is not defined: compare their names.

The parameters of one encoded stream: its codec identifier and the properties of its content, such as the sample rate and the channel layout of an audio stream or the picture size of a video stream. Parameters say how a stream is encoded. They hold no codec state and decode nothing.

A value owns a private deep copy of the native parameters and shares nothing with the object it was read from. It is immutable and the garbage collector releases it. params and BitstreamFilter.init return parameters, and so do the libraries built on this one.

An opened decoder: the working state that turns the packets of one stream into frames, driven by decode and flush_decoder.

A decoder value owns its native codec context. The garbage collector releases it. There is no explicit close, and collection flushes nothing.

A decoder is in one of three states:

• open, from its creation: decode accepts packets;
• draining, once flush_decoder signalled the end of the stream and the decoder accepted it: decode raises Error `Eof;
• drained, once the decoder delivered its last frame: decode raises Error `Eof and flush_decoder returns at once.

A drained decoder stays drained. Decoding again takes a new decoder.

Concurrent use. A decoder is memory-safe under any interleaving of calls from several threads or domains. Each native send or receive step takes the decoder exclusively. An operation that finds the decoder taken by another thread raises Error (`Failure "Object in use!") at once; it does not wait. After any error the decoder is valid and in one of the three states.

The interface builds audio and video decoders only: the types subtitle decoder and [`Data] decoder have no value.

An opened encoder: the working state that turns frames into the packets of one stream, driven by encode and flush_encoder.

Ownership, release, the three states and the behaviour under concurrent use are those of a decoder, with encode and flush_encoder in the place of decode and flush_decoder. A video encoder created with a hardware context holds a reference of its own to that context and keeps it alive.

The interface builds audio and video encoders only: the types subtitle encoder and [`Data] encoder have no value.

The 'mode parameter of a codec that encodes.

The 'mode parameter of a codec that decodes.

A profile of a codec, as FFmpeg lists it in the codec's descriptor. id is FFmpeg's number for the profile (an AV_PROFILE_* constant) and profile_name is its name, the empty string when FFmpeg gives none.

FFmpeg's description of a codec identifier. It describes the format, not one implementation of it: an encoder and a decoder of the same identifier share one descriptor.

• media_type: the media kind of the format.
• name: the short name of the format, the empty string when FFmpeg gives none.
• long_name: a descriptive name, None when FFmpeg gives none.
• properties: the properties of the format (intra-only, lossy, lossless and so on), in ascending order of FFmpeg's bit values. A property the bindings have no constructor for is left out.
• mime_types: the MIME types associated with the format, in FFmpeg's order. Empty when FFmpeg lists none.
• profiles: the profiles FFmpeg lists for the format, in FFmpeg's order. Empty when it lists none.

The integer value of FFmpeg's AV_CODEC_FLAG_QSCALE codec flag ("use fixed qscale"). It is read once, when this module is loaded.

The integer value of FFmpeg's AV_CODEC_FLAG_GLOBAL_HEADER codec flag ("place global headers in extradata"). It is read once, when this module is loaded.

params encoder is a fresh, independent snapshot of the encoder's parameters, as FFmpeg derives them from the opened codec context. It is what a container needs to declare the stream the encoder produces.

The call only reads the encoder.

• raises Avutil.Error

  with the mapped FFmpeg code when FFmpeg fails to fill the parameters, and with `Failure "Object in use!" when another thread is inside a send or receive step on the encoder.

descriptor params is the descriptor of the codec identifier the parameters carry, None when FFmpeg has none for it. Every text of the result is a copy.

time_base encoder is the encoder's time base: the unit, in seconds, of the timestamps of the packets it produces.

• raises Avutil.Error

  with `Failure "Object in use!" when another thread is inside a send or receive step on the encoder.

name codec is the codec's name, the one Audio.find_encoder_by_name and the other lookups by name accept. It is the empty string when FFmpeg gives none.

A capability of a codec implementation, FFmpeg's AV_CODEC_CAP_* flags.

capabilities codec is the list of the capabilities the codec declares, in ascending order of FFmpeg's bit values. A capability the bindings have no constructor for is left out. It accepts encoders and decoders.

A way to set up hardware acceleration for a codec, FFmpeg's AV_CODEC_HW_CONFIG_METHOD_* flags.

One hardware configuration a codec supports.

• pixel_format: for a decoder, a hardware pixel format it may decode to when suitable hardware is available. For an encoder, a pixel format it may accept; `None then stands for every pixel format the codec supports.
• methods: the setup methods usable with this configuration, in ascending order of FFmpeg's bit values.
• device_type: the type of hardware device of the configuration. FFmpeg sets it for the `Hw_device_ctx and `Hw_frames_ctx methods; it is meaningless for the others.

hw_configs codec is the list of the hardware configurations the codec declares, in FFmpeg's order. It is empty for a codec with none. A configuration whose pixel format or device type the bindings have no constructor for is left out.

The list tells which Video.hardware_context a video encoder can be given: a device context of type device_type when methods has `Hw_device_ctx, a frame context when it has `Hw_frames_ctx.

Side data of packets and of codec parameters: the kinds FFmpeg defines, raw entries and their typed content. A packet's side data applies to that packet; the side data of codec parameters applies to the whole stream.

The side data of the parameters, which applies to the whole stream, in order. An entry whose kind the bindings have no constructor for is left out.

The codec's extradata (for instance an AudioSpecificConfig or an H.264 avcC record, or Annex-B parameter sets), byte for byte. The empty string when the parameters have none.

The codec profile, an AV_PROFILE_* value; None when unknown.

The codec level; None when unknown.

The block alignment, in bytes; 0 when unset.

The number of bits per coded sample; 0 when unset.

params_with_side_data params l is an independent copy of params whose side data is exactly l, in order. A kind that appears twice keeps its last occurrence. params is unchanged.

Packets: one unit of encoded data of a stream, with its timestamps, its flags and its side data. An encoder produces packets and a decoder consumes them; containers read and write them.

Audio codecs: lookup, supported configurations, decoders, encoders and the audio fields of codec parameters.

Video codecs: lookup, supported configurations, decoders, encoders and the video fields of codec parameters.

Subtitle codecs: lookup only. This module builds no subtitle decoder or encoder. Subtitles are decoded and encoded through containers, in the Av library.

The formats FFmpeg places in none of the audio, video and subtitle families. This module offers their identifiers only: no codec list, no lookup, no decoder and no encoder.

A codec identifier of any family: every member of FFmpeg's AVCodecID enumeration the bindings know.

string_of_id id is FFmpeg's name of the format.

Bitstream filters: transformations applied to the packets of a stream, from packets to packets.

decode decoder f packet gives packet to the decoder and calls f on every frame that becomes available, in order, each as soon as it is received. A packet may produce no frame, or several; producing none is not an error.

The steps are:

1. deliver the frames the decoder has ready, which are those an earlier call interrupted by an exception left behind;
2. send the packet;
3. deliver the frames the decoder has ready.

The decoder references the payload of packet, which is unchanged and stays usable. Each frame passed to f is a new value that owns what the decoder produced. f may keep it.

Each send and each receive releases the OCaml runtime lock: other OCaml threads run during the decoding work. f runs on the calling thread with the lock held, between two native steps. The decoder is free while f runs: f may call any operation on it. The call as a whole is not atomic with respect to other threads.

An exception raised by f propagates unchanged. The frames not yet delivered stay in the decoder and the next decode or flush_decoder delivers them first. When f raises in the first step the packet was not sent; in the third step the decoder accepted it.

• raises Avutil.Error

  with `Eof when the decoder is draining or drained, that is once flush_decoder signalled the end of the stream; with the mapped FFmpeg code when decoding fails; and with `Failure "Object in use!" when another thread is inside a step on the decoder. It never raises Error `Eagain.

flush_decoder decoder f signals the end of the stream to the decoder and calls f on every frame it still holds, in order. It is the call that ends a stream: collecting a decoder delivers nothing.

What it does depends on the state of the decoder (see decoder):

• open: it delivers the frames the decoder has ready, signals the end of the stream, then delivers frames until the decoder reports the end of the stream. The decoder is then drained.
• draining, after a flush that f interrupted by an exception: it delivers the remaining frames.
• drained: it returns at once and calls f on nothing.

The lock, the thread f runs on, the exceptions of f and the ownership of the frames are as in decode.

• raises Avutil.Error

  with the mapped FFmpeg code when decoding fails, and with `Failure "Object in use!" when another thread is inside a step on the decoder. It never raises Error `Eagain.

encode encoder f frame gives frame to the encoder and calls f on every packet that becomes available, in order, each as soon as it is received. A frame may produce no packet, or several; producing none is not an error.

The steps are those of decode: deliver the packets the encoder has ready, send the frame, deliver again.

The encoder references the buffers of frame, which is unchanged and stays usable. An encoder created with a `Frame_context hardware context instead uploads the frame: it takes a frame from the pool of the context, transfers the pixel data to it, copies the properties of frame onto it, timestamps included, and encodes that frame. The pool frame is released after the send.

Each packet passed to f is a new value that owns what the encoder produced. Its timestamps are in the encoder's time base, see time_base.

Each send, upload included, and each receive releases the OCaml runtime lock. f runs on the calling thread with the lock held, between two native steps, with the encoder free: f may call any operation on it. An exception raised by f propagates unchanged, and the packets not yet delivered stay in the encoder: the next encode or flush_encoder delivers them first.

• raises Avutil.Error

  with `Eof when the encoder is draining or drained, that is once flush_encoder signalled the end of the stream; with the mapped FFmpeg code when the upload or the encoding fails; and with `Failure "Object in use!" when another thread is inside a step on the encoder. It never raises Error `Eagain.

flush_encoder encoder f signals the end of the stream to the encoder and calls f on every packet it still holds, in order. It is the call that ends a stream: collecting an encoder flushes nothing.

The three states are handled as in flush_decoder: an open encoder is drained, a draining one delivers what remains, a drained one returns at once. A drained encoder accepts no more frame: encoding again takes a new encoder.

The lock, the thread f runs on, the exceptions of f and the ownership of the packets are as in encode.

• raises Avutil.Error

  with the mapped FFmpeg code when encoding fails, and with `Failure "Object in use!" when another thread is inside a step on the encoder. It never raises Error `Eagain.