feat(network): implement buffered stream for networked playback

Improves reliability of network audio playback by introducing a
buffering layer. This prevents network stutters from directly
impacting the audio thread, avoiding crashes or failures.

- Adds `BufferedNetworkStream`, a thread-safe circular buffer that
  downloads and caches audio data in a background task.
- Updates `DirectStreamProvider` to use `BufferedNetworkStream` for
  large or chunked network sources.
- Optimizes `MiniAudioEngine` device enumeration to reduce memory
  allocations by reusing the device info array on refresh.
- Adds `ReadIntoArray` extension to efficiently marshal native data
  into pre-allocated managed arrays, reducing GC pressure.

Author: LSXPrime

Src/Backends/MiniAudio/MiniAudioEngine.cs

@@ -57,7 +57,6 @@ protected override void CleanupBackend()
         Native.Free(_context);
     }
 
-
     /// <inheritdoc />
     public override AudioPlaybackDevice InitializePlaybackDevice(DeviceInfo? deviceInfo, AudioFormat format, DeviceConfig? config = null)
     {
@@ -225,27 +224,41 @@ public override void UpdateDevicesInfo()
         if (result != Result.Success)
             throw new InvalidOperationException($"Unable to get devices. MiniAudio result: {result}");
 
-        var playbackCount = (uint)playbackDeviceCountNint;
-        var captureCount = (uint)captureDeviceCountNint;
+        var playbackCountUint = (uint)playbackDeviceCountNint;
+        var captureCountUint = (uint)captureDeviceCountNint;
+        var playbackCount = (int)playbackCountUint;
+        var captureCount = (int)captureCountUint;
 
         try
         {
             // Marshal playback devices
             if (playbackCount > 0 && pPlaybackDevices != nint.Zero)
-                PlaybackDevices = pPlaybackDevices.ReadArray<DeviceInfo>((int)playbackCount);
+            {
+                if (PlaybackDevices.Length != playbackCount) PlaybackDevices = new DeviceInfo[playbackCount];
+                
+                // Read the native device information directly into our managed array.
+                pPlaybackDevices.ReadIntoArray(PlaybackDevices, playbackCount);
+            }
             else
-                PlaybackDevices = [];
+            {
+                if (PlaybackDevices.Length != 0) PlaybackDevices = [];
+            }
 
             // Marshal capture devices
             if (captureCount > 0 && pCaptureDevices != nint.Zero)
-                CaptureDevices = pCaptureDevices.ReadArray<DeviceInfo>((int)captureCount);
+            {
+                if (CaptureDevices.Length != captureCount) CaptureDevices = new DeviceInfo[captureCount];
+                pCaptureDevices.ReadIntoArray(CaptureDevices, captureCount);
+            }
             else
-                CaptureDevices = [];
+            {
+                if (CaptureDevices.Length != 0) CaptureDevices = [];
+            }
         }
         finally
         {
-            if (pPlaybackDevices != nint.Zero) Native.FreeDeviceInfos(pPlaybackDevices, playbackCount);
-            if (pCaptureDevices != nint.Zero) Native.FreeDeviceInfos(pCaptureDevices, captureCount);
+            if (pPlaybackDevices != nint.Zero) Native.FreeDeviceInfos(pPlaybackDevices, playbackCountUint);
+            if (pCaptureDevices != nint.Zero) Native.FreeDeviceInfos(pCaptureDevices, captureCountUint);
         }
     }
 }

Src/Providers/NetworkDataProvider.cs

@@ -7,7 +7,6 @@
 using SoundFlow.Interfaces;
 using SoundFlow.Structs;
 
-
 namespace SoundFlow.Providers;
 
 /// <summary>
@@ -239,6 +238,7 @@ public virtual void Dispose()
 
 /// <summary>
 ///     Handles direct audio streams (e.g., MP3, WAV, OGG files).
+///     Uses a background buffering strategy for large files to prevent network issues from crashing the audio thread.
 /// </summary>
 internal sealed class DirectStreamProvider(AudioEngine engine, AudioFormat format, string url, HttpClient client)
     : NetworkDataProviderBase(engine, format, url, client)
@@ -270,8 +270,10 @@ public override async Task InitializeAsync()
         }
         else
         {
-            // Otherwise, use the live network stream. Seeking will not be supported in this case.
-            _stream = await response.Content.ReadAsStreamAsync();
+            // For large or chunked streams, use a buffered stream.
+            var bufferedStream = new BufferedNetworkStream();
+            bufferedStream.StartProducerTask(response); // Starts the background download.
+            _stream = bufferedStream;
         }
 
         _decoder = Engine.CreateDecoder(_stream, Format);
@@ -606,4 +608,170 @@ public override void Dispose()
             _audioBuffer.Clear();
         }
     }
+}
+
+/// <summary>
+///     A thread-safe, in-memory stream that acts as a circular buffer between a producer (network download)
+///     and a consumer (audio decoder). It blocks reads when empty and writes when full.
+/// </summary>
+internal sealed class BufferedNetworkStream(int bufferSize = 1 * 1024 * 1024) : Stream
+{
+    private enum DownloadState { Buffering, Completed, Failed }
+
+    private readonly byte[] _buffer = new byte[bufferSize];
+    private int _writePosition;
+    private int _readPosition;
+    private int _bytesAvailable;
+
+    private readonly object _lock = new();
+    private volatile DownloadState _state = DownloadState.Buffering;
+    private CancellationTokenSource? _cts;
+    private Task? _producerTask;
+    private bool _isDisposed;
+    
+    /// <summary>
+    /// Starts the background producer task that reads from the network response and fills the buffer.
+    /// This method takes ownership of the HttpResponseMessage.
+    /// </summary>
+    /// <param name="sourceResponse">The HTTP response message containing the content stream.</param>
+    public void StartProducerTask(HttpResponseMessage sourceResponse)
+    {
+        _cts = new CancellationTokenSource();
+        _producerTask = Task.Run(async () =>
+        {
+            var tempBuffer = ArrayPool<byte>.Shared.Rent(16384); // 16KB read buffer
+            try
+            {
+                await using var sourceStream = await sourceResponse.Content.ReadAsStreamAsync(_cts.Token);
+                while (!_cts.IsCancellationRequested)
+                {
+                    var bytesRead = await sourceStream.ReadAsync(tempBuffer, _cts.Token);
+                    if (bytesRead == 0) break; // End of network stream
+                    
+                    Write(tempBuffer, 0, bytesRead);
+                }
+
+                if (!_cts.IsCancellationRequested) SignalCompletion();
+            }
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                // Network error occurred.
+                SignalFailure();
+            }
+            finally
+            {
+                ArrayPool<byte>.Shared.Return(tempBuffer);
+                sourceResponse.Dispose();
+            }
+        });
+    }
+
+    public override int Read(byte[] buffer, int offset, int count)
+    {
+        lock (_lock)
+        {
+            while (_bytesAvailable == 0 && _state == DownloadState.Buffering && !_isDisposed)
+            {
+                Monitor.Wait(_lock);
+            }
+
+            if (_bytesAvailable == 0) return 0; // End of stream or failure
+
+            var bytesToRead = Math.Min(count, _bytesAvailable);
+            
+            // Read from circular buffer
+            var firstChunkSize = Math.Min(bytesToRead, _buffer.Length - _readPosition);
+            Buffer.BlockCopy(_buffer, _readPosition, buffer, offset, firstChunkSize);
+            _readPosition = (_readPosition + firstChunkSize) % _buffer.Length;
+
+            if (firstChunkSize < bytesToRead)
+            {
+                var secondChunkSize = bytesToRead - firstChunkSize;
+                Buffer.BlockCopy(_buffer, _readPosition, buffer, offset + firstChunkSize, secondChunkSize);
+                _readPosition = (_readPosition + secondChunkSize) % _buffer.Length;
+            }
+            
+            _bytesAvailable -= bytesToRead;
+            Monitor.PulseAll(_lock); // Signal producer that space is available
+            return bytesToRead;
+        }
+    }
+
+    public override void Write(byte[] buffer, int offset, int count)
+    {
+        if (count == 0) return;
+
+        lock (_lock)
+        {
+            while (_buffer.Length - _bytesAvailable < count && !_isDisposed)
+            {
+                Monitor.Wait(_lock);
+            }
+            
+            if (_isDisposed) return;
+
+            // Write to circular buffer
+            var firstChunkSize = Math.Min(count, _buffer.Length - _writePosition);
+            Buffer.BlockCopy(buffer, offset, _buffer, _writePosition, firstChunkSize);
+            _writePosition = (_writePosition + firstChunkSize) % _buffer.Length;
+
+            if (firstChunkSize < count)
+            {
+                var secondChunkSize = count - firstChunkSize;
+                Buffer.BlockCopy(buffer, offset + firstChunkSize, _buffer, _writePosition, secondChunkSize);
+                _writePosition = (_writePosition + secondChunkSize) % _buffer.Length;
+            }
+
+            _bytesAvailable += count;
+            Monitor.PulseAll(_lock); // Signal consumer that data is available
+        }
+    }
+
+    private void SignalCompletion()
+    {
+        lock (_lock)
+        {
+            _state = DownloadState.Completed;
+            Monitor.PulseAll(_lock); // Wake any waiting readers to signal EOS
+        }
+    }
+
+    private void SignalFailure()
+    {
+        lock (_lock)
+        {
+            _state = DownloadState.Failed;
+            Monitor.PulseAll(_lock); // Wake any waiting readers to signal EOS
+        }
+    }
+    
+    protected override void Dispose(bool disposing)
+    {
+        if (_isDisposed) return;
+        _isDisposed = true;
+
+        if (disposing)
+        {
+            lock (_lock)
+            {
+                _cts?.Cancel();
+                Monitor.PulseAll(_lock); // Unblock any waiting threads
+            }
+            _producerTask?.Wait(TimeSpan.FromSeconds(5)); // Wait for producer to finish
+            _cts?.Dispose();
+        }
+
+        base.Dispose(disposing);
+    }
+    
+    #region Not Supported Stream Members
+    public override bool CanRead => !_isDisposed;
+    public override bool CanSeek => false;
+    public override bool CanWrite => !_isDisposed;
+    public override long Length => throw new NotSupportedException();
+    public override long Position { get => throw new NotSupportedException(); set => throw new NotSupportedException(); }
+    public override void Flush() { }
+    public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
+    public override void SetLength(long value) => throw new NotSupportedException();
+    #endregion
 }

Src/SoundFlow.csproj

@@ -15,7 +15,7 @@
         <PackageIcon>logo.png</PackageIcon>
         <PackageReadmeFile>README.md</PackageReadmeFile>
         <PackageTags>audio, sound, mp3, wav, playback, record, voice, volume, fft, simd, crossplatform, miniaudio, c#, .net, echo, noise</PackageTags>
-        <Version>1.2.1-dev0</Version>
+        <Version>1.2.1</Version>
         <PackageReleaseNotes>https://github.com/LSXPrime/SoundFlow/releases</PackageReleaseNotes>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
         <Company>LSXPrime</Company>

Src/Utils/Extensions.cs

@@ -1,5 +1,6 @@
 using System.Runtime.InteropServices;
 using SoundFlow.Enums;
+using SoundFlow.Structs;
 
 namespace SoundFlow.Utils;
 
@@ -40,21 +41,45 @@ public static unsafe Span<T> GetSpan<T>(nint ptr, int length) where T : unmanage
     }
 
     /// <summary>
-    ///     Reads an array of structures from a native memory pointer.
+    ///     Reads an array of structures from a native memory pointer into a pre-allocated destination array.
     /// </summary>
     /// <typeparam name="T">The type of the structures to read. Must be a value type.</typeparam>
     /// <param name="pointer">The native pointer to the start of the array.</param>
+    /// <param name="destination">The pre-allocated array to write the structures into.</param>
     /// <param name="count">The number of structures to read.</param>
-    /// <returns>An array of structures of type <typeparamref name="T"/> read from the specified pointer.</returns>
-    public static T[] ReadArray<T>(this nint pointer, int count) where T : struct
+    /// <exception cref="ArgumentException">Thrown if the destination array is smaller than <paramref name="count"/>.</exception>
+    public static void ReadIntoArray<T>(this nint pointer, T[] destination, int count) where T : struct
     {
-        var array = new T[count];
+        if (destination.Length < count)
+        {
+            throw new ArgumentException("Destination array is not large enough to hold the requested number of items.", nameof(destination));
+        }
+
+        if (count == 0) return;
+
+        var elementSize = Marshal.SizeOf<T>();
         for (var i = 0; i < count; i++)
         {
-            var currentPtr = (nint)((long)pointer + i * Marshal.SizeOf<T>());
-            array[i] = Marshal.PtrToStructure<T>(currentPtr);
+            var currentPtr = (nint)(pointer + (long)i * elementSize);
+            destination[i] = Marshal.PtrToStructure<T>(currentPtr);
         }
+    }
+
 
+    /// <summary>
+    ///     Reads an array of structures from a native memory pointer, allocating a new managed array.
+    /// </summary>
+    /// <typeparam name="T">The type of the structures to read. Must be a value type.</typeparam>
+    /// <param name="pointer">The native pointer to the start of the array.</param>
+    /// <param name="count">The number of structures to read.</param>
+    /// <returns>A new array of structures of type <typeparamref name="T"/> read from the specified pointer.</returns>
+    public static T[] ReadArray<T>(this nint pointer, int count) where T : struct
+    {
+        if (count == 0)
+            return [];
+        
+        var array = new T[count];
+        ReadIntoArray(pointer, array, count);
         return array;
     }
-}
+}