mix_presentation.proto: Deprecate and supersede "mix gain" fields t…

…o match the spec.

  - New fields are quite similar, but reduce a level of nesting.
  - If both the new and old variant are present the new variant will take precedence.
  - `test_000002.textproto` provides an example in `.textproto` format.
  - Other test vectors will be updated in a follow-up - to prove this change did not break old usage.

PiperOrigin-RevId: 663833695

iamf/cli/proto/mix_presentation.proto

@@ -28,6 +28,8 @@ message MixPresentationElementAnnotations {
 }
 
 message ElementMixConfig {
+  option deprecated = true;
+
   optional MixGainParamDefinition mix_gain = 1;
 }
 
@@ -56,10 +58,14 @@ message SubMixAudioElement {
   repeated string localized_element_annotations = 6;
 
   optional RenderingConfig rendering_config = 5;
-  optional ElementMixConfig element_mix_config = 3;
+  // Superseded by `element_mix_gain`.
+  optional ElementMixConfig element_mix_config = 3 [deprecated = true];
+  optional MixGainParamDefinition element_mix_gain = 7;
 }
 
 message OutputMixConfig {
+  option deprecated = true;
+
   optional MixGainParamDefinition output_mix_gain = 1;
 }
 
@@ -155,7 +161,11 @@ message MixPresentationLayout {
 message MixPresentationSubMix {
   optional uint32 num_audio_elements = 1;
   repeated SubMixAudioElement audio_elements = 2;
-  optional OutputMixConfig output_mix_config = 3;
+
+  // Superseded by `output_mix_gain`.
+  optional OutputMixConfig output_mix_config = 3 [deprecated = true];
+  optional MixGainParamDefinition output_mix_gain = 6;
+
   optional uint32 num_layouts = 4;
   repeated MixPresentationLayout layouts = 5;
 }

iamf/cli/proto_to_obu/BUILD

@@ -134,6 +134,7 @@ cc_library(
         "//iamf/cli:cli_util",
         "//iamf/cli/proto:mix_presentation_cc_proto",
         "//iamf/cli/proto:param_definitions_cc_proto",
+        "//iamf/cli/proto:parameter_data_cc_proto",
         "//iamf/cli/proto:user_metadata_cc_proto",
         "//iamf/common:macros",
         "//iamf/common:obu_util",

iamf/cli/proto_to_obu/mix_presentation_generator.cc

@@ -26,6 +26,7 @@
 #include "iamf/cli/cli_util.h"
 #include "iamf/cli/proto/mix_presentation.pb.h"
 #include "iamf/cli/proto/param_definitions.pb.h"
+#include "iamf/cli/proto/parameter_data.pb.h"
 #include "iamf/common/macros.h"
 #include "iamf/common/obu_util.h"
 #include "iamf/obu/leb128.h"
@@ -166,6 +167,33 @@ absl::Status FillRenderingConfig(
   return absl::OkStatus();
 }
 
+// Prefers selecting `element_mix_gain` (V1.1 field) if it present over
+// `element_mix_config.mix_gain` (deprecated in the proto based on V1.0 spec).
+const iamf_tools_cli_proto::MixGainParamDefinition& SelectElementMixConfig(
+    const iamf_tools_cli_proto::SubMixAudioElement& sub_mix_audio_element) {
+  if (sub_mix_audio_element.has_element_mix_gain()) {
+    return sub_mix_audio_element.element_mix_gain();
+  } else {
+    LOG(WARNING)
+        << "Please upgrade `element_mix_config` to `element_mix_gain`.";
+    return sub_mix_audio_element.element_mix_config().mix_gain();
+  }
+}
+
+// Prefers selecting `output_mix_gain` (V1.1 field) if it present over
+// `output_mix_config.output_mix_gain` (deprecated in the proto based on V1.0
+// spec).
+const iamf_tools_cli_proto::MixGainParamDefinition& SelectOutputMixConfig(
+    const iamf_tools_cli_proto::MixPresentationSubMix&
+        mix_presentation_sub_mix) {
+  if (mix_presentation_sub_mix.has_output_mix_gain()) {
+    return mix_presentation_sub_mix.output_mix_gain();
+  } else {
+    LOG(WARNING) << "Please upgrade `output_mix_config` to `output_mix_gain`.";
+    return mix_presentation_sub_mix.output_mix_config().output_mix_gain();
+  }
+}
+
 absl::Status FillMixConfig(
     const iamf_tools_cli_proto::MixGainParamDefinition& input_mix_gain,
     MixGainParamDefinition& mix_gain) {
@@ -495,15 +523,14 @@ absl::Status MixPresentationGenerator::Generate(
             FillRenderingConfig(input_sub_mix_audio_element.rendering_config(),
                                 sub_mix_audio_element.rendering_config));
 
-        RETURN_IF_NOT_OK(FillMixConfig(
-            input_sub_mix_audio_element.element_mix_config().mix_gain(),
-            sub_mix_audio_element.element_mix_gain));
+        RETURN_IF_NOT_OK(
+            FillMixConfig(SelectElementMixConfig(input_sub_mix_audio_element),
+                          sub_mix_audio_element.element_mix_gain));
         sub_mix.audio_elements.push_back(sub_mix_audio_element);
       }
 
-      RETURN_IF_NOT_OK(
-          FillMixConfig(input_sub_mix.output_mix_config().output_mix_gain(),
-                        sub_mix.output_mix_gain));
+      RETURN_IF_NOT_OK(FillMixConfig(SelectOutputMixConfig(input_sub_mix),
+                                     sub_mix.output_mix_gain));
 
       RETURN_IF_NOT_OK(FillLayouts(input_sub_mix, sub_mix));
       obu_args.sub_mixes.push_back(std::move(sub_mix));

iamf/cli/proto_to_obu/tests/mix_presentation_generator_test.cc

@@ -101,11 +101,9 @@ void FillMixPresentationMetadata(
   FillMixGainParamDefinition(kCommonParameterId, kZeroMixGain,
                              *mix_presentation_metadata->mutable_sub_mixes(0)
                                   ->mutable_audio_elements(0)
-                                  ->mutable_element_mix_config()
-                                  ->mutable_mix_gain());
+                                  ->mutable_element_mix_gain());
   FillMixGainParamDefinition(kCommonParameterId, kZeroMixGain,
                              *mix_presentation_metadata->mutable_sub_mixes(0)
-                                  ->mutable_output_mix_config()
                                   ->mutable_output_mix_gain());
 }
 
@@ -431,15 +429,35 @@ TEST(Generate, IgnoresTagsWhenSetIncludeMixPresentationTagsIsFalse) {
   EXPECT_FALSE(first_obu.mix_presentation_tags_.has_value());
 }
 
+TEST(Generate, CopiesOutputMixGain) {
+  MixPresentationObuMetadatas mix_presentation_metadata;
+  FillMixPresentationMetadata(mix_presentation_metadata.Add());
+  FillMixGainParamDefinition(kCommonParameterId, kNonZeroMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_output_mix_gain());
+  MixPresentationGenerator generator(mix_presentation_metadata);
+
+  std::list<MixPresentationObu> generated_obus;
+  EXPECT_THAT(generator.Generate(generated_obus), IsOk());
+
+  const auto& first_output_mix_gain =
+      generated_obus.front().sub_mixes_[0].output_mix_gain;
+  EXPECT_EQ(first_output_mix_gain.parameter_id_, kCommonParameterId);
+  EXPECT_EQ(first_output_mix_gain.parameter_rate_, kCommonParameterRate);
+  EXPECT_EQ(first_output_mix_gain.param_definition_mode_, kParamDefinitionMode);
+  EXPECT_EQ(first_output_mix_gain.reserved_, kParamDefinitionReserved);
+  EXPECT_EQ(first_output_mix_gain.default_mix_gain_, kNonZeroMixGain);
+}
+
 TEST(Generate, CopiesElementMixGain) {
   MixPresentationObuMetadatas mix_presentation_metadata;
   FillMixPresentationMetadata(mix_presentation_metadata.Add());
   FillMixGainParamDefinition(kCommonParameterId, kNonZeroMixGain,
                              *mix_presentation_metadata.at(0)
                                   .mutable_sub_mixes(0)
                                   ->mutable_audio_elements(0)
-                                  ->mutable_element_mix_config()
-                                  ->mutable_mix_gain());
+                                  ->mutable_element_mix_gain());
   MixPresentationGenerator generator(mix_presentation_metadata);
 
   std::list<MixPresentationObu> generated_obus;
@@ -455,9 +473,10 @@ TEST(Generate, CopiesElementMixGain) {
   EXPECT_EQ(first_element_mix_gain.default_mix_gain_, kNonZeroMixGain);
 }
 
-TEST(Generate, CopiesOutputMixGain) {
+TEST(Generate, CopiesDeprecatedOutputMixConfig) {
   MixPresentationObuMetadatas mix_presentation_metadata;
   FillMixPresentationMetadata(mix_presentation_metadata.Add());
+  mix_presentation_metadata.at(0).mutable_sub_mixes(0)->clear_output_mix_gain();
   FillMixGainParamDefinition(kCommonParameterId, kNonZeroMixGain,
                              *mix_presentation_metadata.at(0)
                                   .mutable_sub_mixes(0)
@@ -477,6 +496,100 @@ TEST(Generate, CopiesOutputMixGain) {
   EXPECT_EQ(first_output_mix_gain.default_mix_gain_, kNonZeroMixGain);
 }
 
+TEST(Generate, CopiesDeprecatedElementMixConfig) {
+  MixPresentationObuMetadatas mix_presentation_metadata;
+  FillMixPresentationMetadata(mix_presentation_metadata.Add());
+  mix_presentation_metadata.at(0)
+      .mutable_sub_mixes(0)
+      ->mutable_audio_elements(0)
+      ->clear_element_mix_gain();
+  FillMixGainParamDefinition(kCommonParameterId, kNonZeroMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_audio_elements(0)
+                                  ->mutable_element_mix_config()
+                                  ->mutable_mix_gain());
+  MixPresentationGenerator generator(mix_presentation_metadata);
+
+  std::list<MixPresentationObu> generated_obus;
+  EXPECT_THAT(generator.Generate(generated_obus), IsOk());
+
+  const auto& first_element_mix_gain =
+      generated_obus.front().sub_mixes_[0].audio_elements[0].element_mix_gain;
+  EXPECT_EQ(first_element_mix_gain.parameter_id_, kCommonParameterId);
+  EXPECT_EQ(first_element_mix_gain.parameter_rate_, kCommonParameterRate);
+  EXPECT_EQ(first_element_mix_gain.param_definition_mode_,
+            kParamDefinitionMode);
+  EXPECT_EQ(first_element_mix_gain.reserved_, kParamDefinitionReserved);
+  EXPECT_EQ(first_element_mix_gain.default_mix_gain_, kNonZeroMixGain);
+}
+
+TEST(Generate, NonDeprecatedElementMixConfigTakesPrecedence) {
+  constexpr uint32_t kDeprecatedParameterId = 2000;
+  constexpr uint32_t kNonDeprecatedParameterId = 3000;
+  constexpr int16_t kDeprecatedElementMixGain = 100;
+  constexpr int16_t kNonDeprecatedElementMixGain = 200;
+
+  MixPresentationObuMetadatas mix_presentation_metadata;
+  FillMixPresentationMetadata(mix_presentation_metadata.Add());
+  // When both both the deprecated and non-deprecated element mix config are
+  // provided, the non-deprecated config takes precedence.
+  FillMixGainParamDefinition(kNonDeprecatedParameterId,
+                             kNonDeprecatedElementMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_audio_elements(0)
+                                  ->mutable_element_mix_gain());
+  FillMixGainParamDefinition(kDeprecatedParameterId, kDeprecatedElementMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_audio_elements(0)
+                                  ->mutable_element_mix_config()
+                                  ->mutable_mix_gain());
+  MixPresentationGenerator generator(mix_presentation_metadata);
+
+  std::list<MixPresentationObu> generated_obus;
+  EXPECT_THAT(generator.Generate(generated_obus), IsOk());
+
+  const auto& first_element_mix_gain =
+      generated_obus.front().sub_mixes_[0].audio_elements[0].element_mix_gain;
+  EXPECT_EQ(first_element_mix_gain.parameter_id_, kNonDeprecatedParameterId);
+  EXPECT_EQ(first_element_mix_gain.default_mix_gain_,
+            kNonDeprecatedElementMixGain);
+}
+
+TEST(Generate, NonDeprecatedOutputMixConfigTakesPrecedence) {
+  constexpr uint32_t kDeprecatedParameterId = 2000;
+  constexpr uint32_t kNonDeprecatedParameterId = 3000;
+  constexpr int16_t kDeprecatedElementMixGain = 100;
+  constexpr int16_t kNonDeprecatedElementMixGain = 200;
+
+  MixPresentationObuMetadatas mix_presentation_metadata;
+  FillMixPresentationMetadata(mix_presentation_metadata.Add());
+  // When both both the deprecated and non-deprecated element mix config are
+  // provided, the non-deprecated config takes precedence.
+  FillMixGainParamDefinition(kNonDeprecatedParameterId,
+                             kNonDeprecatedElementMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_output_mix_gain());
+  FillMixGainParamDefinition(kDeprecatedParameterId, kDeprecatedElementMixGain,
+                             *mix_presentation_metadata.at(0)
+                                  .mutable_sub_mixes(0)
+                                  ->mutable_output_mix_config()
+                                  ->mutable_output_mix_gain());
+  MixPresentationGenerator generator(mix_presentation_metadata);
+
+  std::list<MixPresentationObu> generated_obus;
+  EXPECT_THAT(generator.Generate(generated_obus), IsOk());
+
+  const auto& first_output_mix_gain =
+      generated_obus.front().sub_mixes_[0].output_mix_gain;
+  EXPECT_EQ(first_output_mix_gain.parameter_id_, kNonDeprecatedParameterId);
+  EXPECT_EQ(first_output_mix_gain.default_mix_gain_,
+            kNonDeprecatedElementMixGain);
+}
+
 class MixPresentationGeneratorTest : public ::testing::Test {
  public:
   void SetUp() override {

iamf/cli/testdata/test_000002.textproto

@@ -99,20 +99,7 @@ mix_presentation_metadata {
       rendering_config {
         headphones_rendering_mode: HEADPHONES_RENDERING_MODE_STEREO
       }
-      element_mix_config {
-        mix_gain {
-          param_definition {
-            parameter_id: 100
-            parameter_rate: 16000
-            param_definition_mode: 1
-            reserved: 0
-          }
-          default_mix_gain: 0
-        }
-      }
-    }
-    output_mix_config {
-      output_mix_gain {
+      element_mix_gain {
         param_definition {
           parameter_id: 100
           parameter_rate: 16000
@@ -122,6 +109,15 @@ mix_presentation_metadata {
         default_mix_gain: 0
       }
     }
+    output_mix_gain {
+      param_definition {
+        parameter_id: 100
+        parameter_rate: 16000
+        param_definition_mode: 1
+        reserved: 0
+      }
+      default_mix_gain: 0
+    }
     num_layouts: 1
     layouts {
       loudness_layout {