Document the intention between the OutputSampleRate and `InputSampl…

…eRate` distinction.

  - Maybe we change the function names in the future (`SampleRateForTimingPurposes`?). But for now, just update documentation.
  - Confusingly the spec defines an asymmetry between Opus and other codecs, so this documentation tries to make it extra clear that timing information for Opus is treated as a special case.
  - b/383392238: Pertains to FFmpeg/FFmpeg@76049d1, where `ffmpeg` updated to agree with the `iamf-tools` handling of timing for IAMF-Opus.

PiperOrigin-RevId: 712535637

iamf/obu/codec_config.h

@@ -129,12 +129,22 @@ class CodecConfigObu : public ObuBase {
   absl::Status ReadAndValidateDecoderConfig(ReadBitBuffer& rb);
 
   /*!\brief Gets the output sample rate associated with the OBU.
+   *
+   * This sample rate is used for timing and offset calculations as per
+   * section 3.11 of the IAMF spec.
+   *
+   *   - AAC, FLAC, LPCM: Based on the sample rate of the input stream.
+   *   - Opus: Always 48kHz ("The sample rate used for computing offsets SHALL
+   *           be 48 kHz.").
    *
    * \return Output sample rate in Hz if the OBU was initialized successfully.
    */
   uint32_t GetOutputSampleRate() const { return output_sample_rate_; }
 
   /*!\brief Gets the input sample rate associated with the OBU.
+   *
+   * The sample rate of the data before being passed to the underlying codec
+   * libraries.
    *
    * \return Input sample rate in Hz if the OBU was initialized successfully.
    */

iamf/obu/decoder_config/aac_decoder_config.h

@@ -148,6 +148,12 @@ class AacDecoderConfig {
   absl::Status ReadAndValidate(int16_t audio_roll_distance, ReadBitBuffer& rb);
 
   /*!\brief Gets the output sample rate of the `AacDecoderConfig`.
+   *
+   * This sample rate is used for timing and offset calculations.
+   *
+   * IAMF v1.1.0 section 3.11.2 specifies:
+   *  > "The sample rate used for computing offsets SHALL be the rate indicated
+   *     by the samplingFrequencyIndex in GASpecificConfig()."
    *
    * \param output_sample_rate Output sample rate.
    * \return `absl::OkStatus()` if successful. `absl::InvalidArgumentError()`

iamf/obu/decoder_config/flac_decoder_config.h

@@ -130,6 +130,12 @@ class FlacDecoderConfig {
                                int16_t audio_roll_distance, ReadBitBuffer& rb);
 
   /*!\brief Gets the output sample rate represented within the decoder config.
+   *
+   * This sample rate is used for timing and offset calculations.
+   *
+   * IAMF v1.1.0 section 3.11.3 specifies:
+   *  > "The sample rate used for computing offsets SHALL be the sampling rate
+   *     indicated in the METADATA_BLOCK."
    *
    * \param output_sample_rate Output sample rate.
    * \return `absl::OkStatus()` if successful.  `absl::InvalidArgumentError()`

iamf/obu/decoder_config/lpcm_decoder_config.h

@@ -77,6 +77,11 @@ class LpcmDecoderConfig {
   absl::Status ReadAndValidate(int16_t audio_roll_distance, ReadBitBuffer& rb);
 
   /*!\brief Gets the output sample rate represented within the decoder config.
+   *
+   * This sample rate is used for timing and offset calculations.
+   *
+   * IAMF v1.1.0 section 3.11.4 specifies:
+   *  > "The sample rate used for computing offsets SHALL be sample_rate."
    *
    * \param output_sample_rate Output sample rate.
    * \return `absl::OkStatus()` if successful. `absl::InvalidArgumentError()`

iamf/obu/decoder_config/opus_decoder_config.h

@@ -70,7 +70,10 @@ class OpusDecoderConfig {
 
   /*!\brief Gets the output sample rate represented within the decoder config.
    *
-   * IAMF Spec requires the output to be 48,000 Hz.
+   * This sample rate is used for timing and offset calculations.
+   *
+   * IAMF v1.1.0 section 3.11.1 specifies:
+   *  > "The sample rate used for computing offsets SHALL be 48 kHz."
    *
    * \return Output sample rate.
    */