From fc3b8a8df3eae9afc8e053eb3e2438ceb2b0e9d9 Mon Sep 17 00:00:00 2001 From: Jean-Michel Trivi Date: Mon, 17 Feb 2020 10:35:14 -0800 Subject: [PATCH] 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 --- media/java/android/media/MediaFormat.java | 32 +++++++++++++---------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/media/java/android/media/MediaFormat.java b/media/java/android/media/MediaFormat.java index 57405d762b76a..03b3729a350bf 100644 --- a/media/java/android/media/MediaFormat.java +++ b/media/java/android/media/MediaFormat.java @@ -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). + *

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.

*

The Target Reference Level controls loudness normalization for both MPEG-4 DRC and * MPEG-D DRC. *

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. + *

For MPEG-4 DRC, a value of -1 switches off loudness normalization and DRC processing.

+ *

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}

*

The default value on mobile devices is 64 (-16 LKFS). *

This key is only used during decoding. */ @@ -680,7 +684,7 @@ public final class MediaFormat { * 6General compression * *

The value -1 (Off) disables DRC processing, while loudness normalization may still be - * active and dependent on KEY_AAC_DRC_TARGET_REFERENCE_LEVEL.
+ * active and dependent on {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}.
* The value 0 (None) automatically enables DRC processing if necessary to prevent signal * clipping
* 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. *

The default value is -1 (unknown). - *

The value is ignored when heavy compression is used (see - * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}). + *

The value is ignored when heavy compression (see {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}) + * or MPEG-D DRC is used. *

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. + *

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: *

- * 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.