1 /* 2 * Copyright (c) 2023, Alliance for Open Media. All rights reserved 3 * 4 * This source code is subject to the terms of the BSD 3-Clause Clear License 5 * and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear 6 * License was not distributed with this source code in the LICENSE file, you 7 * can obtain it at www.aomedia.org/license/software-license/bsd-3-c-c. If the 8 * Alliance for Open Media Patent License 1.0 was not distributed with this 9 * source code in the PATENTS file, you can obtain it at 10 * www.aomedia.org/license/patent. 11 */ 12 13 #ifndef CLI_PROTO_CONVERSION_PROTO_TO_OBU_PARAMETER_BLOCK_GENERATOR_H_ 14 #define CLI_PROTO_CONVERSION_PROTO_TO_OBU_PARAMETER_BLOCK_GENERATOR_H_ 15 16 #include <list> 17 18 #include "absl/container/flat_hash_map.h" 19 #include "absl/status/status.h" 20 #include "iamf/cli/audio_element_with_data.h" 21 #include "iamf/cli/demixing_module.h" 22 #include "iamf/cli/global_timing_module.h" 23 #include "iamf/cli/parameter_block_with_data.h" 24 #include "iamf/cli/proto/parameter_block.pb.h" 25 #include "iamf/obu/param_definition_variant.h" 26 #include "iamf/obu/param_definitions.h" 27 #include "iamf/obu/types.h" 28 29 namespace iamf_tools { 30 31 // TODO(b/296815263): Add tests for this class. 32 33 /*!\brief Generator of parameter blocks. 34 * 35 * The use pattern of this class is: 36 * 37 * - Initialize (`Initialize()`). 38 * - Repeat for each temporal unit (along with the audio frame generation): 39 * - For all parameter blocks metadata that start at the current 40 * timestamp: 41 * - Add the metadata (`AddMetadata()`). 42 * - Generate demixing parameter blocks (`GenerateDemixing()`). 43 * - Generate mix gain parameter blocks (`GenerateMixGain()`). 44 * - // After audio frames are decoded and demixed. 45 * - Generate recon gain parameter blocks (`GenerateReconGain()`). 46 */ 47 class ParameterBlockGenerator { 48 public: 49 /*!\brief Constructor. 50 * 51 * \param override_computed_recon_gains Whether to override recon gains 52 * with user provided values. 53 * \param param_definition_variants Mapping from parameter IDs to param 54 * definitions. 55 */ ParameterBlockGenerator(bool override_computed_recon_gains,const absl::flat_hash_map<DecodedUleb128,ParamDefinitionVariant> & param_definition_variants)56 ParameterBlockGenerator( 57 bool override_computed_recon_gains, 58 const absl::flat_hash_map<DecodedUleb128, ParamDefinitionVariant>& 59 param_definition_variants) 60 : override_computed_recon_gains_(override_computed_recon_gains), 61 additional_recon_gains_logging_(true), 62 param_definition_variants_(param_definition_variants) {} 63 64 /*!\brief Initializes the class. 65 * 66 * Must be called before any `Generate*()` function, otherwise they will 67 * be no-ops (not failing). 68 * 69 * \param audio_elements Input Audio Element OBUs with data. 70 * \return `absl::OkStatus()` on success. A specific status on failure. 71 */ 72 absl::Status Initialize( 73 const absl::flat_hash_map<DecodedUleb128, AudioElementWithData>& 74 audio_elements); 75 76 /*!\brief Adds one parameter block metadata. 77 * 78 * \param parameter_block_metadata parameter block metadata to add. 79 * \return `absl::OkStatus()` on success. A specific status on failure. 80 */ 81 absl::Status AddMetadata( 82 const iamf_tools_cli_proto::ParameterBlockObuMetadata& 83 parameter_block_metadata); 84 85 /*!\brief Generates a list of demixing parameter blocks with data. 86 * 87 * \param global_timing_module Global timing module to keep track of the 88 * timestamps of the generated parameter blocks. 89 * \param output_parameter_blocks Output list of parameter blocks with data. 90 * \return `absl::OkStatus()` on success. A specific status on failure. 91 */ 92 absl::Status GenerateDemixing( 93 GlobalTimingModule& global_timing_module, 94 std::list<ParameterBlockWithData>& output_parameter_blocks); 95 96 /*!\brief Generates a list of mix gain parameter blocks with data. 97 * 98 * \param global_timing_module Global timing module to keep track of the 99 * timestamps of the generated parameter blocks. 100 * \param output_parameter_blocks Output list of parameter blocks with data. 101 * \return `absl::OkStatus()` on success. A specific status on failure. 102 */ 103 absl::Status GenerateMixGain( 104 GlobalTimingModule& global_timing_module, 105 std::list<ParameterBlockWithData>& output_parameter_blocks); 106 107 /*!\brief Generates a list of recon gain parameter blocks with data. 108 * 109 * \param id_to_labeled_frame Data structure for samples. 110 * \param id_to_labeled_decoded_frame Data structure for decoded samples. 111 * \param global_timing_module Global timing module to keep track of the 112 * timestamps of the generated parameter blocks. 113 * \param output_parameter_blocks Output list of parameter blocks with data. 114 * \return `absl::OkStatus()` on success. A specific status on failure. 115 */ 116 absl::Status GenerateReconGain( 117 const IdLabeledFrameMap& id_to_labeled_frame, 118 const IdLabeledFrameMap& id_to_labeled_decoded_frame, 119 GlobalTimingModule& global_timing_module, 120 std::list<ParameterBlockWithData>& output_parameter_blocks); 121 122 private: 123 /*!\brief Generates a list of parameter blocks with data. 124 * 125 * \param proto_metadata_list Input list of user-defined metadata about 126 * parameter blocks. 127 * \param global_timing_module Global Timing Module. 128 * \param output_parameter_blocks Output list of parameter blocks with data. 129 * \return `absl::OkStatus()` on success. A specific status on failure. 130 */ 131 absl::Status GenerateParameterBlocks( 132 const IdLabeledFrameMap* id_to_labeled_frame, 133 const IdLabeledFrameMap* id_to_labeled_decoded_frame, 134 std::list<iamf_tools_cli_proto::ParameterBlockObuMetadata>& 135 proto_metadata_list, 136 GlobalTimingModule& global_timing_module, 137 std::list<ParameterBlockWithData>& output_parameter_blocks); 138 139 const bool override_computed_recon_gains_; 140 141 bool additional_recon_gains_logging_; 142 143 // Mapping from parameter IDs to param definitions. 144 const absl::flat_hash_map<DecodedUleb128, ParamDefinitionVariant>& 145 param_definition_variants_; 146 147 // User metadata about Parameter Block OBUs categorized based on 148 // the parameter definition type. 149 absl::flat_hash_map< 150 ParamDefinition::ParameterDefinitionType, 151 std::list<iamf_tools_cli_proto::ParameterBlockObuMetadata>> 152 typed_proto_metadata_; 153 }; 154 155 } // namespace iamf_tools 156 157 #endif // PROTO_TO_OBU_CLI_PARAMETER_BLOCK_GENERATOR_H_ 158