Guitar Practice App

Hands-free control of YouTube practice videos and a standalone metronome, orchestrated by Claude Code. Say "hey jarvis, loop the intro solo three times at half speed" and the video does it — your hands never leave the guitar.

"open the stairway backing track"
"save this spot as intro solo start"
"loop the intro solo 3 times at 0.5, 0.75, then full speed"
"start a metronome at 90 bpm in 3/4"
"a bit slower"        ← context carries across commands

Works two ways with the same toolset:

• Typed — talk to Claude Code in your terminal like normal.
• Voice — an always-on daemon: wake word → local speech-to-text → a persistent headless Claude session. Everything runs locally except the Claude API call.

Architecture

            you (voice)                          you (typing)
                │                                     │
        ┌───────▼────────┐                   ┌────────▼────────┐
        │ voice/daemon.py│                   │ interactive     │
        │ openWakeWord   │                   │ Claude Code     │
        │ Silero VAD     │                   │ session         │
        │ faster-whisper │                   └────────┬────────┘
        └───────┬────────┘                            │
                │ stream-json stdio                   │ (only ONE of these
        ┌───────▼────────┐                            │  runs at a time)
        │ headless Claude│◀───────────────────────────┘
        │ Code session   │
        └───────┬────────┘
                │ MCP (stdio)
        ┌───────▼─────────────────────────────────────────────┐
        │ server/  — the guitar MCP server (Node/TypeScript)  │
        │  ├─ node:sqlite → data/practice.db   (video library │
        │  │                                    + timestamps) │
        │  ├─ ws://127.0.0.1:8765  ◀── Chrome extension (MV3) │
        │  │       └─ content script drives the <video>       │
        │  │         element on youtube.com (seek, rate,      │
        │  │         volume, loop engine with per-pass speeds)│
        │  └─ JSON IPC → detached mpv looping a generated     │
        │               one-bar click WAV      (metronome)    │
        └─────────────────────────────────────────────────────┘

Design notes that matter:

• Bot-safe by construction. The extension's content script only reads/writes properties of the already-loaded <video> element (currentTime, playbackRate, volume, play()/pause()) — invisible to YouTube's servers. No UI clicks, no scraping, no rapid navigation, ever.
• Loops run in the browser, not in Claude. loop_section returns immediately with an ETA; a 50 ms poll in the content script handles the loop boundaries and per-pass speed changes. Claude never sleeps or polls.
• The metronome is a detached process. It keeps perfect time (the click WAV is exactly one bar, sample-exact, so looping it can't drift) and survives server restarts.
• One brain at a time. The voice daemon and an interactive Claude Code session each spawn their own MCP server, which binds port 8765. The daemon checks at startup and tells you to close the other one.

Repo layout

Path	What it is
server/	The guitar MCP server: 16 tools, SQLite library, WebSocket bridge, metronome controller
extension/	Chrome MV3 extension: background service worker (WS client, tab management) + content script (video control, loop engine)
voice/	Always-on voice daemon (Python 3.12/uv): wake word, VAD, STT, headless Claude session — see voice/README.md
scripts/	fake-extension.mjs (mock extension), mcp-poke.mjs (full no-browser smoke test)
data/	SQLite database (created on first run, gitignored)
prompts/	The original project spec this was built from

Prerequisites

• Linux with PipeWire (developed on Ubuntu; the metronome and voice cues use pw-play)
• Node.js ≥ 23.4 (uses the built-in node:sqlite — no native deps)
• Chrome/Chromium
• Claude Code CLI
• sudo apt install mpv (metronome) and libportaudio2 (voice mic capture)
• uv (voice daemon only)

Setup

git clone <this repo> && cd guitar-practice-app
npm install && npm run build

1. Load the extension: chrome://extensions → enable Developer mode → Load unpacked → select extension/dist. (Reload it there after every rebuild.)
2. Start Claude Code in the repo root and approve the project's guitar MCP server when prompted. The extension connects to it within ~5 seconds (until then its console logs harmless ERR_CONNECTION_REFUSED retries).
3. Smoke-test without Chrome (optional): node scripts/mcp-poke.mjs exercises every tool against a mock extension.

Then just talk to Claude Code:

save https://youtu.be/xxxx as my stairway backing track open stairway, set speed to 0.75 and volume to 60 save this spot as solo start … save this spot as solo end loop the solo 4 times

Voice mode

cd voice
uv sync                            # one-time venv setup (Python 3.12)
uv run daemon.py --list-devices    # pick your mic, set [audio].input_device in config.toml
uv run daemon.py --test-wake       # say "hey jarvis" → beep
uv run daemon.py --test-stt        # speak after each beep, check transcripts
uv run daemon.py                   # the real thing (close interactive Claude Code first)

First run downloads models locally (openWakeWord + Silero VAD + Whisper base.en, ~80 MB total). Wake word, mic, end-of-speech timing, STT model, and feedback style are all in voice/config.toml; the tuning guide for loud-room reliability is in voice/README.md.

To save a new video while the daemon is running: browse to it in Chrome like a human, then say "save this one as <title>" — the extension knows what's open, so URLs never need to be typed or spoken.

MCP tools

All time inputs are forgiving: "90", "1:30", "1m30s", "1:02:03". Speeds accept "0.75x"; volume accepts 0–100 or "+10"/"-10". Most tools default to the currently open video.

Tool	Does
save_video / find_videos / open_video	Library: save by URL + title, fuzzy search, open in the managed tab (reuses one tab)
save_timestamp / list_timestamps / delete_timestamp	Named positions; omit the time to capture "this spot"; add end_time to make a loopable section
play / pause / seek	play/seek accept a time or a saved label
set_speed / set_volume	0.25–2.0x; element volume
loop_section / stop_loop	Loop N passes with optional per-pass speeds ([0.5, 0.75, 1.0]); returns immediately with an ETA
metronome_start / metronome_stop	bpm 20–400 + time signature (accent on beat 1); retunes live if already running
get_state	Player + loop + metronome status; works even with the extension disconnected

Troubleshooting

Symptom	Cause / fix
Port 8765 is already in use	Two brains: close the interactive Claude Code session before starting the voice daemon (or vice versa)
Extension console: ERR_CONNECTION_REFUSED spam	Normal — no Claude session is running, the extension is just retrying
Tools answer "extension is not connected"	Load/reload the unpacked extension at chrome://extensions
Loops/seeks misbehave at video start	An ad owns the player; the loop engine suspends until it ends (get_state reports adShowing)
Metronome tools error with "mpv is not installed"	sudo apt install mpv
Voice daemon: PortAudio library not found	sudo apt install libportaudio2

Roadmap

• Custom "hey claude" wake word (openWakeWord Colab training) to replace hey_jarvis
• Optional spoken replies (piper TTS — the config hook exists)
• systemd user service for true always-on (sketch in voice/README.md)
• save_video without a URL (defaults to the currently open video)

License

MIT — see LICENSE.