ludi-uni/FilteringCV

stars

commits

Python

primary language

Jul 30, 2026

updated

README

FilteringCV / cv-preprocess

Common Voice から TTS 学習用コーパスを作るツールです。ライセンスは Apache License 2.0。

対話操作は GUI が前提です。CLI は CI・自動化・上級者向けです。

すぐ始める（GUI）

# Windows: Dev Container 推奨（作成時に依存が入る）
# Linux / コンテナ内:
uv sync --extra sidon --extra gui --extra dev
./scripts/start-gui.sh

ブラウザで http://127.0.0.1:8765 を開きます。

手順	画面	やること
1	Setup	YAML を選ぶか、`config/example.yaml` から作成（既定: `config/default.yaml`）
2	Config	`input.corpus_root` や話者フィルタなどを編集して保存
3	Jobs	Build（推奨）を開始（scan→…→audit を一括実行）
4	Clips / Coverage	結果の確認・override・カバレッジ確認

詳細手順は docs/gui.md。環境・GPU・extra は docs/開発環境.md。

GUI の画面

画面	役割
Setup	設定 YAML の選択・新規作成（未バインド時）
Dashboard	パス・最近のジョブ・run manifest
Jobs	ビルダー段階の実行・進捗・キャンセル（下表の順番）
Config	YAML の Form / テキスト編集と検証・保存
Coverage	特徴量カバレッジ
Clips	カタログ閲覧・再生・override
Compare	2 つの `work/` または出力ディレクトリの比較

設定の切替はサイドバーの Switch config（実行中ジョブがあると不可）。

Jobs の順番（ビルダー）

YAML で dataset_builder.enabled: true のとき、Jobs では次の順で進みます。初めては Build だけで十分です。

#	Job	何をするか	主な出力
1	`scan`	コーパス / TSV の件数・パスを確認	概要（ジョブ結果）
2	`analyze`	解析・品質ゲート・音声キャッシュ・カタログ作成（重い）	`work/catalog/`、`audio_cache`
3	`plan-split`	train / val / test の分割計画（意味はプロトコル依存・下表）	`work/plans/split_plan.json`
4	`select`	coverage 目標を予約したうえでクリップ選択（既定オン）	`work/plans/selection_plan.parquet`、`work/reports/selection/`
5	`materialize`	WAV・メタデータ等を出力。既定で piper_plus / Style-Bert-VITS2 用 `exports/` も生成	最終コーパス + `exports/`
6	`audit`	選択・分割・出力の整合性チェック	監査結果
★	`build`（推奨）	scan→（coverage）→analyze→…→audit（途中成果物があれば再開）	上記すべて + `run_manifest.json`

coverage.enabled: true のとき、Build は analyze の前に希少音素カバレッジ（軽量 index + 有望候補のみ品質解析）を差し込みます。

select は常に coverage-aware です（selection.coverage_constraints.enabled: true が既定）。Force Build で解析した希少特徴を、最終セットでも落とさないようにします。使い方は下の「coverage-aware select」と docs/coverage-automation.md。

個別ステージは「analyze だけやり直す」「select だけ再実行」など向けです。Force は既存成果物があっても再実行します。

`plan-split` と `select` の関係（よくある疑問）

Jobs 上の順番は常に plan-split → select ですが、中身の「どちらが先か」は dataset_builder.split.protocol で変わります。

プロトコル	実質の流れ	なぜ
`unseen_speaker`（既定でよく使う）	先に話者を train/val/test に割当 → 各バケット内で select	同一話者が train と val/test に出ないようにするため。全体を先に select すると、あとで話者を分けたときにカバレッジが崩れる
`seen_speaker` / `single_speaker`	先に全体で select → 選ばれたクリップに split を付与	話者またぎを許す（または単話者）ので、クリップ割当は選択後でよい

「select してから split した方がいいのでは？」は後者ではその感覚どおりです。話者を分けたい unseen_speaker では、今の順（話者計画 → バケット内選択）が意図どおりです。設定の split.protocol を確認してください。詳細は docs/dataset-builder.md。

アルゴリズム・列定義は docs/dataset-builder.md、docs/selection-algorithm.md、docs/catalog-schema.md。

設定で最初に触る場所

Setup で作った YAML（または config/example.yaml）を Config 画面かエディタで編集します。

input.corpus_root … Common Voice の言語ルート（例: …/ja）
speakers.include_client_ids … 空なら全話者。絞るなら client_id を列挙
dataset_builder.enabled: true … ビルダー（GUI Jobs）を使う場合は true
coverage.features.*.targets … 希少音素などの目標件数（select が最終セットで保証）
音声チェーン / 品質ゲート … docs/仕様.md

coverage-aware select（使い方）

Config で coverage.features に目標を書く（例: phoneme.targets.v: 5）。数値だけなら minimum = desired = その値。
（推奨）coverage.enabled: true のまま Build → Force Build が希少特徴クリップを先に解析して eligible に入れる。
続く select（Build 内でも単独でも）が目標を先に予約し、残り時間を通常選択で埋める。
結果確認: work/reports/selection/coverage-audit.csv（達成 / コーパス上限 / 制約衝突など）。不足特徴は missing-features.json。

無効化したいときだけ:

selection:
  coverage_constraints:
    enabled: false
  acoustic_diversity:
    enabled: false

CLI 例:

cv-preprocess select -c config/default.yaml
# 監査出力先を変えるとき:
cv-preprocess select -c config/default.yaml --coverage-audit-output work/reports/selection
# 音響多様性だけ切る:
cv-preprocess select -c config/default.yaml --disable-acoustic-diversity

config/default.yaml と config/*.local.yaml は gitignore 対象です。

`validated.tsv` と話者 ID

TSV はクォート付きフィールドで 物理行 ≠ 論理レコード になり得ます。話者 ID はスプレッドシートや wc -l ではなく、本ツールの scan（Jobs） やパーサ結果を基準にしてください。

ドキュメント

文書	内容
docs/gui.md	GUI 起動・Setup・画面
docs/開発環境.md	Dev Container / `uv` / GPU / optional extra
docs/仕様.md	パイプライン・ゲート・設定キーの正
docs/dataset-builder.md	ビルダー段階・CLI 参照
docs/architecture.md	Core API 構成
docs/追加仕様.md	二次パイプライン・HiFi-GAN など
docs/音素照合マニフェスト.md	音素マニフェスト
docs/coverage-automation.md	希少音素カバレッジ自動確保
docs/migration-v1-v2.md	レガシー `preprocess` からの移行

オプション機能（必要なときだけ）

セットアップやゲートの詳細は docs/開発環境.md / docs/仕様.md へ。

機能	概要
Sidon（既定例）	enhance 用。`uv sync --extra sidon`
Dasheng / SGMSE / WPE+DFN / HiFi-GAN	設定に応じて対応 extra を追加
NFA（Dev Container）	`nfa_gate`。コンテナに別 venv あり。`mfa_gate` と同時 true 不可
MFA（ホスト）	Dev Container 非同梱。conda 等で `mfa` を用意
レガシー preprocess / secondary	`dataset_builder.enabled: false` 時の逐次前処理など。CLI 向け

CLI（自動化・上級者向け）

エントリ: cv-preprocess（python -m cv_preprocess）。ヘルプは cv-preprocess --help。

GUI と同じ Core API を呼びます。Jobs と同じビルダー段階:

scan → analyze → plan-split → select → materialize → audit
# 一括:
cv-preprocess build -c config/default.yaml

その他（レガシー・ユーティリティ）: preprocess, secondary, phoneme-manifest, suggest-mfa-g2p-map, suggest-nfa-g2p-map, dataset-partition, compare-runs, benchmark-selection, text-normalize, phonemize など。詳細は各 --help と上表のドキュメント。

希少音素カバレッジ自動化

目標件数に届かない音素・モーラ等を、全件重解析せずに補う機能です。

cv-preprocess coverage-index -c config/default.yaml -o output/coverage/clip-index.jsonl
cv-preprocess coverage-plan  -c config/default.yaml --index output/coverage/clip-index.jsonl -o output/coverage/plan.json
cv-preprocess coverage-run   -c config/default.yaml --index output/coverage/clip-index.jsonl -o output/coverage/run-001 --dry-run

詳細は docs/coverage-automation.md。

計算バックエンド

compute.backend: auto（既定）で Polars、不可時は Python にフォールバック。run_manifest.json にステージ時間などが記録されます。

Contributors

ludi-uni

41 commits

Similar repos

MatiasDiBernardo/Lowcost-ITW-curation

Low-cost, CPU-friendly preprocessing pipeline and metric toolkit to curate and evaluate in-the-wild…

rioharper/VocalForge

Your one-stop solution for voice dataset creation

130

N01N9/VoxUnravel

Etherll/Timbre

Extract a target speaker’s clean, non-overlapped speech from multi-speaker audio and export…

nineninesix-ai/kanitts-2-dataset-pipeline

saeedzou/speech-dataset-factory

A configurable pipeline for creating speech datasets (ASR, TTS, VC)

HoangTuyen-1005/build-cs-dataset

NVIDIA/NeMo-speech-data-processor

A toolkit for processing speech data and creating speech datasets

219

Languages

Python

89.8%

TypeScript

8.7%

CSS

1.1%

ludi-uni/FilteringCV

stars

commits

Python

primary language

Jul 30, 2026

updated

README

FilteringCV / cv-preprocess

Common Voice から TTS 学習用コーパスを作るツールです。ライセンスは Apache License 2.0。

対話操作は GUI が前提です。CLI は CI・自動化・上級者向けです。

すぐ始める（GUI）

# Windows: Dev Container 推奨（作成時に依存が入る）
# Linux / コンテナ内:
uv sync --extra sidon --extra gui --extra dev
./scripts/start-gui.sh

ブラウザで http://127.0.0.1:8765 を開きます。

手順	画面	やること
1	Setup	YAML を選ぶか、`config/example.yaml` から作成（既定: `config/default.yaml`）
2	Config	`input.corpus_root` や話者フィルタなどを編集して保存
3	Jobs	Build（推奨）を開始（scan→…→audit を一括実行）
4	Clips / Coverage	結果の確認・override・カバレッジ確認

詳細手順は docs/gui.md。環境・GPU・extra は docs/開発環境.md。

GUI の画面

画面	役割
Setup	設定 YAML の選択・新規作成（未バインド時）
Dashboard	パス・最近のジョブ・run manifest
Jobs	ビルダー段階の実行・進捗・キャンセル（下表の順番）
Config	YAML の Form / テキスト編集と検証・保存
Coverage	特徴量カバレッジ
Clips	カタログ閲覧・再生・override
Compare	2 つの `work/` または出力ディレクトリの比較

設定の切替はサイドバーの Switch config（実行中ジョブがあると不可）。

Jobs の順番（ビルダー）

YAML で dataset_builder.enabled: true のとき、Jobs では次の順で進みます。初めては Build だけで十分です。

#	Job	何をするか	主な出力
1	`scan`	コーパス / TSV の件数・パスを確認	概要（ジョブ結果）
2	`analyze`	解析・品質ゲート・音声キャッシュ・カタログ作成（重い）	`work/catalog/`、`audio_cache`
3	`plan-split`	train / val / test の分割計画（意味はプロトコル依存・下表）	`work/plans/split_plan.json`
4	`select`	coverage 目標を予約したうえでクリップ選択（既定オン）	`work/plans/selection_plan.parquet`、`work/reports/selection/`
5	`materialize`	WAV・メタデータ等を出力。既定で piper_plus / Style-Bert-VITS2 用 `exports/` も生成	最終コーパス + `exports/`
6	`audit`	選択・分割・出力の整合性チェック	監査結果
★	`build`（推奨）	scan→（coverage）→analyze→…→audit（途中成果物があれば再開）	上記すべて + `run_manifest.json`

coverage.enabled: true のとき、Build は analyze の前に希少音素カバレッジ（軽量 index + 有望候補のみ品質解析）を差し込みます。

個別ステージは「analyze だけやり直す」「select だけ再実行」など向けです。Force は既存成果物があっても再実行します。

`plan-split` と `select` の関係（よくある疑問）

Jobs 上の順番は常に plan-split → select ですが、中身の「どちらが先か」は dataset_builder.split.protocol で変わります。

プロトコル	実質の流れ	なぜ
`unseen_speaker`（既定でよく使う）	先に話者を train/val/test に割当 → 各バケット内で select	同一話者が train と val/test に出ないようにするため。全体を先に select すると、あとで話者を分けたときにカバレッジが崩れる
`seen_speaker` / `single_speaker`	先に全体で select → 選ばれたクリップに split を付与	話者またぎを許す（または単話者）ので、クリップ割当は選択後でよい

アルゴリズム・列定義は docs/dataset-builder.md、docs/selection-algorithm.md、docs/catalog-schema.md。

設定で最初に触る場所

Setup で作った YAML（または config/example.yaml）を Config 画面かエディタで編集します。

input.corpus_root … Common Voice の言語ルート（例: …/ja）
speakers.include_client_ids … 空なら全話者。絞るなら client_id を列挙
dataset_builder.enabled: true … ビルダー（GUI Jobs）を使う場合は true
coverage.features.*.targets … 希少音素などの目標件数（select が最終セットで保証）
音声チェーン / 品質ゲート … docs/仕様.md

coverage-aware select（使い方）

Config で coverage.features に目標を書く（例: phoneme.targets.v: 5）。数値だけなら minimum = desired = その値。
（推奨）coverage.enabled: true のまま Build → Force Build が希少特徴クリップを先に解析して eligible に入れる。
続く select（Build 内でも単独でも）が目標を先に予約し、残り時間を通常選択で埋める。
結果確認: work/reports/selection/coverage-audit.csv（達成 / コーパス上限 / 制約衝突など）。不足特徴は missing-features.json。

無効化したいときだけ:

selection:
  coverage_constraints:
    enabled: false
  acoustic_diversity:
    enabled: false

CLI 例:

cv-preprocess select -c config/default.yaml
# 監査出力先を変えるとき:
cv-preprocess select -c config/default.yaml --coverage-audit-output work/reports/selection
# 音響多様性だけ切る:
cv-preprocess select -c config/default.yaml --disable-acoustic-diversity

config/default.yaml と config/*.local.yaml は gitignore 対象です。

`validated.tsv` と話者 ID

ドキュメント

文書	内容
docs/gui.md	GUI 起動・Setup・画面
docs/開発環境.md	Dev Container / `uv` / GPU / optional extra
docs/仕様.md	パイプライン・ゲート・設定キーの正
docs/dataset-builder.md	ビルダー段階・CLI 参照
docs/architecture.md	Core API 構成
docs/追加仕様.md	二次パイプライン・HiFi-GAN など
docs/音素照合マニフェスト.md	音素マニフェスト
docs/coverage-automation.md	希少音素カバレッジ自動確保
docs/migration-v1-v2.md	レガシー `preprocess` からの移行

オプション機能（必要なときだけ）

セットアップやゲートの詳細は docs/開発環境.md / docs/仕様.md へ。

機能	概要
Sidon（既定例）	enhance 用。`uv sync --extra sidon`
Dasheng / SGMSE / WPE+DFN / HiFi-GAN	設定に応じて対応 extra を追加
NFA（Dev Container）	`nfa_gate`。コンテナに別 venv あり。`mfa_gate` と同時 true 不可
MFA（ホスト）	Dev Container 非同梱。conda 等で `mfa` を用意
レガシー preprocess / secondary	`dataset_builder.enabled: false` 時の逐次前処理など。CLI 向け

CLI（自動化・上級者向け）

エントリ: cv-preprocess（python -m cv_preprocess）。ヘルプは cv-preprocess --help。

GUI と同じ Core API を呼びます。Jobs と同じビルダー段階:

scan → analyze → plan-split → select → materialize → audit
# 一括:
cv-preprocess build -c config/default.yaml

希少音素カバレッジ自動化

目標件数に届かない音素・モーラ等を、全件重解析せずに補う機能です。

cv-preprocess coverage-index -c config/default.yaml -o output/coverage/clip-index.jsonl
cv-preprocess coverage-plan  -c config/default.yaml --index output/coverage/clip-index.jsonl -o output/coverage/plan.json
cv-preprocess coverage-run   -c config/default.yaml --index output/coverage/clip-index.jsonl -o output/coverage/run-001 --dry-run

詳細は docs/coverage-automation.md。

計算バックエンド

compute.backend: auto（既定）で Polars、不可時は Python にフォールバック。run_manifest.json にステージ時間などが記録されます。

Similar repos

MatiasDiBernardo/Lowcost-ITW-curation

Low-cost, CPU-friendly preprocessing pipeline and metric toolkit to curate and evaluate in-the-wild…

rioharper/VocalForge

Your one-stop solution for voice dataset creation

130

N01N9/VoxUnravel

Etherll/Timbre

Extract a target speaker’s clean, non-overlapped speech from multi-speaker audio and export…

nineninesix-ai/kanitts-2-dataset-pipeline

saeedzou/speech-dataset-factory

A configurable pipeline for creating speech datasets (ASR, TTS, VC)

HoangTuyen-1005/build-cs-dataset

NVIDIA/NeMo-speech-data-processor

A toolkit for processing speech data and creating speech datasets

219

Contributors

ludi-uni

41 commits

Languages

Python

89.8%

TypeScript

8.7%

CSS

1.1%

ludi-uni/FilteringCV

README

FilteringCV / cv-preprocess

すぐ始める（GUI）

GUI の画面

Jobs の順番（ビルダー）

plan-split と select の関係（よくある疑問）

設定で最初に触る場所

coverage-aware select（使い方）

validated.tsv と話者 ID

ドキュメント

オプション機能（必要なときだけ）

CLI（自動化・上級者向け）

希少音素カバレッジ自動化

計算バックエンド

Contributors

Similar repos

Languages

ludi-uni/FilteringCV

README

FilteringCV / cv-preprocess

すぐ始める（GUI）

GUI の画面

Jobs の順番（ビルダー）

plan-split と select の関係（よくある疑問）

設定で最初に触る場所

coverage-aware select（使い方）

validated.tsv と話者 ID

ドキュメント

オプション機能（必要なときだけ）

CLI（自動化・上級者向け）

希少音素カバレッジ自動化

計算バックエンド

Similar repos

Contributors

Languages

`plan-split` と `select` の関係（よくある疑問）

`validated.tsv` と話者 ID

`plan-split` と `select` の関係（よくある疑問）

`validated.tsv` と話者 ID