RELEASE_NOTES.md
A patch release. The headline fix is packaging: the NAudio and NAudio.Extras
meta-packages now ship a plain net9.0-windows leg, so WinForms and WPF projects
targeting netX.0-windows get the full Windows stack again.
AudioFileReader now throws NotSupportedException instead of InvalidOperationException when the cross-platform build is asked for a format it cannot read, and the messages simply state that rather than suggesting an NAudio.Wasapi install that could never have helped (#1407)NAudio and NAudio.Extras meta-packages resolving their portable net9.0 asset on projects targeting a plain netX.0-windows TFM (the WinForms/WPF template default), which silently dropped the entire Windows stack — no WaveOut, WASAPI, Media Foundation, ASIO, DMO or WinForms types, and AudioFileReader throwing "MP3 file reading requires the NAudio.Wasapi package". Both packages now also ship a plain net9.0-windows leg (#1407)netX.0-windows TFM may now see CA1416 warnings when calling WASAPI process-loopback capture. The warning is correct — those callers do need an OperatingSystem.IsWindowsVersionAtLeast(10, 0, 19041) guard — and was previously hidden because the only Windows asset available already implied that floor (#1407)AiffFileReader reporting too long a Length and throwing IndexOutOfRangeException when the SSND chunk declares a non-zero offset (#1405)AiffFileReader.Read throwing IndexOutOfRangeException when the source stream returns fewer bytes than requested (#1405)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.
Upgrading from NAudio 2? Migrating from NAudio 2 to NAudio 3
walks through every breaking change with before/after code. Most apps need only
re-target to net9.0, rename WaveOutEvent to WaveOut, and adjust custom
providers to the new Span<T> Read signature.
net9.0 — legacy .NET Framework and .NET Standard 2.0 support is droppedNAudio is now a set of focused packages: NAudio.Core, NAudio.Midi, NAudio.WinMM, NAudio.Wasapi, NAudio.Asio, NAudio.Dmo, NAudio.WinForms, plus the new NAudio.Effects (shipped 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.mdNAudio.Core, NAudio.Midi, NAudio.Wasapi, NAudio.Dmo, NAudio.Sampler, NAudio.SoundFile and NAudio.Alsa are Native-AOT compatible (IsAotCompatible=true), enforced in CI by NAudioAotSmokeTestNAudio.Wasapi targets plain net9.0 (Windows-only at runtime via [SupportedOSPlatform("windows")]), so cross-platform apps can reference it and build on Linux/macOS without EnableWindowsTargeting. The WinRT MIDI backend moved to NAudio.Midi, which now dual-targets net9.0;net9.0-windows10.0.19041.0 (#1384)NAudio.Uap package is removed — use WasapiPlayerBuilder / WasapiRecorderBuilder.snupkg symbol packages and an embedded SPDX SBOMEach new subsystem has its own tutorial or README; only the headline is listed here.
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.mdWasapiPlayer / WasapiRecorder, built via WasapiPlayerBuilder / WasapiRecorderBuilder: IAudioClient3 low latency, MMCSS thread priority, IAsyncDisposable, zero-copy buffers, per-process loopback capture, automatic stream routing that follows the default endpoint (#942), acoustic-echo-cancellation reference control (#1223), communications mode, raw mode (#476), and resample-free bit-depth/channel adaptation in exclusive and low-latency modes. See Docs/WasapiPlayer.md and Docs/WasapiRecorder.mdAsioDevice replacing AsioOut: explicit playback/recording/duplex modes, non-contiguous channels, per-channel Span<float> callbacks, driver-reset recovery and per-buffer timing. AsioOut is preserved as a facade. See Docs/AsioMigration.mdNAudio.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)NAudio.Alsa package: AlsaOut (IWavePlayer) and AlsaIn (IWaveIn) plus AlsaDeviceEnumerator, backed by libasound. See Docs/PlayAudioFileLinuxAlsa.md and Docs/RecordAudioFileLinuxAlsa.md (#1182)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 GmbHNAudio.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.mdMMDeviceEnumerator.CreateNotificationClient() returns an MMDeviceNotificationClient exposing DeviceStateChanged, DeviceAdded, DeviceRemoved, DefaultDeviceChanged and PropertyValueChanged as ordinary events, so callers no longer implement a COM interface or manage CCW lifetime (#1395)NAudio.Midi's portable leg is now cross-platform; new WinRT WinRTMidiIn / WinRTMidiOut and backend-agnostic IMidiInput / IMidiOutput; and a new IMidiInstrument seam (MidiFileSequence / SequencedMidiPlayer / OfflineMidiRenderer / LiveMidiInstrument) giving an end-to-end MIDI-file → audio pipeline that drives the sampler or a hosted VST 3 instrument. MidiFile also reads RIFF-RMID (.rmi) files (#1236) and MidiFile.Export gains a Stream overload, thanks to @MaKiPL (#499)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.mdNAudio.Extras helpers CaptureMixerInput and RealtimeCaptureMixer capture and live-mix several sources with different sample rates and channel counts (e.g. microphone + system loopback) into one wall-clock-paced stream. See Docs/MixMicrophoneAndSystemAudio.md (#761)AudioFileReader and CachedSound gain Stream constructors, detecting WAV/AIFF from the contents and delegating anything else to Media Foundation, so embedded or in-memory audio plays without a temp file (#927, #963). StreamMediaFoundationReader also gains optional contentType / originName hints and Ogg container sniffing (#952)WaveFileReader.Chunks with an IWaveChunkInterpreter<T> extension point and built-in interpreters for cue lists, BWF bext (BroadcastExtension, now read and write, with v2 loudness) and LIST/INFO (InfoMetadata); WaveFileWriter gains AddCue, WriteCueList, WriteBroadcastExtension, arbitrary AddChunk and RF64 promotion via WaveFileWriterOptions (#1013)IWaveLatency interface in NAudio.Core exposing AverageLatency / CurrentLatency for A/V sync and drift detection, implemented across the playback and capture classes (#601)ChannelMixerSampleProvider with ready-made ChannelMixMatrix routings, thanks to @antiduh (#982); a new FftProcessor; Span<T> overloads across the codec/DSP surface; reusable building blocks (EnvelopeFollower, DelayLine, Lfo, Oversampler, LinkwitzRileyCrossover, PartitionedConvolver, …); plus improvements to SmbPitchShiftingSampleProvider (#922), AdsrSampleProvider (#671) and FadeInOutSampleProvider (#1136)ValidBitsPerSample / ChannelMask, and a [Flags] Speakers enum for building channel masks (#1325)AudioSessionControl.SetDuckingPreference(bool) (#760); WasapiPlayer / WasapiRecorder expose DeviceId and DeviceFriendlyName for the active endpoint (#681)The full upgrade walkthrough — every breaking change with before/after code — is in Migrating from NAudio 2 to NAudio 3. The highest-impact changes:
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 methodWaveOutEvent is renamed to WaveOut and WaveInEvent to WaveIn (the old names remain as [Obsolete] subclasses). WaveOut / WaveIn now default to event-driven callbacks; the window-based variants are WaveOutWindow / WaveInWindow in NAudio.WinForms, and WaveCallbackInfo / WaveCallbackStrategy are removedWaveOut.DesiredLatency is replaced by BufferMilliseconds, which sizes each individual buffer rather than the total across all of them. WaveIn's default record format changes from 8 kHz mono to 44.1 kHz stereoWasapiOut, 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, though it now adapts bit depth and channels, so only a sample-rate mismatch requires upstream resamplingIMMNotificationClient interface and MMDeviceEnumerator.RegisterEndpointNotificationCallback / UnregisterEndpointNotificationCallback are now internal — use CreateNotificationClient() and its events. The raw Core Audio and Media Foundation COM interfaces are likewise internal, and PropertyStoreProperty.Value is now object rather than PropVariantwinmm 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[Obsolete] throughout NAudio 2, each with a direct replacement on the same class: WaveFileWriter.WriteData (both overloads → Write / WriteSamples), WaveFileReader.TryReadFloat (→ ReadNextSampleFrame, which doesn't drop channels on stereo), AcmStream.Convert(int) (→ the overload returning sourceBytesConverted), WaveFormatConversionStream.SourceToDest / DestToSource (unreliable estimates with no replacement — use Position / Length), and AsioAudioAvailableEventArgs.GetAsInterleavedSamples() (→ the overload taking a reusable array, avoiding an allocation per ASIO callback). AsioOut.Volume is kept despite its obsolete notice — it's an IWavePlayer interface memberAudioMediaSubtypes moved from the NAudio.Dmo namespace to NAudio.Wave. It ships in NAudio.Core, so cross-platform code previously needed using NAudio.Dmo; to name the media subtype GUIDs even on Linux without the DMO package; it now sits alongside WaveFormatExtensibleSimpleCompressorStream, ImpulseResponseConvolution and NAudio.Extras.Equalizer were removed — superseded by NAudio.Effects (CompressorEffect, ConvolutionReverbEffect, Equalizer)CueWaveFileReader, CueWaveFileWriter, BwfWriter and BextChunkInfo were removed, along with WaveFileReader.ExtraChunks / GetChunkData — the unified chunk model on WaveFileReader.Chunks and WaveFileWriter replaces themMixingWaveProvider32 was removed — it was an untested float-only mixer that offered nothing over MixingSampleProvider. ImaAdpcmWaveFormat was removed — it was a non-functional stub used nowhereWaveFileWriter / AiffFileWriter no longer dispose a caller-supplied stream, matching the readers' ownership rule; only the filename constructor owns and closes the file. IgnoreDisposeStream is no longer needed when writing to a stream you want to keep (#1040)MediaFoundationTransform, MediaFoundationEncoder and MediaBuffer, and MediaType is now IDisposable — call Dispose()CoreAudioException / MediaFoundationException, both subclasses of COMException, so existing catch (COMException) keeps workingThe sampler, effects and WASAPI subsystems also saw extensive correctness work during development. The full per-PR list is on the GitHub Release; the fixes most likely to affect existing NAudio 2 code are:
WaveFileWriter.WriteSample / WriteSamples: fixed 32-bit WaveFormatExtensible output writing near-silence or corrupt data — both paths ignored the declared SubFormat (#651)ToSampleProvider() now handles WAVE_FORMAT_EXTENSIBLE PCM and IEEE float sources (e.g. multichannel or >16-bit WAV) instead of throwing Unsupported source encoding (#639); AudioFileReader no longer routes such WAVs through an unnecessary ACM conversion streamWaveFileReader / AiffFileReader: malformed headers declaring BlockAlign=0 throw InvalidDataException from the constructor rather than DivideByZeroException later (#1254); an oversized data chunk length is clamped to the bytes actually present (#1090); an oversized fmt cbSize no longer throws (#482)AiffFileReader / AiffFileWriter: 8-bit PCM is now read and written as signed two's-complement per the AIFF spec, fixing DC-shifted/garbled playback (#1178)BlockAlignReductionStream.Read: a read larger than the 4-second internal buffer no longer silently truncates the stream — e.g. converting a non-PCM WAV via AudioFileReader (#1022)WaveOut: fixed a race where stopping or disposing faster than the buffer latency could throw a NullReferenceException via PlaybackStopped (#804); DirectSoundOut: fixed a startup race that could collapse playback immediately (#759)WasapiRecorder, WasapiCapture and WasapiLoopbackCapture: a capture device removed mid-recording no longer crashes the process — RecordingStopped always fires with the originating exception (#672). Silent packets no longer leak the uninitialised WASAPI buffer as a burst of stale audioRegisterEndpointNotificationCallback — Windows does not AddRef the client, so the CCW was being collected (#1394)AudioClient.Dispose is now idempotent and safe against concurrent disposal (#1183); MMDevice.Dispose releases the property store deterministically (#1145); AudioSessionControl supports multiple event clients without leaking (#1263); AudioEndpointVolume.OnVolumeNotification reports the correct channel (#351)AcmInterop: serialised all msacm32 P/Invokes process-wide, fixing process-killing access violations under concurrent ACM useResamplerDmoStream: 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 source can't satisfy a read (#1338)FastFourierTransform.FFT: fixed drifting high-frequency bins at large FFT sizes by carrying the twiddle-factor recurrence in double precision (#520)WdlResampler: backported upstream Cockos WDL fixes, including reinterleaving on channel-count change and denormal flushing in the IIR feedback path (#800)WaveViewer: fixed rendering upside-down (#801, #818) and now renders any source format via ToSampleProvider() (#564)Mp3FileReader: fixed false sample-rate-change errors near end of file, and more robust frame parsing against album art and trailing metadata; MidiFile preserves running status across meta eventsWaveFormat.Serialize: PCM formats now write the canonical 16-byte fmt chunk (#934, #1098)NAudioDemo and NAudioWpfDemo were substantially reworked against the new APIs, including a rebuilt WASAPI Recorder panel driven by WasapiRecorderBuilder, transport/volume/position controls across the playback panels, and a Graphic EQ panel on NAudio.EffectsConcentus, replacing the vendored NSpeex binary), and gained a tutorialDocs/ and the source XML comments. Every package's projectUrl and README now point at it; nuget.org still links the GitHub repo via the package's repository metadataPropertyStore and Core Audio property access (#1206)WasapiCapture from using exclusive mode (#1122)WaveFileChunkReader.ReadWaveHeader (#1231)PropVariant now supports VT_EMPTY by returning null (#1071)AcmStream.Convert (#1108)AcmStreamHeader finalizer crash with corrupted data (#1199)net6.0 targets for NAudio.Asio and NAudio.WinMM to remove registry dependency (#1139)WdlResampler is now publicMmException can return function nameAUDCLNT_E HRESULT values from audioclient.hAiffFileWriter chunk size bugfixIPart, IAudioAutoGainControl, IAudioMute, IAudioVolumeLevel, IControlChangeNotify, IControlInterface, IKsJackDescription, IPerChannelDbLevel)ComImport attribute to CoreAudioApi interfacesMediaType, and to specify MediaFoundationEncode buffer sizeMediaFoundationEncoder bugfixes for null referenceWdlResampler is now publicMmException can return function nameErrorCodes provides all the AUDCLNT_E HRESULT values from audioclient.hAiffFileWriter chunk size bugfixIPart, IAudioAutoGainControl, IAudioMute, IAudioVolumeLevel , IControlChangeNotify, IControlInterface, IKsJackDescription, IPerChannelDbLevel)ComImport attribute to CoreAudioApi interfacesMediaType, and to specify MediaFoundationEncode buffer sizeMediaFoundationEncoder bugfixes for null referenceAudioFileReader will use MediaFoundationReader as the default for MP3sIWavePlayer now has an OuputWaveFormat propertyWasapiCapture and WasapiLoopbackCapture support sample rate conversion so you can capture at a sample rate of your choiceWasapiOut supports built-in sample rate conversion in shared modeMediaFoundationEncoder allows you to encode to a StreamIAudioClient.IsFormatSupportedAsioOut will no longer stop when it reaches the endDmoEffectWaveProvider #413BwfWriterWaveInEvent #403WaveIn and WaveInEvent support GetPosition #399CueWaveFileReader support for Stream #409, #376IAudioCaptureClient cast exception issue #350WaveOut and WaveOutEvent read the actual volume #349PropVariant support for VT_FILETIME #341StereoToMonoSampleProvider #312KeySignatureEvent reports flats properly as negative number #295WaveInProvider.Read uses offset parameter #297