Flickies

io.github.psyb0tPublished by GitHub account psyb0tv0.3.17Updated Oct 31, 2026

Self-hosted MCP server: video lipsync, face restore, and ffmpeg ops (trim, concat, transcode).

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

Self-hosted video toolkit MCP server for lipsync, face restoration and ffmpeg operations such as trim, concat, transcode, scale and audio muxing.

What you can do
  • Run lipsync on a video with a supplied audio track, and restore or sharpen faces with GFPGAN.
  • Trim, concatenate, transcode, scale and change fps or codec, including GIF output.
  • Mux or extract audio tracks and build thumbnail grids.
  • Read ffprobe metadata such as duration, codec, fps, dimensions and bitrate.
  • List the available engines and their status before running a job.
When to use it
Useful when an assistant should produce or edit video files locally without cloud services: dubbing a clip to new audio, cleaning up faces, or doing routine ffmpeg conversions and cuts. It fits self-hosted setups where a GPU or CPU box can run the container and files are shared through a mounted data directory.
Requirements
Runs as a Docker container exposing an HTTP endpoint with an MCP path; the assistant connects to that endpoint, optionally through a local stdio bridge plugin. Needs a bind-mounted data directory for files, model weights and logs, and network access to download model weights from Hugging Face on first use unless they are staged offline. A CUDA GPU is required for LatentSync and GFPGAN; the CPU image handles ffmpeg work and Wav2Lip only. Optional bearer token via FLICKIES_AUTH_TOKEN.
Before you install
Auth is off unless FLICKIES_AUTH_TOKEN is set, so an exposed endpoint is open to anyone who can reach it. Jobs write files into the mounted data directory and can download large model weights from Hugging Face. Enabling Wav2Lip requires opting into a non-commercial license gate. Logs are written to a rotating file under the data directory; sensitive keys are redacted but request details are recorded.

Installation

In SourceWeft

  1. Open Flickies in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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; 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.

What's in the box

👄 LipsyncLatentSync 1.5 (ByteDance, Apache-2.0, default on CUDA) + Wav2Lip / Wav2Lip-GAN (Rudrabha, fast/low-VRAM, behind FLICKIES_ENABLE_NONCOMMERCIAL=1)
🧹 Face restoreGFPGAN v1.4 (TencentARC, Apache-2.0) — chains after Wav2Lip to fix the soft 96×96 mouth crop, or use 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 serverAll endpoints exposed as MCP tools so function-calling LLMs can drive the pipeline
📜 Spec-firstopenapi.yaml is the single source of truth — server-side Pydantic, Go client, and Python client all regenerated from one file
🐳 Hot-swap eviction + idle unloadOne GPU pool. Different model requested → current model evicted. Idle longer than FLICKIES_IDLE_UNLOAD_SECS (default 600s) → unloaded by the sweeper.

Quick start

bash
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

CUDA 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:

engineHF repo
wav2lip / wav2lip-ganNekochu/Wav2Lip
S3FD detectorByteDance/LatentSync-1.5 (bundled in auxiliary/)
gfpganleonelhs/gfpgan
latentsync-1.5ByteDance/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).

Auth

Bearer token set via env. Any string works:

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

Unset → auth disabled. /healthz is always probe-exempt.

Logging

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.

MCP

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.

Hardware ceiling

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.

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.

EngineLicenseGate
LatentSync 1.5Apache-2.0none
Wav2Lip / Wav2Lip-GANLRS2 non-commercialFLICKIES_ENABLE_NONCOMMERCIAL=1
GFPGANApache-2.0none
ffmpeg / ffprobe (not an engine; standard CPU helper)LGPL (ffmpeg)none

Same pattern as audiolla's MusicGen / matchering gates.

Spec-first

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.

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

Never hand-edit generated files. Edit openapi.yaml, run make generate, commit everything together.

Generated clients

Go

bash
go get github.com/psyb0t/docker-flickies/pkg/clients/go@latest
go
import flickies "github.com/psyb0t/docker-flickies/pkg/clients/go"
c, _ := flickies.NewClient("http://localhost:8000")resp, err := c.PostVideoLipsync(ctx, flickies.VideoLipsyncRequest{...})

Python

bash
pip install "git+https://github.com/psyb0t/docker-flickies.git#subdirectory=pkg/clients/python/flickies-client"
python
from flickies_client import Clientfrom flickies_client.api.lipsync import post_video_lipsyncfrom flickies_client.models import VideoLipsyncRequest
client = Client(base_url="http://localhost:8000")result = post_video_lipsync.sync(client=client, body=VideoLipsyncRequest(...))

Agent integrations

The skill works in any agent that reads .agents/skills/ (such as peen), and installs natively in the clients below.

Claude Code

bash
claude plugin marketplace add psyb0t/agentsclaude plugin install flickies@psyb0t

Claude Code prompts for the flickies URL and, if auth is enabled, the token — the token is stored in your OS keychain.

Codex

bash
codex plugin marketplace add psyb0t/agentscodex plugin add flickies@psyb0t

Installed 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.

OpenClaw

The skill is published to ClawHub on every release:

bash
openclaw skills install @psyb0t/flickies

For MCP clients that speak local stdio, the @psyb0t/flickies plugin bridges to flickies' /v1/mcp endpoint:

bash
openclaw plugins install clawhub:@psyb0t/flickies

Then set FLICKIES_URL (and FLICKIES_AUTH_TOKEN if the server requires one).

aigate integration

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.

License

WTFPL for flickies itself. Bundled models follow their upstream licenses — review before commercial redistribution.

Source: README.md at commit d8b19e5

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.3.17LatestOct 10, 2026
  2. v0.3.16Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts