Document Audio Pipeline

Util/Audio/Clip/AudioClipResolver.cs

@@ -16,6 +16,10 @@ namespace ADOFAIRenderer.Util.Audio.Clip;
 /// </summary>
 internal static class AudioClipResolver
 {
+    /// <summary>
+    /// Returns the source registered under <paramref name="key"/> in <paramref name="store"/>, opening it on first use
+    /// (file first, then the Unity clip; see the class summary). A key that could not be opened is remembered as null.
+    /// </summary>
     /// <param name="store">Store of the current render.</param>
     /// <param name="key">audioLib key of the clip (for example "song.ogg*external" or "sndKick").</param>
     /// <param name="clip">Loaded Unity clip for the key, used when the clip has no file; may be null when the key has a file.</param>
@@ -38,6 +42,9 @@ internal static class AudioClipResolver
                 Melon<RenderMod>.Logger.Warning($"[AudioClipResolver] FFmpeg could not open '{path}' for '{key}', using the Unity clip: {e.Message}");
             }
 
+            // The reader opened here becomes the first decode stream; additional streams reopen the file with OpenFile.
+            // When no source results (store disposed, or the source could not be created), the reader is disposed here
+            // (readers allow Dispose more than once).
             if (fileReader != null)
             {
                 var source = store.GetOrAdd(key, () => fileReader, () => OpenFile(path));