#10330 closed defect (fixed)

Opus documentation: lowdelay is too trivialized

Reported by: Mingye Wang Owned by:
Priority: normal Component: documentation
Version: unspecified Keywords: libopus docs
Cc: MasterQuestionable Blocked By:
Blocking: Reproduced by developer: no
Analyzed by developer: no

Description (last modified by 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

Change History (8)

comment:1 by Mingye Wang, 20 months ago

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.

comment:2 by Mingye Wang, 20 months ago

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).

Last edited 20 months ago by Mingye Wang (previous) (diff)

comment:3 by Mingye Wang, 20 months ago

Description: modified (diff)

comment:4 by MasterQuestionable, 20 months ago

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

comment:5 by MasterQuestionable, 20 months ago

Cc: MasterQuestionable added

comment:6 by Mingye Wang, 20 months ago

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

comment:7 by MasterQuestionable, 19 months ago

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

comment:8 by Stefano Sabatini, 14 months ago

Resolution: fixed
Status: newclosed

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.

Note: See TracTickets for help on using tickets.