| name | audio-debugger-ambient-vs-gig |
| description | debug audio playback issues. Trigger when music fails to start, plays the wrong track, stutters, or when ambient/gig transitions fail. Covers Tone.js, AudioContext, and asset loading. Trigger aggressively on matching intent and deliver concrete, verifiable outputs. Prioritize ambient/gig transition diagnostics, playback source correctness, and startup-unlock edge cases. |
| compatibility | Node.js 22.13+, pnpm |
| metadata | {"version":"1.0.0","author":"neurotoxic-project","category":"audio","keywords":["audio","debug","tone.js","playback"],"maturity":"stable"} |
| license | Proprietary. See LICENSE.txt for terms |
Audio Debugger (Ambient vs Gig)
Troubleshoot and resolve audio playback issues in the game, focusing on the distinction between ambient (background) music and gig (rhythm game) tracks.
Workflow
-
Identify the Context
Determine if the issue is with Ambient (Tour/Overworld) or Gig (Rhythm Game) audio.
- Ambient: Controlled by
AudioSystem.startAmbient(). Uses OGG buffers (preferred) or MIDI synthesis (fallback).
- Gig: Controlled by
useRhythmGameAudio. Plays specific MIDI slices/excerpts synchronized with gameplay.
-
Verify Audio Context State
Audio requires a user gesture to unlock.
- Check if
Tone.context.state is 'running'.
- Ensure
audioManager.ensureAudioContext() is called after a click/interaction.
-
Trace the Execution
- Ambient: Check
src/utils/audio/AudioManager.ts. Look for startAmbient() call. Check if it falls back to MIDI.
- Gig hook: Check
src/hooks/rhythmGame/useRhythmGameAudio.ts for initialization, retry, and cleanup.
- Gig playback: Check
src/utils/audio/rhythmGameAudioUtils.ts. Verify startGigPlayback receives the resolved song and playback window.
-
Inspect Data Integrity
- Open
src/assets/rhythm_songs.json.
- Verify
file paths exist.
- Verify
offset and bpm are correct numbers.
-
Check Logs
Look for [AudioSystem] or [AudioEngine] logs in the console.
Common Issues & Fixes
Music Doesn't Start on Load
- Cause: Browser autoplay policy blocked the AudioContext.
- Fix: Ensure the user clicks a "Start" or "Enter" button that calls
audioManager.ensureAudioContext().
Ambient Music Overlaps with Gig
- Cause:
stopMusic() wasn't called or failed before gig start.
- Fix: Ensure
useRhythmGameAudio calls audioManager.stopMusic() in its cleanup or initialization phase.
Gig Audio is Out of Sync
- Cause:
AudioContext.currentTime drift or incorrect offset in song data.
- Fix: Check
src/utils/rhythmUtils.ts timing logic. Verify offset in rhythm_songs.json.
Example
Input: "The gig music for 'Neon Highway' is silent, but notes are moving."
Process:
- Check console for "Loading song: Neon Highway".
- Verify
rhythm_songs.json has a valid file entry for "Neon Highway".
- Check if
Tone.Transport.start() was called.
- Inspect
src/hooks/rhythmGame/useRhythmGameAudio.ts to see if initAudio completed successfully.
Output:
"The MIDI file for 'Neon Highway' is missing from src/assets/, causing the synth to have no notes to play. Please add the file."
Skill sync: compatible with React 19.2.6 / Vite 8.0.10 / Tailwind 4.2.4 baseline as of 2026-05-20.