Stringhand

# Stringhand 一把由本地浏览器持续演奏、Agent 提前交付乐句意图的吉他。包含完整前端 PWA、九个 MCP 工具、规则式 Guitar Brain、真实采样、听唱反射、曲谱库、录音与离线原创谱渲染。 **非商业许可：PolyForm Noncommercial 1.0.0。** 原创代码及随附原创内容允许按许可用于非商业用途、修改和再分发；商业用途需另获权利人授权。完整条款见 [LICENSE.md](LICENSE.md)，范围与例外见 [LICENSE-STATUS.md](LICENSE-STATUS.md)。这是非商业源码公开（source-available），不是 OSI 定义的开源。第三方 CC0 采样不受新增非商业限制。 0.2 更新：共享实时/离线编配器、持续低音与空弦共鸣、逐颗冲突日志、17 根音完整尾音采样、柔化勾弦/滑音，以及离线并联房间混响。见 [编配指南](docs/ARRANGEMENT.md) 与 [音色说明](docs/SOUND.md)。编配自然度仍有改进空间。 ## 启动 需要 Node.js 22+、Python 3.10+、FFmpeg（带 libmp3lame）在 PATH。采样已包含，无需下载或调用音乐生成 API。 ```sh 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](docs/VALIDATION.md)。 手机需要 HTTPS。把 `GUITAR_ORIGIN` 改成实际 HTTPS origin，使用 `ops/nginx.conf.example` 将 `/guitar/` 反代至本机3072，保留 Host/Origin 与 WebSocket。勿将 `/control/` 暴露到公网。已有网站可用普通菜单链接 `/guitar/` 嵌入；无需原作者的主页或登录服务。 ## 接 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。即兴建议一次提交开场： ```json {"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/`。界面所有能力见 [功能对照表](docs/FEATURES.md)。 - 开唱轻降力度、长停唱边界 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](docs/SCORE.md)。 ## 测试 ```sh 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秒租约超时安全暂停；新开页需在线鉴权。这些是现有实现的限制，不以“完整导出”冒充尚未实现的能力。