Synkinema

Local video editing for people and agents.

Build a reel by hand, chat with a local CLI agent inside Studio, or connect an AI client through MCP—all on the same project. Synkinema combines a desktop video editor with a headless FFmpeg engine, REST API, MCP server and CLI. Your projects, media, revisions and exports stay on your machine. Manual editing requires no account; AI agents use your provider's login.

One project. Your edit. Your agent.

Start a project in Studio, shape the cut by hand, then open Agent chat or bring in an AI client through MCP. You and your agent work on the same local project and editable timeline; revision history and undo keep every change under your control.

Media, preview and a multi-track edit—together in Studio's focus mode.

In action · Quick start · Features · Agent chat · Connect through MCP · Documentation · Development · Contributing

Quick start

Docker with your local CLI agents

To use the built-in chat with Codex, Claude Code or Copilot installed and signed in on your computer, install Docker and curl, and start your Docker engine (Docker Desktop or Colima).

Moving an existing Compose installation to this mode? Finish any running renders or agent turns, then run docker compose stop synkinema in its checkout before the installer. This keeps the synkinema_synkinema-data volume and your projects/media. The launcher needs exclusive access to that volume and port 43817; changing only the port does not resolve a shared-volume conflict.

Then run:

curl -fsSL https://github.com/dziksu/synkinema/releases/latest/download/synkinema-local-install.sh | sh

The installer verifies SHA-256, installs a standalone launcher for macOS/Linux arm64/x64, and starts the matching Docker image. No cloning, Python, Node.js or local FFmpeg installation is needed. The selected release must include the launcher assets and a publicly readable matching GHCR image.

Open http://localhost:43817, then Agent chat → Agent settings. The localhost gateway runs your native CLI with its existing login and proxies Studio/API/media to a private Docker backend on port 43818. Projects/media/exports stay in synkinema_synkinema-data; chat and settings live in ~/.local/share/synkinema/chat. Existing Docker conversations are copied once, keeping the originals. CLI credentials are never mounted into Docker.

Keep the terminal open. Ctrl+C stops the launcher, agents and its managed container while retaining projects, media and conversations. Start again with:

~/.local/share/synkinema/synkinema-local
# In another terminal:
~/.local/share/synkinema/synkinema-local status
~/.local/share/synkinema/synkinema-local stop

The launcher refuses occupied ports, foreign containers and a volume already used by another running container. If installation succeeded but startup failed, fix the reported problem and rerun the installed launcher; no reinstallation is needed. If your earlier docker run used synkinema-data, pass --volume synkinema-data. Use --port 43819, --backend-port, --data-dir, --read-only and --no-open as needed. If pulling the matching image reports unauthorized, denied or manifest unknown, see launcher troubleshooting. To update, stop the launcher and rerun the installer; helper and image versions must match. See local launcher details.

Docker engine and external MCP clients

With Docker installed and running, start the published image. No cloning, Python, Node.js or local FFmpeg installation is needed:

docker run -d --name synkinema --init \
  -p 127.0.0.1:18080:8080 \
  -v synkinema-data:/data \
  --restart unless-stopped \
  ghcr.io/dziksu/synkinema:latest

Open http://localhost:18080 and create a project. The first run downloads the image. Projects, media, models and exports persist in the synkinema-data Docker volume; restarting the container keeps them.

The command requires a published, publicly readable GHCR image. Before the first release, or if you get denied / manifest unknown, use the source build. See releases and image troubleshooting.

Check startup:

docker logs --tail 100 synkinema
curl --fail http://localhost:18080/api/health

Run docker start after stopping an existing container; repeating docker run with the same name will fail. If host port 18080 is occupied, use -p 127.0.0.1:18081:8080 and port 18081 in your browser and MCP client.

The default setup is local and single-user, with no login. Keep it on localhost unless you deliberately configure trusted network access. For upgrades, pin a published vX.Y.Z tag or digest and keep the same volume. The release workflow builds Linux images for AMD64 and ARM64.

Build from source

For development or before a public image is available:

git clone https://github.com/dziksu/synkinema.git
cd synkinema
docker compose up --build -d

If you already have a checkout, run only the last command there. Once an image is published, docker compose -f compose.release.yaml up -d uses it without building. The default Compose mapping is 127.0.0.1:43817:8080; open http://localhost:43817 after starting it. To restore an existing Compose installation without rebuilding, run docker compose up -d synkinema in the same checkout; it keeps the existing Compose volume. Compose normally uses synkinema_synkinema-data, a different volume from the standalone command's synkinema-data. Reuse the original volume when moving an existing installation; see deployment and backups.

Your first video

1. Open Projects, create a project and choose its output profile.
2. Upload footage into Project media, or add reusable assets from Library.
3. Drag a source onto the preview to insert it at the playhead. Trim it on the timeline and position layers on the canvas. Add separate tracks for simultaneous overlays or captions; ordinary clips cannot overlap on one track.
4. Add captions, then import narration or generate a take in Script → Voiceover. Video tracks are silent: extract source audio or add it to an audio track to include it in the mix. Add music and sound effects as separate layers.
5. Export a short preview, inspect it, then render the final video. Play and download the result from the project's Exports tab or the global Render queue.

Follow the manual editing guide for source ranges, canvas controls and audio. To work through an agent, follow the first MCP reel walkthrough.

What you can make

The interface defaults to English; scripts, captions and project names can use other languages. Desktop mouse and keyboard workflows are the current focus. Your CLI agent or AI client supplies the reasoning and script writing. Synkinema supplies the editing tools, local media processing and durable production jobs.

In-app agent chat

Open Agent chat in the bottom-right corner of Studio to talk to Codex CLI, Claude Code or GitHub Copilot CLI without leaving the editor. Start a general conversation or attach it to a project; a project conversation keeps its scope when you navigate elsewhere in the app.

A real Codex CLI reply inside Studio, based on the demo project's actual timeline.

The local launcher keeps the engine in Docker while a host Codex CLI commits a real project edit through scoped MCP.

• Ask inspects project, script and timeline context without changing the project.
• Edit project lets the agent apply atomic edits against a confirmed revision. Changes appear in the same project history and support undo.
• Replies and tool progress appear as the agent works. Stop cancels the running turn; closing the panel keeps it running.
• Conversations and agent settings are stored locally. Rename, archive or restore chats from their options menu, and hold a conversation for 350 ms to reorder it.

To get started:

1. Install and sign in to a supported CLI on your computer, then use the local Docker launcher or the native development setup.
2. Open Agent chat → Agent settings and check that the CLI is available. Set its executable path if needed; for Codex, choose a model from Available models or leave the model ID empty to use the CLI default.
3. Select a project, create a conversation and start in Ask. Choose Edit project when you want timeline changes.

The CLI process runs locally; model requests normally use your provider account and its quota. Agent chat requires a local connection. The stock Docker image does not include agent CLIs or their login, and a CLI installed on your host is not automatically available inside the container. The local launcher handles this by running chat on your computer. See local chat setup and behavior for provider settings, context, cancellation and access rules.

MCP and agents

Use http://localhost:18080/mcp/, transport Streamable HTTP. The container already includes the MCP server. You do not need to clone this repository, install the Synkinema Python package on your agent's machine, or configure a Synkinema API key for the default local setup. Your AI client's own account requirements apply. Studio's Engine and integrations → Connect an AI agent guide offers copyable configuration for Codex, Claude, Copilot, Cursor, Gemini and other MCP clients, followed by a read-only connection check and a video-production workflow prompt.

For example, with Codex CLI installed:

codex mcp add synkinema --url http://localhost:18080/mcp/

Codex's local CLI, desktop app and IDE extension use the same MCP configuration. Codex MCP documentation.

First connection check — paste into your agent:

Use the Synkinema MCP server. Read get_agent_guide, get_capabilities,
get_production_capabilities and get_voice_provider_status, then call list_projects.
Summarize what is available and whether local speech/transcription models are
installed. Do not change anything.

Then use the ready-to-paste creation brief to make a reel. The connection guide covers verification, timeouts and troubleshooting. Cloud-hosted agents cannot reach your computer's localhost; choose a client running locally or use the documented private connection setup.

For exact payloads, let the agent discover get_project_schema and get_operation_reference. The canonical agent guide also ships inside the image, available via get_agent_guide, the MCP resource synkinema://agent-guide and HTTP. Read capabilities from the running version instead of assuming every image has the same tool set. API and MCP reference.

Optional local speech and transcription

The container includes the speech runtime; model weights are an explicit, one-time download into the data volume. Ask your connected agent to install the local models using the install_voice_model and install_transcriber production tasks, then wait for each task to finish. Choose tiny.en for English transcription or tiny for multilingual input. See the MCP walkthrough.

To install just the Supertonic voice model from a terminal:

docker exec synkinema python -m synkinema.supertonic_tts --install

Then use Script → Voiceover → Supertonic 3, select a supported language and voice, and listen to the generated take. Synthesis and recognition run locally on CPU after model installation. Agent-based batch narration returns real durations and word timing for editable captions. Neither workflow silently falls back to a paid speech provider.

Supertonic supports 31 declared languages and is an optional, pinned integration with an archived upstream. Its weights have a separate OpenRAIL-M license and output-disclosure requirements. See setup and licensing. ElevenLabs is a separate optional provider using your server-side key and credits.

Development

Use Python 3.12, Node 24.21.0 (nvm use), FFmpeg and ffprobe. Docker includes FFmpeg and the required fonts; local development needs DejaVu Sans or a configured TTF. Windows users can use Docker or WSL2.

python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pip install --no-build-isolation --no-deps -e .
npm ci --ignore-scripts
npm --prefix apps/studio ci
npm --prefix apps/studio run build
.venv/bin/synkinema serve

For frontend hot reload, keep the backend running and start npm --prefix apps/studio run dev in another terminal. Vite runs at http://127.0.0.1:5174; TanStack Start streams SSR and proxies /api, /media and /mcp to port 8080. Set the server-only SYNKINEMA_API_ORIGIN to use another engine origin.

The Python serve command runs the engine API. To serve a production Studio build locally, keep that engine running and start npm --prefix apps/studio start in another terminal (HOST=127.0.0.1 PORT=5174). Docker starts both processes behind its existing port 8080. See Studio architecture and runtime.

make format              # Biome for web/tooling; Ruff for Python
make check               # Same code, contract, tests and build gate as CI
npm run workflows:check  # Pinned actionlint, archive checksum verified
npm run release:check    # Local commit analysis; never publishes or creates tags

The root npm manifest contains release tooling only. The Studio has its own manifest and lockfile. Biome formats JavaScript, TypeScript, CSS, HTML and JSON; Ruff formats and lints Python. YAML is checked by actionlint. See Contributing for the full workflow.

API architecture — mandatory

Every Studio API request goes through TanStack Query and the swagger-typescript-api generated HTTP client. OpenAPI and the operation catalog are the source of truth. Reversible edits use optimistic updates with rollback; project writes serialize against the last confirmed server revision.

After an API change, run npm --prefix apps/studio run api:generate and include the schema, generated client and defaults together. CI's api:check rejects drift. See the architecture guide and AGENTS.md.

flowchart LR
  UI[React Studio + TanStack Query] --> API[REST API]
  AI[AI client] --> MCP[MCP server]
  CLI[CLI] --> API
  API --> Domain[Shared editing services]
  MCP --> Domain
  Domain --> Store[SQLite + local media]
  Domain --> Render[FFmpeg worker]
  Render --> Output[MP4 + frame and audio inspection]

Deployment and data

The default configuration is a local, single-user application. There is no Studio login or multi-user authorization. Trusted LAN access is opt-in; do not expose the port publicly. /api and /mcp can use a bearer token for headless integrations, but that does not protect media URLs. MCP's host checks currently allow loopback hosts; use a private tunnel for another computer. Security policy.

Keep the complete data directory: database, imported media, models and renders. Run only one server/worker against a data volume. Explicit media/export deletion also removes the corresponding owned file when it is safe to do so; shared usage is validated. Configuration, LAN access, upgrades and backups.

Examples and current limits

The repository includes production scripts and credits for an English Steam reel, a Steam horror showcase, a Polish wildlife reel, and a reusable sound effects library. The MCP-only production example exercises remote footage, local speech, composition, verification and delivery through MCP; see its acceptance results. Large source footage, private project JSON and rendered videos are excluded from Git; examples are not bundled in the published image.

The editor preview is simplified; FFmpeg exports and inspections are authoritative. Word timing is approximate ASR alignment; unmatched words are flagged as estimated. Generated speech, game research and final visuals need editorial review. The showcase helper currently targets portrait layouts; other edits use the ordinary timeline operations. There is no LUT workflow, stabilization or multi-user collaboration. Cache size is not automatically capped. See Roadmap.

Documentation

• Documentation index — choose a guide by task.
• Agent setup and first MCP reel.
• Manual editing and export formats.
• Deployment, upgrades and backups.
• API / MCP, web API architecture and contributing.

Releases and license

Conventional Commits on main drive semantic-release after the code checks and both container smoke tests pass. It opens or updates a release PR with the generated changelog and matching application versions. With the documented repository rules and auto-merge enabled, passing required checks automatically squash-merge that PR. The merge publishes the version tag, GitHub release notes and GHCR image. No npm or PyPI package is published.

Release and first-push guide · Changelog · MIT license · Third-party notices