Issue #5 created in Lithopsian/deadbeef-opus
Ogg Opus decoder plugin for DeaDBeeF. SUMMARY Uses the OpusFile library to decode Opus audio. The DeaDBeeF music player can then output this 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 used to manually edit and change the tags. With the replaygain scanner plugin, new replaygain values can be written. SAVING, ENCODING, and CONVERTING 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. REPLAYGAIN 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 replaygain adjustments to each track, for a level of -23 LUFS. The Opus specification recommends not using the REPLAYGAIN* tags common in most codecs and music players. By default, playback will apply the Output Gain and use R128 gain in preference to REPLAYGAIN gain if both sets of tags are present. Note that the Output Gain will even be applied if gain control is completely disabled and when "raw" output is used, for example during conversion to another audio format or a new replaygain scan. PREFERENCES Due to the existence of two possible replaygain tagging systems, there is a preference to control whether REPLAYGAIN or R128 tags are used for gain control when both are present, and to control the reference loudness for playback with gain control. The default is to use the R128 tags and to apply gain control without attempting to adjust the reference loudness. Since the reference loudness specified for R128 tags is -23 LUFS and the reference loudness for replaygain tags is 89 dB, Opus tracks containing R128 tags may play more quietly than other tracks. Playback of all tracks can be adjusted to approximately the same loudness by setting the reference loudness preference, with the assumption that 89 dB SPL is equivalent to -18 LUFS. There is also a preference to disable the Output Gain in certain situations: when gain control is disabled in DeaDBeeF; when REPLAYGAIN tags are being used for gain control; or when "raw" output is required, for example for the converter or replaygain scanner. Note that when the Output Gain preference is disabled, it will be reset to zero when new replaygain values are written or replaygain is removed from the file. It is configurable whether R128 tags, REPLAYGAIN tags, or both, are written when the results of a replaygain scan are applied. By default only R128 tags are written. A new replaygain scan always removes all existing gain control tags, with the configurable exception of the Output Gain, even if no new tags are configured to be written. There are also file path patterns for the save commands on the context menu, including all the substitutions allowed in other parts of DeaDBeeF. TAGGING 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 could 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. Gain control tags are also shown in the track properties dialog: REPLAYGAIN_ALBUM_GAIN, REPLAYGAIN_ALBUM_PEAK, REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, REPLAYGAIN_REFERENCE_LOUDNESS, R128_TRACK_GAIN, and R128_ALBUM_GAIN. There is also an OPUS_HEADER_GAIN property shown on the second tab of the dialog. Each of these tags can be added, removed, or changed by manually entering the name and value in the track properties dialog. Adding and saving an OPUS_HEADER_GAIN tag will modify the Output Gain field in the header, but this property cannot be removed. Entering an invalid value will result in a default value being saved, for example 0 dB for a gain tag. Invalid values already in one of these tags will not be modified, but a default value will be used during playback.