[FFmpeg-devel] [PATCH 4/5] doc: Add LC3/LC3plus muxer and encoder parameters documentation

[Stefano Sabatini]

On date Tuesday 2024-03-26 23:07:56 +0000, ffmpeg-devel Mailing List wrote:
> Signed-off-by: Antoine Soulier <asoulier at google.com>
> ---
>  doc/encoders.texi         | 57 +++++++++++++++++++++++++++++++++++++++
>  doc/general_contents.texi | 11 +++++++-
>  doc/muxers.texi           |  6 +++++
>  3 files changed, 73 insertions(+), 1 deletion(-)
> 
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 7c223ed74c..0719ba13cc 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -814,6 +814,63 @@ ffmpeg -i input.wav -c:a libfdk_aac -profile:a aac_he -b:a 64k output.m4a
>  @end example
>  @end itemize
>  
> + at anchor{liblc3-enc}
> + at section liblc3
> +
> +liblc3 LC3 (Low Complexity Communication Codec) encoder wrapper.
> +
> +Requires the presence of the liblc3 headers and library during configuration.
> +You need to explicitly configure the build with @code{--enable-liblc3}.
> +
> +This encoder has support for the Bluetooth SIG LC3 codec for the LE Audio
> +protocol, and the following features of LC3plus:

> + at itemize @minus

nit: you can skip @minus (I don't think it's much used in other
places)

> + at item
> +Frame duration of 2.5 and 5ms.
> + at item
> +High-Resolution mode, 48 KHz, and 96 kHz sampling rates.
> + at end itemize
> +
> +For more information see the liblc3 project at
> + at url{https://github.com/google/liblc3}.
> +
> + at subsection Options
> +
> +The following options are mapped on the shared FFmpeg codec options.
> +
> + at table @option

> + at item b

nit: here and below you can use:
@item b @var{bitrate}

to clarify the argument content

> +Set the bit rate in bits/s. This will determine the fixed size of the encoded
> +frames, for a selected frame duration.
> +
> + at item ar
> +Set the audio sampling rate (in Hz).
> +
> + at item channels
> +Set the number of audio channels.
> +
> + at item frame_duration
> +Set the audio frame duration in milliseconds. Default value is 10ms.
> +Allowed frame durations are 2.5ms, 5ms, 7.5ms and 10ms.
> +LC3 (Bluetooth LE Audio), allows 7.5ms and 10ms; and LC3plus 2.5ms, 5ms
> +and 10ms.
> +
> +The 10ms frame duration is available in LC3 and LC3 plus standard.
> +In this mode, the produced bitstream can be referenced either as LC3 or LC3plus.
> +

> + at item high_resolution

in this case it would be @var{bool}

> +Enable the high-resolution mode if set to 1. The high-resolution mode is

> +available with all LC3plus frame durations and for a sampling rate 48 KHz,

something is missing, for a sampling rate _of_ 48 KHz ?

> +and 96 KHz.

> +
> +The encoder automatically turns off this mode at lower sampling rates and
> +activates it at 96 KHz.
> +
> +This mode should be preferred at high bitrates. In this mode, the audio
> +bandwidth is always up to the Nyquist frequency, compared to LC3 at 48 KHz,
> +which limits the bandwidth to 20 KHz.
> + at end table
> +
>  @anchor{libmp3lame}
>  @section libmp3lame
>  
> diff --git a/doc/general_contents.texi b/doc/general_contents.texi
> index f269cbd1a9..e7cf4f8239 100644
> --- a/doc/general_contents.texi
> +++ b/doc/general_contents.texi
> @@ -237,6 +237,14 @@ Go to @url{http://sourceforge.net/projects/opencore-amr/} and follow the
>  instructions for installing the library.
>  Then pass @code{--enable-libfdk-aac} to configure to enable it.
>  
> + at subsection LC3 library
> +
> +FFmpeg can make use of the Google LC3 library for LC3 decoding & encoding.
> +
> +Go to @url{https://github.com/google/liblc3/} and follow the instructions for
> +installing the library.
> +Then pass @code{--enable-liblc3} to configure to enable it.
> +
>  @section OpenH264
>  
>  FFmpeg can make use of the OpenH264 library for H.264 decoding and encoding.
> @@ -1300,7 +1308,8 @@ following image formats are supported:
>      @tab encoding and decoding supported through external library libilbc
>  @item IMC (Intel Music Coder)  @tab     @tab  X
>  @item Interplay ACM            @tab     @tab  X
> - at item MACE (Macintosh Audio Compression/Expansion) 3:1  @tab     @tab  X
> + at item LC3                    @tab E  @tab  E
> +    @tab supported through external library liblc3
>  @item MACE (Macintosh Audio Compression/Expansion) 6:1  @tab     @tab  X
>  @item Marian's A-pac audio     @tab     @tab  X
>  @item MI-SC4 (Micronas SC-4 Audio)  @tab     @tab  X
> diff --git a/doc/muxers.texi b/doc/muxers.texi
> index a10a8e216f..9687746c30 100644
> --- a/doc/muxers.texi
> +++ b/doc/muxers.texi
> @@ -2612,6 +2612,12 @@ WebDAV server every second:
>  ffmpeg -f x11grab -framerate 1 -i :0.0 -q:v 6 -update 1 -protocol_opts method=PUT http://example.com/desktop.jpg
>  @end example
>  
> + at section lc3
> +Bluetooth SIG Low Complexity Communication Codec audio (LC3), or
> +ETSI TS 103 634 Low Complexity Communication Codec plus (LC3plus).
> +
> +This muxer accepts a single @code{lc3} audio stream.
> +
>  @section matroska

LGTM otherwise, thanks.

Note: you might move the doc bits to the relevent functional changes
and drop this patch.