Voice Quality Analyzer

特定の話者の音源から声質を計測し、可視化する高機能な音声分析ツールです。

🎯 概要

このツールは音声ファイルから様々な音響特徴量を抽出し、話者の声質を科学的に分析・可視化します。研究、音声品質評価、音声学習などの用途に活用できます。

✨ 主な機能

📊 音声特徴量分析

• 基本特徴量: 継続時間、振幅統計、RMSエネルギー
• ピッチ分析: 基本周波数（F0）の平均・範囲・変動・安定性
• スペクトル分析: スペクトル重心・帯域幅・ロールオフ・ゼロ交差率
• フォルマント分析: F1, F2, F3周波数（母音特性）
• MFCC係数: 音色特徴の詳細分析（13次元）
• 品質スコア: ピッチ安定性・音色豊かさ・エネルギー一貫性

📈 可視化機能

• 波形表示: 時間軸での音声波形
• スペクトログラム: 時間-周波数分析
• ピッチ輪郭: 基本周波数の時間変化
• スペクトル特徴: 各種スペクトル特徴量の時系列表示
• MFCC係数: メル周波数ケプストラム係数の可視化
• 特徴量サマリー: 主要指標の統合表示
• インタラクティブダッシュボード: Plotlyによる動的可視化

📄 レポート生成

• HTMLレポート: 美しいデザインの詳細分析レポート
• JSON出力: 機械可読形式での全特徴量データ
• 画像出力: 高解像度の可視化グラフ（PNG形式）

🚀 クイックスタート

方法1: 通常のPython環境

# リポジトリをクローン
git clone <repository-url>
cd voice-quality-analyzer

# セットアップスクリプトを実行
./run.sh

# サンプル音声で試す
python src/main.py

# 実際の音声ファイルを分析
python src/main.py --input input/your_audio.wav --output output/

方法2: Docker環境

# Dockerイメージをビルド
docker-compose build

# サンプル分析を実行
docker-compose run voice-analyzer python src/main.py

# 実際のファイルを分析（inputフォルダに音声ファイルを配置）
docker-compose run voice-analyzer python src/main.py --input input/your_audio.wav --output output/

# 開発モード（インタラクティブシェル）
docker-compose run voice-analyzer-dev

📋 詳細な使用方法

コマンドライン引数

python src/main.py [OPTIONS]

オプション:
  --input, -i PATH     入力音声ファイルのパス（必須）
  --output, -o PATH    出力ディレクトリのパス（デフォルト: output/）
  --format, -f FORMAT  出力形式 [json|html|plots|all]（デフォルト: all）
  --no-plots          可視化グラフの生成をスキップ
  --verbose, -v       詳細な出力を表示
  --help              ヘルプメッセージを表示

使用例

# 基本的な使用方法
python src/main.py --input input/speech.wav --output results/

# JSON形式のみ出力
python src/main.py -i input/voice.mp3 -o output/ --format json

# 可視化なしでHTMLレポートのみ生成
python src/main.py -i input/audio.wav -o output/ --format html --no-plots

# 詳細ログ付きで全形式出力
python src/main.py -i input/sample.wav -o output/ --verbose

🎵 対応音声形式

• WAV: 非圧縮音声（推奨）
• MP3: MPEG Audio Layer III
• M4A: MPEG-4 Audio
• FLAC: Free Lossless Audio Codec
• OGG: Ogg Vorbis
• その他librosaが対応する形式

📁 プロジェクト構造

voice-quality-analyzer/
├── src/                          # ソースコード
│   ├── __init__.py              # パッケージ初期化
│   ├── main.py                  # メインスクリプト
│   ├── voice_analyzer.py        # 音声分析エンジン
│   ├── visualizer.py            # 可視化エンジン
│   └── report_generator.py      # レポート生成エンジン
├── input/                       # 入力音声ファイル
├── output/                      # 分析結果出力
├── requirements.txt             # Python依存関係
├── run.sh                       # セットアップ・実行スクリプト
├── Dockerfile                   # Dockerイメージ定義
├── docker-compose.yml           # Docker Compose設定
└── README.md                    # このファイル

📊 出力ファイル詳細

HTMLレポート (*_report.html)

• 美しいデザインの包括的な分析レポート
• 主要指標のサマリーカード
• 品質スコアの可視化
• 特徴量の詳細テーブル
• 分析結果の解釈

可視化グラフ (*_plots/)

• waveform.png: 音声波形
• spectrogram.png: スペクトログラム
• pitch_contour.png: ピッチ輪郭
• spectral_features.png: スペクトル特徴量
• mfcc.png: MFCC係数
• feature_summary.png: 特徴量サマリー
• interactive_dashboard.html: インタラクティブダッシュボード

データファイル

• *_features.json: 全特徴量の詳細データ
• *_summary.json: 主要指標とメタデータ

🛠 開発環境セットアップ

必要な環境

• Python 3.9以上
• pip（パッケージ管理）
• 仮想環境（推奨）

手動セットアップ

# 仮想環境の作成
python3 -m venv venv

# 仮想環境のアクティベート
source venv/bin/activate  # Linux/Mac
# または
venv\Scripts\activate     # Windows

# 依存関係のインストール
pip install --upgrade pip
pip install -r requirements.txt

Docker開発環境

# 開発用コンテナを起動
docker-compose run voice-analyzer-dev

# コンテナ内でのコード編集・テスト
root@container:/app# python src/main.py --help
root@container:/app# python src/main.py --input input/sample.wav

🔧 技術仕様

主要ライブラリ

• librosa: 音声信号処理・特徴量抽出
• matplotlib: 静的グラフ生成
• plotly: インタラクティブ可視化
• seaborn: 統計的可視化
• numpy: 数値計算
• scipy: 科学計算
• pandas: データ処理・分析
• soundfile: 音声ファイル入出力

分析アルゴリズム

• ピッチ抽出: librosa.piptrack（調波・打楽器分離）
• スペクトル分析: 短時間フーリエ変換（STFT）
• フォルマント推定: FFTピーク検出
• MFCC: メル尺度フィルタバンク

🎯 使用例・応用

音声品質評価

# 録音品質の評価
python src/main.py -i recording.wav -o quality_check/

話者特性分析

# 複数話者の比較分析
python src/main.py -i speaker1.wav -o speaker1_analysis/
python src/main.py -i speaker2.wav -o speaker2_analysis/

音声学習・研究

# 詳細な音響分析
python src/main.py -i research_sample.wav -o research_results/ --verbose

🐛 トラブルシューティング

よくある問題

1. フォントの警告が表示される

   • 日本語フォントが見つからない場合の警告です
   • 機能には影響しませんが、日本語フォントをインストールすると解決します

2. 音声ファイルが読み込めない

   • ファイル形式を確認してください
   • ファイルパスに日本語が含まれていないか確認してください

3. メモリ不足エラー

   • 長時間の音声ファイルの場合、メモリ使用量が多くなります
   • ファイルを短く分割するか、より多くのメモリを割り当ててください

Docker関連の問題

# コンテナの再ビルド
docker-compose build --no-cache

# ボリュームの確認
docker-compose down -v
docker-compose up

📈 パフォーマンス

• 処理速度: 1分の音声につき約10-30秒（環境依存）
• メモリ使用量: 音声長に比例（目安: 1分あたり100-200MB）
• 出力サイズ: HTMLレポート約500KB、画像ファイル合計約2-5MB

🤝 貢献・カスタマイズ

新しい特徴量の追加

src/voice_analyzer.pyのVoiceQualityAnalyzerクラスに新しいメソッドを追加

可視化のカスタマイズ

src/visualizer.pyのVoiceVisualizerクラスで新しいプロット関数を作成

レポートのカスタマイズ

src/report_generator.pyでHTMLテンプレートやスタイルを変更

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。

🙏 謝辞

• librosa: 音声分析ライブラリ
• matplotlib: 可視化ライブラリ
• plotly: インタラクティブ可視化