madgen — 音MAD自動生成ツール

target と source（音声/動画、複数可）を渡すと、source の断片を自動で選んで切り貼りし、target を再現した音声/動画を生成します。Unit Selection TTS と同じ方式（候補の絞り込み → Viterbi DP）です。

モードは2つあり、1回のレンダリングで併用できます。

インストール

# 道具として入れる（uv が Python も用意します）
uv tool install madgen

# 歌詞モードの素材解析まで使う場合（GPU 推奨）
uv tool install "madgen[lyrics]" --torch-backend=auto

--torch-backend=auto は、uv が GPU とドライバを調べて、その環境に合う PyTorch を選ぶ指定です。Windows と ARM 版 Linux で GPU を使う場合は必須です。付けないと PyPI の既定が入りますが、その中身は環境によって違います。

pip でも入ります（Python 3.12 以上）:

pip install madgen
pip install "madgen[lyrics]"

pip には環境を見て選ぶ機能がありません。上の表で CPU 専用になる環境で GPU を使う場合は、uv を使ってください。 PyTorch を先に CUDA 版で入れる方法もありますが、madgen が要求するバージョンと合わせる必要があり、依存が更新されるたびに指定し直すことになります。

# 既存の環境に入れる場合も、uv なら1コマンドで済みます
uv pip install --torch-backend=auto "madgen[lyrics]"

配布版の uv tool install / uv pip install / pip install には、下記のリポジトリ専用の tool.uv.sources 設定は適用されません。配布版では上記の --torch-backend=auto、リポジトリでは下記の --extra cpu / --extra cu128 で PyTorch の取得先を選んでください。

Windows / Linux 版（Python を入れずに使う）

Releases から、環境に合うものを落として展開してください。

# Windows: madgen-vX.Y.Z-windows-x64.zip を展開して
madgen.exe build-corpus --source sources\ --db work\corpus.sqlite
madgen.exe render --db work\corpus.sqlite --melody target\target.mid --out-dir work\out --video

# Linux: madgen-vX.Y.Z-linux-x64.tar.gz を展開して
tar xzf madgen-vX.Y.Z-linux-x64.tar.gz && cd madgen-vX.Y.Z-linux-x64
./madgen build-corpus --source sources/ --db work/corpus.sqlite
./madgen render --db work/corpus.sqlite --melody target/target.mid --out-dir work/out --video

• メロディモード専用です。歌詞モード（音素解析）は含みません。歌詞モードを使う場合は、上の uv tool install "madgen[lyrics]" --torch-backend=auto で入れてください（GPU 推奨）。
• ffmpeg を同梱しているため、これらの配布物には GPLv3 が適用されます（madgen 自身のソースコードは MIT のままです）。詳細は同梱の THIRD_PARTY_LICENSES/ を参照してください。
• Linux 版は glibc 2.35 以降（Ubuntu 22.04、Debian 12 以降など）で動きます。それより古い環境では uv tool install madgen を使ってください。
• macOS 用の配布物はありません。uv tool install madgen で入れてください（必要なものは自動で用意されます）。

リポジトリを直接使う場合:

uv sync                                # メロディモードだけならこれで十分
uv sync --extra lyrics --extra cpu      # 歌詞モード: CPU
uv sync --extra lyrics --extra cu128    # 歌詞モード: NVIDIA GPU（CUDA 12.8、Windows / Linux）

cpu と cu128 はどちらか一方を選び、uv run にも同じ extra を指定してください。PyTorch・torchaudio・torchvision の取得先を extra ごとに固定するため、手動で GPU 版を入れ直す必要はありません。両方を同時に指定すること（--all-extras を含む）はできません。

macOS は cpu を使ってください（PyTorch は通常の index から取得します）。cu128 は対応する NVIDIA GPU とドライバーが必要です。--device cpu / cuda は実行時の選択で、インストールする PyTorch の種類は変更しません。--extra lyrics の単独指定は推奨しません。 cpu / cu128 を省くと PyTorch は通常の index から取得され、PyPI の既定では環境によって CPU / CUDA の種類が異なります（上の表を参照）。GPU があっても CPU 版が入る場合があるため、バックエンドを明示してください。

• ffmpeg は imageio-ffmpeg の静的バイナリを使うので、システムへのインストールは不要です。
• 歌詞モードの素材解析は GPU（CUDA）を推奨します。CPU では --device cpu --whisper-model small を指定してください。既定の large-v3 を使う場合、初回は whisperX と音素認識モデル（計約4 GB）をダウンロードします。
• メロディモードだけなら GPU は不要です。素材解析・マッチング・合成・動画はすべて CPU で動きます。
• uv sync を extra 指定なしで実行すると歌詞モードの依存が削除されます。再導入する場合も uv sync --extra lyrics --extra cpu または --extra cu128 を指定してください。uv run は通常、余分なパッケージを削除しませんが、選択した依存定義に合わせてパッケージを置き換えることがあります。

クイックスタート

uv tool install で入れた場合は madgen ...、リポジトリ内では uv run madgen ... で実行します。

# 1. 素材を解析して DB に追加（解析済みのファイルはスキップ）
uv run madgen build-corpus --source sources/ --db work/corpus.sqlite

# 2. MIDI のメロディに合わせて合成（フォルダに mix とパートごとの音声・動画）
uv run madgen render --db work/corpus.sqlite --melody target/target.mid \
    --out-dir work/out --video --split-parts

歌わせる場合（歌詞モード、NVIDIA GPU）:

# 素材の音素解析を追加（音高の解析が済んでいる素材は、音素の解析だけを行う）
uv run --extra lyrics --extra cu128 madgen build-corpus --source sources/ --db work/corpus.sqlite --phonemes wav2vec2

# 歌パート（USTX）＋伴奏（歌トラックを抜いた MIDI）
uv run --extra lyrics --extra cu128 madgen render --db work/corpus.sqlite \
    --ust target/iwashi.ustx --melody target/iwashi.mid \
    --out-dir work/iwashi --video --split-parts

auto は build-corpus と render を続けて実行します（--ust があれば音素解析も行う）。

uv run --extra lyrics --extra cu128 madgen auto --source sources/ --db work/corpus.sqlite \
    --ust target/iwashi.ustx --melody target/iwashi.mid --out-dir work/iwashi --video --split-parts

CPU で素材を解析する場合は、次のように実行します。解析後の render にも --extra lyrics --extra cpu を指定できます。

uv run --extra lyrics --extra cpu madgen build-corpus --source sources/ --db work/corpus.sqlite \
    --phonemes wav2vec2 --device cpu --whisper-model small

出力

--out FILE.wav（--video-out FILE.mp4 で動画も）で1ファイル、--out-dir DIR でフォルダに出力します。

パート、accompaniment、vocals は mix と同じ音量で書き出すので、足し合わせると mix になります。

オプション

render / auto

build-corpus

同じ内容のファイル（ハッシュで判定）は二度解析しません。同じパスで内容が変わったファイルは、古い解析結果を消して解析し直します。

歌詞モードの詳細

UST/USTX と MIDI の用意: --melody の MIDI からは、UST 側で歌わせるトラックを抜いておいてください（MIDI は伴奏として、メロディモードで作られます）。UST/USTX と MIDI は同じ時間軸（0小節目が揃っている）である必要があります。

歌詞の読み方

• 1ノートにつき1モーラ。「さくら」のように複数モーラなら、ノートを等分します。各モーラは子音（先頭60ms、短いノートでは最大40%）と母音に分けてマッチングします。
• R / pau / br / 息 / 空欄は休符（無音）。+ / - / ー は直前の母音を伸ばします（メリスマ）。a か のような連続音表記は後ろのかなを使います。っ は無音です。
• USTX のトラック音量（dB）とミュートは反映します。パン・ピッチカーブ・ビブラートなどの表情は使いません（音高はノートの音程）。

マッチング: 候補は (音素コスト, ピッチ＋長さコスト, 接続コスト) の辞書式順序で比較します。上の段が同点のときだけ、下の段で比べます。

1. 音素コスト: 1位の候補で一致 ＜ 2位で一致 ＜ 3位で一致 ＜ 一致なし（音声学的距離表で代用）。同じ順位の中では、確信度が低いほどコストが増えます（4段階）。
2. ピッチ＋長さコスト: 目標ピッチとの差（しきい値以内は0、それを超えると半音ごとに+1）と、素材がノートより短い割合（1割ごとに+1）の和。子音はピッチを見ません。
3. 接続コスト: 隣のユニットと元の素材で隣接していれば0、そうでなければ1。

同点が起きるように各段を整数に量子化し、上位の桁から音素、ピッチ＋長さ、接続の順に詰めた1つの整数にして、Viterbi で探索します。1位の候補だけで目標音素に一致する素材が K 件（50件）以上あるときは、2位・3位の候補は見ません。

合成: 不自然になっても、UST の音程と長さを忠実に再現することを優先します。母音と「ん」は次のように作ります。

1. 素材の区間から 芯（有声で、区間内の最大音量から12dB以内のフレームが一番長く続く部分）を取り出します。音素アライメントの区間には、母音の後の減衰・息・無音が含まれることが多く、そのまま使うと伸ばしきれないためです。
2. 芯をノートの長さにぴったり合わせます。長ければ切り、短ければ WORLD で伸ばします（頭と末尾の20msはそのまま、中間を伸ばす）。plan.json の stretch_ratio が伸ばした倍率です。
3. 音程は、既定ですべてのフレームをノートの音高にそろえます（--lyrics-pitch-threshold 0 --lyrics-pitch-flatten 1）。芯の中の無声フレームにも音高を付けます。設計書どおり「25セント以内は自然な声のまま」にするには --lyrics-pitch-threshold 25 --lyrics-pitch-flatten 0.6 を指定します。補正するかどうかは、芯の音高で判断します（plan.json の used_f0_hz）。
4. 息っぽい素材でも音程がはっきり聞こえるよう、4 kHz 以下の非周期性（ノイズ成分）を抑えます。また、フレームごとの音量を芯の中央値にそろえて、音量を一定にします。

子音は素材をそのまま使い（ピッチ補正なし）、母音より6dB小さい音量にそろえます。

参考（iwashi のリード、0.15秒以上の母音467個）: ノートの長さに対してしっかり鳴っている割合は平均91%（90%以上鳴っている母音が84%）、音程の誤差は中央値1セント、100%が50セント以内です。

音素解析（build-corpus --phonemes wav2vec2）: whisperX large-v3 で書き起こし → pyopenjtalk で音素に変換 → wav2vec2 の音素認識モデル（facebook/wav2vec2-xlsr-53-espeak-cv-ft）の posteriorgram に強制アライメントして区切ります。各区間の候補は、その区間で事後確率の総量が大きい上位3音素です（確信度は正規化した値）。アライメントの確率が低すぎる発話（音楽やノイズに対する whisper の誤認識が多い）は、まるごと除外します。

動画のレイヤー合成

既定では、パートを重ねて1枚の映像にします（--video-layout fullscreen で以前の全画面切り替えに戻せます）。

--layer Bass=background --layer ust0=lead のように手動で指定できます。1トラックしかない動画（parts/ の各パート）は、並べる相手がいないので常に全画面です。

クロマキー: 何も映っていない部分（パートの休符、縦横比が合わないときの余白、空きの画面）は、黒ではなくキー色で塗ります。他の編集ソフトでそのまま合成素材として使えます。キー色は既定で、素材の映像を16フレーム調べて最も含まれていない色を自動で選びます（--chroma-key で固定も可能）。レイヤー合成も、このキー色を抜いて重ねています。

ただし mix だけは背景を黒にします（完成品にキー色が残ると不自然なため）。vocals / accompaniment / parts/ はキー色のままなので、他のツールでそのまま重ねられます。

同じ素材の同じ位置が続けて選ばれたときは、毎回頭から出し直さず、そのまま再生を続けます（打楽器のように同じ素材が繰り返し選ばれるパートが、止まって見えるのを防ぐため）。

打楽器

MIDI の打楽器トラック（GM のチャンネル10）は、音符番号が音の高さではなく楽器の種類を表します。そのため既定では、楽器ごとに音素の素材を1つ割り当てて、サンプラーのように使います。

• 音の高さは見ません。ピッチ補正もしません。
• 長さは楽器ごとの上限で切ります（クローズハイハットなら80ms、キックなら200ms）。
• 同じ楽器は常に同じ音、別の楽器には別の音が割り当てられます。
• 音素解析済みの素材が必要です（build-corpus --phonemes wav2vec2）。無い場合は自動的に pitched に切り替わります。

割り当ての順番

素材の取り合いは、次の2段階の優先順位で決まります。

1. 楽器の順番 — 先に選んだ楽器がよい素材を取り、後の楽器は「他の楽器が使っている音」のペナルティを負います。そのため順番は曲の登場順ではなく、楽器の重要度で固定しています（キック・スネア → ハイハット・タム・シンバル → クラップ・カウベルなど → シェイカー・タンバリン）。拍を支えるパートの音が悪いほうが目立つためです。これにより、イントロがどの楽器で始まっても、トラックをどう分割しても、同じ素材が選ばれます。
2. 音素の順番 — 上の表は左から順に優先されます。ただし絶対ではなく、長さ・音量・有声/無声の一致と合算した点数で決まるので、先頭の音素によい素材が無ければ次の音素が選ばれます。

実際に何が選ばれたかは、レンダリング時に kit キック: b source.wav 12.30-12.48s のように表示されます。

素材の好みを変えたいときは --drum-material 楽器=音素,... を使います（繰り返し指定可）。楽器は名前か GM のノート番号で指定します。

madgen render --db corpus.sqlite --melody song.mid --out-dir out \
  --drum-material キック=b,g --drum-material 42=ts,s

--percussion で切り替えられます。

フィルタ・EQ

トラックごとに帯域を整理できます。指定しなければ何もしません。

uv run madgen render ... --filter Bass=lp:800 --filter Standard=hp:2000 --filter all=hp:30

--filter Bass=lp:800,hp:40 のようにカンマで繋げられます。トラックの指定は --gain と同じです（トラック名、MIDI の番号、UST は ust0、全トラックは all）。

処理は周波数領域で行うため位相のずれがなく、打楽器の立ち上がりが鈍りません。

音量調節

順に、自動の歌/伴奏バランス（--vocal-boost）→ グループの音量（--ust-gain / --melody-gain）→ トラックごとの音量（--gain）をかけてからミックスし、全体のピークを -1 dBFS にそろえます。音量は鳴っている部分だけで測ります。

# 歌をもっと前に出して、ベースを少し下げ、リードをさらに上げる
uv run madgen render ... --vocal-boost 9 --gain Bass=-3 --gain ust0=+2

無音の扱い

• target の休符: 無音のまま出力します。前の音を休符まで伸ばしません（例外は各音の末尾20msのフェードアウトだけ）。
• source の無音・息・ノイズ: 素材解析の段階で除外し、素材候補にしません。メロディモードでは、無音フレーム（-45 dBFS 未満、または素材の大きい音から35 dB以上小さい）と無声フレーム（f0なし）を除きます。歌詞モードでは、無音の区間と、ほとんど無声の母音・「ん」（息やささやき）を除きます。
• 素材がノートより短い場合: メロディモードでは伸ばさず、残りは無音です（短い素材はマッチングで選ばれにくくなります）。歌詞モードでは母音の芯をノートの長さまで伸ばします（--no-lyrics-stretch で無音に戻せます）。
• 動画: フレームごとに、鳴っているトラックの中で優先度が一番高いものの映像を出します。優先トラックが休んでいる間は、他のトラックの映像を出します。0.5秒未満の休符では直前の映像を表示し続けます。黒画面になるのは、そのファイルに含まれるどのトラックも0.5秒以上鳴っていないときだけです。

進捗ログ

すべてのコマンドが、進捗をファイルに追記します。進み具合に関係なく20秒ごとに、段階・進捗率・経過時間・残り時間の目安を1行書くので、処理が生きているかの確認に使えます。最後の行は finished: ok か finished: failed で、失敗時はエラー内容も残ります。

tail -f work/corpus.sqlite.log   # build-corpus
tail -f work/iwashi/render.log   # render --out-dir work/iwashi

参考の所要時間（RTX 3070 Ti Laptop、4時間44分の素材）:

音素解析を CPU で動かした場合の目安（60秒の素材での実測から換算）:

CPU で使う場合は --whisper-model small を指定してください。素材解析の結果は DB に残るので、重いのは最初の1回だけです。

構成

開発

uv run ruff check   # lint（設定は pyproject.toml）
uv run pytest       # テスト

開発の手順やコミットメッセージの規約は CONTRIBUTING.md を参照してください。

ライセンス

MIT License（© 2026 0266st）

• 配布用の Windows 版 zip には ffmpeg（GPLv3）を同梱しているため、その zip の再配布には GPLv3 の条件がかかります。同梱物の詳細とソースコードの入手先は THIRD_PARTY_LICENSES/ にまとめています。pip / uv で入れる場合は ffmpeg が利用者の環境に入るため、この条件はかかりません。

• ライセンスが対象にするのは、このツールのコードだけです。素材（source の音声・動画）や target の楽曲・歌詞の権利は、それぞれの権利者に帰属します。生成物の公開や配布は、素材の権利を確認したうえで行ってください。

• ffmpeg は、依存パッケージ imageio-ffmpeg に同梱されたバイナリ（GPLv3 でビルドされたもの）を別プロセスとして呼び出しています。このリポジトリには ffmpeg を含みません。

• 歌詞モードで実行時にダウンロードするモデル（whisperX large-v3、facebook/wav2vec2-xlsr-53-espeak-cv-ft）は、それぞれのライセンスに従います。