SEGAN

SEGAN — Sound Effect Grammar And Notation

SEGAN 在 AI 与游戏音频之间搭建桥梁。它定义了一套简洁的文本记谱法，用于描述音效和音乐——乐器套件、步进网格乐曲和分层合成器音效，全部采用 YAML 格式——AI Agent 可以流畅地编写；同时还提供一个 Python 工具，用于检查这些内容、生成试听图（Agent 可以查看的声音图像），并构建可直接用于引擎的 WAV、manifest.json 和 Godot 资源。它是 PAGAN（Pixel Art Grammar And Notation）的姊妹库：设计相同，只是处理的对象从像素变成了声音。

patterns:
  a:
    length: 16
    lead: |
      ....|....|..p-|....  F5
      ....|..p-|....|p---  E5
      p-..|....|....|....  A4
    drums: |
      x...|....|x.x.|....  k
      ....|X...|....|X..o  s

• 套件是调色板：乐曲使用单字符乐器键；滚动行是乐曲调性中的音符，因此无法写出调外音符。系统会检查行标签，避免缺少的行导致网格错位。
• 音效由合成器层组成，具有音高／增益／滤波器关键帧、11 种预设（coin、jump、laser、explosion、hit、hurt、powerup、blip、select、door、step）、变体、阶段和无缝循环。
• 录制音效可用于真实世界的声音：segan sounds search 可在 Freesound 上查找录音（仅限 CC0 和 CC BY）；segan sounds add 会将其记录到 sounds.lock 中（下载到用户缓存，通过 sha256 校验，不会复制到仓库）；音效层可播放这些录音（sample: freesound:<id> 或文件），并可独立进行裁剪、反转、淡入淡出、移调和时间拉伸，再与合成声音叠加。segan sounds credits 会生成 CC BY 要求的署名信息。参见 examples/demo/sfx/boss_gong.sfx.yaml。
• 丰富的音色选择：带限振荡器、乐器模型（拨弦与弓弦、歌唱元音与合唱、敲击木槌、铃铛与金属、加法合成风琴、波表、超级锯齿波、3–4 算子 FM）、硬同步、副振荡器、铜管弱音器、13 种鼓组宏，以及单乐器效果（合唱、合奏、移相、镶边、节奏同步延迟、混响、失真、梳状滤波、环形调制、自动声像……）。
• 可在任意套件中使用采样乐器：sample: 可播放 WAV、SFZ 映射和 SoundFont（.sf2）；通过 segan samples fetch 按需下载四个 CC0 音色库：vsco2（管弦乐）、vcsl（三角钢琴、电钢琴、风琴、木槌乐器、管乐、世界音乐与手打打击乐）、karoryfer（吉他、贝斯、二胡、带有刷子的鼓组）、neosound（人声、钢弦吉他、竹笛）。参见 examples/orchestra。
• 精心设计的多样性：随机项目种子、segan kit roll（根据风格词生成套件，并共享一个 identity 组）、segan suggest song（生成项目现有乐曲中没有的调性、调式、速度、拍号、织体和开头），以及相似度检查：当乐曲开头相似或前几小节相同时，lint 会发出警告；segan similarity 会对每一对乐曲进行评分。
• 统一混音（[mix]：房间、音色、压碎、过采样、响度目标、真峰值限制器）适用于所有资源，让游戏中的声音风格一致；只需修改一次，即可重新渲染全部内容。
• 确定性：相同的源文件会生成字节完全相同的 WAV（带限振荡器、基于查找表的数学运算、无随机数生成器漂移）。每条命令都支持 --json，遇到错误时会以非零状态码退出；lint 检查结果包含规则 ID、文件、行号和修复建议。

状态： v0.17：完整流程均已可用（套件、音效、乐曲、lint、试听图、构建、Godot 4、MIDI 导入、MCP 服务、Claude 技能），支持合成器和采样乐器。参见 PLAN.md 和 CHANGELOG.md。

安装

需要 Python 3.11+。该软件包在 PyPI 上名为 segan-gen；命令和导入名称均为 segan：

pip install segan-gen              # the CLI, the library and the MCP server
pip install "segan-gen[ogg]"       # + Ogg Vorbis music export, .ogg/.flac/.mp3 recordings
segan --version

开发：

git clone https://github.com/lukasgolino/segan.git && cd segan
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
mypy && pytest

快速开始

segan init audio --style "cold ship, warm crew"   # segan.toml (with a project seed), BRIEF.md, SOUND.md, kits/core.kit.yaml
cd audio
segan kit show                      # every instrument playing a test phrase: previews/kits/core.listen.png + WAVs
segan new sfx coin --preset coin --description "bright two-note pickup"
segan suggest song theme --mood "exploration"   # key, tempo, meter, texture, opening, progression, instruments
segan new song theme --description "exploration loop"   # takes the suggestion (or --key/--tempo/--meter)
segan lint                          # format errors + warnings from the source and the rendered audio
segan preview coin theme            # WAV + listen sheet (+ loop seam view) per output; numbers with --json
segan gallery                       # every asset side by side + loudness by category
segan build                         # WAVs + manifest.json (+ Godot resources) into output_dir

examples/demo/ 中的演示项目包含三个套件（nes、fm_soft、arcade_synth）、预设音效和带变体的循环歌曲；examples/godot/ 是构建生成的 Godot 4.7 项目（先在 examples/demo 中运行 segan build，然后在 Godot 中打开并按下 Play）。

聆听表：Agent 如何“听”

Agent 无法听声音，因此 segan preview 会绘制声音：包含数字的标题（时长、峰值、真峰值、LUFS 与目标值的对比、限幅器、前奏、循环接缝处的咔嗒声）、编曲和每个音轨的钢琴卷帘（来自源文件）、波形（削波部分以红色显示）、带八度线的对数频率频谱图、预期音高（白色）和检测到的音高（青色），以及随时间变化的响度。--json 会添加起音、以音分为单位的逐音音高检查、频谱质心等信息。它无法判断的是审美：每个资源的状态都会保持为 status: draft，直到有人类聆听并运行 segan mark <asset> --status approved。

在游戏中使用输出

segan build 会生成 WAV 文件（16 位，循环点位于 smpl 区块中，标记作为提示点）和 manifest.json：每个资源都包含其文件、以采样数为单位的时长和循环点；歌曲还包含以采样数、秒和小节为单位的节奏、段落、编曲和标记，以及变体和分轨；音效则包含其变体和阶段。使用 export = ["wav", "godot"]，并将 output_dir 设在 Godot 项目内时，SEGAN 还会将每个 WAV 的循环点和压缩设置写入其 .import 文件，为每个音效生成一个包含变体的 AudioStreamRandomizer，并为每首歌曲生成一个包含分轨的 AudioStreamSynchronized（export + "stems"）：

$Music.stream = load("res://assets/generated/audio/music/overworld.wav")   # loops seamlessly by itself
$Music.play()
$Coin.stream = load("res://assets/generated/audio/sfx/coin.tres")          # a different variation each time
$Coin.play()

这些文件都是普通 WAV（音乐使用 "ogg" 时则为 Ogg），因此任何引擎都能播放；manifest.json 是与引擎无关的接口约定（变体、循环点、总线、播放提示）。在 export 中加入 "web" 后，构建还会生成 segan_audio.js，这是一个用于读取清单的 Web Audio 播放器。关于 Unity、Unreal 和 Defold，请参阅引擎主题中的“其他引擎”（segan docs engines），了解它们的导入设置以及如何读取清单。

将 SEGAN 与 Claude 搭配使用

SEGAN 附带一个 Claude 技能，用于指导 Agent 完成整个工作流（设置游戏音频、编写套件、音效和歌曲、如实解读聆听表，以及随着时间推移调整声音）：

segan skill install          # copies it to <repo>/.claude/skills/segan/

在任意 Agent 中使用 SEGAN（MCP）

claude mcp add segan -- uvx segan-gen mcp --project /path/to/audio    # no install needed (uv); or `segan mcp` after pip install

一个 stdio MCP 服务：26 个工具、以图片形式呈现的聆听表、以音频形式呈现的 WAV。其他客户端只需在配置中使用相同命令：

{ "mcpServers": { "segan": { "command": "uvx", "args": ["segan-gen", "mcp", "--project", "/path/to/audio"] } } }

SEGAN 已以 io.github.lukasgolino/segan 的名称列入 MCP Registry。

生成器脚本和 MIDI

segan.api（音阶、和弦、和弦进行、欧几里得节奏、琶音、模式构建器和 YAML 编写器）是一个稳定的 API，适用于生成大量声音或程序化音乐的脚本。segan import midi song.mid --kit nes 会将 MIDI 文件转换成歌曲：按网格量化、对齐到调性、将声部映射到套件乐器，并报告每项变更。

许可证

Apache 2.0。请参阅 LICENSE。