From 64881eca018712cdb2a594c5e6e929c6c19f7f61 Mon Sep 17 00:00:00 2001 From: Ralph Giles <giles@thaumas.net> Date: Fri, 8 Aug 2014 14:16:50 -0700 Subject: [PATCH] Ogg Opus Draft: Clean up R128 tag descriptions. Promote the new tag definitions to a separate subsection, balance tags, improve wording, and document our motivation for the R128 tags. --- doc/draft-ietf-codec-oggopus.xml | 59 +++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/doc/draft-ietf-codec-oggopus.xml b/doc/draft-ietf-codec-oggopus.xml index a9e51d34e..9f073c99c 100644 --- a/doc/draft-ietf-codec-oggopus.xml +++ b/doc/draft-ietf-codec-oggopus.xml @@ -688,9 +688,9 @@ sample *= pow(10, output_gain/(20.0*256)) , <vspace blankLines="1"/> Virtually all players and media frameworks should apply it by default. If a player chooses to apply any volume adjustment or gain modification, such - as the R128_TRACK_GAIN (see <xref target="comment_header"/>) or a user-facing - volume knob, the adjustment MUST be applied in addition to this output gain in - order to achieve playback at the desired volume. + as the R128_TRACK_GAIN, R128_ALBUM_GAIN (see <xref target="comment_header"/>) + or a user-facing volume knob, the adjustment MUST be applied in addition + to this output gain in order to achieve playback at the desired volume. <vspace blankLines="1"/> An encoder SHOULD set this field to zero, and instead apply any gain prior to encoding, when this is possible and does not conflict with the user's wishes. @@ -1166,17 +1166,24 @@ Making this check before allocating the associated memory to contain the data user comments than than could possibly fit in the packet. </t> +<section anchor="comment_format" title="Tag Definitions"> <t> The user comment strings follow the NAME=value format described by - <xref target="vorbis-comment"/> with the same recommended tag names. + <xref target="vorbis-comment"/> with the same recommended tag names: + ARTIST, TITLE, DATE, ALBUM, and so on. </t> +<t> +Two new comment tags are introduced for Ogg Opus: +</t> + <figure align="center"> - <preamble>Two new comment tags are introduced for Ogg Opus:</preamble> + <preamble>An optional gain for track nomalization</preamble> <artwork align="left"><![CDATA[ R128_TRACK_GAIN=-573 ]]></artwork> <postamble> -representing the volume shift needed to normalize the track's volume. +representing the volume shift needed to normalize the track's volume + during isolated playback, in random shuffle, and so on. The gain is a Q7.8 fixed point number in dB, as in the ID header's 'output gain' field. </postamble> @@ -1186,41 +1193,53 @@ This tag is similar to the REPLAYGAIN_TRACK_GAIN tag in Vorbis <xref target="replay-gain"/>, except that the normal volume reference is the <xref target="EBU-R128"/> standard. </t> +<figure align="center"> + <preamble>An optional gain for album nomalization</preamble> <artwork align="left"><![CDATA[ R128_ALBUM_GAIN=111 ]]></artwork> <postamble> -representing the volume shift needed to normalize the volume of a collection - of tracks. -The gain is a Q7.8 fixed point number in dB, as in the ID header's 'output - gain' field. +representing the volume shift needed to normalize the overall volume when + played as part of a collection of tracks. +The gain is also a Q7.8 fixed point number in dB, as in the ID header's + 'output gain' field. </postamble> </figure> <t> -An Ogg Opus file MUST NOT have more than one of each tags, and if present - their values MUST be an integer from -32768 to 32767, inclusive, represented in - ASCII with no whitespace. -If present, R128_TRACK_GAIN MUST correctly represent the R128 - normalization gain relative to the 'output gain' field specified in the ID header. +An Ogg Opus file MUST NOT have more than one of each tag, and if present + their values MUST be an integer from -32768 to 32767, inclusive, + represented in ASCII with no whitespace. +If present, R128_TRACK_GAIN and R128_ALBUM_GAIN MUST correctly represent + the R128 normalization gain relative to the 'output gain' field specified + in the ID header. If a player chooses to make use of the R128_TRACK_GAIN tag or the - R128_ALBUM_GAIN, it MUST be applied <spanx style="emph">in addition</spanx> to - the 'output gain' value. + R128_ALBUM_GAIN tag, it MUST apply those gains + <spanx style="emph">in addition</spanx> to the 'output gain' value. +</t> +<t> If an encoder wishes to use R128 normalization, and the output gain is not otherwise constrained or specified, the encoder SHOULD write the R128 gain into the 'output gain' field and store a tag containing "R128_TRACK_GAIN=0". That is, it should assume that by default tools will respect the 'output gain' field, and not the comment tag. If a tool modifies the ID header's 'output gain' field, it MUST also update or - remove the R128_TRACK_GAIN and R128_ALBUM_GAIN comment tags. + remove the R128_TRACK_GAIN and R128_ALBUM_GAIN comment tags if present. </t> <t> To avoid confusion with multiple normalization schemes, an Opus comment header SHOULD NOT contain any of the REPLAYGAIN_TRACK_GAIN, REPLAYGAIN_TRACK_PEAK, REPLAYGAIN_ALBUM_GAIN, or REPLAYGAIN_ALBUM_PEAK tags. +The <xref target="EBU-R128"/> normalization is preferred to the earlier + REPLAYGAIN schemes because of its clear definition and adoption by industry. +PEAK normalizations are difficult to calculate reliably because of variation + in excursion heights due to decoder differences. +In the authors' investigations they were not applied consistently or broadly + enough to merit inclusion here. </t> -</section> +</section> <!-- end comment_format --> +</section> <!-- end comment_header --> -</section> +</section> <!-- end headers --> <section anchor="packet_size_limits" title="Packet Size Limits"> <t> -- GitLab