Audio as Code Skill 技能

技能简介

Audio as Code 是一款面向 AI Agent 的开源音乐合成框架，由开发者 João Carvalho 维护，2026-10-03 在 GitHub 创建仓库后已迭代至 0.4.0 alpha 版本。它把 70 件可演奏的乐器（涵盖 7 类弹拨弦乐、4 类弓弦、6 件键盘、6 件木管、4 件铜管、16 件鼓与打击乐、7 件有调打击乐、20 件电子音色）全部用 Python 代码合成出来，让 Agent 用简洁的 JSON 评分（score）或 Python API 写出乐谱，再通过 aac render 命令在本地离线渲染为立体声 WAV 或 MIDI 文件。整套流程不需要任何 API Key、音频设备、模型权重或采样素材，也不需要 DAW 软件——Agent 拿到任务后可以自己安装、作曲、校验、渲染、交付，整个创作过程保持完全可编辑、可复现、可审计。

项目以 MIT 协议开源，定位是「Agent 的便携式小型管弦乐团」：评分（score）是核心数据结构，包含 BPM、节拍、种子、轨道、音符、力度和声相等；Agent 写出一份 score 之后，渲染器会把音符转换为带电平检查、峰值检查、静音检查的 WAV 文件，并生成包含时长、峰值、RMS、轨道数等指标的 render report，方便 Agent 评估音质后再迭代修订。

核心能力

• 70 件乐器全部代码合成：弹拨弦乐（吉他、曼陀林、竖琴等）、弓弦、键盘（含钢琴、拨弦键琴）、木管、铜管、打击乐（含完整 GM 鼓映射）、有调打击乐（马林巴、钟琴、卡林巴等）和电子音色，每个声部都是数学生成的程序化声音，不依赖任何外部音频素材。
• 完整 CLI 命令集：提供 aac instruments（浏览乐器）、aac schema（导出 JSON Schema）、aac validate（校验 score）、aac inspect（不渲染的情况下检查就绪状态）、aac render（渲染 WAV 与 stems）、aac midi（导出 MIDI）、aac analyze（电平分析）、aac mix（混音/增益调整）等子命令，所有操作都返回结构化 JSON 输出。
• Python 与 JSON 双 API：可以用 Pattern.sequence() / Song / Track 等高级 Python 接口作曲，也可以直接写符合 song-v1.schema.json 的 JSON 评分——任何语言的 Agent 都能直接生成 score 文件。
• 可复现渲染：相同 score + 相同 Python 环境能产出字节级一致的 WAV；seed 参数让鼓点和激励信号可被精确复现，便于版本管理和回归测试。
• 分级文档生态：内置 SKILL.md（便携式作曲技能）、llms.txt（针对大模型的导览索引）、instruments.json（乐器目录）、music/manifest.json（示例曲目清单）、docs/*.md（全部 Markdown 指南），Agent 可以按需加载。
• 离线与轻量化：依赖仅 numpy=1.24、mido=1.3、pydantic=2.7，可选 pyloudnorm 做 LUFS 响度归一化；首次安装后即可断网工作。
• MIDI + WAV 双导出：渲染时同步生成主混音、每个轨道的 stem、可继续在 DAW 编辑的 Type 1 MIDI 文件，以及包含电平指标的 render report。

安装配置

• uv 项目方式（推荐）：在已有 pyproject.toml 的项目里执行 uv add "audio-as-code==0.4.0"，然后 uv run --locked aac instruments 与 uv run --locked aac schema 验证安装。
• uvx 一次性方式：执行 uvx --from audio-as-code==0.4.0 aac init my-soundtrack 创建新项目模板，再 cd my-soundtrack && uv sync && uv run aac doctor，模板已带 composer、JSON score 和 Agent 指令。
• Python venv 方式：用 python -m venv .venv 建虚拟环境后，执行 .venv/bin/python -m pip install audio-as-code==0.4.0（Windows 用 .venvScriptspython.exe -m pip install ...），然后 python -m audio_as_code --help。
• 源码 ZIP 方式：从官网 download/audio-as-code-0.4.0-source.zip 下载完整源码（含示例、文档、可移植 skill），解压后用 uv sync --locked 安装依赖。

使用步骤

1. Agent 读取 SKILL.md：访问 https://audioascode.com/llms.txt 与仓库 skills/audio-as-code/SKILL.md，了解命令契约、score 结构和局限性。
2. 构建 score：用 Pattern.sequence([...]) 组合旋律与鼓点，或直接编辑符合 song-v1.schema.json 的 JSON 文件，填入 BPM、节拍数、轨道、音符（pitch/start/duration/velocity）。
3. 校验与检查：依次执行 uv run aac validate score.json（校验合法性）、uv run aac inspect score.json（不渲染检查导出约束和阻塞项），修正所有提示后再继续。
4. 渲染并分析：执行 uv run aac render score.json -o output/song.wav --stems output/stems --report output/report.json 生成主混音、stem 与电平报告；再用 uv run aac analyze output/song.wav 确认时长、峰值、RMS、静音与削波检查。
5. 导出 MIDI 并交付：用 uv run aac midi score.json -o output/song.mid 生成 Type 1 MIDI（480 ticks/quarter，可继续在 DAW 中编辑），把 WAV、MIDI、JSON score、Python 源码与 render report 一起交付给下游项目（视频、游戏、幻灯片）。
6. 迭代修订：把 score 和源码与音频一起放进项目里，下次场景变化时只需修改 score 文件并重新渲染即可，无需重建音色库。

适用场景

• AI Agent 配乐：让 Agent 根据场景描述（龙 boss 战斗、季度汇报反派节奏、发布会倒计时）自动生成可编辑的管弦乐 cue，并把 WAV 直接嵌入项目。
• 独立游戏音效：为 2D / 像素 / 解谜游戏的关卡、菜单、过场制作短乐句；同一 score 可在修订时直接调整乐器、节奏或力度。
• 视频与发布会：用一首 score 同时输出 WAV（直接导入剪辑软件）和 MIDI（让音乐人继续润色），生成 logo sting、过场短乐、片段循环。
• 教学与算法作曲演示：用 5 件乐器（吉他、马林巴、钟琴、贝斯、鼓）演示物理/模态合成模型，无需任何外部采样文件即可在课堂上演示声学原理。
• 古典名曲再创作：仓库内置 Für Elise、巴赫大提琴组曲、莫扎特土耳其进行曲、Greensleeves、欢乐颂 5 首公版作品，提供「经典版」与「AI Reimagined 改编版」对照示例。
• Hyperframes / Codex / Claude Code 工作流：官网 integrations 文档给出在视频时间线、游戏音频目录、幻灯片场景中调用 Agent 配乐的具体 recipe。

适用人群

• 给 AI Agent 设计任务流的开发者，希望 Agent 能自助输出可编辑、可复现的配乐；
• 独立游戏 / 互动叙事 / 教学课件作者，需要按场景批量生成短乐句，又不想购买采样库或订阅云端 TTS；
• 视频剪辑师与发布会制作人，需要快速拿到一段 logo sting 或过场短乐，能在 DAW 里继续修订；
• 算法作曲 / 程序化音频研究者，关注物理/模态合成模型、可复现渲染与 JSON Schema 评分契约；
• 教育场景里演示「用 Python 写一段乐器模型」的讲师，可直接运行 70 件乐器的浏览示例。

工作原理

Audio as Code 采用「评分即数据结构」的设计：score 是 JSON 或 Python 对象，描述 BPM、节拍、种子、轨道（乐器、音符、力度、增益、声相），渲染器从 score 出发，按声学模型（基础波形 sine/triangle/saw/pluck/bass/pad/kick/snare/hat，加上模态/物理近似如吉他、马林巴、钟琴、弓弦、木管）实时生成 PCM 流。instruments.py 定义乐器目录与发声能力；model.py 维护跨版本 score 契约；pattern.py 把旋律/鼓点拆解为音符时间线；render.py 负责多轨混合与电平归一化；physical.py 实现弦/棒/铃的物理/模态模型；orchestra.py 提供弓弦与管乐的声学近似；acoustics.py 共享噪声与共鸣体；midi.py 提供 MIDI 互通；cli.py 把所有能力暴露为 Agent 可调用的 shell 命令。每一份 score 都带 hash 写入 render report，保证评分可追溯；float 与依赖变化可能改变字节，但相同 lockfile 下渲染结果可被 git diff。

官方链接

• 官方网站与示例试听：https://audioascode.com
• 仓库与问题跟踪：https://github.com/joaoCarvalho1000/audio-as-code
• PyPI 包：https://pypi.org/project/audio-as-code/
• Agent 技能（SKILL.md）：https://github.com/joaoCarvalho1000/audio-as-code/blob/main/skills/audio-as-code/SKILL.md
• 文档索引（llms.txt）：https://audioascode.com/llms.txt
• 评分 JSON Schema：https://github.com/joaoCarvalho1000/audio-as-code/blob/main/schemas/song-v1.schema.json
• 创意工作流集成指南：https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/integrations.md
• 0.4.0 源码 ZIP：https://audioascode.com/download/audio-as-code-0.4.0-source.zip
• 支持作者（Ko-fi）：https://ko-fi.com/joaothecarvalho