feat: 感情条件付き TTS (Style Vector + PE-A Emotion Loss) — 実装完了 / 実 GPU 学習は未実施

[ayutaz]

このPRで何ができるようになるか

piper-plus に 「声の感情を切り替える」機構 を追加する。
学習時に音声から抽出した emotion embedding (style_vector) をモデルに食わせ、推論時には任意の感情ベクトルを与えて「悲しい声」「怒った声」などを生成できる。

• 既存モデルは 何もしなくても今まで通り動く (--style-vector-dim 0 がデフォルトのため bit-for-bit 互換)
• 6 ランタイム (Python / Rust / C++ / C# / Go / WASM) すべてで style_vector 入力に対応
• emotion embedding は Meta facebook/pe-av-small (Apache-2.0) を loss として使用 (推論グラフには載らない、商用利用可)

取り込み元: fork yusuke-ai/piper-plus@314b3355 の先行実装を本家 dev に統合したもの。

使い方

1) 学習: スタイル次元を有効にする

uv run python -m piper_train \
  --dataset-dir <DATASET> \
  --style-vector-dim 256 \
  --style-condition-mode global \
  --style-condition-dropout 0.1 \
  ...

CLI オプション	用途	デフォルト
--style-vector-dim N	スタイルベクトル次元 (0 で完全無効化 = 後方互換)	0
--style-condition-mode	注入箇所 (global = 大域条件 g に加算 / text = TextEncoder のみ)	global
--style-condition-dropout	学習時に style を確率的に zero-mask	0.0
--load_weights_from_checkpoint <PATH>	shape 不一致を WARN で skip しつつ既存 ckpt から partial load	-

PE-A loss を有効にする場合 (要 uv sync --extra pea):

... --pea-emotion-style-bank style_bank.npz \
    --pea-emotion-loss-weight 0.5 \
    --pea-emotion-centroid-weight 0.3 \
    --pea-emotion-margin-weight 0.2 \
    --pea-emotion-warmup-steps 2000

2) 推論: 任意の感情ベクトルを与える

Python:

uv run python -m piper_train.infer_onnx \
  --model emotion.onnx --config emotion.json \
  --text "Hello, world." \
  --style-vector path/to/angry.npy   # .npy / .pt / .pth

Rust / C# / Go / C++ CLI: 各ランタイムで同名の --style-vector PATH フラグ。
WASM/JS: piperPlus.synthesize(text, { styleVector: Float32Array })
HTTP (FastAPI): X-Style-Vector-B64 ヘッダー or ?style_vector_b64= クエリ (base64-encoded float32 LE)

3) Style Bank (感情 centroid) の作り方

CREMA-D など感情ラベル付き音声を集めて、emotion ごとの中心ベクトル (.npz) を生成:

uv run python -m piper_train.tools.build_pea_style_bank \
  --audio-dir crema_d/audio \
  --metadata crema_d/metadata.csv \
  --output style_bank.npz

このファイルを学習時に --pea-emotion-style-bank に渡すと、generator が PE-A 空間でこの centroid に近づくよう loss が掛かる。

互換性 / 後方互換

• --style-vector-dim 0 (デフォルト) のとき、ONNX 入出力・モデルサイズ・推論速度は bit-for-bit 互換。既存 voice モデルは再学習不要。
• ONNX に追加した style_vector 入力は mask パターン (style_vector + style_vector_mask の 2 入力)。古いモデル (input なし) と新しいモデル (input あり、mask=0 でゼロ填) を同一ランタイムで扱える。
• C ABI (PiperPlusSynthOptions) は _reserved[5] → _reserved[3] + style_vector 2 フィールド追加で sizeof 維持 → Dart FFI / Godot GDExtension の既存ビルドは無修正で動く。
• 6 ランタイム横断の I/O 契約は docs/spec/style-vector-contract.toml に固定。

設計判断 (なぜこうしたか)

トピック	採択	却下した代替案
Emotion embedding ソース	PE-AV (Meta, Apache-2.0)	wav2vec2-emotion (GPL/non-commercial 混在) / ESD 自前学習 (regression リスク)
注入箇所	VITS 大域条件 g (decoder + flow + DP に伝播)	TextEncoder のみ (イントネーションに乗らない) / 全層 projection (学習負荷)
デフォルト挙動	--style-vector-dim 0 で完全無効	有効化を default にすると既存 ckpt が動かない
ONNX Optional 入力	mask パターン (2 入力)	None 入力 (古い ORT 非対応) / 別モデル分岐 (ファイル数 2 倍)
Optional dep の扱い	pyproject.toml の [pea] extra	デフォルト依存にすると torchcodec / decord / opencv-python など transitive で CI 肥大

ローカル動作確認 (このPRで PASS したもの)

• ✅ ruff check / ruff format / cargo fmt / cargo clippy -D warnings 全 PASS
• ✅ Python テスト 139 PASS (新規) + 875+ リグレッション影響なし
  • style_vector 学習側統合: 11
  • load_weights_from_checkpoint: 3
  • PE-A emotion loss: 20
  • 6 ランタイム契約: 24 + 6 (WASM)
  • style bank 関連ツール: 58
  • emotion fine-tune ツール: 20
• ✅ Rust release ビルド (83 MB binary) / C# dotnet build PiperPlus.sln 0 errors / WASM node --test 6 PASS
• ✅ shell script syntax: scripts/run_crema_d_finetune.sh / scripts/export_and_verify_emotion_runtimes.sh

残タスク (このPRに含まれない、別セッションで実施)

#	作業	所要	必要環境
1	PE-A 実機ロード確認 (uv sync --extra pea → PoC スクリプト)	~1h	CPU 可
2	6lang ベース → CREMA-D fine-tune	~2 日	GPU x1
3	SER (≥65%) + MOS (PESQ ≥2.8 / STOI ≥0.85) + 多言語 regression 評価	~半日	学習済み ckpt
4	Go / C++ ランタイム実機ビルドで MD5 一致確認	~半日	Linux / 別環境

再開コマンド:

bash scripts/run_crema_d_finetune.sh stage5a   # style bank 構築 (~30 min)
bash scripts/run_crema_d_finetune.sh stage5b   # fine-tune 実行 (~2 日)
bash scripts/export_and_verify_emotion_runtimes.sh   # ONNX export + 6 ランタイム MD5
uv run python tools/benchmark/evaluate_emotion_finetune.py --checkpoint <path>

主要な追加ファイル

領域	ファイル
学習側統合	src/python/piper_train/vits/{models,dataset,lightning,commons}.py, __main__.py, infer.py
PE-A loader	src/python/piper_train/perception/pea_loader.py
ONNX export	src/python/piper_train/export_onnx.py (mask パターン + metadata_props)
Python 推論	src/python_run/piper/{voice.py,infer_onnx.py,http_server.py}
Rust 推論	src/rust/piper-core/src/engine.rs, src/rust/piper-cli/src/main.rs
C++ 推論	src/cpp/piper.{cpp,hpp}, piper_plus_c_api.cpp, main.cpp
C# 推論	src/csharp/PiperPlus.Core/Inference/, PiperPlus.Cli/Program.cs
Go 推論	src/go/piperplus/{engine,options}.go, numpy.go, cmd/piper-plus/main.go
WASM/JS	src/wasm/openjtalk-web/src/index.js, types/index.d.ts
Style bank ツール	src/python/piper_train/tools/{build_pea_style_bank,inject_style_labels,validate_style_bank}.py
評価ツール	tools/benchmark/evaluate_emotion_finetune.py
学習 driver	scripts/run_crema_d_finetune.sh, scripts/export_and_verify_emotion_runtimes.sh
仕様書	docs/spec/style-vector-contract.toml (6 ランタイム I/O 契約)
機能ガイド	docs/features/style-bank.md

依存追加 (optional, デフォルトでは入らない)

uv sync --extra pea
# perception-models @ git+https://github.com/facebookresearch/perception_models.git

ライセンス: LICENSE.PE = Apache-2.0 (商用可、MIT 互換)。

関連リンク

• 仕様書 (6 ランタイム I/O 契約): docs/spec/style-vector-contract.toml
• 機能ガイド: docs/features/style-bank.md, CLAUDE.md の Style Vector Conditioning セクション
• Fork (取り込み元): yusuke-ai@314b3355
• PE-A モデル: https://huggingface.co/facebook/pe-av-small

[ayutaz]

現状メモ (2026-05-14)

• 実装完了・研究段階
• 実 GPU での学習・検証が未実施のため Draft 継続
• 学習実験完了後に評価結果をもとに merge 判断

[ayutaz]

トリアージ (2026-05-14)

CI: 89/89 checks passing ✅
MergeState: DIRTY (コンフリクトあり)
Branch: docs/peav-style-conditioning-research

現状

感情条件付き TTS (Style Vector + PE-A Emotion Loss) の実装コードは完成しています。ただし以下のブロッカーがあります:

1. 実 GPU 学習未実施 — --style-vector-dim N で学習したモデルが存在しない
2. ブランチ名 が docs/peav-style-conditioning-research (研究調査段階を示す)
3. dev へのリベースが必要

対応方針

GPU リソースと感情ラベル付きデータセットが確保できた段階でブランチを feat/emotion-tts にリネーム・リベースして研究実験を再開予定。当面は Draft のまま保留。

[github-actions]

この PR は 90 日間 activity がないため stale label を付与しました。
7 日以内に進展がなければ自動 close されます。 rebase / push / コメント
のいずれかで stale clear。