Repository navigation
Agents
formencoder's engine exposes every command to agents through MCP, the same commands the menus and buttons run. Changes appear in the window live, and the undoable ones are one step in History.
-
In formencoder: the Terminal panel (or the Agent workspace) opens a shell in formencoder's agent workspace. Its Claude Code, Codex and Cursor buttons start an agent that already has the
formencoderMCP server and theformencoder-harnessskill; it works without permission prompts. -
From the repository:
.mcp.json,.codex/config.tomland.cursor/mcp.jsonrun./formencoder mcp, which starts the engine when it is not running. The first change asks once in the formencoder window: Allow, Allow Always or Don't Allow. -
From anywhere:
./formencoder agents install(or the Agents panel) adds the MCP server and the skill to your Claude Code, Codex and Cursor setup.
FORMENCODER_AGENTS sets the policy for outside agents: ask (default), allow or deny.
21 tools: status, list_commands, describe_command, execute, batch, probe, encode, queue, export_settings, preview_frame, contact_sheet, wait, verify, presets, formats, watch_folder, family, log, history, ui, guide. encode queues, encodes, waits and verifies in one call; preview_frame and contact_sheet render frames through an output's exact settings so an agent looks before it encodes; verify probes the file against its settings.
.claude/skills/formencoder-harness (mirrored to .agents/skills) teaches the loop: status, probe, choose a preset by destination, queue, look, encode, verify. Its sub-skills cover the queue and presets, export settings, effects and loudness, captions and metadata, watch folders and ingest, the form family bridge, publish, verification, the window and recipes for common deliveries. Its references/ hold the commands, tools, presets and formats, generated from the engine by ./formencoder agents sync.
./formencoder encode FILE --preset system/youtube-1080p, queue, exec ID 'JSON', batch 'JSON', commands FILTER, describe ID, presets QUERY, probe FILE, frame OUT.png --output '#1' --time 2, wait, extensions, extension ID COMMAND --args 'JSON'.
form-functions.json at the repository root lists formencoder's Form functions: window-free, server-free callables a graph (NodeMode's hub) runs as nodes. Each is fn(inputs, params, out_dir) -> dict in backend/app/functions, takes local file paths in, writes only inside out_dir, and returns each output's path.
-
encode(app.functions:encode): one video or audio file in (media), the same file encoded with a formencoder preset out (media).params.presetis required and must be one of the presets in the manifest's enum: the encode presets that write one video or audio file with FFmpeg alone (no stills, image sequences, DCP, P2 or AS-10/AS-11).params.settingsis an optional export settings patch merged over the preset, asqueue.addSourcetakes it, limited to an allowlist of fields that name no file: picture size, rate and quality, audio rate, channels and bitrate, fast start, range, crop, rotation, scaling and loudness normalisation. No field takes a free string: each string is one of the engine's own values (the manifest lists them) and each number has bounds. Anything else (a LUT, an overlay image, a caption source, a report folder, publish, plug-ins, the output name, the format or codec) is refused with an error, not dropped. The output's extension follows the preset's container;outputs[0].by_param.presetgives each preset's kind and extension. - It runs the engine's own queue path (
queue.addSource,queue.start,encode.report,encode.verify) on a headless engine with a private, temporary data folder, so it never touches the person's queue, presets or preferences, and fails when the output does not verify. - Suggested defaults:
system/webm-vp9-1080pfor web video (VP9 is in the LGPL FFmpeg on every host; the H.264 presets such assystem/match-source-mediumneed a hardware encoder or OpenH264) andsystem/aac-256for audio only.
From a shell, in backend with the engine venv:
python -m app.functions run encode --inputs '{"media": "clip.mp4"}' --params '{"preset": "system/aac-256"}' --out out
python -m app.functions manifest --check
run prints the result as one JSON line (or {"error"} and exit 1). After changing presets or formats, python -m app.functions manifest --write rebuilds form-functions.json from the engine; backend/tests/test_functions.py fails while it drifts.
extensions_list and extension_command reach the extensions loaded in the window (see Extensions). Extension commands run in the open window, so they need one, and the first run of an extension version asks the person there.