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
• 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
• 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 (#1289)
• Linux audio — new NAudio.Alsa package: AlsaOut (IWavePlayer) and AlsaIn (IWaveIn) plus AlsaDeviceEnumerator, backed by libasound. See Docs/PlayAudioFileLinuxAlsa.md and 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/WasapiRecorder.md and 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)
• Reading audio from streams — AudioFileReader and CachedSound now have Stream constructors, detecting WAV/AIFF from the stream contents and delegating any other format to Media Foundation, so audio held in an embedded resource or in-memory byte array can be played without writing a temporary file (#927, #963)
• 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); AdsrSampleProvider now exposes the full envelope (DecaySeconds and SustainLevel in addition to AttackSeconds / ReleaseSeconds), supports multi-channel sources, adds Start() / State and an EnvelopeCompleted event, and no longer throws on stereo input (#671)

Breaking changes

The full upgrade walkthrough — every breaking change with before/after code — is in Migrating from NAudio 2 to NAudio 3. 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+)
• WasapiRecorder.DataAvailable now also reports each packet's WASAPI device and QPC positions (devicePosition / qpcPosition), matching the timestamps already exposed by CaptureAsync, so audio captured via the zero-copy event path can be time-aligned with a wall clock (#948)
• WasapiPlayerBuilder.WithRawMode() and WasapiRecorderBuilder.WithRawMode() open a raw stream (AUDCLNT_STREAMOPTIONS_RAW) that bypasses the system signal-processing pipeline (audio enhancements / APO effects such as downmixing toward mono), so samples reach the device unaltered; requires IAudioClient2 (#476)
• 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)
• MixingWaveProvider32 was removed — it was an untested float-only mixer that offered nothing over MixingSampleProvider (use waveProvider.ToSampleProvider() for inputs and .ToWaveProvider() if you need an IWaveProvider out)
• WaveFileWriter / AiffFileWriter no longer dispose a caller-supplied stream — the stream constructor now leaves the stream open (it still flushes/finalizes the header on Dispose), matching the readers' ownership rule; only the filename constructor owns and closes the file. The IgnoreDisposeStream wrapper is no longer needed when writing to a stream you want to keep. If you passed a throwaway stream and relied on the writer closing it, dispose it yourself or use the filename overload (#1040)

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.

• WaveOut: fixed a race where stopping/disposing faster than the buffer latency could throw a NullReferenceException via PlaybackStopped (#804)
• DirectSoundOut: fixed a startup race where the secondary buffer could begin LOOPING playback before it was primed (the priming Feed was gated on PlaybackState, which Play() flips to Playing on the calling thread), so playback could collapse immediately — most visibly when a caller spun on PlaybackState (#759)
• 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)
• WasapiRecorder, WasapiCapture and WasapiLoopbackCapture: a capture device removed mid-recording (unplugged, or the default device changed) no longer crashes the process with an unhandled exception on the capture thread — the teardown Stop/Reset calls that themselves fail on the dead device are now best-effort, so RecordingStopped always fires with the originating exception and the recorder cleans up correctly (#672)
• 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)
• AiffFileReader / AiffFileWriter: 8-bit PCM is now read and written as signed two's-complement per the AIFF spec, instead of being mishandled as unsigned (WAV-style) — fixing DC-shifted/garbled 8-bit AIFF playback (#1178)
• 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)
• RawSourceWaveStream: the byte[] constructor now disposes the MemoryStream it creates internally when the stream is disposed (it previously leaked); a caller-supplied source stream is still left open
• 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
• WdlResampler: reinterleave buffered samples when the channel count changes between calls, and flush denormals in the IIR feedback path (further upstream Cockos WDL backports) (#800)
• Hardened Media Foundation and DMO interop against COM ref leaks on error paths (MediaFoundationReader, MediaFoundationEncoder, MediaFoundationTransform, MediaBuffer, Mf* wrappers) (#1293)
• MediaFoundationReader: seeking is now sample-accurate — since IMFSourceReader.SetCurrentPosition only seeks to the nearest container keyframe, the reader now reads forward and skips into the decoded buffer to reach the exact requested position, instead of restarting playback from the keyframe (audible on audio extracted from video, e.g. Vorbis/AAC). Position now reflects the byte position actually reached (#628)
• 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