Sa.Media 0.20.0

dotnet add package Sa.Media --version 0.20.0
                    
NuGet\Install-Package Sa.Media -Version 0.20.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Sa.Media" Version="0.20.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Sa.Media" Version="0.20.0" />
                    
Directory.Packages.props
<PackageReference Include="Sa.Media" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Sa.Media --version 0.20.0
                    
#r "nuget: Sa.Media, 0.20.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Sa.Media@0.20.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Sa.Media&version=0.20.0
                    
Install as a Cake Addin
#tool nuget:?package=Sa.Media&version=0.20.0
                    
Install as a Cake Tool

Sa.Media

English | Русский

Async, memory-efficient WAV file reader for .NET 10+. Designed for Native AOT compatibility with zero allocations on hot paths. Includes a stereo cross-feed suppression pipeline (Sa.Media.Echo) for separating closely miked sources.

Installation

dotnet add package Sa.Media

Contents

Features

  • Fully asynchronous — PipeReader-based streaming, no blocking I/O
  • Memory efficient — ArrayPool/MemoryPool buffer reuse, minimal GC pressure
  • Multi-format support — PCM 8/16/24/32-bit, IEEE Float 32/64-bit
  • Extensible — supports WAVE_FORMAT_EXTENSIBLE chunks
  • Time-based trimming — read only the portion you need via TimeRange
  • Channel-aware — per-channel sample enumeration with position tracking
  • Automatic chunk skipping — JUNK, LIST, and other metadata chunks are transparently skipped
  • Cross-feed suppression — stereo separation pipeline in Sa.Media.Echo

Quick Start

Read header

using var stream = File.OpenRead("test.wav");
await using var reader = AsyncWavReader.Create(stream);

var header = await reader.GetHeaderAsync(ct);
Console.WriteLine($"{header.NumChannels}ch @ {header.SampleRate}Hz, " +
    $"{header.BitsPerSample}-bit {header.AudioFormat}");

Read raw samples per channel

await using var reader = AsyncWavReader.CreateFromFile("test.wav");

await foreach (var packet in reader.ReadSamplesPerChannelAsync(
    cancellationToken: ct))
{
    Console.WriteLine($"Ch#{packet.ChannelId}: {packet.Sample.Length} bytes at pos {packet.Position}");
}

Read normalized double samples [-1.0 … 1.0]

await using var reader = AsyncWavReader.CreateFromFile("test.wav");

await foreach (var packet in reader.ReadDoubleSamplesAsync(cancellationToken: ct))
{
    Console.WriteLine($"Ch#{packet.ChannelId}: {packet.Sample:F4}");
}

Read normalized float samples (DSP path)

await using var reader = AsyncWavReader.CreateFromFile("test.wav");

// Same values as the double path, but converted straight to float — no double round-trip.
await foreach (var packet in reader.ReadFloatSamplesAsync(cancellationToken: ct))
{
    Console.WriteLine($"Ch#{packet.ChannelId}: {packet.Sample:F4}");
}

Streamable batches (ideal for audio pipelines)

await using var reader = AsyncWavReader.CreateFromFile("test.wav");

await foreach (var batch in reader.ReadStreamableChunksAsync(
    samplesPerBatch: 4096,
    cancellationToken: ct))
{
    // Each yield produces independent data — safe to process asynchronously
}

Trim by time range

await using var reader = AsyncWavReader.CreateFromFile("test.wav");

// Read only seconds 5–15
var range = TimeRange.Seconds(5, 15);
await foreach (var packet in reader.ReadDoubleSamplesAsync(range, cancellationToken: ct))
{
    // Samples from the trimmed range only
}

Convert to different format

await using var reader = AsyncWavReader.CreateFromFile("input.wav");

// Convert to 24-bit PCM
await foreach (var packet in reader.ConvertToFormatAsync(
    AudioEncoding.Pcm24BitSigned,
    cancellationToken: ct))
{
    // Raw 24-bit PCM bytes per sample
}

Cross-feed suppression (Sa.Media.Echo)

Separates a stereo recording of two closely miked speakers/microphones into two near-dialectal tracks. The algorithm estimates the acoustic cross-talk between channels (y_L = x_L + β·x_R, y_R = x_R + α·x_L) and inverts the model.

Supports two modes:

  • Linear — cross-talk cancellation only (fast, low memory).
  • Aggressive — cross-talk cancellation plus per-frequency spectral masking for sharper separation (higher CPU/GPU cost).
using Sa.Media.Echo;

// Automatic mode: in-memory for short clips, streaming for long ones
await CrossFeedSeparator.ExecuteAsync(new AudioSeparationOptions(
    InputPath: "recording.wav",
    OutputPath: "separated.wav"), CancellationToken.None);

// Aggressive mode with spectral masking
await CrossFeedSeparator.ExecuteAsync(new AudioSeparationOptions(
    InputPath: "recording.wav",
    OutputPath: "separated_aggressive.wav",
    Processing: CrossFeedSeparator.ProcessingMode.Aggressive,
    DominanceThresholdDb: 6.0,   // dB threshold for single-speaker regions
    SpectralMaskPower: 4.0,      // spectral mask sharpening exponent
    MaskFloor: 0.01),            // minimum mask floor [0, 1]
    CancellationToken.None);

The separator must run on a 2-channel (stereo) recording. Output is 16-bit PCM WAV, peak-normalized. The linear path streams and avoids loading the whole file into memory; the in-memory path kicks in automatically for short recordings (≤ 32 M frames, ~12 minutes at 44.1 kHz).


Supported Formats

Format Read Write
PCM 8-bit (unsigned) ✅ ✅
PCM 16-bit (signed) ✅ ✅
PCM 24-bit (signed) ✅ ✅
PCM 32-bit (signed) ✅ ✅
IEEE Float 32-bit ✅ ✅
IEEE Float 64-bit ✅ ✅

All formats support mono and stereo. Unknown chunks (JUNK, LIST, etc.) are automatically skipped.


Public API Reference

Core types

Type Description
AsyncWavReader Main async WAV reader — creates from Stream or file path
WavHeader Parsed RIFF/WAV header with computed properties (IsPcm, IsStereo, Duration)
AudioPacket Record: (ChannelId, Sample, Position, IsEof) — raw/conversion bytes
AudioNormalizedPacket Record: (ChannelId, Sample, Position, IsEof) — normalized double [-1.0, 1.0]
AudioFloatPacket Record: (ChannelId, Sample, Position, IsEof) — normalized float [-1.0, 1.0]
TimeRange Record: (From, To) — time-based trimming with factory methods
AudioEncoding Enum: PCM 8/16/24/32, IEEE Float 32/64
WaveFormatType Enum: Pcm, Adpcm, IeeeFloat, Extensible

Echo types (Sa.Media.Echo)

Type Description
CrossFeedSeparator Stereo cross-feed suppression pipeline (entry point)
CrossFeedSeparator.ProcessingMode Enum: Auto, MaximumSpeed, MinimumMemory, MinimumMemoryFastNormalize, Aggressive
AudioSeparationOptions Record: InputPath, OutputPath, Processing, DominanceThresholdDb, SpectralMaskPower, MaskFloor

Key methods on CrossFeedSeparator

Method Returns Description
ExecuteAsync(AudioSeparationOptions, ct) Task Runs separation and writes the output WAV

Key methods on AsyncWavReader

Method Returns Description
Create(Stream) AsyncWavReader Factory from stream
CreateFromFile(string) AsyncWavReader Factory from file path
GetHeaderAsync(ct) Task<WavHeader> Thread-safe lazy header parsing; not poisoned by the first caller's cancellation
ReadSamplesPerChannelAsync() IAsyncEnumerable<AudioPacket> Raw samples per channel
ReadDoubleSamplesAsync() IAsyncEnumerable<AudioNormalizedPacket> Normalized double samples
ReadFloatSamplesAsync() IAsyncEnumerable<AudioFloatPacket> Normalized float samples (DSP path, no double)
ConvertToFormatAsync() IAsyncEnumerable<AudioPacket> Convert to target encoding
ReadStreamableChunksAsync() IAsyncEnumerable<AudioPacket> Batched samples for pipelines

TimeRange factories

Method Example Description
TimeRange.Create(from, to) Basic constructor From/to TimeSpan
TimeRange.Ms(from, to) By milliseconds Millisecond precision
TimeRange.Seconds(from, to) By seconds Double-second precision
TimeRange.RangeFromDuration(from, dur) From start + duration Build from offset
TimeRange.Default [0, ∞) Full file, no trim

Performance Notes

  • allowBufferReuse=true (default) reuses pooled buffers across yields — caller must copy before next iteration
  • allowBufferReuse=false allocates a fresh array per sample — safer for parallel consumers
  • ReadStreamableChunksAsync keeps allowBufferReuse:true by default: each per-channel batch points at that channel's pooled buffer and is overwritten by the next batch of the same channel, so copy or process the memory before advancing (pass allowBufferReuse:false for independent arrays)
  • All internal awaits use ConfigureAwait(false) — safe in any synchronization context

Project Layout

src/Sa.Media/
├── AsyncWavReader.cs        # Main reader class
├── AudioEncoding.cs         # Format enum
├── AudioEncodingExtensions.cs
├── AudioPacket.cs           # Raw sample record
├── AudioNormalizedPacket.cs # Normalized double sample record
├── AudioFloatPacket.cs      # Normalized float sample record
├── BinaryPipeReader.cs      # Little-endian binary reader
├── PipeReaderExtensions.cs  # Skip helpers
├── SampleConverter.cs       # PCM ↔ double conversion
├── TimeRange.cs             # Trimming range
├── TimeRangeExtensions.cs   # Expander, merge, sort
├── WavHeader.cs             # RIFF header model
├── WavHeaderReader.cs       # Header parser
├── WaveFormatType.cs        # Format type enum
└── WaveFormatTypeExtensions.cs

src/Sa.Media/Echo/
├── CrossFeedSeparator.cs     # Entry point — estimate + invert cross-talk
├── AudioSeparationOptions.cs # Public options record
├── AggressiveMode.cs         # STFT-based spectral masking
├── AudioMath.cs              # Coefficient math, percentile, normalization
├── AudioConstants.cs         # Tunable constants
└── WavIO.cs                  # Interleaved float I/O helpers

License

MIT

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.20.0 88 11/13/2026
0.18.0 95 11/3/2026
0.17.0 100 10/29/2026
0.16.0 107 10/14/2026
0.15.0 105 10/2/2026
0.12.0 136 7/28/2026
0.11.0 123 7/14/2026
0.10.0 135 7/2/2026
0.9.0 137 3/20/2026
0.8.1 132 3/12/2026
0.8.0 137 2/10/2026
0.7.0 136 1/27/2026
0.6.0 141 1/15/2026
0.5.0 136 12/29/2025
0.4.0 312 12/17/2025
0.3.0 181 10/17/2025
0.1.0 229 9/1/2025
0.0.3 216 6/16/2025
0.0.2 246 5/28/2025