Module Avcodec.Video

A video codec.

The identifier of a video format, FFmpeg's AV_CODEC_ID_* values of the video family. An identifier names a format; several codecs may implement the same one.

descriptor id is FFmpeg's descriptor of the format, None when FFmpeg has none for it. Every text of the result is a copy.

Every video identifier the bindings know.

The video encoders FFmpeg registers, in FFmpeg's order. The list is built once, when this module is loaded. It holds the encoders whose identifier is in id, so get_id succeeds on each of them.

The video decoders FFmpeg registers, under the rules of encoders.

find_encoder_by_name name is the video encoder FFmpeg registers under name, for example "libx264".

• raises Avutil.Error

  with `Encoder_not_found when FFmpeg has no encoder of that name, or has one that is not a video codec.

find_encoder id is an encoder FFmpeg registers for the format id.

• raises Avutil.Error

  with `Encoder_not_found when FFmpeg has no encoder for it.

find_decoder_by_name name is the video decoder FFmpeg registers under name.

• raises Avutil.Error

  with `Decoder_not_found when FFmpeg has no decoder of that name, or has one that is not a video codec.

find_decoder id is a decoder FFmpeg registers for the format id.

• raises Avutil.Error

  with `Decoder_not_found when FFmpeg has no decoder for it.

get_supported_frame_rates codec is the list of the frame rates, in frames per second, the codec declares it supports, in the codec's order. The empty list means the codec declares none, which FFmpeg uses for a codec with no restriction.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

get_supported_color_spaces codec is the list of the colour spaces the codec declares it supports, in the codec's order. The empty list means the codec declares none. A value the bindings have no constructor for is left out.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

get_supported_color_ranges codec is the list of the colour ranges the codec declares it supports, under the rules of get_supported_color_spaces.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

get_supported_pixel_formats codec is the list of the pixel formats the codec declares it supports, under the rules of get_supported_color_spaces. The list may hold hardware pixel formats.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

find_best_frame_rate codec default is default when the codec declares no frame rate or declares one equal to it as a fraction. Otherwise it is the first frame rate the codec declares.

• raises Avutil.Error

  as get_supported_frame_rates.

find_best_pixel_format ?hwaccel codec default is a pixel format to give the codec, default when possible. It is default when the codec declares no pixel format or declares default. Otherwise it is the first format the codec declares that hwaccel allows, and default when none is left.

• parameter hwaccel

  Whether a hardware pixel format, one whose descriptor carries the `Hwaccel flag, may be chosen in place of default. Defaults to false: hardware formats are skipped.

• raises Avutil.Error

  as get_supported_pixel_formats.

create_decoder ?params codec allocates a decoder for codec and opens it. The decoder decodes in software and takes no option. FFmpeg chooses its number of threads.

Opening releases the OCaml runtime lock: other OCaml threads run meanwhile. On failure everything allocated is released.

• parameter params

  The parameters of the stream to decode, as read from a container. They are copied onto the decoder before it is opened; the value is read and not retained. Without params the decoder opens with the codec's defaults.

• raises Avutil.Error

  with the mapped FFmpeg code when the parameters cannot be applied or the codec cannot be opened.

A hardware context for a video encoder:

• `Device_context: a hardware device. The encoder receives frames as they are given to it.
• `Frame_context: a pool of hardware frames. The encoder uploads each frame given to it into a frame of the pool before encoding it, see Avcodec.encode.

create_encoder ?opts ?frame_rate ?hardware_context ~pixel_format ~width ~height ~time_base codec allocates an encoder for codec, sets the typed arguments on it, and opens it with the entries of opts.

Opening releases the OCaml runtime lock: other OCaml threads run meanwhile. On failure everything allocated is released and opts is untouched.

• parameter opts

  Options for the codec. The opening consumes the entries it recognises: the codec's private options first, then the generic codec context options. After a successful call the table holds exactly the entries that were not consumed, so a key still in it was not used. An entry that addresses the same setting as a typed argument is applied after it and prevails. FFmpeg chooses the number of threads unless a threads entry is given. No table means no option and nothing reported.

• parameter frame_rate

  The frame rate of the stream, in frames per second. It is left unset without it, and a rate with a zero numerator counts as not given.

• parameter hardware_context

  The hardware device or hardware frame pool the encoder works with, see hardware_context and Avcodec.hw_configs. The encoder takes a reference of its own to the context and keeps it alive.

• parameter pixel_format

  The pixel format the encoder is opened with.

• parameter width

  The picture width, in pixels.

• parameter height

  The picture height, in pixels.

• parameter time_base

  The unit, in seconds, of the timestamps of the frames given to the encoder and of the packets it produces.

• parameter side_data

  side data that applies to all the frames the encoder will be given, such as the global entries of the first one. FFmpeg writes those it knows a stream-level form of, the display matrix among them, to the parameters of the encoder.

• raises Avutil.Error

  with the mapped FFmpeg code when the codec cannot be opened, for example when it rejects one of the arguments or the value of an option, and with `Failure _ when width, height or a member of frame_rate or time_base does not fit a C int.

get_name codec is the codec's name, as Avcodec.name.

get_description codec is the codec's descriptive name, the empty string when FFmpeg gives none.

string_of_id id is FFmpeg's name of the format, for example "h264".

get_id codec is the identifier of the format the codec implements.

• raises Avutil.Error

  with `Failure _ for a codec whose identifier is outside id. No codec of encoders or decoders is one, but the lookups by name can return one: FFmpeg types a few codecs as video while their identifier is in Unknown.id.

get_params_id params is the codec identifier of the parameters.

• raises Avutil.Error

  with `Failure _ when the identifier is outside id.

get_width params is the picture width, in pixels.

get_height params is the picture height, in pixels.

get_sample_aspect_ratio params is the aspect ratio of one pixel, width over height, as the parameters store it. It is 0/1 when unknown.

get_pixel_format params is the pixel format of the stream, None when the parameters have none.

• raises Avutil.Error

  with `Failure _ for a format the bindings have no constructor for.

get_pixel_aspect params is get_sample_aspect_ratio as an option: None when the ratio is unknown, that is when its numerator is 0.

get_bit_rate params is the average bit rate of the encoded stream, in bits per second.

The number of frames the decoder outputs late because of reordering (B-frames); 0 for a stream without reordering.

The field order of interlaced video; `Unknown when unset. `Tt: top field coded and displayed first; `Bb: bottom first; `Tb: top coded first, bottom displayed first; `Bt: the reverse.

The colour properties of the stream, as the codec parameters store them.