Automate Video Rendering with the ExpoCut MCP & Render Engine

If you have ever tried to render the same video for fifty products, fifty listings, or fifty social handles on a phone, you have probably noticed that the phone is the bottleneck. This guide shows you how to keep the phone where it shines — design, AI editing, instant feedback — and move the rendering itself onto a real desktop or a build server. The piece that makes this possible is that both halves speak the same project format.

1. Why combine the two?

Think of ExpoCut as two surfaces with the same brain in the middle:

• The mobile app is where projects are designed — by you, by an AI assistant over the in-app MCP server, or by importing a .ectpl template.
• The Render Engine is where projects get turned into finished video — on a developer laptop, a build server, a render farm, or a CI pipeline.

Both speak the same project JSON and the same .ectpl template format. Anything the app exports, the engine can render — pixel-for-pixel. Anything the engine accepts, an AI agent can author programmatically. That symmetry is what lets you treat video like data and rendering like a build step.

2. The pipeline at a glance

The full loop has six links. You will rarely need them all on the same day — most workflows only touch three or four — but it is helpful to see them together.

┌────────────┐   MCP    ┌────────────┐   export    ┌──────────────┐   render    ┌─────────┐
│ AI Agent   │ ───────▶ │ Mobile App │ ──────────▶ │   .json /    │ ──────────▶ │  MP4 /  │
│ (Claude,   │   tools  │ (iOS /     │   project   │   .ectpl     │   engine    │  HLS /  │
│  ChatGPT…) │ ◀─────── │  Android)  │             │  on disk     │             │ frames  │
└────────────┘  preview └────────────┘             └──────┬───────┘             └─────────┘
                                                          │
                                                  data ───┤
                                                  rows    │  expocut-engine fills slots
                                                  / CSV   │  → one MP4 per row
                                                          ▼
                                                   ┌──────────────┐
                                                   │  out/*.mp4   │
                                                   └──────────────┘

3. Prerequisites

You need three things before any of the steps below work. Do them once and you are done.

1. ExpoCut installed on your phone — the App Store or Google Play link.
2. The Render Engine on your computer. Follow the install steps for macOS, Windows, or Linux. While you are there, install ffmpeg with the same package manager — it is needed for MP4 and HLS output.
3. (Optional) An MCP-compatible AI client. Claude Desktop, Claude in your IDE, or any other tool that speaks Model Context Protocol. You only need this for Parts 2 and 9.

Verify both halves are reachable:

# on your computer
expocut-engine --version
ffmpeg -version | head -n 1

4. Part 1 — Hello, headless render

Before doing anything fancy, render one project end-to-end. This proves the engine is installed and gives you a baseline to compare against.

1. Open any project in the app

   Any project will do — a fresh blank one with a single text layer is enough.

2. Tap Export Project

   Find it in the project menu (the three-dot button at the top of the editor). The app writes a small JSON file. Share it to your computer the usual way and save it as my-project.json.

3. Render

   expocut-engine mp4 my-project.json --out my-project.mp4

   Open the resulting .mp4. You should see the same composition you saw in the app's preview — same text, same colours, same timing. If not, jump to Troubleshooting.

5. Part 2 — Drive the app from an AI agent

This is where the Model Context Protocol comes in. ExpoCut's in-app MCP server exposes 190+ typed tools — add layers, apply effects, tweak transforms, run a template, export a project — to any AI client that can talk to it. The agent and the app live on the same Wi-Fi network; nothing leaves your house.

1. Turn the MCP server on

   In ExpoCut: Settings → AI & Automation → MCP Server. Toggle it on. The screen shows a URL like http://192.168.1.42:7080/mcp and a single-tap auth token. The server is off by default and binds only to your local Wi-Fi.

2. Add the connector in your AI client

   In Claude Desktop, for example, open Settings → Connectors → Add, paste the URL and the token. Claude then sees the full ExpoCut tool surface — explore it with list_tools, or just ask the assistant "What can you do in ExpoCut?".

3. Ask the agent to design something

   A real prompt:

   # in Claude (or any MCP client)
   Create a new 9:16 project, 8 seconds long.
   Drop a bold title "JUST LISTED" with a typewriter entrance.
   Add a lower-third in the bottom third with my brand colour
   (#CF4C4E) showing "123 Main St · $899k".
   Finish with a slide-up exit on every text layer.

   The agent calls create_project, add_text_layer, apply_glyph_anim, add_lower_third, set_transition, and so on — each as an undoable step the app records in its history. Watch the timeline build itself in front of you.

4. Capture the result

   Ask the agent to capture_canvas at a few timestamps to verify the layout, then call export_project. The exported project lands in the app's files; share it to your computer as in Part 1.

6. Part 3 — Export & ingest the project

However the project was authored — by hand, by an agent, by importing a template — it ends up as a small JSON file. The engine will accept the mobile-app export directly, but you can also normalise it to canonical engine JSON first for source control or for diffing.

# optional: convert the mobile export into the engine's canonical JSON
expocut-engine import phone-export.json --out project.json
# now project.json is a clean, version-controllable description of the video

Either file is a legitimate input to every render command — the engine detects which shape it received and adapts.

7. Part 4 — Import a .ectpl template

The most powerful pattern in the whole pipeline is template + data. A .ectpl template (see the format guide) is a recipe with named slots. You design it once in the app, then fill it with different content for every render.

Where templates come from

• From the app: design a project, then Save as Template. ExpoCut auto-detects slots (full-bleed video / image become media slots, text becomes text slots, lower-third lines become their own slots).
• From the gallery: open the template gallery in the app and tap the share / export icon on any built-in template to get its .ectpl file.
• Hand-authored: a .ectpl is plain JSON. An AI agent or a developer can write one directly — useful for brand-locked or programmatic templates.

Listing a template's slots from the command line

Before filling a template, check what it expects:

expocut-engine import templates/just-listed.ectpl --describe
# prints something like:
# slots:
#   title         text       (default: "Just Listed")
#   address       text       (default: "123 Main St")
#   price         text       (default: "$899k")
#   media_1       image|video
#   media_2       image|video
#   media_3       image|video
#   agent_name    text       (default: "Your Agent")
#   logo          image
#   accent_color  color      (default: #CF4C4E)

8. Part 5 — Fill slots from data

Now render the template with real content. There are two equivalent ways to feed slot values: one-off flags on the command line, or a JSON file that bundles every value together.

Inline flags (one-off renders)

expocut-engine mp4 templates/just-listed.ectpl \
  --slot title="JUST LISTED" \
  --slot address="742 Evergreen Terrace" \
  --slot price="\$1.2M" \
  --slot media_1=./photos/front.jpg \
  --slot media_2=./photos/kitchen.jpg \
  --slot media_3=./photos/backyard.jpg \
  --slot agent_name="Jane Doe" \
  --slot logo=./brand/logo.png \
  --slot accent_color=#2E5BFF \
  --out evergreen.mp4

A slot-fill JSON (scripted renders)

For anything more than a handful of values, write a small JSON file and point the engine at it:

// listing-evergreen.json
{
  "title":        "JUST LISTED",
  "address":      "742 Evergreen Terrace",
  "price":        "$1.2M",
  "media_1":      "./photos/front.jpg",
  "media_2":      "./photos/kitchen.jpg",
  "media_3":      "./photos/backyard.jpg",
  "agent_name":   "Jane Doe",
  "logo":         "./brand/logo.png",
  "accent_color": "#2E5BFF"
}

expocut-engine mp4 templates/just-listed.ectpl \
  --slots-from listing-evergreen.json \
  --out evergreen.mp4

This second form is what AI agents and bulk scripts use — write a slot-fill JSON per row, render in a loop.

9. Part 6 — Bulk render in parallel

Once one render works, every render works. The engine is independent across runs, so you can fan out across CPU cores. Two common shapes:

Shell loop with parallelism

# listings.csv: address, photo_1, photo_2, photo_3, agent, logo, accent

cat listings.csv \
  | xargs -P 4 -I{} sh -c '
      IFS=, read addr p1 p2 p3 agent logo accent <<< "{}"
      slug=$(echo "$addr" | tr -c "A-Za-z0-9" "-")
      expocut-engine mp4 templates/just-listed.ectpl \
        --slot title="JUST LISTED" \
        --slot address="$addr" \
        --slot media_1="$p1" --slot media_2="$p2" --slot media_3="$p3" \
        --slot agent_name="$agent" --slot logo="$logo" \
        --slot accent_color="$accent" \
        --out "out/$slug.mp4"
    '

A Python orchestrator

# bulk_render.py
import csv, json, subprocess, pathlib, concurrent.futures as cf

def render(row):
    out = pathlib.Path("out") / f"{row['address']}.mp4"
    fill = pathlib.Path("out") / f"{row['address']}.json"
    fill.write_text(json.dumps(row))
    subprocess.run([
        "expocut-engine", "mp4", "templates/just-listed.ectpl",
        "--slots-from", str(fill),
        "--out", str(out),
    ], check=True)

with open("listings.csv") as f, cf.ProcessPoolExecutor(max_workers=8) as pool:
    pool.map(render, csv.DictReader(f))

For a couple of dozen listings either approach finishes while you make coffee. For tens of thousands of clips, you would point the same script at a build server or a render farm — it does not change a line.

10. Part 7 — Live preview server

Sometimes you want to see the render happen — while you tweak slot values, while an AI agent edits, or as a virtual camera into OBS. The engine ships a tiny HTTP server that streams the live composition as MJPEG.

expocut-engine serve project.json --port 8787
# open http://localhost:8787 in any browser
# or add it as an MJPEG source in OBS

Combine this with the MCP loop in Part 9 and you have a live AI-driven editor on your desk: the agent edits the project on the phone, the engine paints the new composition on your laptop, and the browser window updates in real time.

11. Part 8 — Wire it into CI

Because the engine is deterministic — same input, same pixels — you can use it as a build step. The two patterns we recommend:

• Reference-frame snapshot tests. Commit a project JSON and a reference PNG. In CI, render a frame at the same timestamp and assert it matches.
• Smoke renders on every PR. Render a 1-second smoke version of each shipping template to catch broken slots or missing assets before a designer notices.

GitHub Actions example

# .github/workflows/video-snapshots.yml
name: video-snapshots
on: [pull_request]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install ffmpeg
        run: sudo apt-get install -y ffmpeg
      - name: Install ExpoCut engine
        run: |
          curl -L https://expocut.com/download/expocut-engine-linux.tgz \
            | tar -xz -C /usr/local/bin
          chmod +x /usr/local/bin/expocut-engine
      - name: Snapshot frame
        run: |
          expocut-engine frame fixtures/promo.json --at 1500ms --out actual.png
          cmp actual.png fixtures/promo-1500ms.png

12. Part 9 — A loop that runs itself

Once both halves are in place, you can hand the whole pipeline to an AI agent. The agent uses MCP to plan and edit on the phone, then triggers an engine render through a local shell tool. Here is the prompt shape that works well — give it to Claude (or any agent that can call MCP tools and run shell commands):

# prompt for an AI agent that has both:
#   - ExpoCut MCP connector (configured per Part 2)
#   - shell access on the laptop with `expocut-engine` on PATH

You are a video-automation agent. For each row of `listings.csv`:

  1. Use the ExpoCut MCP tools to load `templates/just-listed.ectpl`
     and write a slot-fill JSON describing the row.
  2. Capture the canvas at 500 ms and 5500 ms; verify the layout
     looks right (no text overflow, photos cropped sensibly). If
     something is wrong, adjust the slot values and re-capture.
  3. Run `expocut-engine mp4 templates/just-listed.ectpl
     --slots-from <the json> --out out/<slug>.mp4` via the shell.
  4. Move to the next row.

Stop when every row has a corresponding MP4 in `out/`.

This is the loop that makes "treat video like data" real. The agent designs, verifies, renders, and moves on — you watch the out/ folder fill up.

13. Troubleshooting

The MP4 is missing audio

Most often ffmpeg is not on the engine's PATH, so the engine falls back to a video-only output. Run ffmpeg -version in the same shell; if it errors, install it and retry.

The AI client cannot reach the MCP server

Both devices must be on the same Wi-Fi. Some corporate networks block peer-to-peer traffic — switch to a personal hotspot to verify the connector itself is fine. The URL shown in Settings → MCP Server is authoritative; if your phone moves networks the URL changes.

A slot value is rejected

Slots are typed. media_* slots accept a path to an image or a video. text slots accept any string. color slots accept hex (#RRGGBB) or named CSS colours. Pass --describe to see the slot types of any template.

The render runs but the output is solid black

Almost always a missing asset. Run with --log-level info — the engine logs every layer it loads and the first missing source file will show up there.

I want the render to be faster

Three knobs help:

• Parallelism. Render multiple jobs side by side. The engine is single-process per render but happily runs N renders at once across cores.
• Resolution. Add --scale 0.5 to render at half resolution for previews; drop it for the final.
• Accelerator. Pass --accelerator auto to let the engine engage a GPU compositor when one is available; fall back to CPU automatically.

14. FAQ

Can I use the MCP server without an AI assistant?

Yes. The tools are plain JSON-RPC; any HTTP client can call them. People use the MCP surface from Python scripts, shell scripts, and small custom dashboards.

Can I use the Render Engine without the mobile app?

Yes. The engine accepts hand-written or AI-generated project JSON and .ectpl templates with no app round-trip required. The app just happens to be the easiest authoring tool.

Will my projects keep working as ExpoCut evolves?

Yes. Project JSON and .ectpl both carry a schemaVersion. Newer engines read older projects; new features only kick in when a project's schema declares them.

Where do I learn more about the template format?

Read "How to Use .ectpl" — the long-form guide to slots, layer prototypes, the brand-binding inflater, the percentage-based canvas, and the asset bundle.

Is any of this billed?

No. The MCP server runs on your phone and the engine runs on your machine. Availability follows the plan shown in the app, and there is no separate per-render charge.