SYSTEM_DOCUMENTATION.md

# 分散GPU音声文字起こしシステム

## 概要

このシステムは、長時間の音声ファイルを効率的に文字起こしするための分散処理システムです。GPUを使用する重い処理をHugging Face Space上で行い、ファイルの分割と結合をローカル環境で実行します。

## システム構成

### 1. Space側（GPU処理）
- ファイル: `space_app.py`
- 役割: GPUを使用した文字起こし処理
- 環境: Hugging Face Space（GPU環境）
- 主な機能:
  - 音声ファイルの受信
  - GPUを使用した文字起こし
  - 結果のJSON形式での返却

### 2. ローカル側（制御）
- ファイル: `local_controller.py`
- 役割: ファイル分割と結果の結合
- 環境: ローカルマシン（CPUのみ）
- 主な機能:
  - 音声ファイルの分割
  - Space APIとの通信
  - 文字起こし結果の結合
  - 最終結果の保存

## データフロー

1. **音声ファイルの分割**
   - 入力: 音声ファイル（mp3, wav等）
   - 処理: 1時間単位で分割（30秒のオーバーラップ）
   - 出力: 分割された音声チャンク

2. **Spaceでの処理**
   - 入力: 音声チャンク
   - 処理: GPUを使用した文字起こし
   - 出力: JSON形式の中間データ
     ```json
     {
       "segments": [
         {
           "start": 0.0,
           "end": 10.5,
           "text": "文字起こしテキスト"
         }
       ],
       "words": [
         {
           "start": 0.0,
           "end": 1.5,
           "word": "単語"
         }
       ]
     }
     ```

3. **結果の結合**
   - 入力: 各チャンクの中間データ
   - 処理: タイムスタンプの調整と重複除去
   - 出力: 結合された文字起こし結果

## 環境要件

### Space側
- Hugging Face Space（GPU環境）
- 必要なパッケージ:
  - nemo
  - torch
  - gradio

### ローカル側
- Python 3.8以上
- 必要なパッケージ:
  - requests
  - pydub
  - ffmpeg-python
- ffmpeg（システム要件）

## 使用方法

1. **Spaceのデプロイ**
   - `space_app.py`をHugging Face Spaceにデプロイ
   - SpaceのURLを取得

2. **ローカル環境のセットアップ**
   ```bash
   pip install -r requirements.txt
   ```

3. **実行**
   ```bash
   python local_controller.py "path/to/audio.mp3" --output-dir "path/to/output"
   ```

## 設定パラメータ

### チャンク設定
- `CHUNK_LENGTH_SECONDS`: 3600（1時間）
- `CHUNK_OVERLAP_SECONDS`: 30（30秒）

### Space設定
- `SPACE_URL`: Hugging Face SpaceのURL

## エラーハンドリング

1. **ファイル処理エラー**
   - 一時ファイルの自動削除
   - エラーログの出力

2. **API通信エラー**
   - リトライ機能
   - エラーメッセージの表示

3. **メモリ管理**
   - 一時ファイルの適切な管理
   - メモリ使用量の最適化

## 出力形式

- JSON形式で保存
- セグメントと単語レベルのタイムスタンプ
- 必要に応じてSRT/VTT等に変換可能

## 制限事項

1. **ファイルサイズ**
   - 入力ファイル: 制限なし（チャンク分割により処理）
   - 出力ファイル: システムのメモリ制限に依存

2. **処理時間**
   - 音声長に比例
   - ネットワーク状況に依存

3. **API制限**
   - Spaceの利用制限に従う
   - レート制限の考慮

## 今後の拡張性

1. **機能拡張**
   - 複数言語対応
   - カスタムモデルの使用
   - リアルタイム処理

2. **最適化**
   - 並列処理の改善
   - メモリ使用量の最適化
   - エラー回復機能の強化

3. **UI/UX**
   - Webインターフェースの追加
   - 進捗表示の改善
   - 設定のGUI化