CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Build & Test Commands
6 
7AudioKit uses Swift Package Manager. The CI builds target iOS Simulator:
8 
9```bash
10# Build
11xcodebuild -scheme AudioKit -destination "platform=iOS Simulator,name=iPhone 17 Pro"
12 
13# Run all tests
14xcodebuild -scheme AudioKit -destination "platform=iOS Simulator,name=iPhone 17 Pro" test
15 
16# Run a single test
17xcodebuild -scheme AudioKit -destination "platform=iOS Simulator,name=iPhone 17 Pro" test -only-testing:AudioKitTests/DistortionTests/testDefault
18```
19 
20You can also open the package in Xcode (drag the folder onto Xcode's dock icon) and run tests with Cmd-U.
21 
22## Architecture
23 
24**AudioKit** is a Swift-only audio framework wrapping AVFoundation. It targets macOS 11+, iOS 13+, tvOS 13+, and visionOS 1+. It has zero external dependencies.
25 
26### Core Abstractions
27 
28- **Node** (`Internals/Engine/Node.swift`) — Protocol wrapping `AVAudioNode`. All audio graph elements (effects, generators, players, mixers) conform to Node. Nodes connect to each other to form the signal chain.
29- **AudioEngine** (`Internals/Engine/AudioEngine.swift`) — Wraps `AVAudioEngine`. Set `engine.output` to a Node to drive connections. Provides `startTest()`/`render()` methods for headless test rendering.
30- **@Parameter** — Property wrapper for audio parameters on nodes.
31- **Settings** (`Internals/Settings/`) — Platform-specific audio session and format configuration.
32 
33### Source Layout (Sources/AudioKit/)
34 
35- `Nodes/` — Audio graph nodes organized by category:
36  - `Effects/` (Distortion, Dynamics, Filters)
37  - `Generators/` (PlaygroundOscillator, PlaygroundNoiseGenerator)
38  - `Mixing/` (Mixer, MatrixMixer, Mixer3D, EnvironmentalNode)
39  - `Playback/` (AudioPlayer, MultiSegmentAudioPlayer, AppleSampler, VariSpeed, TimePitch)
40- `MIDI/` — CoreMIDI wrapper with listener/transformer pattern, file parsing, virtual ports
41- `Taps/` — Non-intrusive audio stream analysis (AmplitudeTap, FFTTap, RawDataTap, NodeRecorder)
42- `Internals/` — Engine, hardware devices, settings, tables, utilities, error handling
43- `Audio Files/` — FormatConverter, AVAudioFile/AVAudioPCMBuffer extensions
44- `Sequencing/` — AppleSequencer (CoreAudio/MIDI-based)
45 
46### Extension Ecosystem
47 
48This repo is the **base layer only** (Swift wrapping AVFoundation). C++/DSP functionality lives in separate packages: AudioKitEX/CAudioKitEX provide the DSP layer, and packages like SoundpipeAudioKit, DunneAudioKit, STKAudioKit extend it with additional nodes.
49 
50## Testing Approach
51 
52Tests use **MD5 hash comparison** of rendered audio buffers for deterministic validation. The workflow:
53 
541. Create an `AudioEngine`, attach nodes, call `engine.startTest(totalDuration:)`
552. Render audio with `engine.render(duration:)`
563. Validate with `testMD5(audio)` which checks against hashes in `ValidatedMD5s.swift`
57 
58During test development, use `audio.audition()` to listen to output, then capture the MD5 hash and add it to the validated dictionary. Remove `audition()` before committing.
59 
60## Style Conventions
61 
62- camelCase variables (lowercase first), uppercase Classes. No Hungarian notation.
63- Descriptors before nouns: `leftOutput` not `outputLeft`
64- Omit units from names: `frequency` not `frequencyInHz`
65- Only collections are pluralized: `channelCount` not `numberOfChannels`
66- Acronyms all CAPS or all lowercase: `enableMIDI` not `enableMidi`
67- Booleans: `is` prefix with `ed`/`ing` suffix: `isLooping`, `isFilterEnabled`
68- Time intervals are called "Durations" (to distinguish from moments in time)
69