If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/naudio/NAudio shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 9 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 75% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live naudio/NAudio repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/naudio/NAudio.

What it runs against: a local clone of naudio/NAudio — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in naudio/NAudio | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of naudio/NAudio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/naudio/NAudio.git
#   cd NAudio
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of naudio/NAudio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "naudio/NAudio(\\.git)?\\b" \\
  && ok "origin remote is naudio/NAudio" \\
  || miss "origin remote is not naudio/NAudio (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "NAudio/NAudio.csproj" \\
  && ok "NAudio/NAudio.csproj" \\
  || miss "missing critical file: NAudio/NAudio.csproj"
test -f "NAudio/Wave/WaveStream.cs" \\
  && ok "NAudio/Wave/WaveStream.cs" \\
  || miss "missing critical file: NAudio/Wave/WaveStream.cs"
test -f "NAudio/Wave/WaveFormat.cs" \\
  && ok "NAudio/Wave/WaveFormat.cs" \\
  || miss "missing critical file: NAudio/Wave/WaveFormat.cs"
test -f "NAudio/Wave/IWaveProvider.cs" \\
  && ok "NAudio/Wave/IWaveProvider.cs" \\
  || miss "missing critical file: NAudio/Wave/IWaveProvider.cs"
test -f "NAudio/Wave/WaveOutEvent.cs" \\
  && ok "NAudio/Wave/WaveOutEvent.cs" \\
  || miss "missing critical file: NAudio/Wave/WaveOutEvent.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/naudio/NAudio"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

NAudio is a comprehensive .NET audio and MIDI library that enables developers to play, record, encode, and manipulate audio across multiple Windows audio APIs (WaveOut, DirectSound, ASIO, WASAPI). It provides decoders for WAV, MP3, AIFF, WMA, AAC, and Media Foundation formats, with a 32-bit floating-point mixing engine for real-time signal processing, effects, and MIDI file handling. Multi-project solution: NAudio core library in the root, AudioFileInspector (WinForms diagnostic tool in /AudioFileInspector with FileInspectors/ for WAV/MP3/MIDI/SoundFont formats), /Docs with markdown guides per feature, and /NAudioDemo for usage examples. Architecture is layered: low-level audio APIs wrapped in provider classes (WaveOutEvent, AsioOut, WasapiOut), sample providers for mixing/effects, and codec-specific readers.

Windows desktop and UWP developers building audio applications—game audio engineers, DAW developers, real-time audio processing applications, and developers needing to record/playback/encode audio without wrestling with low-level Windows audio APIs directly.

Highly mature and production-ready. NAudio has been actively developed for 15+ years, is widely used in commercial audio software, and maintains a modern CI/CD pipeline (Azure DevOps builds visible in badges). The codebase shows substantial scale (2.8M lines of C#), comprehensive documentation in /Docs, and demo applications in AudioFileInspector and NAudioDemo.

Low risk for core functionality but Windows-specific: NAudio is tightly coupled to Windows audio subsystems (WASAPI, DirectSound, ASIO) and will not work on Linux/macOS without major architectural changes. Single maintainer (Mark Heath) is a potential concern for emergency fixes. No package.json visible suggests limited NuGet dependency sprawl, reducing transitive dependency risk.

Active development implied by versioning on NuGet badge and maintained Azure DevOps CI. AudioFileInspector is a shipped tool (InstallScript.nsi shows NSIS packaging). Documentation is comprehensive and recent (Docs/ contains guides for Media Foundation, ASIO, WASAPI, pitch shifting). Specific recent work not visible in file list alone, but project structure shows ongoing Windows audio API coverage.

Clone with git clone https://github.com/naudio/NAudio.git && cd NAudio. Restore dependencies and build: dotnet build NAudio.sln (or msbuild NAudio.sln if on Visual Studio 2019+). No external services required. Run AudioFileInspector demo: dotnet run --project AudioFileInspector/AudioFileInspector.csproj or open in Visual Studio and F5.

Daily commands: For library: dotnet build NAudio.sln generates DLLs under bin/. For AudioFileInspector demo: dotnet run --project AudioFileInspector/AudioFileInspector.csproj launches the WinForms app. For console examples, see /Docs (e.g., PlayAudioFileConsoleApp.md shows instantiating IWavePlayer and loading streams).

• NAudio/NAudio.csproj — Main project file defining the core library structure, dependencies, and build configuration that all audio processing relies on
• NAudio/Wave/WaveStream.cs — Abstract base class for all wave audio sources; understanding this is essential for implementing custom audio providers and decoders
• NAudio/Wave/WaveFormat.cs — Defines audio format metadata (sample rate, channels, bit depth); fundamental to all audio file I/O and playback operations
• NAudio/Wave/IWaveProvider.cs — Core interface for audio sample provision; all playback and processing chains implement or depend on this abstraction
• NAudio/Wave/WaveOutEvent.cs — Primary Windows audio output implementation using WaveOut API; most playback scenarios use this as the final output stage
• AudioFileInspector/AudioFileInspectorForm.cs — Entry point for the primary GUI application demonstrating how to integrate NAudio library components end-to-end
• Docs/PlayAudioFileWinForms.md — Reference documentation showing the standard pattern for consuming the library in real applications

Add support for a new audio file format

1. Create a new reader class in NAudio/FileFormats/ inheriting from WaveStream or implementing IWaveProvider (NAudio/FileFormats/WaveFileReader.cs)
2. Parse the file header and set WaveFormat property with correct sample rate, channels, and bit depth (NAudio/Wave/WaveFormat.cs)
3. Implement Read(buffer, offset, count) to decode and return PCM samples (NAudio/Wave/WaveStream.cs)
4. Register the reader in AudioFileInspector/FileInspectors/ to make it discoverable in the GUI tool (AudioFileInspector/FileInspectors/WaveFileInspector.cs)

Add a custom audio effect or sample processor

1. Create a new class in NAudio/Wave/SampleProviders/ implementing ISampleProvider (NAudio/Wave/SampleProviders/ISampleProvider.cs)
2. Wrap an input ISampleProvider and implement Read(buffer, offset, count) with your DSP logic (NAudio/Wave/SampleProviders/VolumeSampleProvider.cs)
3. Ensure WaveFormat property matches the input provider unless intentionally changing format (NAudio/Wave/WaveFormat.cs)
4. Chain your effect into a playback pipeline: sourceProvider → yourEffect → deviceOut (Docs/PlayAudioFileWinForms.md)

Implement a new audio output device backend

1. Create a new class in NAudio/Wave/ implementing IWavePlayer or inheriting from an existing output class (NAudio/Wave/WaveOutEvent.cs)
2. Use Windows P/Invoke to call the audio API (e.g., WASAPI, ASIO, DirectSound) (NAudio/Wave/Asio/AsioOut.cs)
3. Implement Init(IWaveProvider) to prepare the device and Start/Stop/Dispose for lifecycle management (NAudio/Wave/IWavePlayer.cs)
4. Fire PlaybackStopped event when playback ends or errors occur to notify consumers (Docs/PlaybackStopped.md)

Create a new MIDI event type

1. Create a new class inheriting from MidiEvent in NAudio/Midi/ (NAudio/Midi/MidiEvent.cs)
2. Override GetAsShortMessage() and AbsoluteTime property to define event encoding (NAudio/Midi/NoteOnEvent.cs)
3. Register the event type in MidiFile.cs so it is parsed from MIDI files (NAudio/Midi/MidiFile.cs)
4. Test serialization/deserialization using MidiFileConverter or AudioFileInspector MIDI tab (AudioFileInspector/FileInspectors/MidiFileInspector.cs)

• .NET Framework / .NET Core — Cross-platform Windows audio support; strong P/Invoke interop for native Windows audio APIs (WaveOut, WASAPI, ASIO, DirectSound)
• Windows WaveOut / WASAPI / ASIO / DirectSound APIs — Multiple output backends allow developers to choose latency vs. compatibility trade-offs; WASAPI/ASIO for pro audio, WaveOut for universal support
• Media Foundation / ACM codecs — Leverages OS-installed codecs for MP3, AAC, WMA, and others without bundling large codec libraries
• ISampleProvider abstraction — Separates high-level audio processing (float-based) from low-level device I/O (PCM); enables composable effects chains

• Windows-only audio APIs (WaveOut, WASAPI, ASIO, DirectSound)
  • Why: Mature, feature-complete access to professional audio hardware; tight OS integration for low-latency playback
  • Consequence: Not suitable for cross-platform audio; Linux/macOS users must use alternative libraries

NAudio is Windows-only: P/Invoke calls to Windows audio APIs will fail on non-Windows platforms. Audio deadlock risk: improper ISampleProvider chaining or blocking calls in Read() can freeze audio. No built-in thread safety on sample providers—caller must synchronize access. ASIO support requires ASIO SDK files (not in repo; licensing constraint). Media Foundation codec availability varies by Windows version (Windows 7+). Bit depth conversions (8/16/24/32-bit) are lossy in dithering code—verify conversion quality for critical audio work.

• ISampleProvider (audio signal chain abstraction) — Core architectural pattern in NAudio—all audio processing (mixing, effects, resampling) chains ISampleProviders; understanding this interface is prerequisite for extending NAudio or debugging audio quality issues
• WaveFormat (PCM descriptor) — NAudio's canonical representation of audio encoding (sample rate, bit depth, channels, codec); every read/write operation validates and converts between WaveFormats, essential for codec interop
• P/Invoke (platform invoke) — NAudio's foundation for Windows audio API access (WASAPI, DirectSound, WaveOut); understanding P/Invoke signatures and marshaling is critical for debugging low-level audio issues or adding new Windows audio backends
• ACM Codecs (Audio Compression Manager) — Windows legacy codec interface that NAudio wraps for MP3, GSM, ADPCM decoding on older Windows versions; understanding ACM is needed to debug codec failures or add legacy format support
• Media Foundation Transforms (MFT) — Modern Windows codec interface (replaces ACM) that NAudio uses for WMA, AAC, MP4 decoding; MFT knowledge required for adding modern format support or diagnosing codec enumeration bugs
• WASAPI (Windows Audio Session API) — Low-latency Windows audio API that NAudio wraps for real-time playback/recording; critical for audio apps requiring sub-50ms latency; different from legacy WaveOut due to session management and exclusive mode
• ASIO (Audio Stream Input Output) — Professional audio API for low-latency, high-channel-count I/O (bypasses Windows mixing); NAudio supports ASIO but requires external SDK; essential for music production software

• naudio/NAudioDemo — Official companion repository containing runnable WinForms and console demos for all NAudio features; essential reference for integration patterns
• MonoGame/MonoGame — Uses NAudio for cross-platform audio playback in game development; shows how to wrap NAudio's Windows-only APIs for abstraction layers
• Cakewalk/Cakewalk-by-BandLab — Commercial DAW that uses NAudio as its .NET audio foundation; reference for production-scale usage patterns
• cscore/cscore — Alternative .NET audio library with similar scope (playback, recording, codecs) but different API philosophy; useful for comparing architectural decisions
• dotnet/runtime — Low-level .NET runtime providing P/Invoke infrastructure that NAudio depends on for Windows audio API bindings

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for IAudioFileInspector implementations

The AudioFileInspector project contains multiple file format inspectors (MidiFileInspector.cs, Mp3FileInspector.cs, SoundFontInspector.cs, WaveFileInspector.cs) that implement IAudioFileInspector.cs, but there's no visible test project in the file structure. These inspectors parse binary audio formats and would benefit from comprehensive unit tests to ensure correctness and prevent regressions when format handling code is modified.

• [ ] Create a new test project (e.g., AudioFileInspector.Tests) following .NET standards
• [ ] Add unit tests for each FileInspectors/*.cs class with test cases for valid files, malformed files, and edge cases
• [ ] Include sample audio files (minimal WAV, MP3, MIDI, SoundFont) in test resources
• [ ] Reference existing Docs/*.md files (e.g., MidiFile.md) to understand expected behavior and document test scenarios

Document and create abstraction for WaveProvider implementations

The Docs/WaveProviders.md file exists but the file structure shows multiple scattered sample providers (FadeInOutSampleProvider.md, OffsetSampleProvider.md, SmbPitchShiftingSampleProvider.md documented separately). There's likely duplicate or inconsistent implementation patterns across these providers. Creating a base class or interface documentation and refactoring common patterns would improve maintainability.

• [ ] Review all *SampleProvider.cs and *WaveProvider.cs implementations in the codebase
• [ ] Identify common functionality (initialization, disposal, position tracking, format handling)
• [ ] Create or enhance a base class/interface for consistent behavior across providers
• [ ] Add specific code examples to Docs/WaveProviders.md showing inheritance patterns and best practices for new provider implementations

Add WASAPI loopback and output documentation with platform-specific examples

Docs/WasapiLoopbackCapture.md and Docs/WasapiOut.md exist but WASAPI is Windows-only with complex initialization and error handling. New contributors struggle with platform checks, COM initialization, and device enumeration. Enhancing these docs with specific code examples for common scenarios and error handling would reduce support burden.

• [ ] Expand Docs/WasapiLoopbackCapture.md with working example code for stereo loopback capture
• [ ] Expand Docs/WasapiOut.md with examples showing device enumeration (reference Docs/EnumerateOutputDevices.md) and fallback strategies
• [ ] Add a new Docs/WasapiErrorHandling.md documenting common HRESULT errors and recovery strategies
• [ ] Reference platform-specific considerations and OS version requirements in each document

• Add XML documentation comments to public ISampleProvider implementations in NAudio/Wave/SampleProviders/; many classes lack IntelliSense hints, hindering discoverability.
• Expand Docs/ with a guide for 'Creating a Custom ISampleProvider' (e.g., implementing a simple gain control); only 60 docs exist and signal processing chains are a core feature.
• Add unit tests for AudioFileInspector FileInspectors (WaveFileInspector, Mp3FileInspector, MidiFileInspector); currently no test files visible and parsing binary formats is error-prone.

NAudio is an audio processing library with a moderate security posture. The primary concerns relate to file parsing of untrusted binary audio formats (MP3, WAV, MIDI, SoundFont) which could be vectors for exploitation if not carefully implemented. The codebase lacks visible hardcoded credentials or obvious injection vulnerabilities based on the file structure alone. Recommendations include conducting thorough code review of file parsers, implementing input validation throughout the application, keeping native dependencies updated, and performing security testing on file handling operations. The absence of visible documentation on security practices and potential reliance on older .NET APIs (WinForms) should be addressed.

• Medium · Potential Unsafe File Operations in Audio File Inspectors — AudioFileInspector/FileInspectors/*.cs. The FileInspectors directory contains multiple file parsers (Mp3FileInspector, WaveFileInspector, MidiFileInspector, SoundFontInspector) that read binary audio files. Without visibility into implementation details, there is potential risk of buffer overflow, format string vulnerabilities, or improper validation of malformed audio files which could lead to denial of service or code execution. Fix: Implement strict input validation for all audio file formats, use safe parsing libraries, implement file size limits, add try-catch blocks for malformed files, and perform fuzzing tests on file parsers with malicious/malformed audio files.
• Medium · Unvalidated User Input in UI Forms — AudioFileInspector/*.cs, MidiFileConverter/*.cs, MixDiff/*.cs. Multiple WinForms applications (AudioFileInspector, MidiFileConverter, MixDiff) with Designer.cs files suggest GUI-based file handling. Without reviewing the actual code, there may be risks around unvalidated file paths, command injection through file operations, or insecure deserialization of form settings. Fix: Validate all user inputs (file paths, form inputs), use Path.GetFullPath() to canonicalize paths, implement whitelist validation for file extensions, avoid passing user input to system commands, and sanitize settings deserialization.
• Low · Dependency on NSpeex Native DLL — Lib/NSpeex/NSpeex.dll. The codebase includes a reference to Lib/NSpeex/NSpeex.dll, a native library. Native dependencies can introduce security risks if they are outdated, come from untrusted sources, or are not properly verified. Fix: Verify the NSpeex library's source and version, keep native dependencies updated, use signed binaries, consider replacing with managed alternatives if available, and implement integrity checks for native libraries.
• Low · Missing Security Headers in Configuration — .globalconfig, .editorconfig, app.config files. The .globalconfig and .editorconfig files are present but no explicit security configuration is visible. Applications handling media files from untrusted sources should have security hardening measures in place. Fix: Implement application security policies in configuration files, enable CAS (Code Access Security) if targeting .NET Framework, specify safe defaults for file handling, and document security requirements.
• Low · Potential Information Disclosure via Installer Scripts — AudioFileInspector/InstallScript.nsi, MidiFileConverter/InstallScript.nsi. InstallScript.nsi files in AudioFileInspector and MidiFileConverter may contain sensitive information or hardcoded paths. NSIS scripts should be reviewed for security issues. Fix: Review installer scripts for hardcoded credentials, ensure proper file permissions in installation targets, implement signature verification for installers, and avoid exposing system paths in error messages.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.