Opus documentation: lowdelay is too trivialized

[Mingye Wang]

Summary of the bug:

FFmpeg currently describes (at https://ffmpeg.org/ffmpeg-codecs.html#libopus-1) -application lowdelay as simply "Restrict to only the lowest delay modes." This is true, but does not cover the whole picture. Compare the ​Official documentation of OPUS_APPLICATION_RESTRICTED_LOWDELAY: "Only use when lowest-achievable latency is what matters most. Voice-optimized modes cannot be used."

A better wording based on the above would be:
"Restrict to only the lowest delay modes by disabling voice-optimized codec. This is usually unnecessary, as basic Opus already has a delay of 26.5 ms. Try -frame_duration before using this."

How to reproduce:
Well, just navigate to the page. Or

ffmpeg -h enccoder=libopus

[Mingye Wang]

Huh, the description for cutoff is also wrong. On a setting of 0, libopusenc.c does not enforce a maximum at all and keeps the default OPUS_BANDWIDTH_FULLBAND in libopus's opus_encoder.c st->maximum_bandwidth. However, the st->user_bandwidth is still OPUS_AUTO, making it subject to a combination of auto-detection and bitrate-based selection in opus_encode_native(). The former will do nothing noticeable to the signal, but the latter does this:

    if (st->mode != MODE_CELT_ONLY && max_rate < 15000)
    {
       st->bandwidth = IMIN(st->bandwidth, OPUS_BANDWIDTH_WIDEBAND);
    }

It's not a bad idea, but it needs to be documented. Try:

The default is 0 (cutoff disabled). Note that libopus forces a wideband cutoff for bitrates < 15 kbps, unless CELT-only (lowdelay) mode is used.

[Mingye Wang]

A better wording here is...

Restrict to only the lowest delay modes. Specifically, disable speech-optimized codec (SILK) to remove a 4 ms delay.

That clarifies what you lose and what you gain.

For the short AVOption text, try

Restrict to only the lowest delay modes (disables SILK).

[MasterQuestionable]

Side note: "-application lowdelay" may also reduce decoding complexity.
And I noticed Opus seems to handle not anything above 20,000 Hz.

For clarity:
|*| OPUS_BANDWIDTH_FULLBAND = 20000
|*| OPUS_BANDWIDTH_WIDEBAND = 8000

See also:
​https://github.com/FFmpeg/FFmpeg/blob/master/libavcodec/libopusenc.c
​https://github.com/xiph/opus/blob/master/src/opus_encoder.c

[Mingye Wang]

I honestly don't care about that. Most lossy encoders do the 20 KHz cutoff. I'm neither a human infant nor a dolphin...

[MasterQuestionable]

Encoders that enforce 20 KHz cut-off are few. (IIRC, only Opus)
Which rendered Opus only meaningful for low bit rate applications.

(assuming Stereo)
Opus at 160 Kbps already matched MP3 at 320 Kbps, while raising the bit rate all the way to 500 Kbps still producing practically identical result...

[Stefano Sabatini]

I tried to address this in commit:

commit 00eb4966aa8a71a70c4758254027fdc6925f8f86 (HEAD -> master, origin/master, origin/HEAD)
Author: Stefano Sabatini <stefasab@gmail.com>
Date:   Sat Aug 26 15:45:33 2023 +0200

    doc/encoders/libopus: clarify lowdelay and cutoff options
    
    Extend descriptions for the application=lowdelay and cutoff options.
    Based on notes by Mingye Wang.
    
    Address issues:
    http://trac.ffmpeg.org/ticket/10330
    http://trac.ffmpeg.org/ticket/10343

Marking as closed, but feel free to reopen or suggest a better wording.

Thanks for the report.