Module Avcodec.Audio

An audio codec.

The identifier of an audio format, FFmpeg's AV_CODEC_ID_* values of the audio 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 audio identifier the bindings know.

The audio 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 audio decoders FFmpeg registers, under the rules of encoders.

find_encoder_by_name name is the audio encoder FFmpeg registers under name, for example "libmp3lame".

• raises Avutil.Error

  with `Encoder_not_found when FFmpeg has no encoder of that name, or has one that is not an audio 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 audio 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 an audio 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_channel_layouts codec is the list of the channel layouts the codec declares it supports, in the codec's order. Each layout is an independent copy. 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_sample_formats codec is the list of the sample formats the codec declares it supports, in the codec's order. The empty list means the codec declares none. A format the bindings have no constructor for is left out.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

get_supported_sample_rates codec is the list of the sample rates, in Hz, the codec declares it supports, in the codec's order. The empty list means the codec declares none.

• raises Avutil.Error

  with the mapped FFmpeg code when the query fails.

find_best_channel_layout codec default is a channel layout the codec supports, default when possible. It is default when the codec declares no layout or declares one equal to it under Avutil.Channel_layout.compare. Otherwise it is the first layout the codec declares.

• raises Avutil.Error

  as get_supported_channel_layouts.

find_best_sample_format codec default is default when the codec declares no sample format or declares default. Otherwise it is the first sample format the codec declares.

• raises Avutil.Error

  as get_supported_sample_formats.

find_best_sample_rate codec default is default when the codec declares no sample rate or declares default. Otherwise it is the first sample rate the codec declares.

• raises Avutil.Error

  as get_supported_sample_rates.

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.

sample_format decoder is the sample format of the frames the decoder currently produces.

• raises Avutil.Error

  with `Failure "Object in use!" when another thread is inside a send or receive step on the decoder, and with `Failure _ for a format the bindings have no constructor for.

create_encoder ?opts ~channel_layout ~sample_rate ~sample_format ~time_base codec allocates an encoder for codec, sets the four 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 channel_layout

  The layout of the frames the encoder will receive. It is copied.

• parameter sample_rate

  The sample rate of those frames, in Hz.

• parameter sample_format

  The sample format of those frames.

• parameter time_base

  The unit, in seconds, of the timestamps of the frames given to the encoder and of the packets it produces. { num = 1; den = sample_rate } counts in samples.

• 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 sample_rate or a member of time_base does not fit a C int.

frame_size encoder is the number of samples per channel the encoder wants in each frame given to Avcodec.encode. It is 0 for an encoder that accepts frames of any size.

• raises Avutil.Error

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

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 "mp3".

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 audio 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_channel_layout params is an independent copy of the channel layout of the stream.

get_nb_channels params is the number of channels of the stream's channel layout.

get_sample_format params is the sample format of the stream.

• raises Avutil.Error

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

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

get_sample_rate params is the sample rate of the stream, in Hz.

get_initial_padding params is the number of priming samples per channel the encoder puts before the first input sample; 0 when unset.