SEGAN

SEGAN — Sound Effect Grammar And Notation

SEGAN は AI とゲームオーディオの間をつなぎます。効果音と音楽のための小さなテキスト記法を定義します。楽器キット、ステップグリッド形式の楽曲、レイヤー構成のシンセ SFX はすべて YAML で記述され、AI エージェントが流暢に書けます。また、記法のリンティング、（エージェントが見て音を把握できる画像である）リッスンシートのレンダリング、エンジンで利用できる WAV、manifest.json、Godot リソースの生成を行う Python ツールも提供します。これは 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

• キットはパレットです：楽曲では1文字の楽器キーを記述します。ロール行は楽曲のキーの音を表すため、キーから外れた音は記述できません。行ラベルも検証されるので、行が欠けてもグリッドがずれることはありません。
• SFX はシンセレイヤーです：ピッチ／ゲイン／フィルターのキーフレーム、11種類のプリセット（コイン、ジャンプ、レーザー、爆発、ヒット、ダメージ、パワーアップ、ブリップ、選択、ドア、足音）、バリエーション、フェーズ、シームレスループに対応します。
• 録音した SFXで現実世界の音を使用できます：segan sounds search で Freesound 上の録音を検索できます（CC0 と CC BY のみ）。segan sounds add で sounds.lock に登録すると、ユーザーキャッシュに取得され、sha256 で検証されます。リポジトリにコピーされるものはありません。SFX レイヤーでは、録音を個別にトリミング、逆再生、フェード、ピッチシフト、タイムストレッチして再生できます（sample: freesound:<id> またはファイル）。シンセサウンドとのレイヤーも可能です。segan sounds credits で CC BY が求めるクレジットを作成できます。examples/demo/sfx/boss_gong.sfx.yaml をご覧ください。
• 幅広い音色パレット：帯域制限オシレーター、楽器モデル（プラック／ボウイング弦楽器、歌声の母音と合唱、打楽器のマレット、ベルと金属音、加算合成オルガン、ウェーブテーブル、スーパーソー、3〜4オペレーター FM）、ハードシンク、サブオシレーター、ブラスミュート、13種類のドラムマクロ、楽器ごとのエフェクト（コーラス、アンサンブル、フェイザー、フランジャー、テンポ同期ディレイ、リバーブ、ドライブ、コム、リング、オートパンなど）。
• サンプリング楽器は任意のキットで使えます：sample: で WAV、SFZ マップ、SoundFont（.sf2）を再生できます。また、CC0 のライブラリ4種類は segan samples fetch で必要に応じてダウンロードできます：vsco2（オーケストラ）、vcsl（グランドピアノ、エレクトリックピアノ、オルガン、マレット、管楽器、ワールド楽器、ハンドパーカッション）、karoryfer（ギター、ベース、二胡、ブラシ付きドラムキット）、neosound（声、スチールギター、竹笛）。examples/orchestra をご覧ください。
• 設計段階から多様性を実現：プロジェクトのランダムシード、segan kit roll（スタイルを表す語句から、共有の identity グループを持つキットを生成）、segan suggest song（キー、モード、テンポ、拍子、テクスチャ、冒頭部分を、プロジェクト内の楽曲と異なるものに提案）、類似性チェックに対応します。リンティングでは、楽曲の冒頭が似ている場合や最初の小節を共有している場合に警告し、segan similarity ではすべてのペアの類似度をスコア化します。
• 共通ミックス（[mix]：ルーム、トーン、クラッシュ、オーバーサンプリング、ラウドネス目標、トゥルーピークリミッター）をすべてのアセットに適用するため、ゲーム内のサウンドに統一感が生まれます。一度変更すれば、すべてが再レンダリングされます。
• 決定性：ソースが同じなら WAV もバイト単位で同一になります（帯域制限オシレーター、テーブルベースの演算、乱数生成器のドリフトなし）。すべてのコマンドで --json を指定でき、エラー時にはゼロ以外の終了コードを返します。リンティングの指摘には、ルール ID、ファイル、行番号、修正のヒントが含まれます。

ステータス： v0.17：パイプライン全体（キット、SFX、楽曲、リンティング、リッスンシート、ビルド、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/ のデモプロジェクトには、3つのキット（nes、fm_soft、arcade_synth）、プリセットの効果音、バリエーション付きのループ曲が含まれています。ビルド先となる Godot 4.7 プロジェクトは examples/godot/ にあります（まず examples/demo で segan build を実行し、その後 Godot で開いて「再生」を押してください）。

リッスンシート：エージェントはどのように「聴く」のか

エージェントには音が聴こえないため、segan preview は音を描画します。長さ、ピーク、トゥルーピーク、目標値に対する LUFS、リミッター、リードイン、ループ接続部のクリック音などの数値をまとめたヘッダー、アレンジとトラックごとのピアノロール（ソースから生成）、波形（クリッピング箇所は赤色）、オクターブ線入りの対数周波数スペクトログラム、意図したピッチ（白）と検出されたピッチ（水色）、時間経過に伴うラウドネスが表示されます。--json を指定すると、オンセット、音符ごとのピッチ検査（セント単位）、スペクトル重心なども追加されます。判断できないのは好みの問題です。人間が聴いて segan mark <asset> --status approved を実行するまでは、すべてのアセットが status: draft のままです。

ゲームでの出力の使用

segan build は WAV（16 ビット、smpl チャンク内のループポイント、キューとしてのマーカー）と manifest.json を書き出します。アセットごとにファイル、長さ、サンプル単位のループポイントが記録されます。曲については、テンポ、セクション、アレンジ、サンプル・秒・小節単位のマーカー、バリエーション、ステムも記録されます。効果音については、バリエーションとフェーズが記録されます。export = ["wav", "godot"] を設定し、Godot 4 プロジェクト内に output_dir を指定すると、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" を含めると、ビルド時にマニフェスト用の Web Audio プレーヤー segan_audio.js も書き出されます。Unity、Unreal、Defold については、エンジンのトピックの「その他のエンジン」（segan docs engines）を参照してください。インポート設定と、マニフェストから読み取る情報が説明されています。

Claude での SEGAN の使用

SEGAN には、ゲームのオーディオ設定、キットの作成、効果音や曲の作成、リッスンシートの正確な読み取り、時間の経過に伴うサウンドの変化など、ワークフロー全体をエージェントに教える Claude スキルが付属しています。

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

MCP を使った任意のエージェントからの SEGAN の使用

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 は MCP Registry に io.github.lukasgolino/segan として登録されています。

ジェネレータースクリプトと MIDI

segan.api（キー、コード、コード進行、ユークリッドリズム、アルペジオ、パターンビルダー、YAML ライター）は、多数のサウンドやプロシージャル音楽を生成するスクリプト向けの安定した API です。segan import midi song.mid --kit nes は MIDI ファイルを曲に変換します。グリッドに量子化し、キーに合わせて調整し、パートをキットの楽器に割り当て、変更内容をすべてレポートします。

ライセンス

Apache 2.0 です。LICENSE を参照してください。