Guitar Practice App
BlaiseMoses01/guitar-practice-app
Controle hands-free de YouTube e metrônomo para prática de guitarra
Ver no GitHubMCP server que orquestra controle hands-free de vídeos do YouTube e metrônomo para prática de guitarra via Claude Code. Funciona por voz (daemon local com Whisper) ou digitação, permitindo comandos como 'loop intro 3 vezes em 0.5x velocidade' sem soltar o instrumento.
Instalação
npx convez-ai BlaiseMoses01/guitar-practice-app1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Praticar trechos de músicas em diferentes velocidades sem soltar a guitarra
- Orquestração de backing tracks com metrônomo sincronizado por voz
- Construção de biblioteca pessoal de vídeos de prática com timestamps
Veredito

Solução criativa que integra Claude Code com controle de browser e áudio local de forma elegante. Arquitetura robusta (loops no browser, metrônomo detached, segurança bot-safe) para um caso de uso nicho, mas bem executado — recomendado para quem quer experimentar orquestração voice + video.
README
A tradução para o português deste README ainda está na fila.
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_sectionreturns 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) andlibportaudio2(voice mic capture)uv(voice daemon only)
Setup
git clone <this repo> && cd guitar-practice-app
npm install && npm run build
- Load the extension:
chrome://extensions→ enable Developer mode → Load unpacked → selectextension/dist. (Reload it there after every rebuild.) - Start Claude Code in the repo root and approve the project's
guitarMCP server when prompted. The extension connects to it within ~5 seconds (until then its console logs harmlessERR_CONNECTION_REFUSEDretries). - Smoke-test without Chrome (optional):
node scripts/mcp-poke.mjsexercises 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_videowithout a URL (defaults to the currently open video)
License
MIT — see LICENSE.