Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit fc3b8a8d authored by Jean-Michel Trivi's avatar Jean-Michel Trivi
Browse files

MediaFormat AAC DRC documentation updates

Better doc for Target Ref level.
Clarify behavior of -1 for Target Ref level

Bug: 148385721
Test: atest DecoderTestXheAac DecoderTestAacDrc
Change-Id: I8ef83abc73d72552c4ea8e63839cc6efb4d22a45
parent 9fdd67b8
Loading
Loading
Loading
Loading
+18 −14
Original line number Diff line number Diff line
@@ -650,16 +650,20 @@ public final class MediaFormat {
    public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count";

    /**
     * A key describing a gain to be applied so that the output loudness matches the
     * Target Reference Level. This is typically used to normalize loudness across program items.
     * The gain is derived as the difference between the Target Reference Level and the
     * Program Reference Level. The latter can be given in the bitstream and indicates the actual
     * loudness value of the program item.
     * A key describing the Target Reference Level (Target Loudness).
     * <p>For normalizing loudness across program items, a gain is applied to the audio output so
     * that the output loudness matches the Target Reference Level. The gain is derived as the
     * difference between the Target Reference Level and the Program Reference Level (Program
     * Loudness). The latter can be given in the bitstream and indicates the actual loudness value
     * of the program item.</p>
     * <p>The Target Reference Level controls loudness normalization for both MPEG-4 DRC and
     * MPEG-D DRC.
     * <p>The value is given as an integer value between
     * 40 and 127, and is calculated as -4 * Target Reference Level in LKFS.
     * Therefore, it represents the range of -10 to -31.75 LKFS.
     * <p>For MPEG-4 DRC, a value of -1 switches off loudness normalization and DRC processing.</p>
     * <p>For MPEG-D DRC, a value of -1 switches off loudness normalization only. For DRC processing
     * options of MPEG-D DRC, see {@link #KEY_AAC_DRC_EFFECT_TYPE}</p>
     * <p>The default value on mobile devices is 64 (-16 LKFS).
     * <p>This key is only used during decoding.
     */
@@ -680,7 +684,7 @@ public final class MediaFormat {
     * <tr><th>6</th><th>General compression</th></tr>
     * </table>
     * <p>The value -1 (Off) disables DRC processing, while loudness normalization may still be
     * active and dependent on KEY_AAC_DRC_TARGET_REFERENCE_LEVEL.<br>
     * active and dependent on {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}.<br>
     * The value 0 (None) automatically enables DRC processing if necessary to prevent signal
     * clipping<br>
     * The value 6 (General compression) can be used for enabling MPEG-D DRC without particular
@@ -697,8 +701,8 @@ public final class MediaFormat {
     * 0 and 127, which is calculated as -4 * Encoded Target Level in LKFS.
     * If the Encoded Target Level is unknown, the value can be set to -1.
     * <p>The default value is -1 (unknown).
     * <p>The value is ignored when heavy compression is used (see
     * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}).
     * <p>The value is ignored when heavy compression (see {@link #KEY_AAC_DRC_HEAVY_COMPRESSION})
     * or MPEG-D DRC is used.
     * <p>This key is only used during decoding.
     */
    public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level";
@@ -739,17 +743,17 @@ public final class MediaFormat {
    public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level";

    /**
     * A key describing the selection of the heavy compression profile for DRC.
     * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light
     * compression, and DVB-specific heavy compression. When selecting the application of the heavy
     * compression, one of the sequences is selected:
     * A key describing the selection of the heavy compression profile for MPEG-4 DRC.
     * <p>Two separate DRC gain sequences can be transmitted in one bitstream: light compression
     * and heavy compression. When selecting the application of the heavy compression, one of
     * the sequences is selected:
     * <ul>
     * <li>0 enables light compression,</li>
     * <li>1 enables heavy compression instead.
     * </ul>
     * Note that only light compression offers the features of scaling of DRC gains
     * Note that heavy compression doesn't offer the features of scaling of DRC gains
     * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the
     * boost and attenuation factors, and frequency-selective (multiband) DRC.
     * boost and attenuation factors), and frequency-selective (multiband) DRC.
     * Light compression usually contains clipping prevention for stereo downmixing while heavy
     * compression, if additionally provided in the bitstream, is usually stronger, and contains
     * clipping prevention for stereo and mono downmixing.