NAudio.Sampler 3.2.0

• net9.0

  • NAudio.Core (>= 3.2.0)
  • NAudio.Midi (>= 3.2.0)
  • NAudio.SoundFile (>= 3.2.0)

A feature and tidy-up release. Its headline is a first preview of macOS
support: the new `NAudio.MacOS` package wraps Core Audio for playback and
recording, Extended Audio File Services for reading and writing compressed
formats, and AudioConverter for resampling. It ships pre-release only while its
API settles, alongside the stable versions of the other packages. VB.NET users
also get base classes and a guide that keep the NAudio 2 array-based `Read`
signature.

Several legacy APIs that have modern replacements are now `[Obsolete]`, to be
removed in the next major version. The
fixes include `DirectSoundOut`, which failed every playback in 3.1.0, and
`WasapiPlayer`/`WasapiOut` getting stuck in the `Playing` state after a source
error.

* **macOS support (preview)** - A new wrappers library is added wrapping macOS native API's for playback/recording, reading/writing files and resampling audio. The `NAudio.MacOS` package ships pre-release only (`X.Y.Z-preview.N`) while its API settles, so it stays pre-release alongside stable releases of the other packages. Special thanks to @mdcdi1315 (#1325) for the work and the tests. For more information, see the [design](Docs/Architecture/MacOSWrappersDesign.md) doc that describes the decisions that helped shape the wrappers. (#1398)
* **VB.NET support** - Added `SampleProviderBase` and `WaveProviderBase`, base classes that keep the NAudio 2 `Read(buffer, offset, count)` signature for languages that cannot name a `Span<T>` in a method signature, and a [Using NAudio from VB.NET](Docs/UsingNAudioFromVB.md) guide covering playback, recording and custom providers from VB (#1426)
* Deprecated legacy APIs that have modern replacements: `Wave16ToFloatProvider`, `WaveFloatTo16Provider` and `Wave32To16Stream` (use `ToSampleProvider()` / `ToWaveProvider16()`), `IgnoreDisposeStream` (no longer needed), `ByteArrayExtensions` (use the BCL), `MidiMessage` (use the typed MIDI events), `ResamplerDmoStream`/`DmoResampler` (use `MediaFoundationResampler` or `WdlResamplingSampleProvider`), `DmoEffectWaveProvider` and the `Dmo*` effects (use `NAudio.Effects`), `AsioOut`'s recording path (use `AsioDevice`), `WaveFilter`, and `ProgressLog`. Added `AsioOut.IsSupported()` and deprecated the lowercase `isSupported()` (#1466)
* Deprecated `WaveFileReader.ReadNextSampleFrame` in favour of `ToSampleProvider()`, which supports more formats and doesn't allocate an array per sample frame (#1465)
* Reduced allocations when reading and writing WAV files, added `ReadOnlySpan<byte>` overloads of `WaveFileWriter.AddChunk` and `ChunkIdentifier.ChunkIdentifierToInt32`, and fixed `WaveChunks.GetData` leaving the stream position changed when a read fails. `ChunkIdentifierToInt32` now throws `ArgumentOutOfRangeException` for identifiers that aren't four bytes (#1457)
* Fixed `DirectSoundOut` failing every playback with `DirectSoundException 0x80004001` (or an `ArgumentException` for a format with extra data, e.g. one read from a WAV by `WaveFileReader`): the secondary buffer's `WAVEFORMATEX` was still a GCHandle-pinned `WaveFormat` instance — a site missed in the #1432 marshalling conversion, since `WaveFormat` no longer carries `[StructLayout]` — and now marshals via `WaveFormat.MarshalToPtr` (#1456)
* Fixed `WasapiPlayer` and `WasapiOut` being stranded in the `Playing` state, unable to play again, when the source's `Read` threw or the source ended before the first buffer was filled (#1442)
* Fixed `WaveFileWriter.WriteSample` and `WriteSamples(short[])` throwing for plain (non-extensible) 32-bit integer PCM formats (#1463)
* `WaveFileReader.ReadNextSampleFrame` now throws `InvalidDataException` for a WAV header with an invalid channel count or bit depth (#1464)
* Changed the `WaveStream.CurrentTime` setter to clamp to the bounds of the stream, and corrected the XML documentation for the core audio interfaces (#1441)
* Reworked the macOS `CoreAudioPlayer` and `CoreAudioRecorder` non-interleaved path, used for devices that expose one mono stream per channel; the recorder now also drains buffered audio when stopped, and non-interleaved streams carrying more than one channel are rejected explicitly (preview) (#1461)
* `ExtendedAudioFileServicesReader.CurrentTime` and `TotalTime` on macOS now throw `ObjectDisposedException` after the reader is disposed, rather than a native exception (preview) (#1451)
* Refreshed the NuGet package icon, now rendered from the new SVG version of the NAudio logo as a sharper, square 256×256 PNG (#1467)
* Fixed the Help and About links in the AudioFileInspector, MidiFileConverter and MixDiff sample apps, which threw on .NET 9 instead of opening the help page or browser, and pointed the links and help pages at GitHub rather than CodePlex (#1469)