NAudio.Extras 3.3.0

• net9.0

  • NAudio (>= 3.3.0)
  • NAudio.Core (>= 3.3.0)

A packaging and nullability release. The `NAudio` meta-package is now a single
`net9.0` package that brings the Windows backends (WinMM and WASAPI) to plain
`netX.0` projects, so a `net10.0` console app on Windows gets working MP3
decoding and playback rather than a cross-platform subset that threw
`NotSupportedException`. In exchange it no longer pulls in `NAudio.Asio`,
`NAudio.Dmo` or `NAudio.WinForms`, which must now be referenced directly if
used. `NAudio.WinMM`, `NAudio.Asio`, `NAudio.Dmo` and `NAudio.Vst3` likewise
now target plain `net9.0`.

Every NAudio package is now compiled with nullable reference types enabled.
This is a source-level change with no binary breaks, but projects with
nullable enabled may see new warnings, and a number of members that used to
throw `NullReferenceException` now throw `ObjectDisposedException` or
`InvalidOperationException` instead.

The fixes centre on `WasapiRecorder`/`WasapiCapture` restarting cleanly after
both successful and failed starts, buffer and handle lifetime bugs in the
winmm MIDI backend, and frame-aligned seeking in `MediaFoundationReader`.

* **Breaking:** the `NAudio` meta-package is now a single `net9.0` package that pulls in `NAudio.Core`, `NAudio.Midi`, `NAudio.WinMM` and `NAudio.Wasapi` on every target framework. A plain `netX.0` project on Windows (e.g. a console app on `net10.0`) now gets `Mp3FileReader`, `WaveOut`, `WasapiPlayer` and an `AudioFileReader` that reads MP3, where previously it silently got a cross-platform subset that threw `NotSupportedException` (#1472). It **no longer includes `NAudio.Asio`, `NAudio.Dmo` or `NAudio.WinForms`**: add those packages if you use `AsioOut`/`AsioDevice`, `DirectSoundOut` or the DMO effects, or `WaveOutWindow`/`WaveInWindow`/the `NAudio.Gui` controls. `AudioFileReader` now chooses its Media Foundation/ACM paths at runtime, and off Windows its `NotSupportedException` messages point to `NAudio.SoundFile`. `NAudio.Extras` is now single-target `net9.0`, with `AudioPlaybackEngine` marked Windows-only (#1485)
* `NAudio.WinMM`, `NAudio.Asio`, `NAudio.Dmo` and `NAudio.Vst3` now target plain `net9.0` instead of `net9.0-windows`, matching `NAudio.Wasapi`. They remain Windows-only, enforced by `[SupportedOSPlatform("windows")]`, but can now be referenced directly from a plain `netX.0` project (calls show `CA1416` warnings unless guarded or the project is marked Windows-only) and built on Linux/macOS without `EnableWindowsTargeting`. No change for projects targeting `netX.0-windows` (#1482)
* **Nullable reference types in NAudio.Core** - `NAudio.Core` is now compiled with nullable reference types enabled, so its public API carries nullability annotations (e.g. `WaveFileReader.ReadNextSampleFrame` and `Mp3Frame.LoadFromStream` return nullable types, and `Mp3Frame.RawData` is `byte[]?` when a frame is read without its data). This is a source-level change only: there are no binary breaks, but projects with nullable enabled may see new warnings, and overrides of NAudio.Core virtual members may need matching annotations. `XingHeader.LoadXingHeader` now returns `null` for a frame read without its data instead of throwing. Thanks to @Seb-stian (#1452)
* **Nullable reference types in NAudio.Midi** - `NAudio.Midi` is now also compiled with nullable reference types enabled (e.g. `MidiInMessageEventArgs.MidiEvent` and `NoteOnEvent.OffEvent` are nullable). Source-level change only; projects with nullable enabled may see new warnings. `MidiEvent.ReadNextEvent` now throws `FormatException` instead of `NullReferenceException` for running status with no previous event, and `RawMetaEvent` treats null data as empty (#825)
* **Nullable reference types in NAudio.WinMM** - `NAudio.WinMM` is now compiled with nullable reference types enabled (e.g. `AcmDriver.FindByShortName` and `WaveCapabilitiesHelpers.GetNameFromGuid` return nullable types, and `AcmDriver.ShowFormatChooseDialog` has nullable `out` parameters). Source-level change only; projects with nullable enabled may see new warnings. `WaveOut.OutputWaveFormat` before `Init` now throws `InvalidOperationException`, `AcmStream` members throw `ObjectDisposedException` after dispose, and `GetNameFromGuid` returns null instead of throwing when the registry key is missing, where each previously threw `NullReferenceException` (#825)
* **Nullable reference types in NAudio.SoundFile and NAudio.Sampler** - both packages are now compiled with nullable reference types enabled (e.g. the `SoundFileTags` fields, `SoundFileWriterOptions.Tags` and `SoundFileException.Function` are nullable, and the `TryLoad` methods on `WaveSampleLoader` / `ISfzSampleLoader` mark `left` as non-null on success and `right` as null for mono). Source-level change only; projects with nullable enabled may see new warnings, and custom `ISfzSampleLoader` implementations may need matching annotations (#825)
* **Nullable reference types in NAudio.WinForms, NAudio.Alsa and NAudio.Extras** - these packages are now compiled with nullable reference types enabled (e.g. `WaveViewer.WaveStream`, `AlsaException.Function` and the control/device events are nullable). Source-level change only; projects with nullable enabled may see new warnings. `AlsaOut.OutputWaveFormat` and `WaveOutWindow.OutputWaveFormat` now throw `InvalidOperationException` before `Init` (previously null and `NullReferenceException` respectively), and `WaveOutWindow.Play` before `Init` throws `InvalidOperationException` instead of `NullReferenceException` (#825)
* **Nullable reference types in NAudio.Asio** - `NAudio.Asio` is now compiled with nullable reference types enabled (e.g. the optional `AsioPlaybackOptions.OutputChannels` / `AsioDuplexOptions.InputChannels`, the `AsioDevice`/`AsioOut` events and the `AsioDriverExt` callbacks are nullable; required option members such as `Source` and `Processor` stay non-nullable). Source-level change only; projects with nullable enabled may see new warnings. `AsioOut` members now throw `ObjectDisposedException` after `Dispose` and `AsioOut.OutputWaveFormat` throws `InvalidOperationException` when no playback source is initialised, where they previously threw `NullReferenceException` or returned null (#825)
* **Nullable reference types in NAudio.Dmo** - `NAudio.Dmo` is now compiled with nullable reference types enabled (e.g. `DirectSoundOut.PlaybackStopped` and `DirectSoundDeviceInfo.ModuleName` are nullable). Source-level change only; projects with nullable enabled may see new warnings. `DirectSoundOut.OutputWaveFormat` now throws `InvalidOperationException` before `Init` instead of returning null, and the `MediaObject` wrappers, `DmoResampler.MediaObject`, `WindowsMediaMp3Decoder.MediaObject` and `DmoOutputDataBuffer.MediaBuffer` throw `ObjectDisposedException` after `Dispose` instead of returning null or throwing `NullReferenceException` (#825)
* **Nullable reference types in NAudio.Wasapi (CoreAudioApi and MediaFoundation)** - the `NAudio.CoreAudioApi` and `NAudio.MediaFoundation` types are now annotated for nullable reference types (e.g. `AudioClient.TryGetAcousticEchoCancellationControl`, `MMDeviceEnumerator.TryGetDefaultAudioEndpoint`, `MfSourceReader.ReadSample`, `PropertyStoreProperty.Value` and `Part.AudioVolumeLevel`/`AudioMute`/`JackDescription` are nullable); `WasapiOut`, `WasapiCapture` and the other top-level classes follow in a separate change. Source-level change only; projects with nullable enabled may see new warnings. The CoreAudio and Media Foundation COM wrappers now throw `ObjectDisposedException` when used after `Dispose` instead of `NullReferenceException`, `AudioSessionManager.Sessions` throws `InvalidOperationException` instead of returning null when sessions are unavailable, and `AudioSessionControl.AudioMeterInformation` / `SimpleAudioVolume` throw `NotSupportedException` instead of returning null if the session does not expose those interfaces (#825)
* **Nullable reference types in NAudio.Wasapi (playback, capture and Media Foundation classes)** - `WasapiOut`, `WasapiCapture`, `WasapiPlayer`, `WasapiRecorder`, their builders and `MediaFoundationReader`/`StreamMediaFoundationReader`/`MediaFoundationEncoder` are now annotated too, completing NAudio.Wasapi (e.g. `WasapiPlayer`/`WasapiRecorder.DeviceId` and `DeviceFriendlyName`, `LowLatencyUnavailableReason`, `WasapiRecorder.AcousticEchoCancellationControl`, `WasapiPlayer.GetSupportedExclusiveFormat`, `MediaFoundationEncoder.SelectMediaType` and the playback/recording events are nullable). Source-level change only; projects with nullable enabled may see new warnings. The WASAPI classes now throw `ObjectDisposedException` when used after `Dispose`, and report `InvalidOperationException` instead of `NullReferenceException` through `PlaybackStopped` when playback is started without `Init` (#825)
* **Nullable reference types in NAudio.MacOS** - `NAudio.MacOS` is now compiled with nullable reference types enabled (e.g. `AudioSystemObject.DefaultInputDevice`/`DefaultOutputDevice`, the `ConvertUIDToDevice`-style lookups, `AudioObject.Owner`, `AudioDevice.Icon`, `ExtendedAudioFileReaderSettings.OutputFormat`, `ExtendedAudioFileWriterSettings.FileType`/`ProvidingFormat` and the player, recorder and property-listener events are nullable). Source-level change only; projects with nullable enabled may see new warnings. Object-list properties such as `AudioSystemObject.Devices` now skip unknown object IDs instead of returning null entries, the parameterless `CoreAudioPlayer`/`CoreAudioRecorder` constructors throw `InvalidOperationException` instead of `ArgumentNullException` when there is no default device, and `ExtendedAudioFileWriter` captures `ProvidingFormat` when created rather than re-reading the settings object on every write (#825)
* Fixed `WasapiRecorder` and `WasapiCapture` failing with `AUDCLNT_E_ALREADY_INITIALIZED` when restarted after a start that failed late in initialization (e.g. no AEC reference control); the original error is now reported again (#1493)
* Fixed `WasapiRecorder` and `WasapiCapture` being left in the `Starting` state when initialization throws, so later `StartRecording` calls failed with `"Already recording"`. (#1490)
* Fixed `WasapiRecorder` not able to re-start after successfully stopping the recorder. (#1479)
* Fixed several buffer and handle lifetime bugs in the winmm MIDI backend: `MidiOut.SendBuffer` no longer frees a sysex buffer while the driver may still own it, `MidiIn` now stops input before resetting it, and neither class calls into winmm with a handle it never opened. `MidiOut.SendBuffer` now blocks until the driver releases the buffer and throws `MmException` if the send fails (#1478)
* Fixed `MediaFoundationReader` reporting a `Position` that was not a whole number of frames after seeking a compressed file (e.g. MP3 or AAC), up to a frame before the requested position, and a `Length` that could include a partial frame. Seeks now round down to a frame boundary and land exactly on it (#1488)