Document Audio Pipeline

Util/Audio/Clip/PCMResampler.cs

@@ -11,16 +11,27 @@ namespace ADOFAIRenderer.Util.Audio.Clip;
 /// </summary>
 internal sealed unsafe class PCMResampler : IDisposable
 {
+    /// <summary>Resampler context owned by this instance; null after <see cref="Dispose"/>.</summary>
     private SwrContext* _swr;
+
+    /// <summary>True after <see cref="Flush"/> until <see cref="Reset"/>.</summary>
     private bool _flushed;
 
+    /// <summary>Channel count of input and output (interleaved).</summary>
     public int Channels { get; }
+
+    /// <summary>Input sample rate in Hz.</summary>
     public int InputRate { get; }
+
+    /// <summary>Output sample rate in Hz.</summary>
     public int OutputRate { get; }
 
     /// <summary>Value of the SwrContext "filter_size" option (filter length per phase in taps at a 1:1 ratio).</summary>
     public int FilterSize { get; }
 
+    /// <summary>Creates and initializes a float-to-float resampler with the default channel layout for <paramref name="channels"/>.</summary>
+    /// <exception cref="ArgumentOutOfRangeException">A count or rate is not positive.</exception>
+    /// <exception cref="InvalidOperationException">libswresample cannot allocate or initialize the context.</exception>
     public PCMResampler(int channels, int inputRate, int outputRate)
     {
         if (channels <= 0) throw new ArgumentOutOfRangeException(nameof(channels));
@@ -45,6 +56,8 @@ internal sealed unsafe class PCMResampler : IDisposable
             throw new InvalidOperationException($"swr_alloc_set_opts2 failed ({ret}).");
         _swr = swr;
 
+        // Falls back to 32, the libswresample default of "filter_size", when the option cannot be read.
+        // Reference: https://github.com/FFmpeg/FFmpeg/blob/master/libswresample/options.c (filter_size)
         long filterSize;
         FilterSize = ffmpeg.av_opt_get_int(_swr, "filter_size", 0, &filterSize) >= 0 ? (int)filterSize : 32;
 
@@ -96,6 +109,7 @@ internal sealed unsafe class PCMResampler : IDisposable
         return ret;
     }
 
+    /// <summary>Frees the context. Safe to call more than once.</summary>
     public void Dispose()
     {
         if (_swr == null) return;