HUB
Sign inSign up

psyb0t/flickies

By psyb0t

•Updated 9 days ago

Self-hosted video API in one Docker container. Lipsync (LatentSync 1.5, Wav2Lip), face restoratio...

Image
0

6.7K

psyb0t/flickies repository overview

Source⁠ | Project page⁠

⁠flickies

CI version license Docker Pulls

Video toolkit. One port. Zero cloud. Lipsync, face restore, ffmpeg. Fire-and-forget async jobs. Webhooks. Spec-first OpenAPI; 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.


⁠What's in the box

👄 LipsyncLatentSync 1.5 (ByteDance, Apache-2.0, default, CUDA image) + Wav2Lip / Wav2Lip-GAN (Rudrabha, fast and low-VRAM, behind FLICKIES_ENABLE_NONCOMMERCIAL=1)
🧹 Face restoreGFPGAN v1.4 (TencentARC, Apache-2.0). Cleans up the soft 96×96 Wav2Lip mouth crop, or use it standalone
⚙️ ffmpeg opsTrim · concat · transcode (incl. gif + fps + codec change) · scale · mux audio · extract audio · thumbnail grid. Pure ffmpeg, CPU
📋 Infoffprobe metadata at /v1/video/info: duration, codec, fps, dimensions, bitrate
🔗 MCP server11 tools at /v1/mcp so function-calling LLMs can drive the pipeline
📜 Spec-firstopenapi.yaml is the single source; server models, Go client and Python client are all generated from it
🐳 Hot-swap eviction + idle unloadOne GPU pool, one model resident. A different model evicts the current one. Idle longer than FLICKIES_IDLE_UNLOAD_SECS (default 600s) and the sweeper unloads it

⁠Quick start

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

curl -s -X PUT --data-binary @clip.mp4 \
  http://localhost:8000/v1/files/uploads/clip.mp4

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

Paths are relative to the staging area, /data/files in the container.

psyb0t/flickies:latest-cuda (with --gpus all) runs every engine at usable speed and is the only image with LatentSync 1.5. The CPU image runs every ffmpeg op, GFPGAN on the CPU, and Wav2Lip on the CPU (about 44s for a 3s clip, fine for short ones).

Weights download from Hugging Face on first use into /data/hf, in the standard cache layout any other Hugging Face tool on the same mount can reuse. Set FLICKIES_ENABLED_ENGINES or FLICKIES_PREFETCH_ALL=1 to pull them at boot instead.

Auth is off until you set FLICKIES_AUTH_TOKEN. Set it before the port leaves your machine.

⁠Documentation

Full docs: psyb0t.github.io/docker-flickies⁠

SectionWhat's there
Getting started⁠First upload, trim, lipsync job and download
Deployment⁠Images, /data layout, model weights, prefetch, offline staging, upgrades
Configuration⁠Every environment variable and its default
REST API⁠Every endpoint, async jobs, webhooks, headers, error codes
Engines⁠LatentSync, Wav2Lip, GFPGAN, licenses, VRAM, hot-swap
MCP and agents⁠The 11 MCP tools, Claude Code, Codex and OpenClaw installs
Generated clients⁠Go and Python clients and their gaps
Logging⁠JSON log fields, request ids, redaction, DEBUG
Security⁠What it reaches and stores, what to set before exposing it
Troubleshooting⁠Error messages, causes and fixes
Development⁠Make targets, tests, code generation, CI and releases

⁠License posture

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. Details in Engines⁠.

⁠Agent integrations

The skill⁠ works in any agent that reads .agents/skills/ (such as peen⁠), and installs natively in Claude Code (claude plugin install flickies@psyb0t), Codex (codex plugin add flickies@psyb0t) and OpenClaw (openclaw skills install @psyb0t/flickies). Marketplace setup and the OpenClaw MCP bridge plugin are in MCP and agents⁠.

⁠aigate integration

aigate⁠ runs flickies at /flickies/ (CPU, FLICKIES=1) and /flickies-cuda/ (CUDA, FLICKIES_CUDA=1).

⁠License

WTFPL for flickies itself. Bundled models and vendored code follow their upstream licenses (THIRD_PARTY.md⁠), so review them before commercial redistribution.

⁠Sponsor

Buy Me a Coffee

Tag summary

Content type

Image

Digest

sha256:f287c83cd…

Size

2.7 GB

Last updated

9 days ago

docker pull psyb0t/flickies