NAudio.SoundFile 3.0.0-preview.15

Prefix Reserved
This is a prerelease version of NAudio.SoundFile.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package NAudio.SoundFile --version 3.0.0-preview.15
                    
NuGet\Install-Package NAudio.SoundFile -Version 3.0.0-preview.15
                    
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="NAudio.SoundFile" Version="3.0.0-preview.15" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="NAudio.SoundFile" Version="3.0.0-preview.15" />
                    
Directory.Packages.props
<PackageReference Include="NAudio.SoundFile" />
                    
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 NAudio.SoundFile --version 3.0.0-preview.15
                    
#r "nuget: NAudio.SoundFile, 3.0.0-preview.15"
                    
#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 NAudio.SoundFile@3.0.0-preview.15
                    
#: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=NAudio.SoundFile&version=3.0.0-preview.15&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=NAudio.SoundFile&version=3.0.0-preview.15&prerelease
                    
Install as a Cake Tool

NAudio.SoundFile

Cross-platform audio file reading and writing for NAudio, backed by libsndfile.

Type Role
SoundFileReader WaveStream + ISampleProvider — decode WAV/AIFF/FLAC/Ogg/Opus/MP3
SoundFileWriter Stream sink — encode WAV/AIFF/FLAC/Ogg-Vorbis/Opus/MP3
SoundFileCapabilities query which codecs the installed libsndfile supports
SoundFileException thrown on libsndfile errors (exposes ErrorCode)

This is the first cross-platform FLAC/Vorbis/Opus encoder in NAudio, and on Linux/macOS the first general-purpose decoder (there is no Media Foundation off Windows).

Platform

Truly cross-platform — net9.0, no [SupportedOSPlatform]. It P/Invokes a system libsndfile, resolved automatically per OS (libsndfile.so.1 / libsndfile.1.dylib / sndfile.dll / libsndfile-1.dll). You must provide it:

sudo apt install libsndfile1     # Debian/Ubuntu
brew install libsndfile          # macOS
vcpkg install libsndfile         # Windows (or the official binaries)

Not pulled in by the NAudio meta-package — reference it explicitly:

dotnet add package NAudio.SoundFile

Supported formats

Format Read Write Requires
WAV, AIFF, AU, CAF, W64, RAW always
FLAC libsndfile built with libFLAC (typical)
Ogg/Vorbis libvorbis (typical)
Ogg/Opus libsndfile ≥ 1.0.29 + libopus
MP3 libsndfile ≥ 1.1.0

Codec availability depends on how libsndfile was built — query it:

foreach (var f in SoundFileCapabilities.GetSupportedMajorFormats())
    Console.WriteLine(f);
bool canFlac = SoundFileCapabilities.IsFormatSupported(SoundFileMajorFormat.Flac);

AAC / M4A / ALAC / WMA are out of scope (the MPEG-4 family is FFmpeg territory).

Read any file

SoundFileReader decodes to 32-bit float, so it is both a WaveStream and an ISampleProvider:

using NAudio.SoundFile;
using NAudio.Wave;

using var reader = new SoundFileReader("song.flac");
Console.WriteLine($"{reader.WaveFormat} {reader.TotalTime}");
// feed it into any NAudio output, mixer or sample pipeline

Write FLAC / Ogg / Opus

using (var source = new SoundFileReader("in.wav"))
    SoundFileWriter.CreateSoundFile("out.flac", source,
        SoundFileMajorFormat.Flac,
        new SoundFileWriterOptions { CompressionLevel = 0.8 });

// Ogg Vorbis at VBR quality 0.6, with tags
using (var source = new SoundFileReader("in.wav"))
    SoundFileWriter.CreateSoundFile("out.ogg", source,
        SoundFileMajorFormat.OggVorbis,
        new SoundFileWriterOptions
        {
            VbrQuality = 0.6,
            Tags = new SoundFileTags { Title = "Demo", Artist = "NAudio" }
        });

Read embedded metadata back:

using var reader = new SoundFileReader("song.flac");
Console.WriteLine($"{reader.Tags.Artist} – {reader.Tags.Title}");
Console.WriteLine(SoundFileCapabilities.LibraryVersion);

The output format is also inferred from the extension:

SoundFileWriter.CreateSoundFile("out.flac", source); // → FLAC

Streams

Both ends work over a System.IO.Stream (via libsndfile virtual I/O):

using var ms = new MemoryStream();
SoundFileWriter.WriteSoundFileToStream(ms, source, SoundFileMajorFormat.OggVorbis, null);
ms.Position = 0;
using var reader = new SoundFileReader(ms);   // stream not disposed by the reader

FLAC/Ogg/Opus/MP3 stream fine to a forward-only target; WAV/AIFF back-patch their header at close and require a seekable stream (the writer throws early if you pair a non-seekable stream with such a format).

Notes

  • The writer accepts 16-bit PCM or 32-bit IEEE float input — the two container types NAudio pipelines naturally produce. Convert other formats with SampleToWaveProvider16 or .ToSampleProvider() first.
  • AOT-compatible: source-generated [LibraryImport], SafeHandle lifetime, and [UnmanagedCallersOnly] virtual-I/O callbacks.
  • The wrapper is MIT; libsndfile itself is LGPL-2.1+ and supplied by the user as a system library (no binary is shipped) — the same model as NAudio.Alsa.

Tutorial

For a worked walkthrough (reading, encoding, format conversion, streams, tags, capability detection) see Cross-platform audio file reading and writing with NAudio.SoundFile.

Product Compatible and additional computed target framework versions.
.NET net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  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 (1)

Showing the top 1 NuGet packages that depend on NAudio.SoundFile:

Package Downloads
NAudio.Sampler

A cross-platform software sampler for NAudio that plays MIDI through SoundFont (.sf2) and SFZ instruments, or a single sample mapped across the keyboard. Polyphonic voice engine with DAHDSR envelopes, LFOs, modulated filters, the SF2 modulator engine and reverb/chorus sends, exposed as an ISampleProvider.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
3.0.0-preview.16 51 7/1/2026
3.0.0-preview.15 54 6/28/2026
3.0.0-preview.14 61 6/25/2026
3.0.0-preview.10 73 6/8/2026
3.0.0-preview.9 63 5/27/2026
3.0.0-preview.8 66 5/22/2026
3.0.0-preview.7 61 5/21/2026
3.0.0-preview.6 63 5/21/2026

NAudio 3 is a major release. The single `NAudio` assembly is now split into
focused, independently usable packages; the minimum target framework moves to
`net9.0`; the core is cross-platform and Native-AOT compatible; and several
large new subsystems — a cross-platform effects suite, a software sampler, VST 3
hosting, and ALSA and libsndfile backends — join the library. The headline
changes are below; see the linked tutorials and the per-package READMEs for the
detail.

#### Packages and platform

* Minimum target framework is now `net9.0` — legacy .NET Framework and .NET Standard 2.0 support is dropped
* `NAudio` is now a set of focused packages: `NAudio.Core`, `NAudio.Midi`, `NAudio.WinMM`, `NAudio.Wasapi`, `NAudio.Asio`, `NAudio.WinForms`, `NAudio.Dmo`, plus the new `NAudio.Effects` (in `NAudio.Core`), `NAudio.Sampler`, `NAudio.Vst3`, `NAudio.Alsa` and `NAudio.SoundFile`. The `NAudio` meta-package still pulls the Windows stack together so existing consumers see no change. See `Docs/Architecture/NAudio3AssemblyLayoutPlan.md`
* `NAudio.Core`, `NAudio.Midi` and `NAudio.Wasapi` are Native-AOT compatible (`IsAotCompatible=true`), enforced in CI by `NAudioAotSmokeTest`. `NAudio.Midi`, `NAudio.Effects`, `NAudio.Sampler` and `NAudio.SoundFile` are cross-platform

#### New capabilities

Each new subsystem has its own tutorial/README; only the headline is listed here.

* **Audio effects** — a cross-platform `NAudio.Effects` framework: `IAudioEffect` / `EffectSampleProvider` / `EffectChain` with click-free bypass, dry/wet mix and an optional parameter model, plus a broad effect set (EQ and filtering, dynamics, saturation/lo-fi, delay and modulation, reverb including FFT convolution, pitch shifting, and voice-comms AGC/noise-suppression). See [Docs/AudioEffects.md](Docs/AudioEffects.md)
* **Software sampler** — new `NAudio.Sampler` package: polyphonic, cross-platform playback of SoundFont (`.sf2`) and SFZ instruments and single-sample instruments, rendered as an `ISampleProvider` (SF2 modulator engine, DAHDSR envelopes, LFOs, modulated filters, reverb/chorus sends, voice stealing, choke groups). See [Docs/Sampler.md](Docs/Sampler.md)
* **VST 3 hosting (preview)** — new `NAudio.Vst3` package (Windows-only): discover, load and host VST 3 effects and instruments, with parameters, state and `.vstpreset` presets, native editor windows, program lists/units, latency compensation, and live/offline MIDI-file playback through the shared MIDI pipeline. See the `NAudio.Vst3` README and `Docs/Architecture/Vst3Hosting.md`. VST is a registered trademark of Steinberg Media Technologies GmbH
* **Cross-platform audio files** — new `NAudio.SoundFile` package: read and write WAV/AIFF/FLAC/Ogg-Vorbis/Opus/MP3 via a system libsndfile on Windows, Linux and macOS (the first cross-platform FLAC/Vorbis/Opus *encoder* in NAudio). See [Docs/CrossPlatformAudioFilesWithSoundFile.md](Docs/CrossPlatformAudioFilesWithSoundFile.md) (#1289)
* **Linux audio** — new `NAudio.Alsa` package: `AlsaOut` (`IWavePlayer`) and `AlsaIn` (`IWaveIn`) plus `AlsaDeviceEnumerator`, backed by `libasound`. See [Docs/PlayAudioFileLinuxAlsa.md](Docs/PlayAudioFileLinuxAlsa.md) and [Docs/RecordAudioFileLinuxAlsa.md](Docs/RecordAudioFileLinuxAlsa.md) (#1182)
* **Sequencing** — a portable `NAudio.Sequencing` namespace in `NAudio.Core` (tempo and time-signature maps, transport, `EventTimeline`, swing, and a sample-accurate per-buffer dispatcher) underpinning MIDI-file playback and the sampler. See `Docs/Architecture/Sequencing.md`
* **Modern WASAPI and ASIO** — high-level `WasapiPlayer` / `WasapiRecorder` (built via `WasapiPlayerBuilder` / `WasapiRecorderBuilder`: `IAudioClient3` low-latency, MMCSS, `IAsyncDisposable`, zero-copy buffers, process-loopback capture, default-device automatic stream routing via `WithDefaultDeviceStreamRouting()` + `BuildAsync()` so playback/capture follows the default endpoint and re-routes when it changes (Windows 10 1607+, #942), acoustic-echo-cancellation reference control via `WithEchoCancellationReferenceEndpoint` / `IAcousticEchoCancellationControl` (Windows 11 build 22621+, #1223) and a `WithCommunicationsMode` capture option that engages the system AEC/noise-suppression/AGC pipeline (also fixing `WasapiPlayerBuilder.WithCategory`, which previously did not apply the stream category), automatic resample-free format adaptation — bit depth and channels — in exclusive and low-latency modes, `WasapiPlayer.GetPlaybackCapability` to validate options up front, and `LowLatencyActive` / `WithLowLatency(required)` to control and inspect low-latency fallback on both `WasapiPlayer` and `WasapiRecorder` (recorder low-latency capture added in #1100)), and a new `AsioDevice` replacing `AsioOut` (explicit playback/recording/duplex modes, non-contiguous channels, per-channel `Span<float>` callbacks, driver-reset recovery, per-buffer timing). See [Docs/WasapiPlayer.md](Docs/WasapiPlayer.md), [Docs/WasapiRecorder.md](Docs/WasapiRecorder.md) and [Docs/AsioMigration.md](Docs/AsioMigration.md)
* **MIDI** — `NAudio.Midi` is now cross-platform; new WinRT `WinRTMidiIn` / `WinRTMidiOut` (in `NAudio.Wasapi`) and backend-agnostic `IMidiInput` / `IMidiOutput`; a new `IMidiInstrument` seam with `MidiFileSequence` / `SequencedMidiPlayer` / `OfflineMidiRenderer` / `LiveMidiInstrument` gives an end-to-end MIDI-file → audio pipeline that drives the sampler or a hosted VST 3 instrument. `MidiFile` now also reads RIFF-RMID (`.rmi`) files (#1236)
* **WaveFormatExtensible** — new constructors let you set the SubFormat (or just choose PCM vs IEEE float via a `useIeeeFloat` flag), valid-bits-per-sample and channel mask explicitly (e.g. 32-bit integer PCM, or 24 valid bits in a 32-bit container), and `ValidBitsPerSample` / `ChannelMask` are now readable; a new `[Flags] Speakers` enum names the standard speaker positions for building channel masks (#1325)
* **WASAPI sessions** — `AudioSessionControl.SetDuckingPreference(bool)` exposes `IAudioSessionControl2::SetDuckingPreference`, so a communications session can opt out of the system's auto-ducking of other audio streams (#760)
* **Sample providers / DSP** — new `ChannelMixerSampleProvider` with ready-made `ChannelMixMatrix` routings (mono↔stereo, stereo→5.1, …), thanks to @antiduh (#982); a new `FftProcessor`, an `IWaveChunkInterpreter<T>` extension point (cue lists, BWF `bext`, LIST/INFO), `Span<T>` overloads across the codec/DSP surface, and reusable building blocks (`EnvelopeFollower`, `DelayLine`, `Lfo`, `Oversampler`, `LinkwitzRileyCrossover`, `PartitionedConvolver`, …) underpinning the effects and sampler; `SmbPitchShiftingSampleProvider` now exposes its phase-vocoder latency (`Latency` / `LatencySamples` / `LatencySamplesPerChannel`) so shifted audio can be time-aligned with unshifted audio (#922)

#### Breaking changes

The full upgrade walkthrough — every breaking change with before/after code — is
in **[Migrating from NAudio 2 to NAudio 3](Docs/MigratingFromNAudio2.md)**. Most
apps need only re-target to `net9.0` and adjust custom providers to the new
`Span<T>` `Read` signature. The highest-impact changes:

* Minimum target framework is now `net9.0` (legacy .NET Framework / .NET Standard 2.0 dropped)
* `IWaveProvider.Read` / `ISampleProvider.Read` now take a single `Span<byte>` / `Span<float>` (was buffer/offset/count) — callers migrate via `source.Read(buffer.AsSpan(offset, count))`; implementations override the span method
* `WasapiOut`, `WasapiCapture` and `WasapiLoopbackCapture` are `[Obsolete]` in favour of `WasapiPlayer` / `WasapiRecorder` (the legacy types still ship and work); `WasapiOut`'s embedded exclusive-mode resampler was removed, but it now adapts bit depth and channels (PCM↔float, mono↔stereo) in exclusive mode, so only a sample-rate mismatch requires upstream resampling
* `WasapiRecorderBuilder.WithProcessLoopback(processId, mode)` now captures audio rendered by a specific process (and optionally its child processes) via `ActivateAudioInterfaceAsync` — build it with the new `BuildAsync()` (Windows 10 2004 / build 19041+)
* `WaveOut` / `WaveIn` now default to event-driven callbacks; the window-based variants are renamed `WaveOutWindow` / `WaveInWindow` in `NAudio.WinForms`
* Some types moved package/namespace as part of the split — classic Windows MIDI I/O and `winmm` types to `NAudio.WinMM`; the DMO/DirectSound types into the new `NAudio.Dmo` package; plus smaller moves (`AudioVolumeLevel`, `CaptureState`, `DmoMp3FrameDecompressor`). Meta-package consumers are unaffected
* `SimpleCompressorStream`, `ImpulseResponseConvolution` and `NAudio.Extras.Equalizer` were removed — superseded by `NAudio.Effects` (`CompressorEffect`, `ConvolutionReverbEffect`, `Equalizer`)

#### Notable bug fixes

In addition to the fixes below, the new sampler/SFZ/SoundFont subsystem saw
extensive correctness work during development — see [Docs/Sampler.md](Docs/Sampler.md).

* `WaveOut`: fixed a race where stopping/disposing faster than the buffer latency could throw a `NullReferenceException` via `PlaybackStopped` (#804)
* `WaveFileWriter`: removed the finalizer that fired an unconditional `Debug.Assert` and could crash the process on the finalizer thread when construction had thrown
* `WaveFileWriter.WriteSample` / `WriteSamples`: fixed 32-bit `WaveFormatExtensible` output writing near-silence or corrupt data — `WriteSample(float)` truncated the normalised float to an `Int32` before scaling (writing zero for almost every sample), and both paths ignored the format's SubFormat; they now write IEEE-float or integer-PCM samples according to the declared subformat (#651)
* `WaveExtensionMethods.AsStandardWaveFormat`: now also resolves the SubFormat of a `WaveFormatExtraData` (how an extensible format read from a file/stream is materialised), not just a `WaveFormatExtensible`
* `AudioClient.Dispose` is now idempotent and safe against concurrent/re-entrant disposal, fixing an intermittent interop `NullReferenceException` (#1183)
* `AcmInterop`: serialised all `msacm32` P/Invokes process-wide, fixing process-killing access violations under concurrent ACM use
* `WaveFileReader` / `AiffFileReader`: malformed headers declaring `BlockAlign=0` now throw `InvalidDataException` from the constructor instead of `DivideByZeroException` later (#1254); `WaveFileReader` no longer throws on an oversized `fmt` `cbSize` (#482)
* `WaveFileReader`: a `data` chunk declaring a bogus/oversized length (e.g. FFmpeg's `0xFFFF1000` placeholder when writing to a non-seekable pipe) is now clamped to the bytes actually present, so reading from a `MemoryStream` no longer throws and the reported length reflects the available audio (#1090)
* `WaveFormat.Serialize`: PCM formats now write the canonical 16-byte `fmt ` chunk (#934, #1098)
* `WaveViewer`: fixed rendering upside-down (#801, #818) and now renders any source format correctly via `ToSampleProvider()` (#564)
* `ToSampleProvider()` now handles `WAVE_FORMAT_EXTENSIBLE` PCM and IEEE float sources (e.g. multichannel / >16-bit WAV files) instead of throwing `Unsupported source encoding` (#639)
* `AudioSessionControl`: now supports multiple registered event clients without leaking, and `UnRegisterEventClient` honours its argument (#1263)
* `MMDevice.Dispose` now releases the device's property store deterministically (`PropertyStore` is now `IDisposable`), instead of leaving it to be reclaimed by COM finalization (#1145)
* `AudioEndpointVolume.OnVolumeNotification`: fixed per-channel notifications all returning channel 0's volume (#351)
* `CueListInterpreter`: WAV files with cue points but no labels now return cues with empty labels instead of null (#549)
* `ResamplerDmoStream`: fixed an infinite loop on `Read` after seeking and the loss of the resampler tail at end-of-stream (#607, #608)
* `LoopStream.Read`: no longer spins at 100% CPU when the wrapped source can't satisfy a read (#1338)
* `Mp3FileReader`: fixed false sample-rate-change errors near end of file, and more robust MP3 frame parsing against album art / trailing metadata
* `MidiFile`: preserve running-status across meta events (fixes "Read too far")
* `BlockAlignReductionStream.Position`: validates the incoming value, so a block-aligned seek after an arbitrary read no longer wrongly throws (#368)
* `BlockAlignReductionStream.Read`: a single read (or `Stream.CopyTo` chunk) larger than the 4-second internal buffer no longer silently discards the rest of the source and truncates the stream — e.g. converting a non-PCM WAV via `AudioFileReader` on .NET Core (#1022)
* `MmException` messages now append a human-readable `MmResult` description (#1192); `Id3v2Tag.ReadTag` no longer throws/catches for tagless MP3 streams (#265)
* ASIO: implemented missing `Asio64Bit` Int24LSB/Float32LSB conversions and fixed a byte-order bug in `GetSamplePosition`; `WdlResampler` backported three upstream Cockos WDL fixes
* Hardened Media Foundation and DMO interop against COM ref leaks on error paths (`MediaFoundationReader`, `MediaFoundationEncoder`, `MediaFoundationTransform`, `MediaBuffer`, `Mf*` wrappers) (#1293)
* Removed dead `naudio.codeplex.com` links from the README, MixDiff and source comments (#985)

#### Performance

* Vectorised mix-add and volume kernels via `System.Numerics.Tensors` (significantly faster on AVX2)
* `WaveStream.Read(Span<byte>)` is overridden directly on every concrete reader (no intermediate byte-array copy); `WasapiCapture`'s path is now zero-copy via the native WASAPI buffer span
* Eliminated per-`Read` allocations in `SmbPitchShiftingSampleProvider`, `ResamplerDmoStream` and `DmoMp3FrameDecompressor` (#971)
* `Mp3FileReader` builds its table-of-contents lazily on first seek; the `Position` setter no longer blocks and rapid scrub seeks debounce
* The sampler and sequencer render allocation-free and lock-free on the audio thread (control-rate envelope/LFO advancement, indexed region lookup, copy-on-write event timelines)

#### Tooling, packaging and modernisation

* Most COM interop migrated from `[ComImport]` to `[GeneratedComInterface]` / `ComWrappers`, and many P/Invokes to `[LibraryImport]`, across the WASAPI/Core Audio activation chain, Media Foundation, the DMO interfaces, DirectSound and the `ComStream` CCW
* Codebase-wide code-style sweep (file-scoped namespaces, target-typed `new`, string interpolation, …) now enforced at build time via `.editorconfig` / `.globalconfig`; added `.git-blame-ignore-revs` so the mechanical commits don't obscure `git blame`
* Each NAudio package now ships its own README and embeds an SPDX 2.2 SBOM under `/_manifest/spdx_2.2/` in its `.nupkg`, and carries per-package `<Description>` metadata
* Tests migrated from VSTest to `Microsoft.Testing.Platform`, and `NAudioTests` split into cross-platform `NAudio.Core.Tests` and Windows-only `NAudio.Windows.Tests`; migrated to the `.slnx` solution format; renamed `license.txt` to `LICENSE`
* Added a DocFX documentation site (tutorials + API reference) published to GitHub Pages, built from `Docs/` and the source XML comments

#### Demos and test harnesses

* New WPF demo modules for the new subsystems: Convolution Reverb, managed Realtime Effects, VST3 Realtime Effects, VST3 Realtime Instrument, VST3 MIDI File Player, a Live MIDI Sampler and a Single-Sample Editor
* New `NAudioConsoleTest` CLI harness (`run-batch` for JSON test plans, `diagnose` for a structured host-audio snapshot) and `MfStressTest` for the new Media Foundation interop
* WPF demos: spectrum analyser rewritten (correct dB/log-frequency/calibration), new `LiveWaveformControl`, loopback + multi-API device selection in the WAV recording demo, and a drum machine rebuilt on the new `NAudio.Sequencing` primitives
* Replaced the deprecated vendored NSpeex with Opus (Concentus) in the network chat demo
* Modernised the network chat demo: now UDP-only (dropped the unsuitable TCP transport), receivers bind to `IPAddress.Any` so it works across machines (not just loopback — #821), separate listen/remote ports for one-PC experiments, async cancellable sockets, a bounded jitter buffer, capture/playback moved to `WasapiRecorder`/`WasapiPlayer`, and a new [tutorial](Docs/NetworkChatDemo.md)