Zoog: Zero Opus Output Gain

Zoog is a Rust library that consists of functionality that can be used to determine the loudness of an Ogg Opus file and also to rewrite that file with new internal gain information as well as loudness-related comment tags. It also has functionality for purely manipulating comment tags of both Ogg Opus and Ogg Vorbis files.

Zoog currently contains two tools, opusgain and zoogcomment. opusgain can be used to:

• set the output gain value located in the Opus binary header inside Opus files so that the file plays at the loudness of the original encoded audio, or of that consistent with the ReplayGain or EBU R 128 standards.

• write the Opus comment tags used by some music players to decide what volume to play an Opus-encoded audio file at.

It is intended to solve the "Opus plays too quietly" problem.

zoogcomment can be used to list, replace or modify the comment tags of Ogg Opus and Ogg Vorbis files. Its usage is roughly based on that of vorbiscomment though many options have different naming for improved clarity.

Although zoog exposes a library, its API is unstable and this package is released on crates.io primarily to allow access to the command-line tools. The API is documented however, and the reading the source may prove useful to anyone else wishing to work with Ogg Opus files.

opusgain

opusgain adjusts the Opus binary header for playback at a specific volume and will always generate the R128_TRACK_GAIN tag and the R128_ALBUM_GAIN tag (when in album mode) such that files will play at an appropriate volume in players that support these tags, and at a more appropriate volume in players that don't. Existing R128_ALBUM_GAIN tags will be stripped when not in album mode.

opusgain (unlike its predecessor zoog) decodes Opus audio in order to determine its volume so that it's possible to be certain that all generated gain values are correct without making assumptions about their existing values.

The following options are available (run opusgain --help for usage):

• -p PRESET, --preset=PRESET

  It is recommended to specify this value explicitly, as the default may change.

  • original: Set the output gain in the Opus binary header to 0dB. In players that do not support R128 tags, this will cause the Opus file to play back at the volume of the originally encoded source. You may want this if you prefer volume normalization to only occur via tags.

  • rg: Set the output gain in the Opus binary header to the value that ensures playback will occur at -18 LUFS, which should match the loudness of ReplayGain normalized files. This is probably the best option when you have a player that doesn't know about Opus R128 tags, but:

    • does support ReplayGain for the other file formats you use, and/or
    • the files you play have been adjusted in a player-agnostic way (mp3gain and aacgain can do this) to the ReplayGain reference volume.

  • r128: Set the output gain in the Opus binary header to the value that ensures playback will occur at -23 LUFS, which should match the loudness of files produced by opusenc from FLAC files which contained ReplayGain information. This is the gain level intended by the Opus authors.

  • no-change: Do not change the output gain in the Opus binary header.

• -o MODE, --output-gain-mode=MODE

  • auto: Set the output gain in the Opus binary header such that each track is album-normalized in album mode, or track-normalized otherwise. In album mode, this results in all tracks having the same output gain value as well as the same R128_ALBUM_GAIN tag.

  • track: Set the output gain in the Opus binary header such that each track is track-normalized, even if album mode is enabled. In album mode, this results in all tracks being given different output gain values as well as different R128_ALBUM_GAIN tags, but their R128_TRACK_GAIN tags will be identical. Unless you know what you're doing, you probably don't want this option.

• -a, --album: Enables album mode. This causes R128_ALBUM_GAIN tags to also be generated. These tell players that support these tags what gain to apply so that each track in the album maintains its relative loudness. By default the output gain value for each file will be set to identical values in order to apply the calculated album gain, but this behaviour can be overridden using the --output-gain-mode option.

• -j N, --num-threads=N: Use N threads for processing. The default is to use the number of cores detected on the system. Larger numbers will be rounded down to this value. To avoid high disk space usage during processing, or a large number of temporary files left around after an error, only one file will be rewritten at a time regardless of the number of threads.

• -c, --clear: Remove all R128 tags from the specified files. The output gain of each file is unchanged, regardless of the specified preset.

• -M, --minimize-mtime-change: Attempts to apply the smallest increment possible (filesystem dependent) to the modification time of the file. This is deliberately not a preserve in order to avoid misleading backup/data-transfer programs that use this information to determine if a file has changed. On modern filesystems (ext4, APFS, btrfs) this is typically a nanosecond, but could be up to two seconds on older filesystems (ext3, FAT32).

• -n, --dry-run: Displays the same output that opusgain would otherwise produce, but does not make any changes to the supplied files.

• -I PATH_PROCESSING_MODE, --interpret-paths=PATH_PROCESSING_MODE

  This option controls how the supplied paths are interpreted.

  • files-singles (default): Each supplied path must be to a file. Files are normalized independently, with any album tags being removed. It is an error to supply a folder.

  • files-album: Each supplied path must be to a file. Files are treated as all belonging to the same album and album normalization tags will be generated. It is an error to supply a folder. This option is equivalent to supplying the -a or --album flag.

  • folders-are-albums: Each file path supplied is treated as a single, with album tags being removed. Each supplied folder path is explored (including recursive traversal of sub-folders) with all found Opus files being treated as part of a single album. This option therefore makes it possible to apply multiple album normalizations in a single opusgain invocation. Which files inside folders are considered Ogg Opus files is controlled by the --file-extensions option.

    For example, if you had the files:

    a.opus
    album1/b.opus
    album1/c.opus
    album2/e.opus
    album2/f.opus
    d.opus
    

    Then opusgain -I folders-are-albums * in that folder would be expanded (by the shell on Linux/MacOS or by opusgain on Windows) to opusgain -I folders-are-albums a.opus album1 album2 d.opus with a.opus and d.opus being treated as singles and album1 and album2 being normalized as independent albums.

• -e FILE_EXTENSIONS, --file-extensions=FILE_EXTENSIONS: When folders are passed on the command line to be searched for files, this option determines what file extensions are considered to be Ogg Opus files. Multiple extensions may be supplied separated by commas. By default this value is opus, but ogg,opus could be supplied to assume that all found .ogg files are Ogg Opus as well.

If the internal gain and tag values are already correct for the specified files, opusgain will avoid rewriting them.

Sequentially multiplexed or "chained" Ogg Opus streams are not supported.

opusgain supports Unix shell style wildcards under Windows, where wildcards must be handled by the application rather than expanded by the shell.

zoogcomment

zoogcomment can be used to delete, append, replace and list the comments located in an Ogg Opus or Ogg Vorbis file.

The following options are available (run zoogcomment --help for usage):

• -l, --list: List all tags in the file in NAME=VALUE format. This will be to standard output unless -O is specified.

• -m, --modify: Tags specified using -t or -I will be appended to the specified file. Tags matching patterns specified using -d will be removed from the existing tags on the file.

• -r, --replace: All existing tags in the file will be removed and will be replaced with those specified using -t or -I.

• -t NAME=VALUE, --tag NAME=VALUE. The specified tag is will be added to the file in modify or replace mode.

• -d NAME[=VALUE], --delete NAME[=VALUE]. Specifies either a tag name, or a name-value mapping to be deleted. All tags that match the pattern will be removed, not just the first. This option is only valid in modify mode.

• -e, --escapes: In all tag input/output either on the command-line or to/from a file escapes will be used for line-feeds (\n), carriage returns (\r), backslashes (\\) and the null character (\0). All other escapes are invalid. This option makes it possible to specify tags which contain newlines which would otherwise fail to be parsed correctly from a comment file.

• -I COMMENT_FILE, --tags-in COMMENT_FILE: In the modify and replace modes, the tags to added will be read from this file in addition to those specified on the command line. Tags are read in NAME=VALUE format, with one tag per line. If - is specified for the