convez.ai
MCP ServerAutomaçãoAvançado
BlaiseMoses01

Guitar Practice App

BlaiseMoses01/guitar-practice-app

Controle hands-free de YouTube e metrônomo para prática de guitarra

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-app

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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_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

PathWhat 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.

ToolDoes
save_video / find_videos / open_videoLibrary: save by URL + title, fuzzy search, open in the managed tab (reuses one tab)
save_timestamp / list_timestamps / delete_timestampNamed positions; omit the time to capture "this spot"; add end_time to make a loopable section
play / pause / seekplay/seek accept a time or a saved label
set_speed / set_volume0.25–2.0x; element volume
loop_section / stop_loopLoop N passes with optional per-pass speeds ([0.5, 0.75, 1.0]); returns immediately with an ETA
metronome_start / metronome_stopbpm 20–400 + time signature (accent on beat 1); retunes live if already running
get_statePlayer + loop + metronome status; works even with the extension disconnected

Troubleshooting

SymptomCause / fix
Port 8765 is already in useTwo brains: close the interactive Claude Code session before starting the voice daemon (or vice versa)
Extension console: ERR_CONNECTION_REFUSED spamNormal — 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 startAn 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 foundsudo 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.

Ver o original no GitHub

Bom para

Relacionados