leadsheet

谱 使用ChatGPT、Claude、Codexini创作简单、可播放的音乐，无需DAW、无需订阅音乐生成服务，也无需专业的音乐软件。`leadsheet`安装了一个本地的MCP服务器和客户端技能，它可以将自然语言提示转换为紧凑、可编辑的`.leadsheet`文件，然后验证并渲染播放的音频。 版本2.0引入了`.leadsheet`格式。它是一种、面向行的音乐DSL，设计用于AI生成和人类编辑：它可用于差异化、版本控制，并且比冗长的JSON代码的音乐符号更节省成本。 ### 通过LLM快速最简单的安装方法是，将以下提示粘贴到您的编码助手终端的LLM中： ```text 为我安装和设置Python包`leadsheet`。 1. 优先使用 tool install leadsheet`；如果`uv`不可用，请pip install leadsheet`. 运行`leadsheet setup`。 3. 使用适合该操作管理器安装推荐的依赖项FluidSynthmpeg。 4. 运行`heet status`并检查每行，包括警告部分。 5.报告缺少依赖项或集成，请在安全时修复它，重新运行设置，然后再次运行状态。 6. 报告已安装的内容、检测到的客户端集成、选定的音频后端以及您需要手动运行的任何剩余警告或请勿修改项目文件或全局客户端配置超出`leadsheet setup`设计的范围。在使用包管理器或在正常Leads和设置流程之外进行更改先询问。 ``` ### 安装后，尝试让您的LLM创作一些简单的作品```text 为我创作一首短小、欢快的曲。时长约为30秒，节奏轻快、愉悦，也许还可以加一些弦乐。 ``` 或者创作放松的音乐： ```为我写一首、和平的乐曲，节奏缓慢。使用弦乐和钢琴等柔和的乐器。时长约为一分钟。 ``` 创作一些有节奏的音乐： ```text 我想创作轻快的歌曲，带有鼓和贝斯。就像在咖啡馆或休息室里听到的那种。保持简单和旋律。 ``` 在您的LLM创建`.leadsheet`文件后，只需让它使歌曲可播放，您就会听到音频。 ## 手动安装 ```bash uv tool install leadsheet # 推荐 leadsheet setup或者，没有`uv ```bash pip install leadsheet le setup ``` `leadsheet setup`是一个必需的一后续步骤 - pip/w没有可靠的安装后钩子，因此这实际上是： 在每个检测到的客户端上CP服务器：Claude（`claude mcpsheet -s userCodex（`~/.codex/config.toml`），或Gemini（`~/.gemini/settings.json`） - 为每个检测到的客户端安装技能：`~/.claude/skills/leadsheet/`适用于Claude Code，`~/.agents/skills/leadsheet/`适用于Codex - 检查可用的音频后端并打印可选的FluidSynth/FFmpeg升级的安装提示 - 下载并缓存用于渲染的通用MIDI音色库 `uv tool install`是首选，因为它将`leadsheet`保持在稳定、持久、隔离的环境中，独立于任何项目venv - `claude mcp add`存储了指向Python解释器的绝对路径，该路径必须在安装命令完成后长期有效，因此不应位于您可能稍后删除的venv中。 在升级后（`pip install -U leadsheet` / `uv tool upgrade leadsheet`）重新运行`leadsheet setup`，以刷新注册的服务器和已安装的技能。 设置完成后，重启您配置的客户端，并让它创作一些内容。 ### AI客户端支持 服务器使用标准MCP协议通过本地stdio，因此相同的`.leadsheet`工作流程适用于支持MCP的客户端： | 客户端 | 设置 | | --- | --- | | ChatGPT | 使用命令`python -m leadsheet.server`添加本地MCP服务器，并使用来自`leadsheet`安装的Python解释器。 | | Claude Code | 运行`leadsheet setup`；它注册服务器并安装技能。 | | Codex | 确保`~/.codex/config.toml`存在，然后运行`leadsheet setup`。 | | Gemini CLI | 确保`~/.gemini/settings.json`存在，然后运行`leadsheet setup`。 | 对于ChatGPT，在您使用的ChatGPT客户端的MCP/开发者设置中配置服务器；命令必须指向安装`leadsheet`的相同环境。连接后，请求ChatGPT或Gemini创建`.leadsheet`文件，调用`validate`，然后调用`compose`。 ## `.leadsheet`格式 文件以必需的节奏行开头，后面跟着和弦、低音、旋律、鼓或自定义轨道。该格式在消除重复值的情况下保持音乐意图的可见性： ```text bpm=85 title="夜晚驾驶" key="A 小调" chords "电钢琴 1" block subdiv=1: Am7 Fmaj7 C G bass "电贝斯（指弹）" root_fifth oct=2: Am7 Fmaj7 C G melody "长笛" notes dur=1/4: A4 C5 E5 x2 r E5 C5 A4 drums "标准" repeat=8: K,H,S,H ``` 旋律是DSL的原生格式，具有为AI和人类作者设计的紧凑符号。实用的音符形式包括： - `dur=`、`int=`和`vel=`设置段默认值。 - `E5@1/2`覆盖一个音符的持续时间；`r`是静止。 - `C5+E5+G5`播放同时发音的音符堆栈。 - `E5 x8`重复前面的音符、静止或堆栈。 ### 重用和歌曲结构 一次性定义可重用的内容并将其应用于多个轨道。`transpose=`和`vel=`是调用站点覆盖： ```text define hook notes dur=1/4: E5 G5 A5 x2 G5 E5 melody "长笛" use: hook melody "小提琴" use: hook transpose=-3 vel=70 ``` 对于合唱或其他多轨道段，定义一个部分并将其放置在任意小节偏移量： ```text section chorus: chords "电钢琴 1" block: Fmaj7 C G Am bass "原声贝斯" root_fifth oct=2: Fmaj7 C G Am drums "标准" repeat=4: K,H,S,H melody "长笛" notes dur=1/4: F5 A5 C5 x2 A5 F5 use section chorus start=8 use section chorus start=24 ``` 完整的语法和约束在安装的技能中为`src/leadsheet/skill/SKILL.md`。`examples/`目录包含完整、验证的`.leadsheet`文件。 ## 从`.leadsheet`文件创作 AI客户端通常通过MCP工具创建和编辑文件。从命令行，可以使用以下命令启动相同的本地服务器： ```bash python -m leadsheet.server ``` MCP工具有： - `list_capabilities` — 可用的和弦类型、GM乐器、鼓套件、样式和防护栏。 - `validate` — 在编译之前分析和理论检查`.leadsheet`文件。 - `compose` — 验证、编译、渲染并保存最佳的可用音频。 更改后，编辑相同的`.leadsheet`文件并再次编译。文本文件是真实来源。 ### 音频输出 `compose`会自动选择最佳的可用输出： - FluidSynth + FFmpeg：标记的MP3 - 仅FluidSynth：可播放的WAV - 可选的TinySoundFont备用方案：可播放的WAV，无系统音频二进制文件 - 无渲染器：MIDI输出和安装警告 FluidSynth和FFmpeg是可选的，但推荐用于最高保真度的标记MP3输出： ```bash brew install fluidsynth # macOS apt-get install fluidsynth # Debian/Ubuntu ``` 如果缺少任一二进制文件，音频不会失败：服务器会回退到WAV，并包含一个警告，告诉调用的LLM可以安装什么来升级结果。 要显式启用进程内备用方案，请安装可选的音频额外包： ```bash pip install 'leadsheet[audio]' ``` ## 其他命令 ```bash leadsheet status # 当前配置信息 leadsheet uninstall # 删除MCP注册和技能 leadsheet uninstall --purge-cache # 同时删除缓存的音色库 ``` ## 工作原理 - **技能**（`~/.claude/skills/leadsheet/SKILL.md`或`~/.agents/skills/leadsheet/SKILL.md`）：教导客户端一个围绕和弦符号（`"Am7"`、`"G7sus4"`）和`.leadsheet`文本格式的小型显式模式。 - **MCP服务器**（`leadsheet.server`，stdio传输，本地注册）：公开四个工具 - - `list_capabilities` — 有效的和弦类型、GM乐器、鼓套件/标记、事件样式和防护栏限制。 - `validate` — 结构和音乐理论验证，无需编译。 - `compose` — 验证、编译、渲染并返回可播放的预览。 一切都是本地的且无状态的：无数据库，无服务器端文件存储，无网络调用，只有一个一次性的音色库下载。 ## 开发 ```bash uv sync uv run pytest ``` 需要FluidSynth和FFmpeg的音频管道测试将在开发环境中自动跳过，如果它们未安装。 ## 许可证 AGPL-3.0-or-later — 请参阅[LICENSE](LICENSE)。