Flickies

flickies

動画ツールキット。ポートは1つ。クラウド不要。リップシンク、顔の復元、ffmpeg。実行したらあとは任せられる非同期ジョブ。Webhook。仕様ファーストの OpenAPI。同じ仕様から生成された、型付きの Go クライアントと Python クライアント。

audiolla（音声）と talkies（音声合成）の動画版です。同じワイヤ形式、同じ非同期ジョブモデル、同じ /data のバインドマウント方式、同じ Makefile の構成、同じ :latest と :latest-cuda の分割、同じオプトイン方式の非商用利用制限です。

JSON 本文を POST すると、動画が返ってきます。curl、シェルスクリプト、生成済みの Go／Python クライアントから実行するか、LLM エージェントに MCP エンドポイントを指定してください。

アカウント不要。サブスクリプション不要。docker run すれば完了です。

---

同梱されているもの

👄 リップシンク	LatentSync 1.5（ByteDance、Apache-2.0、CUDA でデフォルト有効）＋ Wav2Lip / Wav2Lip-GAN（Rudrabha、高速／低 VRAM、FLICKIES_ENABLE_NONCOMMERCIAL=1 で有効化）
🧹 顔の復元	GFPGAN v1.4（TencentARC、Apache-2.0）。Wav2Lip の後に連結して、ぼやけた 96×96 の口元の切り抜きを修正するか、単独で使用できます
⚙️ ffmpeg 操作	トリミング · 結合 · トランスコード（gif ＋ fps ＋コーデック変更を含む） · 拡大縮小 · 音声の多重化 · 音声の抽出 · サムネイルグリッド。ffmpeg のみ、CPU で動作
📋 情報	/v1/video/info の ffprobe メタデータ。再生時間、コーデック、fps、解像度、ビットレート
🔗 MCP サーバー	すべてのエンドポイントを MCP ツールとして公開し、関数呼び出しに対応した LLM からパイプラインを操作できます
📜 仕様ファースト	openapi.yaml を唯一の信頼できる情報源とし、サーバー側の Pydantic、Go クライアント、Python クライアントをすべて1つのファイルから再生成します
🐳 ホットスワップによる追い出し＋アイドル時のアンロード	GPU プールは1つです。異なるモデルが要求されると、現在のモデルは追い出されます。FLICKIES_IDLE_UNLOAD_SECS（デフォルトは600秒）を超えてアイドル状態になると、スイーパーによってアンロードされます。

クイックスタート

docker run -d --name flickies \
  -v $HOME/flickies-data:/data \
  -p 8000:8000 \
  psyb0t/flickies:latest

curl -s -X POST http://localhost:8000/v1/video/info \
  -H "Content-Type: application/json" \
  -d '{"file_path": "uploads/clip.mp4"}' | jq

psyb0t/flickies:latest-cuda の CUDA イメージでは、すべてのエンジンを実用的な速度で実行できます。CPU イメージでは、すべての ffmpeg 操作（トリミング／結合／トランスコード。gif／拡大縮小／多重化／抽出／サムネイルグリッド／情報を含む）と Wav2Lip-CPU（3秒のクリップに約44秒。短いクリップなら問題ありません）を実行できます。GFPGAN と LatentSync 1.5 は CUDA 専用のため、CPU イメージではロードできません。

重みは、/data/hf/hub/models--<org>--<name>/{blobs,snapshots,refs}/… の HuggingFace 標準キャッシュ構成に保存されます。コンテンツアドレス方式の blob とスナップショット名のシンボリックリンクを使うため、バインドマウントを共有する他の HF 対応ツールでも再利用できます（flickies に限りません）。ソース：

エンジン	HF リポジトリ
wav2lip / wav2lip-gan	Nekochu/Wav2Lip
S3FD detector	ByteDance/LatentSync-1.5（auxiliary/ に同梱）
gfpgan	leonelhs/gfpgan
latentsync-1.5	ByteDance/LatentSync-1.5

デフォルトでは遅延読み込みです。各エンジンは初回リクエスト時にリポジトリを取得します。uvicorn の起動前にブート時点で取得するには、FLICKIES_ENABLED_ENGINES=wav2lip,gfpgan（または FLICKIES_PREFETCH_ALL=1）を設定してください。FLICKIES_OFFLINE=1 を設定すると自動ダウンロードが無効になり、オペレーターがスナップショットディレクトリを手動で配置します。

認証

環境変数でベアラートークンを設定します。どのような文字列でも使用できます。

docker run -e FLICKIES_AUTH_TOKEN=testme ...
# clients then send: curl -H "Authorization: Bearer testme" ...

未設定の場合、認証は無効になります。/healthz は常にプローブの対象外です。

ロギング

構造化 JSON を stderr と FLICKIES_LOG_FILE のローテーションファイル（デフォルトは /data/logs/flickies.log、50 MB × 5 バックアップ）の両方に出力します。各行には time（サブミリ秒精度の ISO 8601 UTC）、level、logger、file、line、func、msg、trace_id、request_id と、型付きの追加情報が含まれます。

受信した X-Request-Id（UUID v4 または ULID。無効な値の場合はサーバーが新規に生成）は、ContextVar を介してロギングスコープに引き継がれ、レスポンスでも返されます。送信する httpx のフェッチでは X-Request-Id と X-Trace-Id を転送するため、次のホップのログと関連付けられます。機密性の高いキー（authorization、cookie、*token*、*secret*、hf_*、sk-ant-*）は、フォーマット時に自動的に [REDACTED] に置き換えられます。

デフォルトのレベルは INFO です。再現性を重視したトレースを行うには、FLICKIES_LOG_LEVEL=DEBUG を設定します。すべての ffmpeg/ffprobe コマンドと結果、各変換の判断（例：trim の stream_copy と precise_reencode の使い分け）と出力サイズ、エンジン推論の所要時間（wall_secs）、URL のフェッチ／アップロードのバイト数、ジョブのライフサイクルが記録されます。ログに記録される URL からはクエリ文字列が削除されるため、署名付き URL の認証情報がログに残ることはありません。

MCP

/v1/mcp でストリーミング可能な HTTP JSON-RPC を介して、11 個のツールを提供します：list_engines、info、lipsync、restore、transcode、trim、concat、scale、mux_audio、extract_audio、thumbnail_grid。関数呼び出しに対応した LLM（LibreChat、Cursor、MCP コネクターを使用する Claude デスクトップなど）を接続すれば、パイプラインを操作できます。

ハードウェア上限

テスト済みの対象はRTX 3060 12 GBです。余裕を残して LatentSync 1.5（約 8 GB）を実行できます。Wav2Lip と GFPGAN の組み合わせでは、使用量は最大約 5 GB です。一度にメモリに常駐するエンジンは 1 つのみです。異なるモデルのリクエストがあると、ホットスワップで既存のエンジンを退避させます。

ライセンスに関する方針

Wav2Lip の各バリアントは LRS2（非商用）で学習されています。サーバー環境で FLICKIES_ENABLE_NONCOMMERCIAL=1 が設定されていない限り、サーバーは読み込みを拒否します。LatentSync 1.5（Apache-2.0）は商用利用に安全なデフォルトであり、制限はありません。

エンジン	ライセンス	制限
LatentSync 1.5	Apache-2.0	なし
Wav2Lip / Wav2Lip-GAN	LRS2 非商用	FLICKIES_ENABLE_NONCOMMERCIAL=1
GFPGAN	Apache-2.0	なし
ffmpeg / ffprobe（エンジンではなく、標準的な CPU ヘルパー）	LGPL（ffmpeg）	なし

audiolla の MusicGen / matchering の制限と同じ方式です。

仕様ファースト

すべてのリクエスト／レスポンスの形式は openapi.yaml に定義されています。src/flickies/schema/_generated.py の Pydantic モデル、pkg/clients/go/client.gen.go の Go クライアント、pkg/clients/python/flickies-client/ の Python クライアントは、すべてこの単一ファイルから生成されます。

make generate              # regenerate all three (server models + Go client + Python client)
make generate-models       # just server-side Pydantic
make generate-client-go    # just the Go client
make generate-client-python # just the Python client
make generate-check        # CI gate — fail if generated files drift from openapi.yaml

生成ファイルを手動で編集しないでください。openapi.yaml を編集し、make generate を実行して、すべてをまとめてコミットしてください。

生成されたクライアント

Go

go get github.com/psyb0t/docker-flickies/pkg/clients/go@latest

import flickies "github.com/psyb0t/docker-flickies/pkg/clients/go"

c, _ := flickies.NewClient("http://localhost:8000")
resp, err := c.PostVideoLipsync(ctx, flickies.VideoLipsyncRequest{...})

Python

pip install "git+https://github.com/psyb0t/docker-flickies.git#subdirectory=pkg/clients/python/flickies-client"

from flickies_client import Client
from flickies_client.api.lipsync import post_video_lipsync
from flickies_client.models import VideoLipsyncRequest

client = Client(base_url="http://localhost:8000")
result = post_video_lipsync.sync(client=client, body=VideoLipsyncRequest(...))

エージェント連携

スキルは、.agents/skills/ を読み込むあらゆるエージェント（peen など）で動作し、以下のクライアントにはネイティブにインストールできます。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install flickies@psyb0t

Claude Code では flickies の URL と、認証が有効な場合はトークンの入力を求められます。トークンは OS のキーチェーンに保存されます。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add flickies@psyb0t

マーケットプレイスからインストールすると、このスキルは $flickies:flickies として呼び出されます。また、.agents/skills/ を含むリポジトリでは、Codex がインストールなしでスキルを自動的に認識し、$flickies として呼び出せます。

OpenClaw

このスキルはリリースごとに ClawHub に公開されます。

openclaw skills install @psyb0t/flickies

ローカル stdio を使用する MCP クライアント向けに、@psyb0t/flickies プラグインが flickies の /v1/mcp エンドポイントとのブリッジとして機能します。

openclaw plugins install clawhub:@psyb0t/flickies

次に FLICKIES_URL を設定します（サーバーが必要とする場合は FLICKIES_AUTH_TOKEN も設定してください）。

aigate 連携

aigate に /flickies/ と /flickies-cuda/ をマウントし、同じ nginx の背後で make run-bg を実行します。FLICKIES=1 と FLICKIES_CUDA=1 で各バリアントを切り替えます。

ライセンス

flickies 自体は WTFPL です。同梱モデルにはそれぞれ上流のライセンスが適用されるため、商用目的で再配布する前に確認してください。