Audio Player

One node owns one audio file, chosen in the inspector or driven by a path cable; many nodes play many files simultaneously. Playback happens inside the shared AVAudioEngine graph rather than in a private engine of its own. That single architectural fact explains most of the node's behaviour.

One clock. Every Audio Player, every audio filter node and every Audio Output live in the same render tree with the same hardware clock. Two independent clocks can drift against each other and crackle; one cannot. Loops are scheduled sample-exactly with a one-ahead queue, so they are gapless and click-free at any loop length.

DAW routing semantics. A player is silent until an enabled Audio Output routes it — exactly like a channel strip in a DAW with no output assigned. This is not a bug to work around: monitoring and analysis stay live regardless, so an unrouted player still feeds Audio FFT, Audio Analysis and the ML analysis nodes at full fidelity. One source can also fan out into several filter chains in parallel — the cables you draw are the engine wiring, and any topology change rebuilds the whole engine graph from its declarative description in one coalesced pass, so filters spliced in mid-playback simply work and playback resumes from the same position.

Millisecond analysis. Analysis hooks fire per real render quantum — a few milliseconds — instead of the system's 100 ms tap minimum, so FFT-driven visuals react to a file as fast as they react to the microphone.

Transport semantics. Time Mode selects the world:

• Transport (0) — Play runs or pauses, Speed sets the rate, In Point / Out Point (0–1 fractions of the full duration) mark the region that plays, and Loop Mode decides the end behavior.
• Scrub (1) — the Scrub port is the timeline: 0 is the start, 1 the end, and any meaningful change seeks immediately. Drive it from an LFO, a fader or an EEG channel to scratch audio.

Loop modes: 0 = Loop (seamless, sample-accurate return to the In point) and 1 = Once — Stop. Ping-Pong is not offered here because the underlying player node cannot render audio in reverse; a value of 2 falls back to plain looping.

Pitch Modes decouple speed from pitch:

The mode is switchable live, and the unused unit is bypassed rather than left idling — an idle time-pitch unit smears transients even at rate 1.0, which is why beat detection on files now matches live input. Speed itself is clamped to the range 1/32× to 32×.

Events. Restart is edge-triggered: a rising edge seeks back to the In point. Finished is a one-frame pulse per the event-logic conventions, fired when the play region ends — including on loop wraps, so it doubles as a cycle tick.

Level is a peak-decay RMS of the playing signal: instant rise, musical fall. It gives you loudness-driven brightness or scale without wiring an FFT at all.

File handling. Browsing in the inspector stores a security-scoped bookmark with the project, so the file remains readable after a relaunch under sandboxing. A picked file takes effect immediately. A cabled File path takes priority; otherwise the node's own stored value is used, which is what keeps a disabled player from rebuilding its whole session (file, chain, ring buffer) every frame.

Outputs: Audio (structure — the shared ring-buffer currency; connects directly to Audio FFT, Audio Analysis and every audio filter node), Level (Float, peak-decay RMS), Time (seconds), Progress (0–1 across the full duration), Duration (seconds), Playing (Bool), Finished (a one-frame pulse) and Info (structure with file details).

• Music-driven visuals — Audio Player Audio → Audio FFT → Audio Spectrum → Canvas: a full spectrum visual off a file, with the same millisecond analysis cadence as the microphone.
• Loudness without analysis — Level → a Canvas Opacity or a Circle Radius: instant brightness pumping with a musical fall, one cable, zero FFT.
• Audible playback — Audio Player Audio → Audio Gain → Audio Reverb → Audio Output: the chain you draw is the engine graph; without that Audio Output the player stays silent by design while analysis keeps running.
• Tape stop effect — Pitch Mode Varispeed, an LFO or envelope ramping Speed from 1.0 down to 0.05: the classic pitch-dropping slowdown.
• Pitch-stable slow motion — Pitch Mode Keep Pitch (HQ) with Speed 0.5: half tempo at original pitch, ideal for stretched ambient beds under a slow visual.
• Scratch performance — Time Mode Scrub with a Mouse X or MIDI fader on Scrub: hand-controlled position with immediate seeks.
• ML pipeline — Audio → Pitch Detection → Notes to Points → Plexus: an 88-note polyphonic point cloud driven straight from a file, and Audio → Audio Beat Detection for kick/snare/hat triggers off the same source.
• Loop tick — Finished → Counter: count bars or sections as the loop wraps, since the pulse fires once per cycle.

• Silence is expected without an Audio Output. If a file loads and Playing is true but you hear nothing, the missing piece is an enabled Audio Output node routing the player — analysis works either way, so visuals can look correct while the room is quiet.
• Browse for the file once even when driving File by cable: the browse creates the security-scoped bookmark that survives a relaunch. A bare path string carries no sandbox access of its own.
• Pick the Pitch Mode that matches your intent, not the "safest": Varispeed bypasses the time-pitch unit entirely and is the cleanest path for beat detection and transient-driven visuals.
• Restart is edge-triggered — a permanently true cable fires exactly once. Drive it from a one-frame pulse (a beat trigger, Do Once, a Finished pulse) to retrigger repeatedly.
• Ping-Pong exists on Video Player but not here; if you need a reversed audio phrase, reverse the file offline.
• In Point and Out Point are fractions of the full duration, and Progress is measured against the full duration too — not against the region you looped.
• One source can feed several filter chains in parallel, and every filter carries its own analysis tap, so an Audio FFT can watch the signal anywhere along the chain, not just at the source.