Document Audio Pipeline

Util/Audio/Clip/MP3MonoLayoutReader.cs

@@ -16,6 +16,8 @@ namespace ADOFAIRenderer.Util.Audio.Clip;
 internal sealed class MP3MonoLayoutReader : IPCMReader
 {
     private readonly IPCMReader _inner;
+
+    /// <summary>Reused buffer for inner frames, grown to the largest request.</summary>
     private float[] _innerBuffer = Array.Empty<float>();
 
     /// <param name="inner">Mono reader of the MP3 file with the game's MP3 timing (<see cref="FFmpegPCMReader.IsMP3"/>). Owned by this reader.</param>
@@ -26,10 +28,19 @@ internal sealed class MP3MonoLayoutReader : IPCMReader
         Position = inner.Position * 2;
     }
 
+    /// <summary>Always 1.</summary>
     public int Channels => 1;
+
+    /// <summary>The inner reader's sample rate (the game plays the doubled data at this rate).</summary>
     public int SampleRate => _inner.SampleRate;
+
+    /// <summary>Twice the inner frame count.</summary>
     public long TotalFrames => _inner.TotalFrames * 2;
+
+    /// <inheritdoc/>
     public bool IsForwardOnly => _inner.IsForwardOnly;
+
+    /// <inheritdoc/>
     public long Position { get; private set; }
 
     /// <summary>Moves to <paramref name="frame"/>; the inner reader moves to the inner frame of the next even position.</summary>
@@ -39,12 +50,14 @@ internal sealed class MP3MonoLayoutReader : IPCMReader
         Position = frame;
     }
 
+    /// <inheritdoc/>
     public int Read(float[] buffer, int frameCount)
     {
         var limit = (int)Math.Min(frameCount, TotalFrames - Position);
         var written = 0;
         while (written < limit)
         {
+            // Odd position: the zero slot after an inner sample (also the first frame after a seek to an odd frame).
             if ((Position & 1) == 1)
             {
                 buffer[written++] = 0f;
@@ -52,6 +65,7 @@ internal sealed class MP3MonoLayoutReader : IPCMReader
                 continue;
             }
 
+            // Even position: read enough inner frames for the remaining output, then interleave each with a zero.
             var want = (limit - written + 1) / 2;
             if (_innerBuffer.Length < want) _innerBuffer = new float[want];
             var got = _inner.Read(_innerBuffer, want);
@@ -69,5 +83,6 @@ internal sealed class MP3MonoLayoutReader : IPCMReader
         return written;
     }
 
+    /// <summary>Disposes the inner reader.</summary>
     public void Dispose() => _inner.Dispose();
 }