Add API plans for video generation, preview, thumbnail, progress tracking, queue system, and continuous playback

- Create api_plan.md detailing the purpose, framework, code structure, and endpoints for the API.
- Establish api_preview_plan.md to implement a preview feature during video generation using SSE.
- Outline api_thumbnail_plan.md to return input image thumbnails alongside video download URLs in the /result endpoint.
- Document progress_sse_plan.md for real-time job progress updates using Server-Sent Events (SSE) in the React frontend.
- Explain the queue system in queue_explanation.md, detailing components and their roles in job management.
- Implement video continuous playback functionality in video continuous_playback_plan.md, utilizing SSE to notify clients of new video files.

Author: hndrr

api_plan.md plan/api_plan.mdapi_plan.md renamed to plan/api_plan.md

@@ -0,0 +1,125 @@
+# API プレビュー機能 実装計画
+
+## 1. 目的
+
+`api/` ディレクトリ内の FastAPI アプリケーションにおいて、`demo_gradio.py` と同様の動画生成中のプレビュー機能を実装する。これにより、API クライアントは生成プロセスの途中経過をリアルタイムで確認できるようになる。
+
+## 2. 現状分析と課題
+
+* **`demo_gradio.py` のプレビュー:**
+  * `worker` 内の `sample_hunyuan` コールバックで `vae_decode_fake` を使用し、プレビュー画像を生成。
+  * `AsyncStream` を介して Gradio UI にプレビュー画像を送信。
+* **`api/worker.py` の現状:**
+  * `sample_hunyuan` のコールバックは進捗テキスト更新とキャンセルチェックのみ。プレビュー生成・送信は未実装。
+  * `worker` からクライアントへのリアルタイムデータ送信手段が直接はない。
+* **API での実現課題:**
+  * `api/worker.py` のコールバックでプレビュー画像を生成する必要がある。
+  * 生成したプレビュー画像を API クライアントにリアルタイムで送信する仕組みが必要。
+  * `vae_decode_fake` 関数の利用可否確認 (→ 確認済み、利用可能)。
+
+## 3. 計画
+
+### 3.1. 情報収集 (完了)
+
+* `diffusers_helper/hunyuan.py` を確認し、`vae_decode_fake` 関数が存在することを確認した。
+
+### 3.2. API 設計
+
+* 既存の Server-Sent Events (SSE) エンドポイント `/stream/status/{job_id}` (`api.py` 内) を拡張し、プレビュー画像データも送信するようにする。
+* SSE イベントのデータ構造に、オプションとして Base64 エンコードされたプレビュー画像 (`preview_image_base64`) を追加する。
+
+    ```json
+    {
+      "job_id": "...",
+      "status": "processing",
+      "progress": 25.5,
+      "progress_step": 5,
+      "progress_total": 20,
+      "progress_info": "Sampling...",
+      "preview_image_base64": "data:image/jpeg;base64,..." // Optional
+    }
+    ```
+
+### 3.3. 実装方針
+
+* **`api/worker.py` の修正:**
+  * `callback` 関数内で、`sample_hunyuan` から渡される中間潜在変数 (`d['denoised']`) を取得する。
+  * `vae_decode_fake` を使用してプレビュー画像を生成する。
+  * 生成した画像を JPEG 形式にエンコードし、Base64 文字列に変換する (`data:image/jpeg;base64,...` 形式)。
+  * 変換した Base64 文字列を `queue_manager` の新しい関数 (例: `update_current_preview`) を呼び出してメモリ上のストアに一時保存する。
+* **`api/queue_manager.py` の修正:**
+  * プレビュー情報 (Base64 文字列) を一時的に保持するためのグローバルな辞書 (例: `current_previews = {}`) を追加する。
+  * `worker.py` からプレビュー情報を受け取り、`current_previews` を更新する関数 (例: `update_current_preview(job_id, preview_base64)`) を追加する。
+  * SSE ハンドラからプレビュー情報を取得する関数 (例: `get_current_preview(job_id)`) を追加する。
+  * ジョブ完了時または失敗時に `current_previews` から該当ジョブのエントリを削除する処理を追加する (例: `clear_current_preview(job_id)`)。
+  * **注意:** このプレビュー情報は揮発性であり、JSON キューファイル (`job_queue.json`) には保存しない。
+* **`api/api.py` の修正:**
+  * `/stream/status/{job_id}` の SSE `event_generator` 関数を修正する。
+  * ジョブが `processing` 状態の場合、`queue_manager` の新しい関数 (例: `get_current_preview`) を呼び出して最新のプレビュー画像 Base64 文字列を取得する。
+  * 取得した Base64 文字列を SSE イベントデータの `preview_image_base64` フィールドに含めてクライアントに送信する。
+
+### 3.4. 処理フロー (Mermaid図)
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant FastAPI (api.py)
+    participant QueueManager (queue_manager.py)
+    participant Worker (worker.py)
+    participant Models (models.py / diffusers_helper)
+
+    Client->>FastAPI: POST /generate (画像, プロンプト)
+    FastAPI->>QueueManager: add_to_queue()
+    QueueManager-->>FastAPI: job_id
+    FastAPI-->>Client: {job_id: ...}
+
+    Client->>FastAPI: GET /stream/status/{job_id} (SSE接続)
+    FastAPI->>FastAPI: event_generator() 開始
+
+    loop Worker Thread
+        Worker->>QueueManager: get_next_job()
+        QueueManager-->>Worker: job (or None)
+        opt job is not None
+            Worker->>QueueManager: update_job_status(job_id, "processing") # ファイル更新
+            Worker->>Models: モデルロード/準備 ...
+            Worker->>Models: sample_hunyuan(..., callback=callback_func)
+            loop Sampling Steps
+                Models->>Worker: callback_func(d) 呼び出し
+                Worker->>Models: vae_decode_fake(d['denoised']) # プレビュー生成
+                Models-->>Worker: preview_image_tensor
+                Worker->>Worker: 画像をJPEG Base64に変換
+                Worker->>QueueManager: update_current_preview(job_id, preview_base64) # メモリ更新
+                Worker->>QueueManager: update_job_progress(...) # ファイル更新 (進捗のみ)
+            end
+            Models-->>Worker: generated_latents
+            Worker->>Models: vae_decode() # 最終デコード
+            Models-->>Worker: final_pixels
+            Worker->>Worker: save_bcthw_as_mp4()
+            Worker->>QueueManager: update_job_status(job_id, "completed") # ファイル更新
+            Worker->>QueueManager: clear_current_preview(job_id) # メモリクリア
+        end
+    end
+
+    loop SSE Connection (event_generator)
+        FastAPI->>QueueManager: get_job_by_id(job_id) (ファイルから進捗取得)
+        alt job is processing
+            FastAPI->>QueueManager: get_current_preview(job_id) (メモリからプレビュー取得)
+            QueueManager-->>FastAPI: preview_base64 (or None)
+        end
+        FastAPI->>Client: event: progress, data: {..., preview_image_base64: ...} # 進捗とプレビュー送信
+        alt job is terminal
+            FastAPI->>Client: event: status, data: {...} # 最終ステータス送信
+            break
+        end
+        FastAPI->>FastAPI: asyncio.sleep(1)
+    end
+```
+
+## 4. 懸念点
+
+* **データ受け渡し:** `worker` スレッドと SSE ハンドラ (FastAPI の非同期コンテキスト) 間でのプレビューデータ受け渡し (`queue_manager` のメモリ上の辞書) が、スレッドセーフティやパフォーマンスの観点から問題ないか。高頻度更新時の競合やメモリ使用量に注意が必要。
+* **パフォーマンス:** プレビュー画像の生成 (`vae_decode_fake`)、JPEG エンコード、Base64 エンコードが `worker` のコールバック内で実行されるため、全体の生成時間に影響を与える可能性がある。
+
+## 5. 次のステップ
+
+* この計画に基づき、`code` モードに切り替えて実装を開始する。

plan/api_preview_plan.md

@@ -0,0 +1,92 @@
+# 動画連続再生機能 実装計画
+
+## 概要
+
+ローカルの特定ディレクトリ (`outputs`) に順次追加される動画ファイル (`.mp4`) を検知し、FastAPIのSSE (Server-Sent Events) を通じてクライアント (React想定) に通知する。クライアントは通知されたファイル名を元に動画をリクエストし、連続再生を行う。既存のFramePack API (`api/api.py`) に機能を追加し、他の機能への影響を最小限に抑える。
+
+## 計画詳細
+
+1. **設定更新 (`api/settings.py`):**
+    * 監視対象ディレクトリパス `VIDEO_DIR` を定義する。デフォルトはプロジェクトルート下の `outputs` ディレクトリとする。環境変数 `VIDEO_DIR` が設定されていれば、その値を優先する。
+    * 動画ファイル配信用エンドポイントのベースURL `VIDEO_BASE_URL` を `/videos/` として定義する (主にクライアント側の参考情報)。
+
+2. **ファイル監視ロジック (`api/video_watcher.py` - 新規ファイル):**
+    * `watchdog` ライブラリを使用する `VideoHandler` クラスを作成する。
+    * `on_created` イベントハンドラを実装し、`.mp4` ファイルが作成された場合のみ、FastAPI側のSSEクライアントキューリスト (`sse_clients`) にファイル名を追加する。
+    * 監視を開始/停止する関数 (`start_watcher`, `stop_watcher`) を作成する。
+        * `start_watcher(path, clients)`: 指定されたパスを監視し、通知先のクライアントキューリストを受け取る。`watchdog.observers.Observer` インスタンスを初期化・開始し、そのインスタンスを返す。
+        * `stop_watcher(observer)`: 受け取った `Observer` インスタンスを停止・結合する。
+
+3. **FastAPIエンドポイント追加 (`api/api.py`):**
+    * **グローバル変数:**
+        * `sse_clients = []`: SSEクライアントごとの通知キュー (`asyncio.Queue` など) を保持するリスト。
+        * `observer = None`: `watchdog` の `Observer` インスタンスを保持する変数。
+    * **`/video_stream` (GET, SSE):**
+        * 新しいクライアント接続時に、専用の通知キューを作成し `sse_clients` に追加する。
+        * 非同期ジェネレータ関数を定義する。
+            * 無限ループでクライアントの接続状態をチェックする。
+            * キューから新しいファイル名を取得し、`data: {filename}\n\n` 形式で `yield` する。
+            * クライアント切断時には、対応するキューを `sse_clients` から削除し、ループを終了する。
+        * `StreamingResponse` で上記ジェネレータを返す (`media_type="text/event-stream"`)。
+    * **`/videos/{filename}` (GET):**
+        * `settings.VIDEO_DIR` とリクエストされた `filename` を結合して、動画ファイルのフルパスを構築する。
+        * `os.path.exists` でファイルの存在を確認する。
+        * 存在すれば `FileResponse` を使用して動画ファイル (`media_type="video/mp4"`) を返す。
+        * 存在しなければ `HTTPException(status_code=404, detail="File not found")` を発生させる。
+    * **`/videos` (GET):**
+        * `settings.VIDEO_DIR` 内のファイルを `os.listdir` で取得する。
+        * ファイル名が `.mp4` で終わるもののみをフィルタリングする。
+        * フィルタリングされたファイル名のリストをJSON形式で返す。
+
+4. **ライフサイクル管理 (`api/api.py` の `lifespan`):**
+    * 既存の `lifespan` コンテキストマネージャを修正する。
+    * **Startup:**
+        * `video_watcher.start_watcher(settings.VIDEO_DIR, sse_clients)` を呼び出し、返された `Observer` インスタンスをグローバル変数 `observer` に格納する。
+    * **Shutdown:**
+        * グローバル変数 `observer` が `None` でなければ、`video_watcher.stop_watcher(observer)` を呼び出してファイル監視プロセスを安全に停止する。
+
+5. **依存関係:**
+    * `watchdog` ライブラリが必要となるため、プロジェクトの依存関係ファイル (`requirements.txt` や `pyproject.toml` など) に `watchdog` を追加する。
+
+## Mermaid図
+
+```mermaid
+graph TD
+    subgraph FastAPI Backend (api/api.py)
+        A[Client connects to /video_stream] --> B{Create SSE queue (e.g., asyncio.Queue)};
+        B --> C[Add queue to global sse_clients list];
+        C --> D[Start SSE generation loop (async def)];
+        D -- New filename in queue --> E[yield f"data: {filename}\n\n"];
+        D -- Client disconnects --> F[Remove queue from sse_clients & break loop];
+
+        G[Client requests /videos/{filename}] --> H{Build file path using settings.VIDEO_DIR};
+        H -- os.path.exists is True --> I[Return FileResponse(path, media_type="video/mp4")];
+        H -- os.path.exists is False --> J[Raise HTTPException(404)];
+
+        K[Client requests /videos] --> L{os.listdir(settings.VIDEO_DIR)};
+        L --> M[Filter for .mp4 files, return JSON list];
+
+        N[lifespan startup] --> O[observer = video_watcher.start_watcher(VIDEO_DIR, sse_clients)];
+        P[lifespan shutdown] --> Q[if observer: video_watcher.stop_watcher(observer)];
+    end
+
+    subgraph File System Watcher (api/video_watcher.py - New File)
+        R[Watchdog Observer monitors VIDEO_DIR] -- New .mp4 created --> S[VideoHandler.on_created];
+        S --> T{Get filename};
+        T --> U[Add filename to all queues in sse_clients list];
+        V[start_watcher(path, clients)] --> W[Initialize Observer & Handler, observer.start(), return observer];
+        X[stop_watcher(observer)] --> Y[observer.stop(), observer.join()];
+    end
+
+    subgraph React Frontend (Out of scope)
+        Z[Page load requests /videos] --> AA[Get initial file list];
+        AA --> BB[Initialize playlist];
+        CC[Connects to /video_stream] --> DD[Receive filename via SSE];
+        DD --> EE[Add filename to playlist];
+        BB & EE --> FF[Select random video from playlist];
+        FF --> GG[Request /videos/{filename}];
+        GG --> HH[Receive video data & play];
+    end
+
+    FastAPI_Backend -- Manages --> File_System_Watcher;
+```