Module Avcodec.BitstreamFilter

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

A filter instance is fed with BitstreamFilter.send_packet and read with BitstreamFilter.receive_packet. The library provides no drain loop: the caller alternates the two, reading until Error `Eagain before sending again, and until Error `Eof after BitstreamFilter.send_eof.

type filter = private {
  1. name : string;
  2. codecs : id list;
  3. options : Avutil.Options.t;
}

A bitstream filter FFmpeg registers. Values come from filters only: the record is private.

  • name: the filter's name, the empty string when FFmpeg gives none.
  • codecs: the codec identifiers the filter declares it works on, in FFmpeg's order. Empty when the filter accepts any. An identifier the bindings have no constructor for is left out.
  • options: the filter's private options, the ones init accepts in opts. It lists no option for a filter that has none.
type 'a t

An initialised instance of a bitstream filter, for one stream. The value owns the native filter context and the garbage collector releases it.

Concurrent use. send_packet, send_eof and receive_packet each take the instance exclusively. One that finds the instance taken by another thread raises Error (`Failure "Object in use!") at once; it does not wait. After any error the instance is valid.

val filters : filter list

Every bitstream filter FFmpeg registers, in FFmpeg's order. The list is built once, when this module is loaded.

val init : ?opts:Avutil.opts -> ?time_base:Avutil.rational -> filter -> 'a params -> 'a t * 'a params

init ?opts ?time_base filter params creates and initialises an instance of filter for a stream of parameters params. It returns the instance and the parameters of the stream the instance outputs.

params is copied into the instance and is not modified. The returned parameters are an independent copy. Initialisation releases the OCaml runtime lock. On failure everything allocated is released and opts is untouched.

  • parameter opts

    Options for the filter, among those filter.options lists. After a successful call the table holds exactly the entries the filter did not consume, so a key still in it was not used. No table means no option and nothing reported.

  • parameter time_base

    The time base of the packets sent to the instance. FFmpeg's default without it.

  • raises Avutil.Error

    with `Bsf_not_found when FFmpeg has no filter of that name, and with the mapped FFmpeg code when an option value is rejected or the filter fails to initialise.

val time_base_out : 'a t -> Avutil.rational

The time base of the packets the instance outputs, fixed by its initialisation: often the input time base; a filter that retimes packets chooses its own.

val send_packet : 'a t -> 'a Packet.t -> unit

send_packet filter packet gives packet to the filter. The filter takes a reference of its own to the payload: packet is unchanged and stays usable. FFmpeg treats a packet with no payload and no side data as the end of the stream.

The call releases the OCaml runtime lock.

  • raises Avutil.Error

    with `Eagain when the filter's output must be read with receive_packet first, which is part of normal operation; with the mapped FFmpeg code on another refusal; and with `Failure "Object in use!" when another thread is using the instance.

val send_eof : 'a t -> unit

send_eof filter signals the end of the stream to the filter. The packets the filter still holds are then read with receive_packet, until it raises Error `Eof.

The call releases the OCaml runtime lock.

  • raises Avutil.Error

    with the mapped FFmpeg code when the filter refuses the signal, and with `Failure "Object in use!" when another thread is using the instance.

val receive_packet : 'a t -> 'a Packet.t

receive_packet filter is the next packet the filter has ready. The packet is a new value that owns what the filter produced.

The call releases the OCaml runtime lock.

  • raises Avutil.Error

    with `Eagain when the filter needs more input and with `Eof when it is drained, both part of normal operation; with the mapped FFmpeg code when filtering fails; and with `Failure "Object in use!" when another thread is using the instance.