DittoTalkingHead プロジェクト

プロジェクト概要

このリポジトリは、音声から自然なトーキングヘッド動画を生成するDittoモデルの実装と、そのAPI化を行うプロジェクトです。単一の画像と音声ファイルから、音声に同期した自然な表情や口の動きを持つ動画を生成します。

作業フロー

本プロジェクトは、Statement of Work (SOW) ドキュメントを作成してから実装を行う段階的なアプローチを採用しています。

フェーズ構成

Phase 1: 基本実装 - Hugging Face Spacesへのデプロイ
Phase 2: API実装 - REST API化とクライアント実装
Phase 3: パフォーマンス最適化 - 処理速度の大幅改善

ディレクトリ構造

`/` ルートディレクトリ

README.md - Hugging Face Spaces用のメタデータ付きREADME
README_jp.md - 日本語プロジェクト説明（このファイル）
README_ditto-talkinghead.md - Dittoモデルの技術詳細
README_hf_space.md - Hugging Face Spacesデプロイメント説明
app.py - Gradio Webアプリケーションのメインファイル
inference.py - モデル推論の実装
model_manager.py - モデルファイルの管理・ダウンロード
test_api.py - API機能のテストスクリプト
test_api_client.py - APIクライアントの実装
test_performance.py - パフォーマンステストツール
requirements.txt - Python依存関係
environment.yaml - Conda環境設定
packages.txt - システムパッケージ依存関係

`/ToDo` 計画ドキュメント

plan-v0.md - 初期調査報告と実装計画
0717-1_Phase1_SOW_revised.md - Phase 1 実装仕様書（基本実装）
0717-2_Phase2_API_SOW.md - Phase 2 実装仕様書（API化）
0717-3_Phase3_Performance_SOW.md - Phase 3 実装仕様書（高速化）

`/core` コアモデル実装

/atomic_components - モデルの基本コンポーネント
- audio2motion.py - 音声から動きへの変換
- avatar_registrar.py - アバター登録処理
- wav2feat.py - 音声特徴抽出
- warp_f3d.py - 3D特徴のワーピング
- 他多数の処理モジュール
/aux_models - 補助モデル（顔検出、ランドマーク検出等）
- face_mesh.py - 顔メッシュ検出
- hubert_stream.py - HuBERT音声モデル
- mediapipe_landmark478.py - MediaPipeランドマーク
/models - メインモデル実装
- appearance_extractor.py - 外観特徴抽出
- decoder.py - デコーダー
- lmdm.py - ランドマーク拡散モデル
- /modules - モデルモジュール群
/utils - ユーティリティ関数
- crop.py - 画像クロップ処理
- load_model.py - モデルロード
- tensorrt_utils.py - TensorRT最適化

`/docs` ドキュメント

APIドキュメント.md - API仕様書（日本語）
api_documentation.md - API仕様書（英語）
deployment_guide.md - デプロイメントガイド
model_upload_guide.md - モデルアップロードガイド

`/example` サンプルファイル

audio.wav - サンプル音声
image.png - サンプル画像
2025-07-17_22-12-46.mp4 - 生成サンプル動画

`/scripts` ユーティリティスクリプト

cvt_onnx_to_trt.py - ONNXからTensorRTへの変換

`/stream_pipeline_*` リアルタイム処理

stream_pipeline_online.py - オンラインストリーミング処理
stream_pipeline_offline.py - オフライン処理

主要な機能

1. 基本的な動画生成

音声ファイル（WAV）とソース画像（PNG/JPG）から動画生成
自然な口の動きと表情の同期
高品質な動画出力

2. API機能

REST APIエンドポイント（/process_talking_head）
画像の事前アップロード機能（/prepare_avatar）
非同期処理とキャッシュサポート

3. パフォーマンス最適化（Phase 3実装済み）

✅ 解像度320×320固定による高速化（実装済み）
✅ 画像埋め込みの事前計算とキャッシュ（実装済み）
✅ GPU最適化とMixed Precision（実装済み）
✅ Cold Start最適化（実装済み）
🔄 TensorRT/ONNX最適化（今後実装予定）
達成: 元の処理時間から約50-65%削減

使用方法

Web UI経由

Hugging Face Spaces（https://huggingface.co/spaces/O-ken5481/talkingAvater_bgk）にアクセス
音声ファイルと画像をアップロード
「生成」ボタンをクリック

API経由

Gradio Client

from gradio_client import Client, handle_file

client = Client("O-ken5481/talkingAvater_bgk")
result = client.predict(
    audio_file=handle_file("path/to/audio.wav"),
    source_image=handle_file("path/to/image.png"),
    api_name="/process_talking_head"
)

FastAPI (Phase 3最適化版)

import requests

# 1. アバターを事前準備（高速化）
with open("avatar.png", "rb") as f:
    response = requests.post("http://localhost:8000/prepare_avatar", files={"file": f})
    avatar_token = response.json()["avatar_token"]

# 2. 動画生成
with open("audio.wav", "rb") as f:
    response = requests.post(
        "http://localhost:8000/generate_video",
        files={"file": f},
        data={"avatar_token": avatar_token}
    )
    
# 3. 保存
with open("output.mp4", "wb") as f:
    f.write(response.content)

技術スタック

モデル: Ditto TalkingHead（Ant Group Research）
フレームワーク: PyTorch, ONNX Runtime, TensorRT
WebUI: Gradio
インフラ: Hugging Face Spaces（GPU: A100）
補助モデル: HuBERT（音声特徴）、MediaPipe（顔ランドマーク）

Phase 3の実装内容

最適化モジュール（`core/optimization/`）

resolution_optimization.py: 解像度320×320固定化
gpu_optimization.py: GPU最適化（Mixed Precision、torch.compile）
avatar_cache.py: 画像埋め込みキャッシュシステム
cold_start_optimization.py: 起動時間最適化

新しいアプリケーション

app_optimized.py: Phase 3最適化を含むGradio UI
api_server.py: FastAPI実装（/prepare_avatar、/generate_video）
test_performance_optimized.py: パフォーマンステストツール

詳細は Phase 3最適化ガイドを参照してください。

今後の展開

TensorRT/ONNX最適化の完全実装（追加で50-60%高速化）
リアルタイムストリーミング対応
複数話者の対応
バッチ処理の実装