1. Ian Nartowicz
  2. deadbeef-opus


Ogg Opus decoder plugin for DeaDBeeF.


Uses the OpusFile library to decode Opus audio.  The DeaDBeeF music player can then output these to Alsa, Pulse, Jack, etc.  To play an online stream you'll have to define mime types for Opus on the DeaDBeeF preferences network tab.  The specification says audio/ogg but most streams I see are application/ogg.  The mime types are the same as Ogg Vorbis.

Uses the Ogg libraries via liboggedit to write and edit Vorbis Comment tags in Opus streams within Ogg containers.  The DeaDBeeF track properties dialog can be manually used to edit and change the tags.


To encode to Opus, you will need a standlone encoder such as Opus Tools and a DeaDBeeF converter definition.  DeaDBeeF 0.6.2 includes a preset coverter for Opus and recognises this plugin for adding Vorbis Comment tags if you select this option in the converter settings.  Older versions don't include a converter preset and won't add tags to converted Opus files, so either upgrade to 0.6.2 or get the patch from older versions of this plugin.

There are playlist context menu actions to save links from a chained file as individual files, save the audio stream from a mixed video/audio file, and to embed the current covert art image as a tag.


The Opus decoder plugin has five configuration options which can be found from the DeaDBeeF preferences pugins tab.  The first three all control the behaviour of replay gain tags in Opus files.  The Opus specification includes an Output Gain value which is present in all Opus streams (may be 0 dB) and should be applied to all decoded audio.  It also specifies optional R128_TRACK_GAIN and R128_ALBUM_GAIN tags that may be combined with the Output Gain value to provide replay gain adjustments to each track.

The Opus specification does not include the REPLAYGAIN* tags commonly used in most codecs and music player, but if they are included in an Opus track then this plugin can use them.  By default, REPLAYGAIN* tags will be used if they are found, but there is an option to use the Opus gain tags even if REPLAYGAIN* tags are included.  Note that the Opus Output Gain will also be applied on top of the REPLAYGAIN* adjustments unless you uncheck the preference for this (see next paragraph).

The Opus RTF specifies that the gain value from the header should always be used, but this may not be appropriate in some situations, so there is a preference to disable it.  For example, if using REPLAYGAIN* tags, they may not have been written as offsets to be added to the header gain value.  This preference also causes the header gain to be applied when the replaygain mode is "Disable".

The last replay gain option changes the target reference loudness used with replay gain.  By default, the Opus gain tags use the R128 standard of -23 dB, for an output of approximately 84 dB.  Most REPLAYGAIN* tags target a reference loudness of 89 dB although older versions used a level close to the R128 standard.  If you have problems where some tracks have one type of tag and some another, causing 5-6 dB volume jumps, then you can set a fixed reference loudness and the plugin will attempt to adjust all tracks to that level.  The default is to target the loudness specified in any REPLAYGAIN_REFERENCE_LOUDNESS tag, or 89 dB for REPLAYGAIN* tags without a reference loudness, or 84 dB for Opus gain tags.

There are also file path patterns for the save commands on the context menu, including all the substitutions allowed in other parts of DeaDBeeF.


Metadata tags in Opus files are stored using the Vorbis Comment structure.  You can view and edit most of them from within DeaDBeeF, in the selected properties widget or the track properties dialog.  Ten of the most common, for example Artist and Album, are permanently shown under readable names in common with other tagging systems.  Other standard Vorbis Comment tags are recognised by this plugin and the tag names are formatted to appear in lower case with an initial capital.  A few non-standard tags are also recognised and the tag names are displayed in lower case.  All non-recognised tag names are displayed exactly as written in the file.  There are several exceptions to this scheme.  The ISRC and EAN/UPN tag names are shown in all upper case.  The METADATA_BLOCK_PICTURE tag name is displayed in all lower case.  When tags are saved from the track properties dialog, tag names are always written in all upper case.  A number of tags from streaming servers may also shown but cannot be edited.

Opus files can contain multiple instances of the same tag.  DeaDBeeF only displays one instance of each tag and each value will be written into this tag on a separate line and with a distinct delimiter so that normal multi-line tag values are not affected.  When these values are saved they are written back into separate tags in the Opus file.  It is possible to create multiple tags with the same name by inserting the delimiter and saving, but this requires care so include the correct newline characters.

Several special Vorbis Comment tags are handled in a non-standard way.  The full value of any METADATA_BLOCK_PICTURE tags are not shown in DeaDBeeF since this is not human-readable and coule be extremely long.  Instead a summary of each embedded image is shown on a separate line in the tag value.  Similarly, METADATA_BLOCK_PICTURE tags cannot be added manually from the track properties dialog.  Attempting to add and save this tag will do nothing, and editing an existing tag will also not affect the contents of the Opus file.  However, removing an existing tag and saving the file will remove *all* METADATA_BLOCK_PICTURE tags from the file.  A METADATA_BLOCK_PICTURE tag in an Opus file will be displayed as album art if the Artwork plugin is available and it is configured to use embedded tags.  This support is experimental but should work in most cases.

Several gain control tags are not shown in the metadata tab of the track properties dialog.  Instead they appear on the properties tab.  There should only be one instance of each tag of this type and they will not normally by edited or created manually.  These tags are REPLAYGAIN_ALBUM_GAIN, REPLAYGAIN_ALBUM_PEAK, REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, REPLAYGAIN_REFERENCE_LOUDNESS, R128_TRACK_GAIN, and R128_ALBUM_GAIN, and an OPUS_HEADER_GAIN property is also shown for the output gain stored in the Opus header.  Each of these tags can actually be added or changed by manually entering the name and value in the track properties dialog, but invalid values will be ignored.