.ectpl

A recipe for a video, not a video.

An .ectpl file carries no frames. It carries the instructions that produce frames — which is why it is a few hundred kilobytes instead of a few hundred megabytes, why one file can generate a thousand different videos, and why a machine can write one.

Two physical forms

Both carry the same document. The zip form exists so a template can travel with its own media, fonts and thumbnail.

How it is detected

Detection runs in a fixed order — filename extension, then magic bytes, then a leading-token probe over the first 4 KB. The probe never throws; it returns a format and a confidence so an importer can explain an unsupported file instead of failing silently.

Anatomy of the archive.

The bundle is a standard PKZIP archive written to APPNOTE 6.3.6 — readable by every mainstream unzip tool — with one deliberate restriction: every entry is STORED, never deflated.

my-template.ectpl          ← a zip file
├── template.json          REQUIRED — the document, at the archive root
├── thumbnail.jpg          optional — jpg | jpeg | png | webp, ≤ 512 KB
├── preview.mp4            optional — silent looping demo
└── assets/
    ├── 9f2c4a1b7e05d3f8.mp4   named by the first 16 hex of its sha256
    ├── 1a77be90c4d21f6e.jpg
    └── e30b5c8812af74d9.mp3

Why STORED and never DEFLATE

This is a performance decision, not an oversight, and it has four consequences worth understanding if you are writing an .ectpl yourself:

• The media inside is already compressed. JPEG, MP4 and MP3 give DEFLATE roughly 1–2% for real CPU cost on a phone.
• The document is mostly numbers and short strings — it compresses well, but it is typically under 200 KB anyway, so the saving is noise.
• No compression means no decompression. A reader can map an entry straight out of the archive, which keeps import fast and allocation-free.
• A store-only reader has no zip-bomb surface to defend against: the compressed size and the uncompressed size are the same number.

Entry-name rules

Both the writer and the reader enforce the same rules, so anything ExpoCut writes also validates on the way back in. An entry name must be forward-slash separated, at most 1024 characters, and must not be absolute, contain a backslash, a drive prefix, a NUL byte, or a .. segment.

The template document.

Everything a video needs, in one object. Required fields are marked; everything else is optional and defaults to something safe at inflate time.

// The smallest valid .ectpl — one slot, one track, one animated layer.
{
  "schemaVersion": "1.1",
  "mode": "template",
  "id": "quote-card-01",
  "name": "Quote Card",
  "category": "Promo",
  "aspectRatio": "9:16",
  "durationMs": 5000,

  "slots": [
    { "id": "headline", "label": "Headline", "kind": "text",
      "required": true, "default": "Say something true" }
  ],

  "tracks": [
    { "id": "t0", "type": "overlay", "name": "Headline", "trackIndex": 0 }
  ],

  "layers": [
    {
      "id": "l0", "type": "text", "trackIndex": 0,
      "startTime": 0, "duration": 5000,        // milliseconds
      "slotRef": "headline",
      "content": "Say something true",
      "position": { "x": 0, "y": 44 },       // percent of canvas
      "textFullWidth": true, "textAlign": "center",
      "fontSize": 34, "scale": 1, "rotation": 0,
      "keyframes": {
        "tracks": [
          { "property": "opacity",
            "keyframes": [
              { "t": 0,      "v": 0, "out": { "type": "preset", "name": "easeOut" } },
              { "t": 400000, "v": 1 }   // MICROSECONDS — 0.4 s
            ] }
        ]
      }
    }
  ]
}

A recipe, or the actual edit.

This is the first decision, and it changes every field that follows. Pick wrong and the file is either uselessly generic or impossible to reuse.

The stage, and how you place things on it.

aspectRatio and durationMs define the stage. Everything else is positioned as a percentage of that stage, never in pixels — which is exactly why one template renders correctly at every export resolution.

Units, in one table

Two things that surprise everyone

Layers scale about their own centre

At scale ≠ 1 a layer's visual creeps toward the canvas centre (when shrinking) or away from it (when growing). That is why a logo often sits at a slightly negative y — you push the anchor up to counter the drift. Do not try to solve this in your head; place it, look at a real frame, measure, correct.

Text has two placement modes

• textFullWidth: true — the text box spans the whole canvas width and textAlign places the glyphs. Set position.x: 0; only y matters. This is how you centre a headline.
• textFullWidth: false — a free box anchored by x. Use it for a left-aligned column or a label that sits beside another element.

Matching a source design (a poster, a Figma frame, a screenshot) is a direct conversion:

x%       = px_x / designWidth  × 100
y%       = px_y / designHeight × 100
fontSize = px_fontsize × 0.366        (on a 1080-wide reference)

The holes a person — or a script — fills.

A slot declares one editable input. A layer opts into it with slotRef. Many layers can share one slot, which is how a single "Brand colour" input re-tints six elements at once.

Slot kinds

Slot fields

• id, label, kind — required. Ids must be unique within the document.
• required — when true and unfilled, the layer that depends on it is dropped and the project reports the slot as unfilled.
• default — fallback for text slots.
• preferredDurationMs — a UX hint: "this slot looks best at about this length".
• bindFromBrand — auto-fills from the user's saved brand profile: logo, name, slogan, website, phone, email, address.
• defaultBinding — a pre-bound value carrying the asset's original remote URL, so a template previews correctly on a device that never had the author's local file.

Resolution priority

Every slot resolves once, before any layer is built, so layers sharing a slot always agree:

Slot values

{ "kind": "media",  "uri": "…", "remoteUrl": "…", "posterUri": "…",
                       "durationMs": 0, "width": 0, "height": 0 }
{ "kind": "text",   "value": "…" }
{ "kind": "color",  "hex": "#7C5CFF" }
{ "kind": "number", "value": 42 }
{ "kind": "angle",  "degrees": -6 }
{ "kind": "point",  "x": 50, "y": 42 }
{ "kind": "scale",  "x": 1,  "y": 1 }

One index, two meanings.

trackIndex is both the timeline row a layer occupies and its z-order in the composite. Higher renders on top.

{ "id": "t3", "type": "overlay", "name": "Headline", "trackIndex": 3 }

Sequential clips are the case people get wrong: three shots that play one after another still need three distinct trackIndex values, not one shared row.

Everything visible or audible.

A layer prototype is a partial layer: the five required fields plus any property the editor's layer model supports. There is no parallel data model — what you write here is what the editor holds after inflate.

Always required

id          string   unique within the document
type        enum     see the catalogue below
startTime   number   milliseconds from the start of the timeline
duration    number   milliseconds
trackIndex  number   z-order and timeline row — unique per layer

Common optional properties

slotRef, name, content, position, scale / scaleX / scaleY, rotation, blur, overlayColor, colorGradeDelta, keyframes, cameraEnabled, z (parallax depth, −1…+1), plus a per-type config object.

Layer types

Widget types carry a matching config object — tickerConfig, scoreboardConfig, pollConfig, barChartRaceConfig, and so on. A generativeBg or proceduralFilter layer names its shader through effectId, which is a real id from the live effects catalogue. A brush-stroke layer is a shape whose shapeConfig sets type: "custom_path" plus the stroke geometry (pathData, pathViewW, pathViewH) — bundled brush ids come from the list_brushes catalogue.

Keyframes.

Any layer may carry a keyframes object. The model is deliberately vector-animation-shaped, which is what makes mechanical Lottie import and export possible in both directions.

"keyframes": {
  "tracks": [                // scalar property tracks
    { "property": "transform.scale",
      "timeMode": "absolute",   // or "relative" (0..1 of clip duration)
      "keyframes": [
        { "t": 0,       "v": 1.0, "out": { "type": "preset", "name": "bounce" } },
        { "t": 600000,  "v": 1.18 }
      ] }
  ],
  "positionTrack": { … },   // grouped 2D motion path, wins over transform.x/.y
  "discreteTracks": [ … ]   // held-step values that must not tween
}

Interpolation

out describes how a value leaves its keyframe toward the next one. The last keyframe's out is meaningless. Four shapes:

Animatable properties

Held-step tracks cover values you switch rather than tween: text.fontWeight, text.italic, text.fontFamily, text.align, text.transform, border.pattern, border.glowMode, mask.shape, mask.invert, mask.mirrorAxis, transition.in.id, transition.out.id, shape.fillStyle, fitMode.

Assets that travel with the template.

When a template is packed into a zip, every local asset is hashed, de-duplicated, stored under assets/, and referenced from the layers as bundle://assets/<hash>.<ext>. The manifest that describes them lives under the document's bundle key.

"bundle": {
  "version": "1.0",
  "title": "Just Listed",
  "assets": [
    { "id": "a_9f2c4a1b7e05",
      "kind": "video",                    // font | lut | image | video | audio | data
      "path": "assets/9f2c4a1b7e05d3f8.mp4",
      "sizeBytes": 4812993,
      "sha256": "9f2c4a1b7e05d3f8…",
      "mimeType": "video/mp4" },

    { "id": "font-1", "kind": "font", "path": "assets/inter.ttf",
      "license": { "spdx": "OFL-1.1", "redistributable": true } }
  ]
}

De-duplication

Assets are keyed by sha256. A proxy and its original, or the same clip used by six layers, collapse into a single archive entry — the packer rewrites every reference to the one path. This is usually the difference between a 40 MB bundle and a 200 MB one.

Font licensing

Fonts are the one asset kind with a licence gate, because many font files simply cannot be redistributed. A bundled font must either be marked redistributable: true or carry an SPDX id from the open list:

OFL-1.1 · OFL-1.0 · Apache-2.0 · MIT · BSD-2-Clause · BSD-3-Clause · CC0-1.0 · Unlicense

Anything else is surfaced as a licence issue on the compatibility report rather than silently shipped. Other asset kinds default to permissible.

A template is untrusted input.

Anyone can hand you an .ectpl file. It could point a layer at a private file on your device, or at a URL that auto-downloads arbitrary bytes the moment you tap "use". So every import boundary — the OS file picker, a URL import, a share sheet, an MCP call, a reload from local storage — runs the same policy before the document reaches the editor.

URI scheme whitelist

Every URL-bearing field is walked: uri, posterUri, remoteUrl, previewVideoUri, thumbnail, src, audioUri, videoUri, imageUri, logoUri, maskUri — at any depth, up to 64 levels of nesting.

Privacy: the media strip

When a template is packed for public or community distribution, source footage is stripped by default. Video, image and audio layers lose their content URIs, proxies, freeze and reverse bakes, and their remote-source fallbacks. Everything that makes the template a template — structure, fonts, effects, transitions, positions, colours, keyframes, natural aspect ratios — survives untouched.

The receiver gets the design and must supply their own media before creating a project. Turning the strip off is a deliberate choice for content the author explicitly meant to publish verbatim: stock-only compositions, brand demos, their own product footage.

Every cap, in one place.

These are enforced, not advisory. A document that crosses one is refused with a message naming the field — which makes them a useful pre-flight checklist for anything generating templates programmatically.

From an edit, to a file, to a finished video.

Two directions. Neither has a hidden step — this is the whole path.

Packing

1. The project is serialized either as a slotified recipe or as a verbatim snapshot.
2. For a public share, the privacy strip clears source footage.
3. Every remaining local reference is collected from the known media-bearing fields — content, vector source, source media, media fill, proxy, and the freeze / reverse bake originals.
4. Each asset is hashed, de-duplicated, and rewritten to bundle://assets/<hash16>.<ext>.
5. The manifest is attached, the archive is written STORED, and a rendered demo clip — if there is one — is uploaded as a separate streamed part.

Unpacking

1. Sniff the magic bytes: a PK header takes the zip route, anything else takes the text route.
2. Probe the first 4 KB to classify the format and produce a confidence.
3. Read the archive and require template.json at the root.
4. Validate: schema version, required fields, structural arrays, one-layer-per-track, slot references, and the bundle manifest including font licences.
5. Security check: URI whitelist plus every cap in the table above.
6. Materialise: archive bytes are written into the app's /ectpl/<templateId>/ cache and every bundle:// URI is rewritten to the matching local path. Skipping this step is what produces the classic "text loaded but no video" bug.
7. Inflate: slots resolve, layers get fresh ids so two copies of the same template never collide, and the result is a normal project — layers, tracks and timeline clips.
8. Render: from here on there is no special-casing. It is an ordinary project, and the canvas and the export read the same data.

What the format costs, and what it buys.

Format decisions here were made against a phone, not a workstation. Each one trades a theoretical saving for predictable behaviour on a device that also has to decode video.

What actually costs you frames

The caps tell you what will be refused. This tells you what will be slow well before you reach them.

Impact

The practical consequence of all of this is leverage. One .ectpl file plus a spreadsheet is a video pipeline: the design cost is paid once, and every additional video costs a render. Because the format is declarative and the renderer is deterministic, the same file is safe to version in git, to diff in review, to assert against a reference frame in CI, and to hand to an agent that has never seen your project.

How the app and the engine use it.

In the mobile app

The editor is the reference implementation. A template enters through the Templates gallery, the community gallery, an import from URL, the OS file picker, or the share sheet — and leaves through Save as Snapshot or a community submission. Once inflated it is an ordinary project: the same timeline, the same effects, the same export path to on-device 4K.

Over MCP, for agents

ExpoCut's in-app MCP server exposes the whole lifecycle as typed tools, on a loopback or private network only. The MCP reference has the full surface; these are the template-relevant ones:

On a desktop, in bulk

The Render Engine is a single binary for macOS, Windows and Linux that reads the same .ectpl files and emits MP4, HLS, frame sequences, single frames or a live preview stream — no phone involved.

# listings.csv: address, photo_1, photo_2, photo_3, agent_name, agent_logo

while IFS=, read address p1 p2 p3 agent logo; do
  expocut-engine mp4 templates/just-listed.ectpl \
    --slot title="$address" \
    --slot media_1="$p1" --slot media_2="$p2" --slot media_3="$p3" \
    --slot agent_name="$agent" --slot logo="$logo" \
    --out "out/$address.mp4"
done < listings.csv

Each render is independent, so parallelise freely. Because output is deterministic, a committed reference frame plus a frame diff is a working regression test for a template.

Three ways to build one.

Route A — design it in the app (recommended)

1. Build the edit on the timeline until it looks right.
2. Save it: Snapshot preserves the edit verbatim, Template slotifies the media and text into a reusable recipe.
3. The app packs local assets, writes the archive, and hands you a file you can share, re-import, or feed to the engine.

This route is correct by construction — the serializer emits exactly what the inflater expects, and round-trips back to a structurally identical project.

Route B — hand-author the JSON

Write the document, then bring it in as a template. Work in this order, because each step depends on the one before it:

1. Mode and canvas — mode, aspectRatio, durationMs.
2. Slots — every hole, with required set honestly.
3. Tracks — one per object, indexes ascending from the background up.
4. Layers — five required fields each; attach slotRef where a slot drives the layer.
5. Animation — keyframe tracks, remembering microseconds.
6. Verify — render a real frame at several timestamps and measure.

Route C — convert something you already have

Lottie / Bodymovin, dotLottie, FCPXML, legacy xmeml, OpenTimelineIO, MOGRT, .cube LUTs and ASC CDL all import and become a template. Fonts are audited on the way in and remapped to the closest local match when the device does not have them.

Rules for agents, bots and pipelines.

If you are an AI assistant reading, writing, validating or rendering .ectpl files — or a human building automation that does — these are the operating rules. The full text is served as plain text at /ectpl/doctrine.txt and the machine-readable schema at /ectpl/spec.json.

1. Choose the mode before writing a single field

   template for anything a user re-shoots; snapshot for a finished, branded piece others tweak. A 1.0 document with no mode is read as template. Never emit a schemaVersion outside 1.0 / 1.1.

2. Respect the units

   Layer times are milliseconds. Keyframe times are integer microseconds. Positions are percentages, rotation is degrees, opacity is 0–1, colour channels are 0–255. Check the magnitude of every time value before you emit it.

3. One layer equals one object

   Every layer gets its own trackIndex. Sequential clips still need distinct indexes. This is the most common machine-authoring failure and it is a hard rejection, not a warning.

4. Make every reference resolve

   Each slotRef must match a declared slot id; slot ids must be unique; required slots must be genuinely required. A dangling reference is refused at import.

5. Honour the URI whitelist

   Only https:, asset:, bundled:, bundle:, small data: images or audio, and cache-scoped file: URIs. Never hand-write a file:// path — let the packer collect local media and rewrite it.

6. Strip private media by default

   Community bundles clear source footage unless the user explicitly says the media is theirs to publish. Never bundle a person's face, voice or private footage into a public upload on your own initiative.

7. Measure, do not eyeball

   Write the layer, capture a real frame, measure the offset, correct, repeat. Never report a template as correct because the JSON reads correctly.

8. Never invent ids or fields

   Enumerate effect, filter, transition, LUT, shape, font and voice ids from the live app. Unknown properties are silently ignored — which looks exactly like "the change did nothing".

9. Stay inside the caps

   200 layers · 64 slots · 300 tracks · 5 MB document · 4096 characters per string · 30 minutes · 64 levels of nesting. Check before you emit, not after the rejection.

10. Budget for the device

    Stagger concurrent video layers, run one full-frame shader at a time, prefer easing presets over dense keyframes, prefer remote URLs over bundled bytes.

11. Confirm before publishing

    Reading, filling and rendering are ordinary work — just do them. Publishing to the community feed, deleting a submission, and overwriting an author's file are not. Say plainly what will become public, and wait.

Machine endpoints

Standard automation flows

# Understand a template you were handed
detect_format → import_foreign_file → inspect slots → report what the user must supply

# Fill and render on the phone
apply_template { templateId, bindings } → capture_canvas → verify
  → set_export_settings → export_project

# Fill and render in bulk on a desktop
expocut-engine mp4 template.ectpl --slot key=value … --out file.mp4
  # one row of a CSV per render; independent and deterministic

# Author something new
build in the editor over MCP → save_project_as_template
  # (or import_template_json for a hand-authored document)
  → verify frames → submit_template ONLY when the user asks to publish

What comes in, what goes out.

What a rejection means.

Questions people actually ask.