NAudio 3.0.0-preview.16

• net9.0

  • NAudio.Core (>= 3.0.0-preview.16)
  • NAudio.Midi (>= 3.0.0-preview.16)

• net9.0-windows10.0.19041

  • NAudio.Asio (>= 3.0.0-preview.16)
  • NAudio.Core (>= 3.0.0-preview.16)
  • NAudio.Dmo (>= 3.0.0-preview.16)
  • NAudio.Midi (>= 3.0.0-preview.16)
  • NAudio.Wasapi (>= 3.0.0-preview.16)
  • NAudio.WinForms (>= 3.0.0-preview.16)
  • NAudio.WinMM (>= 3.0.0-preview.16)

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)
* **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](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+)
* `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](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](Docs/NetworkChatDemo.md)