From 3af5518f8a8f755ab44fdaf09a87cfb55a44f486 Mon Sep 17 00:00:00 2001
From: jwcullen <jwcullen@google.com>
Date: Mon, 6 Jan 2025 11:19:39 -0500
Subject: [PATCH] Document the intention between the `OutputSampleRate` and
 `InputSampleRate` 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@76049d1c4564a6a03c467b1f9b0bc853bc971769, where `ffmpeg` updated to agree with the `iamf-tools` handling of timing for IAMF-Opus.

PiperOrigin-RevId: 712535637
---
 iamf/obu/codec_config.h                       | 10 ++++++++++
 iamf/obu/decoder_config/aac_decoder_config.h  |  6 ++++++
 iamf/obu/decoder_config/flac_decoder_config.h |  6 ++++++
 iamf/obu/decoder_config/lpcm_decoder_config.h |  5 +++++
 iamf/obu/decoder_config/opus_decoder_config.h |  5 ++++-
 5 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/iamf/obu/codec_config.h b/iamf/obu/codec_config.h
index fea0df4..d5fa931 100644
--- a/iamf/obu/codec_config.h
+++ b/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.
    */
diff --git a/iamf/obu/decoder_config/aac_decoder_config.h b/iamf/obu/decoder_config/aac_decoder_config.h
index 290b32a..197f88f 100644
--- a/iamf/obu/decoder_config/aac_decoder_config.h
+++ b/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()`
diff --git a/iamf/obu/decoder_config/flac_decoder_config.h b/iamf/obu/decoder_config/flac_decoder_config.h
index d3ceaa3..e12397b 100644
--- a/iamf/obu/decoder_config/flac_decoder_config.h
+++ b/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()`
diff --git a/iamf/obu/decoder_config/lpcm_decoder_config.h b/iamf/obu/decoder_config/lpcm_decoder_config.h
index 0e8dc0e..bfeb22f 100644
--- a/iamf/obu/decoder_config/lpcm_decoder_config.h
+++ b/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()`
diff --git a/iamf/obu/decoder_config/opus_decoder_config.h b/iamf/obu/decoder_config/opus_decoder_config.h
index c5cfc84..704587e 100644
--- a/iamf/obu/decoder_config/opus_decoder_config.h
+++ b/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.
    */