Document Audio Pipeline

Util/Audio/Clip/MP3HeaderFrame.cs

@@ -37,8 +37,13 @@ internal static class MP3HeaderFrame
         return SilentFrames(file);
     }
 
+    /// <summary>
+    /// <see cref="SilentFrames(string)"/> for a seekable stream positioned anywhere (the stream is read from offset 0).
+    /// Only the first valid frame header within <see cref="SyncSearchBytes"/> after the ID3v2 tags is examined.
+    /// </summary>
     public static int SilentFrames(Stream stream)
     {
+        // Skip consecutive ID3v2 tags: 10-byte header + syncsafe size (+ 10-byte footer when flagged).
         var tag = new byte[10];
         long offset = 0;
         while (true)
@@ -65,6 +70,14 @@ internal static class MP3HeaderFrame
         return 0;
     }
 
+    /// <summary>
+    /// Parses the 4-byte frame header at <paramref name="i"/>. False for a missing sync or a reserved version, layer, bitrate
+    /// index (15) or sample rate index (3).
+    /// </summary>
+    /// <param name="data">Bytes to parse.</param>
+    /// <param name="i">Offset of the first header byte in <paramref name="data"/>.</param>
+    /// <param name="samplesPerFrame">Samples per channel in the frame (384, 576 or 1152).</param>
+    /// <param name="tagOffset">Offset of a Xing/Info tag from the header start: 4 + CRC (2) + Layer III side information (0 for Layers I/II).</param>
     private static bool TryParseHeader(byte[] data, int i, out int samplesPerFrame, out int tagOffset)
     {
         samplesPerFrame = 0;
@@ -91,6 +104,7 @@ internal static class MP3HeaderFrame
         return true;
     }
 
+    /// <summary>True when the ASCII string <paramref name="tag"/> is at <paramref name="at"/> within the first <paramref name="length"/> bytes.</summary>
     private static bool HasTag(byte[] data, int length, int at, string tag)
     {
         if (at < 0 || at + tag.Length > length) return false;
@@ -99,6 +113,7 @@ internal static class MP3HeaderFrame
         return true;
     }
 
+    /// <summary>Reads until <paramref name="count"/> bytes or the end of the stream; returns the bytes read.</summary>
     private static int ReadFully(Stream stream, byte[] buffer, int count)
     {
         var total = 0;