Video toolkit. One port. Zero cloud. Lipsync, face restore, ffmpeg. Fire-and-forget async jobs. Webhooks. Spec-first OpenAPI; typed Go + Python clients generated from the same spec.
The video sibling of audiolla (audio) and talkies (speech). Same wire format, same async-job model, same bind-mount-/data story, same Makefile shape, same :latest + :latest-cuda split, same opt-in non-commercial gate.
POST a JSON body. Get a video back. Drive it from curl, shell scripts, the generated Go/Python clients, or point an LLM agent at the MCP endpoint.
No account. No subscription. docker run and you're done.
| 👄 Lipsync | LatentSync 1.5 (ByteDance, Apache-2.0, default on CUDA) + Wav2Lip / Wav2Lip-GAN (Rudrabha, fast/low-VRAM, behind FLICKIES_ENABLE_NONCOMMERCIAL=1) |
| 🧹 Face restore | GFPGAN v1.4 (TencentARC, Apache-2.0) — chains after Wav2Lip to fix the soft 96×96 mouth crop, or use standalone |
| ⚙️ ffmpeg ops | Trim · concat · transcode (incl. gif + fps + codec change) · scale · mux audio · extract audio · thumbnail grid — pure ffmpeg, CPU |
| 📋 Info | ffprobe metadata at /v1/video/info — duration, codec, fps, dimensions, bitrate |
| 🔗 MCP server | All endpoints exposed as MCP tools so function-calling LLMs can drive the pipeline |
| 📜 Spec-first | openapi.yaml is the single source of truth — server-side Pydantic, Go client, and Python client all regenerated from one file |
| 🐳 Hot-swap eviction + idle unload | One GPU pool. Different model requested → current model evicted. Idle longer than FLICKIES_IDLE_UNLOAD_SECS (default 600s) → unloaded by the sweeper. |
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"}' | jqCUDA image at psyb0t/flickies:latest-cuda runs every engine at usable speed. CPU image runs all ffmpeg ops (trim/concat/transcode incl. gif/scale/mux/extract/thumbnail-grid/info) + Wav2Lip-CPU (~44s for a 3s clip; OK for short ones). GFPGAN + LatentSync 1.5 are CUDA-only — CPU image refuses to load them.
Weights live in the standard HuggingFace cache layout under /data/hf/hub/models--<org>--<name>/{blobs,snapshots,refs}/… — content-addressed blobs, snapshot-named symlinks, reusable by any other HF-aware tool sharing the bind mount (not just flickies). Sources:
| engine | HF repo |
|---|---|
wav2lip / wav2lip-gan |
Nekochu/Wav2Lip |
| S3FD detector | ByteDance/LatentSync-1.5 (bundled in auxiliary/) |
gfpgan |
leonelhs/gfpgan |
latentsync-1.5 |
ByteDance/LatentSync-1.5 |
Lazy by default — each engine fetches its repo on first request. Set FLICKIES_ENABLED_ENGINES=wav2lip,gfpgan (or FLICKIES_PREFETCH_ALL=1) to pull at boot before uvicorn starts. FLICKIES_OFFLINE=1 disables auto-download (operators stage the snapshot dir manually).
Bearer token set via env. Any string works:
docker run -e FLICKIES_AUTH_TOKEN=testme ...
# clients then send: curl -H "Authorization: Bearer testme" ...Unset → auth disabled. /healthz is always probe-exempt.
Structured JSON to both stderr AND a rotating file at FLICKIES_LOG_FILE (default /data/logs/flickies.log, 50 MB × 5 backups). Every line carries time (ISO 8601 UTC sub-ms), level, logger, file, line, func, msg, trace_id, request_id + typed extras.
Inbound X-Request-Id (UUID v4 OR ULID; garbage → server mints fresh) threads onto the logging scope via ContextVar + echoes back on the response. Outbound httpx fetches forward X-Request-Id + X-Trace-Id so the next hop's logs correlate. Sensitive keys (authorization, cookie, *token*, *secret*, hf_*, sk-ant-*) get [REDACTED] automatically at format time.
Default level is INFO; set FLICKIES_LOG_LEVEL=DEBUG for reconstruction-grade tracing: every ffmpeg/ffprobe command + result, each transform's decision (e.g. trim stream_copy vs precise_reencode) + output size, engine inference timing (wall_secs), URL fetch/upload byte counts, and job lifecycle. Logged URLs are stripped of their query string so presigned credentials never reach the logs.
Eleven tools at /v1/mcp via streamable-HTTP JSON-RPC: list_engines, info, lipsync, restore, transcode, trim, concat, scale, mux_audio, extract_audio, thumbnail_grid. Point a function-calling LLM at it (LibreChat, Cursor, Claude desktop with the MCP connector) and it drives the pipeline.
Tested target: RTX 3060 12 GB. Fits LatentSync 1.5 (~8 GB) with headroom. Wav2Lip + GFPGAN chain peaks at ~5 GB. One engine resident at a time — different model request triggers hot-swap eviction.
Wav2Lip variants are trained on LRS2 (non-commercial). The server refuses to load them unless FLICKIES_ENABLE_NONCOMMERCIAL=1 is set in the server env. LatentSync 1.5 (Apache-2.0) is the commercial-safe default — no gate.
| Engine | License | Gate |
|---|---|---|
| LatentSync 1.5 | Apache-2.0 | none |
| Wav2Lip / Wav2Lip-GAN | LRS2 non-commercial | FLICKIES_ENABLE_NONCOMMERCIAL=1 |
| GFPGAN | Apache-2.0 | none |
| ffmpeg / ffprobe (not an engine; standard CPU helper) | LGPL (ffmpeg) | none |
Same pattern as audiolla's MusicGen / matchering gates.
Every request/response shape lives in openapi.yaml. The Pydantic models in src/flickies/schema/_generated.py, the Go client in pkg/clients/go/client.gen.go, and the Python client in pkg/clients/python/flickies-client/ are all generated from that single file.
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.yamlNever hand-edit generated files. Edit openapi.yaml, run make generate, commit everything together.
go get github.com/psyb0t/docker-flickies/pkg/clients/go@latestimport flickies "github.com/psyb0t/docker-flickies/pkg/clients/go"
c, _ := flickies.NewClient("http://localhost:8000")
resp, err := c.PostVideoLipsync(ctx, flickies.VideoLipsyncRequest{...})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(...))The skill works in any agent that reads .agents/skills/, and installs natively in the clients below.
claude plugin marketplace add psyb0t/agents
claude plugin install flickies@psyb0tClaude Code prompts for the flickies URL and, if auth is enabled, the token — the token is stored in your OS keychain.
codex plugin marketplace add psyb0t/agents
codex plugin add flickies@psyb0tInstalled via the marketplace, the skill invokes as $flickies:flickies. Codex also picks the skill up automatically with no install in any repo containing .agents/skills/, where it invokes as plain $flickies.
The skill is published to ClawHub on every release:
openclaw skills install @psyb0t/flickiesFor MCP clients that speak local stdio, the @psyb0t/flickies plugin bridges to flickies' /v1/mcp endpoint:
openclaw plugins install clawhub:@psyb0t/flickiesThen set FLICKIES_URL (and FLICKIES_AUTH_TOKEN if the server requires one).
Mounts in aigate at /flickies/ and /flickies-cuda/ behind the same nginx → make run-bg lives. FLICKIES=1 and FLICKIES_CUDA=1 toggle the variants.
WTFPL for flickies itself. Bundled models follow their upstream licenses — review before commercial redistribution.