Hugging Face's logo

Spaces:
Athagi
/
talkingAvater_bgk
Runtime error

App Files Community
talkingAvater_bgk / README_jp.md
oKen38461's picture
oKen38461
README_jp.mdにPhase 3のパフォーマンス最適化の実装状況を更新し、API経由の使用例を追加しました。また、requirements.txtにPhase 3の依存関係を追加しました。
b27232b
preview code
|
raw
history blame contribute delete
6.74 kB

A newer version of the Gradio SDK is available: 6.14.0

Upgrade

DittoTalkingHead プロジェクト

プロジェクト概要

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

作業フロー

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

フェーズ構成

  1. Phase 1: 基本実装 - Hugging Face Spacesへのデプロイ
  2. Phase 2: API実装 - REST API化とクライアント実装
  3. 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経由

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

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%高速化）
  • リアルタイムストリーミング対応
  • 複数話者の対応
  • バッチ処理の実装