Module Avutil.Video

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

type planes = (data * int) array

The planes of a video frame, in the order of the pixel format: for each plane, (data, linesize). data is the memory of the plane, of exactly linesize times the height of the plane bytes, and linesize is the number of bytes from one row to the next. A row is linesize bytes long: the pixels, then FFmpeg's padding. The height of a chroma plane is the height of the frame reduced by the vertical chroma subsampling of the format, rounded up.

val create_frame : int -> int -> Pixel_format.t -> video frame

create_frame width height pixel_format returns a new video frame of that size in pixels and that format, with buffers allocated by FFmpeg and aligned, which shows in the line sizes. The pixel data is unspecified.

  • raises Error

    with `Failure when width or height is below 1 or exceeds a C int.

val frame_get_linesize : video frame -> int -> int

frame_get_linesize frame n is the line size of plane n of frame, in bytes: the second component of entry n of planes.

  • raises Error

    with `Failure when n is not the index of a plane of the frame, and when the frame holds no software pixel data (a hardware frame).

val frame_visit : make_writable:bool -> (planes -> unit) -> video frame -> video frame

frame_visit ~make_writable f frame gives f direct access to the pixel data of frame: it builds the planes of the frame, calls f planes on the calling thread, and returns frame itself.

The bigarrays of planes share their memory with the buffers of the frame. Nothing is copied: a read sees the frame's pixels and a write changes them. The palette of a paletted format is not a plane and is not given.

Lifetime. The bigarrays stay valid for as long as the program holds them: after f returns, once frame is otherwise unreachable, and after a later call with ~make_writable:true gave the frame other buffers, in which case they still designate the buffers they were built on. One limit: a view derived from one of them (Bigarray.Array1.sub, a reshape) does not keep the memory alive by itself. Keep the bigarray it was derived from reachable for as long as the view is in use.

The frame is not locked while f runs, and f may call any function on it. An exception f raises propagates unchanged; the frame keeps the buffers it had when f was called, including private ones a ~make_writable:true just gave it.

  • parameter make_writable

    With true, a frame that shares its buffers with other frames first receives buffers of its own holding a copy of the data, so that the writes of f reach this frame only; the caller must then be the only user of the frame during the call. With false the frame is left as it is, and a write through the planes changes every frame that shares the buffers, such as the frames a decoder still references. Pass true whenever f writes.

  • raises Error

    with `Failure when the frame holds no software pixel data (a hardware frame) or has a plane with a negative line size; with FFmpeg's error when the frame cannot be made writable.

val frame_get_width : video frame -> int

The width of the frame, in pixels.

val frame_get_height : video frame -> int

The height of the frame, in pixels.

val frame_get_pixel_format : video frame -> Pixel_format.t

The pixel format of the frame.

  • raises Error

    with `Failure when the frame has a format this build has no constructor for. The same holds for the five colour getters below.

val frame_get_pixel_aspect : video frame -> rational option

The aspect ratio of one pixel (width over height). None when it is unknown, which FFmpeg stores as a zero numerator.

val frame_get_color_space : video frame -> Color_space.t

The colour space of the frame.

val frame_get_color_range : video frame -> Color_range.t

The colour range of the frame.

val frame_get_color_primaries : video frame -> Color_primaries.t

The colour primaries of the frame.

val frame_get_color_trc : video frame -> Color_trc.t

The colour transfer characteristic of the frame.

val frame_get_chroma_location : video frame -> Chroma_location.t

The location of the chroma samples of the frame.

type frame_format = {
  1. width : int;
  2. height : int;
  3. pixel_format : Pixel_format.t;
  4. pixel_aspect : rational option;
  5. color_space : Color_space.t;
  6. color_range : Color_range.t;
  7. color_primaries : Color_primaries.t;
  8. color_trc : Color_trc.t;
  9. chroma_location : Chroma_location.t;
}

What a consumer of video frames is configured for: a frame whose format differs from the one before needs that consumer set up again. This is the one list of the properties that count.

val frame_set_colors : video frame -> frame_format -> unit

frame_set_colors frame format sets the colour space, range, primaries, transfer characteristic and chroma location of frame to those of format. A frame shared with others is changed for all of them: set it only on a frame the caller owns.

val frame_force_keyframe : video frame -> unit

frame_force_keyframe frame marks frame as an intra picture that the encoder it is given to makes a key frame. A frame shared with others is changed for all of them: mark only a frame the caller owns.

val frame_format : video frame -> frame_format

The format of the frame.

type frame_property = [
  1. | `Color
  2. | `Pixel_aspect
]

The properties a caller may leave out of the comparison: `Color is the colour space, range, primaries, transfer characteristic and chroma location together. The size and the pixel format always count.

val same_frame_format : ?ignore:frame_property list -> frame_format -> frame_format -> bool

Whether two formats are the same, leaving out the properties in ignore (none by default).