NAudio.Sampler 3.0.0-preview.14

• net9.0

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

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), 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)
* **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

#### 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
* `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
* `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)
* `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)
* `AudioSessionControl`: now supports multiple registered event clients without leaking, and `UnRegisterEventClient` honours its argument (#1263)
* `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)
* `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