Stringhand

一把由本地浏览器持续演奏、Agent 提前交付乐句意图的吉他。包含完整前端 PWA、九个 MCP 工具、规则式 Guitar Brain、真实采样、听唱反射、曲谱库、录音与离线原创谱渲染。

非商业许可：PolyForm Noncommercial 1.0.0。 原创代码及随附原创内容允许按许可用于非商业用途、修改和再分发；商业用途需另获权利人授权。完整条款见 LICENSE.md，范围与例外见 LICENSE-STATUS.md。这是非商业源码公开（source-available），不是 OSI 定义的开源。第三方 CC0 采样不受新增非商业限制。

0.2 更新：共享实时/离线编配器、持续低音与空弦共鸣、逐颗冲突日志、17 根音完整尾音采样、柔化勾弦/滑音，以及离线并联房间混响。见 编配指南 与 音色说明。编配自然度仍有改进空间。

启动

需要 Node.js 22+、Python 3.10+、FFmpeg（带 libmp3lame）在 PATH。采样已包含，无需下载或调用音乐生成 API。

npm ci
npm run build
python -m venv .venv
# Linux / macOS
. .venv/bin/activate
# Windows PowerShell 改用 .venv/Scripts/Activate.ps1
pip install -r requirements.txt
cp .env.example .env
# Windows 可用 Copy-Item .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"
# 执行两次，分别填入 .env 中两个不同的密钥；不要提交 .env
python backend/server.py

打开 http://localhost:3072/guitar/，输入 GUITAR_BROWSER_KEY。浏览器只保存 HttpOnly 会话 cookie，不把控制密钥放到前端。选择曲目或即兴，然后点击递琴，首次点击解锁音频。麦克风拒绝授权时仍可手动等我、继续、结束。

可选 Docker：配置 .env 后 docker compose up --build -d。容器包含 Node、Python、FFmpeg，数据通过独立 volume 持久化。Docker 配置随包提供；验证范围见 docs/VALIDATION.md。

手机需要 HTTPS。把 GUITAR_ORIGIN 改成实际 HTTPS origin，使用 ops/nginx.conf.example 将 /guitar/ 反代至本机3072，保留 Host/Origin 与 WebSocket。勿将 /control/ 暴露到公网。已有网站可用普通菜单链接 /guitar/ 嵌入；无需原作者的主页或登录服务。

Related MCP server: Fretboard Voicing Explorer MCP Server

接 Agent

复制并修改 mcp.example.json 中 Python 和脚本的绝对路径，在客户端设置单独的 GUITAR_CONTROL_KEY，它必须与服务端一致。MCP 的 GUITAR_CONTROL_URL 默认 http://localhost:3072；浏览器使用公网 HTTPS 时，MCP 仍可走本机地址。远程 Agent 可通过 SSH 隧道访问控制端；浏览器反代需保持配置的 Host。

九个工具：start / intent / wait / state / stop / fill / hold / tease / score。

页面递琴后，Agent 调用 state 读取 songId、sessionId 与和声预览，再 start。即兴建议一次提交开场：

{"song_id":"improv","bpm":60,"bars_per_phrase":2,"style":"fingerpick","energy":0.32,
 "progression":[{"chords":[{"chord":"Dm7","beatLength":4}]},
                {"chords":[{"chord":"G7","beatLength":4}]}]}

Agent 只提前排未来一两句；错过边界即拒绝。没有新意图，重复上一句而不停止。wait 使用 cursor 与长等待，可加 until_phrase/session_id。守拍、扫弦、反射全部本地执行。stop(style="natural") 自然收尾。

递琴通知为可配置功能：设 GUITAR_HANDOFF_URL，可另设 GUITAR_HANDOFF_TOKEN。点击后服务端 POST {"text":"演奏上下文与工具用法"}，接收方返回2xx表示成功。没有 webhook 时页面仍能递琴，Agent 手动 state/start；不伪造通知送达。含糊失败不自动重复发送。通知不含私人歌词。测试与示例不会向真实 Agent 发消息。

曲谱、录音、离线创作

• 前端导入标准 SongScore JSON；本机曲谱库支持多首、删除、BPM、移调、section/phrase 边界、器乐段与仅本地歌词。原始谱字段见 src/score.ts 与 examples/。界面所有能力见 功能对照表。

• 开唱轻降力度、长停唱边界 vamp、重唱恢复；无转写。每句提供声学四数，事件压缩；不向 Agent 发每拍信息。

• 吉他录音与引擎日志自动保存。人声录制和上传默认关闭，每次可在页面选择。不开上传时人声只留本机；明确允许后上传人声及含人声混音。浏览器麦克风轨不保证纯人声分离。

• data/music/recordings/<日期>-<song_id>/<session_id>/ 保存 WAV、engine-log.json、mix.mp3。独立审计约每5秒同步至 recordings/journals/<session_id>.json，断网本地留存、恢复补传，不依赖音频上传成功。

• 离线原创谱用 score(action="schema") 查格式，save(original=true)、get/list 修稿，render 后用 status 取得 mp3_path。无需浏览器，不占现场 Session，文件发送交给自己的 Agent 客户端。完整指弹谱能力见 docs/SCORE.md。

测试

npm test
python -m unittest discover -s tests -p "test_*.py"
npx playwright install chromium
npm run test:browser
node tests/v2-audio.mjs

浏览器集成测试会启动独立端口的测试服务与临时目录，不读部署的 .env，不连真实 MCP 或通知接口。可设 CHROMIUM_PATH 使用已有 Chromium；可设 PYTHON 使用虚拟环境解释器。

数据与边界

数据默认在 data/，不进入仓库；GUITAR_DATA_DIR 可更改。私谱、歌词、真实演奏日志、录音、密钥、个人运维记录均不随包分发。导出保留全部生产模块与采样，不含原站点账户探针与历史私人测试记录。

当前仍是单用户、单演奏者服务，不是多人托管平台。离线最长20分钟加有限尾音，实时录音20分钟上限不停止伴奏；实时高级谱/变拍支持边界见 SCORE.md。已有页面短断网可继续，30秒租约超时安全暂停；新开页需在线鉴权。这些是现有实现的限制，不以“完整导出”冒充尚未实现的能力。