Skip to content

A motion design studio on your own machine: Claude makes the video step by step, you approve every stage. Bring your own Claude Code or API key.

Transition board: every cut designed before the animatic

Gerrod Noordsyf2688ec39834
diff --git a/.gitignore b/.gitignore
index 3c45938..aaa9fbc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,5 @@
node_modules/
*.log
.DS_Store
+__pycache__/
+*.pyc
diff --git a/README.md b/README.md
index c5e080c..f5e5e77 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ Claude makes the video step by step. You approve every stage.</p>
---
Most "AI video" tools are one prompt and a slot machine. Mortiflix works like a real motion design studio:
-a brief, a script, style frames, an animatic, a final, and **you review each stage** before the next one starts.
+a brief, a script, style frames, a transition board, an animatic, a final, and **you review each stage** before the next one starts.
You pin a note on the exact spot of a frame or the exact moment of a video. The next version answers every note,
one by one, and shows you what changed.
@@ -112,8 +112,8 @@ For scripts: `echo "$KEY" | mortiflix keys set elevenlabs`.
| Pipeline | Steps you review | Good for |
|---|---|---|
-| `explainer` | brief → script → style frames → animatic → music → final | 30 s to 2 min explainers, narrated or not, with an original score |
-| `social-short` | brief → hook frames → final | 15–45 s vertical shorts: hook first, works with sound off |
+| `explainer` | brief → script → style frames → transitions → animatic → music → final | 30 s to 2 min explainers, narrated or not, with an original score |
+| `social-short` | brief → hook frames → transitions → final | 45 s to 3 min vertical shorts: hook first, works with sound off |
| `logo-sting` | directions → final | a 3–8 s logo animation; the quickest real run |
They build in [Remotion](https://www.remotion.dev/) (React video) and check every render with ffmpeg (`qc.mjs`:
@@ -140,6 +140,15 @@ Pick a voice in **Settings › Narration** (or `mortiflix voice`):
Generated lines are checked by speech to text and retaken if words go missing; word timings drive the animation.
Details: [docs/VOICE.md](docs/VOICE.md).
+## Transitions
+
+Before the animatic, every project gets a **transition board**: for each change from one style frame to the next,
+the object or idea on screen that carries it, why the cut happens there, the word it lands on, and real in-between
+frames rendered from the two style frames and the chosen transition. Transitions come from the
+[remotion-transitions](https://github.com/GTKottman/remotion-transitions) library (installed by setup), or are new
+ones inspired by it. The screen never goes blank: no dip to a flat colour, no flash to white. A check reads every
+10% of every transition and fails any frame that does.
+
## Setup: music, assets and 3D
`mortiflix setup` (or **Settings › Setup**) explains each part, why it's needed and what it installs, then asks.
diff --git a/docs/SETUP.md b/docs/SETUP.md
index fb990bb..9b5c9ac 100644
--- a/docs/SETUP.md
+++ b/docs/SETUP.md
@@ -10,6 +10,7 @@ never system-wide and never as root. Deleting `tools/` removes it all.
| Part | Why | What it installs | Size |
|---|---|---|---|
| **Claude** | Claude does the work: writing, design, animation, checks | nothing (your Claude Code login), or your Anthropic API key in `secrets.json` | |
+| **Transitions** | every cut is designed on the transition board, from a library of 50 | the remotion-transitions library, into `tools/remotion-transitions` | ~5 MB |
| **Narration** | a voice reads the script; the animation is timed to its words | an ElevenLabs key, **or** ComfyUI + the TTS Audio Suite (Qwen3-TTS) on your NVIDIA card, **or** nothing | ComfyUI ~10 GB with models |
| **Music** | an original score, written to the approved animatic | Strudel (`@strudel/web` from npm) and a headless Chrome (yours is reused) | ~20 MB (+~100 MB without Chrome) |
| **Assets** | stock assets from sites you already use, in your own Chrome | browser-harness (browser-use, via uv) and the list of your sites | ~60 MB |
diff --git a/harness/skills/blender-3d/__pycache__/mfx3d.cpython-314.pyc b/harness/skills/blender-3d/__pycache__/mfx3d.cpython-314.pyc
deleted file mode 100644
index 4c8de6b..0000000
Binary files a/harness/skills/blender-3d/__pycache__/mfx3d.cpython-314.pyc and /dev/null differ
diff --git a/pipelines/_shared/skills/remotion-motion/setup.mjs b/pipelines/_shared/skills/remotion-motion/setup.mjs
index a825b9e..c033140 100644
--- a/pipelines/_shared/skills/remotion-motion/setup.mjs
+++ b/pipelines/_shared/skills/remotion-motion/setup.mjs
@@ -6,7 +6,7 @@
// Remotion with its own Chrome is ~750 MB and half a minute to install. The studio installs the template's exact
// dependencies once (in $MFX_SHARED, keyed by the template's package.json) and each project links to it, so a new
// project costs kilobytes and no download. Outside a Mortiflix session (no $MFX_SHARED) it installs locally.
-import { existsSync, mkdirSync, cpSync, symlinkSync, readFileSync, writeFileSync, rmSync, lstatSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, cpSync, symlinkSync, readFileSync, writeFileSync, rmSync, lstatSync, statSync, realpathSync } from 'node:fs';
import { join, dirname, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { createHash } from 'node:crypto';
@@ -24,22 +24,44 @@ if (!existsSync(join(target, 'src'))) {
} else console.log(`${target}: already set up (src/ kept)`);
const modules = join(target, 'node_modules');
+const shared = process.env.MFX_SHARED || null;
+const pkg = readFileSync(join(template, 'package.json'));
+const dir = shared ? join(shared, `remotion-${createHash('sha256').update(pkg).digest('hex').slice(0, 12)}`) : null;
+
if (existsSync(modules) || isLink(modules)) {
+ // Linked to an older shared install while the template has since gained packages (e.g. @remotion/transitions):
+ // move to the current one, unless this project added packages of its own.
+ if (dir && isLink(modules) && realpathOr(modules) !== realpathOr(join(dir, 'node_modules'))) {
+ const mine = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8'));
+ const tpl = JSON.parse(pkg);
+ const ownExtras = Object.entries(mine.dependencies || {}).filter(([k, v]) => tpl.dependencies?.[k] !== v);
+ if (!ownExtras.length) {
+ ensureShared();
+ rmSync(modules);
+ symlinkSync(join(dir, 'node_modules'), modules, 'dir');
+ writeFileSync(join(target, 'package.json'), JSON.stringify({ ...mine, dependencies: tpl.dependencies, devDependencies: tpl.devDependencies }, null, 2) + '\n');
+ console.log(`node_modules: moved to the studio's current shared install (the template gained packages): ${dir}`);
+ process.exit(0);
+ }
+ }
console.log(`node_modules: already there (${isLink(modules) ? 'linked to the studio\'s shared install' : 'a local install'})`);
process.exit(0);
}
-const shared = process.env.MFX_SHARED || null;
if (!shared) {
run(npm, ['install', '--no-audit', '--no-fund'], target);
console.log('node_modules: installed locally');
process.exit(0);
}
-const pkg = readFileSync(join(template, 'package.json'));
-const dir = join(shared, `remotion-${createHash('sha256').update(pkg).digest('hex').slice(0, 12)}`);
-const done = join(dir, '.installed');
-if (!existsSync(done)) {
+ensureShared();
+symlinkSync(join(dir, 'node_modules'), modules, 'dir');
+console.log(`node_modules: linked to the studio's shared install (${dir})`);
+console.log('Need another package? Replace the link with a local install first: rm node_modules && npm install && npm install <pkg>');
+
+function ensureShared() {
+ const done = join(dir, '.installed');
+ if (existsSync(done)) return;
mkdirSync(dir, { recursive: true });
// One installer at a time (a lock directory; a stale one after 15 minutes is taken over).
const lock = join(dir, '.installing');
@@ -61,10 +83,8 @@ if (!existsSync(done)) {
rmSync(lock, { recursive: true, force: true });
}
}
-symlinkSync(join(dir, 'node_modules'), modules, 'dir');
-console.log(`node_modules: linked to the studio's shared install (${dir})`);
-console.log('Need another package? Replace the link with a local install first: rm node_modules && npm install && npm install <pkg>');
+function realpathOr(p) { try { return realpathSync(p); } catch { return p; } }
function isLink(p) { try { return lstatSync(p).isSymbolicLink(); } catch { return false; } }
function run(cmd, args, cwd) {
const r = spawnSync(cmd, args, { cwd, stdio: 'inherit' });
diff --git a/pipelines/_shared/skills/remotion-motion/template/package.json b/pipelines/_shared/skills/remotion-motion/template/package.json
index 7d6adac..0910e12 100644
--- a/pipelines/_shared/skills/remotion-motion/template/package.json
+++ b/pipelines/_shared/skills/remotion-motion/template/package.json
@@ -10,6 +10,7 @@
"dependencies": {
"@remotion/cli": "4.0.532",
"@remotion/google-fonts": "4.0.532",
+ "@remotion/transitions": "4.0.532",
"react": "19.3.0",
"react-dom": "19.3.0",
"remotion": "4.0.532"
diff --git a/pipelines/_shared/skills/transition-board/SKILL.md b/pipelines/_shared/skills/transition-board/SKILL.md
new file mode 100644
index 0000000..7a48d1a
--- /dev/null
+++ b/pipelines/_shared/skills/transition-board/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: transition-board
+description: Designing every cut of a video before the animatic - for each change from one style frame to the next, the object or idea that carries it, a transition chosen from the owner's remotion-transitions library (or a new one inspired by it), its timing on the narration, and a board panel showing the real in-between frames. Use for any transitions step, or when a cut changes.
+---
+
+# The transition board
+
+Every cut is designed. Between each style frame and the next there is **something that carries the change**: a
+shape that grows, a line that leads the eye, a camera that moves, an element that becomes another. A transition
+without a carrier and a reason doesn't go on the board.
+
+**The screen never goes blank.** No transition fills the frame with a colour (a cover or dip to purple, black or
+any flat colour) or blows it out to white (a flash or light leak to white). The scenes' own elements do the
+transition: they move, grow, open, fold, carry the eye, or a real object (2D or 3D) passes through the frame and
+brings the next scene with it. `board.mjs check` looks at every 10% of each transition and fails a frame that is
+flooded with a colour neither scene has, blown out, or emptied of the scenes' elements. Library transitions that
+work by covering the frame (most of `04-cover`, dips, flashes) are only usable if the cover itself is made of the
+scenes' elements; otherwise choose another or make a new one.
+
+The transitions come from the owner's library, [remotion-transitions](https://github.com/GTKottman/remotion-transitions)
+(`$MFX_TRANSITIONS`): 50 transitions in nine families, each a drop-in `<TransitionSeries>` presentation with a
+catalog entry and a preview.
+
+```
+B=.claude/skills/transition-board/board.mjs
+node $B list [--function section-break] [--family 04-cover] # choose
+node $B use liquid-fill flash ... # copy them (and their core) into video/src/transitions/
+node $B posters # the library's preview stills, for the board
+node $B check # the rules: must pass
+node $B panels # one review image per cut
+```
+
+## 1. Learn the library
+
+Read `$MFX_TRANSITIONS/TAXONOMY.md` (the nine families, how each works, timing and craft) and skim the catalog with
+`node $B list`. Each entry says what it's for (`function`: continuity, energy, section-break, reveal, progression,
+contrast, brand…), how it's built (`structure`, `origin`, `edge`), its length range in frames, and its parameters.
+Most take `color`: **the incoming scene's background colour**, so the change arrives through a shape in the new
+scene's own colour.
+
+## 2. Find each cut's carrier
+
+Go through the approved script and style frames in order. For every change of scene, before choosing anything, write:
+
+- **The carrier**: the object or element in the frames that makes the change happen. Look at both frames: what in
+ the outgoing frame can lead into the incoming one (the `$` in the price, the terminal window, the stage track's
+ next node, the mark, a line of text, the light)? A good carrier is already on screen.
+- **Why**: what the cut means in the story, in one sentence: continuity (the same idea, carried on), a turn (the
+ story changes direction), a section break, a reveal, a rise in energy, a breath.
+- **Where it lands**: the word or beat in the narration the cut lands on.
+
+## 3. Choose the transition
+
+Pick from the library by what the cut means and what carries it, not for variety's sake:
+
+- **Continuity** inside a section: quiet families (blend, a carry, a match cut, a short motion move).
+- **Section breaks and turns**: the bigger moves (carries, portals, a 3D object through the frame, motion with
+ weight), reserved so they mean something.
+- **A vocabulary**: two to four families across the whole video, used consistently (the same kind of cut means the
+ same kind of change). The check warns when one family dominates or when there are too many.
+- **Length**: inside the transition's range, and long enough to read under the narration; snap cuts on beats,
+ slower ones in breaths.
+
+**3D carriers.** A real 3D object can carry a cut: a wobbling sphere that flies at the camera and fills the lens
+as it passes, revealing the next scene behind it; a ribbon or a swarm that sweeps across. Render it in the
+studio's Blender (blender-3d skill) as a transparent image sequence (`-F PNG`, RGBA, film transparent) and use it
+as the transition's layer, with the outgoing scene before it passes and the incoming scene after. The object is the
+carrier, never a flat cover: the scenes stay visible around and through it.
+
+**If nothing in the library fits**, design a new one, inspired by the library entries closest to it: write it in the
+library's format (`transition.json` + `index.tsx`, built on `video/src/transitions/core`) in
+`video/src/transitions/<new-id>/`, and mark it on the board as `{"new": "<new-id>", "inspired_by": ["<id>", …]}`.
+Never edit the library itself (it's the owner's repository; a new transition worth sharing can be proposed there
+through its CONTRIBUTING protocol later, by the owner).
+
+Write `transitions/board.json`:
+
+```json
+{ "cuts": [
+ { "from": "SF01 · The hook", "to": "SF02 · The turn",
+ "a": "out/frames/sf01.png", "b": "out/frames/sf02.png",
+ "carrier": "the gradient inside the $5,400",
+ "why": "The price's colour floods the frame and drains away into the promise: the cost dissolves.",
+ "transition": "liquid-fill", "params": { "color": "#0B0913" }, "frames": 96,
+ "lands_on": "\"Now\", the first word of beat 2",
+ "mids": ["out/board/cut-01-35.png", "out/board/cut-01-65.png"],
+ "strip": ["out/board/cut-01/10.png", "…", "out/board/cut-01/90.png"] }
+] }
+```
+
+Cuts run through the scenes in order (each starts where the last ended). Run `node $B check` until it passes.
+
+## 4. Copy the transitions into the video
+
+`node $B use <id> …` copies the library's `core/` and each chosen transition into `video/src/transitions/` with
+their imports fixed. Use them exactly as the library says:
+
+```tsx
+import { TransitionSeries, linearTiming } from '@remotion/transitions';
+import { toPresentation } from './transitions/core';
+import liquidFill from './transitions/liquid-fill';
+
+<TransitionSeries.Transition presentation={toPresentation(liquidFill, { color: '#0B0913' })}
+ timing={linearTiming({ durationInFrames: 96 })} />
+```
+
+Always `linearTiming` (each transition does its own easing). Transitions whose catalog entry `requires` `webgl2`
+render with `--gl=angle` (or `--gl=swangle` with no GPU). Keep every cut in one place in the video's code (one
+list of cuts), so a changed board changes the video in one edit.
+
+## 5. Render the in-betweens
+
+For each cut, a board composition puts the two style frames in a `<TransitionSeries>` with the chosen transition and
+renders real stills **from the transition itself**, at about 35% and 65% of its length, so the owner sees exactly
+how one frame becomes the next:
+
+```tsx
+const HOLD = 30; // frames of the outgoing still before the transition starts
+<TransitionSeries>
+ <TransitionSeries.Sequence durationInFrames={HOLD + cut.frames}><Still src={cut.a} /></TransitionSeries.Sequence>
+ <TransitionSeries.Transition presentation={...} timing={linearTiming({ durationInFrames: cut.frames })} />
+ <TransitionSeries.Sequence durationInFrames={HOLD + cut.frames}><Still src={cut.b} /></TransitionSeries.Sequence>
+</TransitionSeries>
+// stills at frame HOLD + round(cut.frames * 0.35) and HOLD + round(cut.frames * 0.65)
+```
+
+Also render the **strip**: a still every 10% of the transition (10% to 90%), listed as `"strip"` in the cut's
+entry: the check reads every one of them for blank frames. Render through `mfx render` (`npx remotion still …
+--frame=N`, with `--gl=angle` where needed). Look at every in-between: if the carrier doesn't read in it, the cut
+isn't working yet. Fix the choice, not the frame.
+
+## 6. Submit the board
+
+`node $B posters`, then `node $B panels`: one image per cut, reading left to right: the outgoing frame, the real
+in-betweens, the incoming frame, and the library's preview still of that transition, dimmed, for reference.
+
+Submit every panel as an image item, labelled `Cut 03 · SF03 → SF04 · Liquid Fill (cover) · carried by the terminal
+window`, and `transitions/BOARD.md` as a text item: for each cut, the carrier, the why, the transition and its
+family, its length, and the word it lands on. The note: the video's transition vocabulary in two or three lines.
+
+The approved board is the animatic's cut list: the animatic uses these transitions at these lengths, landing on
+these words.
diff --git a/pipelines/_shared/skills/transition-board/board.mjs b/pipelines/_shared/skills/transition-board/board.mjs
new file mode 100644
index 0000000..4983cca
--- /dev/null
+++ b/pipelines/_shared/skills/transition-board/board.mjs
@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// The transition board's tool, over the remotion-transitions library ($MFX_TRANSITIONS).
+//
+// node board.mjs list [--function energy] [--family 04-cover] the catalog, compact, to choose from
+// node board.mjs use <id> [<id>...] copy src/core + those transitions into video/src/transitions/
+// node board.mjs posters [board.json] each chosen transition's preview poster → transitions/posters/
+// node board.mjs check [transitions/board.json] the board's rules (must pass before submitting)
+// node board.mjs blank <image>... [--a A.png --b B.png] whether a frame blanks the screen (flood, flash, emptied)
+// node board.mjs panels [transitions/board.json] one review image per cut: A → in-betweens → B → the library's poster
+import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync, rmSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const LIB = process.env.MFX_TRANSITIONS;
+const args = process.argv.slice(2);
+const cmd = args.shift();
+const opt = (name) => { const i = args.indexOf(`--${name}`); if (i < 0) return null; const v = args[i + 1]; args.splice(i, 2); return v; };
+const die = (m) => { console.error(`✖ ${m}`); process.exit(1); };
+if (!LIB || !existsSync(join(LIB, 'catalog.json'))) die('The transitions library isn\'t installed in this studio ($MFX_TRANSITIONS). `mfx needs-you "Run mortiflix setup transitions, then resume."`');
+const catalog = JSON.parse(readFileSync(join(LIB, 'catalog.json'), 'utf8'));
+const byId = new Map(catalog.transitions.map((t) => [t.id, t]));
+const media = (url) => String(url || '').replace('<mediaBase>', catalog.mediaBase);
+
+if (cmd === 'list') {
+ const fn = opt('function'); const fam = opt('family');
+ for (const t of catalog.transitions) {
+ if (fn && !t.facets.function.includes(fn)) continue;
+ if (fam && t.family !== fam) continue;
+ const params = t.params.map((p) => p.name).join(', ');
+ console.log(`${t.id.padEnd(24)} ${t.family}/${t.subfamily} ${t.facets.structure}, ${t.facets.origin}, ${t.facets.function.join('+')} ${t.duration.min}-${t.duration.max}f (${t.duration.default})${t.requires.length ? ` needs ${t.requires.join(',')}` : ''}`);
+ console.log(` ${t.summary}${params ? ` [${params}]` : ''}`);
+ }
+ console.log(`\n${catalog.transitions.length} transitions. Read TAXONOMY.md in ${LIB} for how they work and when each family fits.`);
+} else if (cmd === 'use') {
+ if (!args.length) die('use <id> [<id>...]');
+ const dest = join('video', 'src', 'transitions');
+ mkdirSync(dest, { recursive: true });
+ rmSync(join(dest, 'core'), { recursive: true, force: true });
+ cpSync(join(LIB, 'src', 'core'), join(dest, 'core'), { recursive: true });
+ for (const id of args) {
+ const t = byId.get(id);
+ if (!t) die(`no transition "${id}" in the library (node board.mjs list)`);
+ const to = join(dest, id);
+ rmSync(to, { recursive: true, force: true });
+ cpSync(join(LIB, t.path), to, { recursive: true });
+ // The library imports its core as ../../../../src/core from every file: point them at the copy next door.
+ for (const f of readdirSync(to, { recursive: true }).map(String).filter((f) => /\.(tsx?|mjs|js)$/.test(f))) {
+ const file = join(to, f);
+ const depth = f.split(/[\\/]/).length - 1;
+ const up = '../'.repeat(depth + 1);
+ writeFileSync(file, readFileSync(file, 'utf8').replace(/(['"])(?:\.\.\/)+src\/core(\/[^'"]*)?\1/g, (_, q, rest = '') => `${q}${up}core${rest}${q}`));
+ }
+ console.log(`✔ ${id} → ${to}${t.requires.length ? ` (needs ${t.requires.join(', ')}: render with --gl=angle, or --gl=swangle without a GPU)` : ''}`);
+ }
+ console.log(` core → ${join(dest, 'core')}. Use: <TransitionSeries.Transition presentation={toPresentation(t, params)} timing={linearTiming({ durationInFrames })} />`);
+} else if (cmd === 'posters') {
+ const board = JSON.parse(readFileSync(args[0] || 'transitions/board.json', 'utf8'));
+ mkdirSync('transitions/posters', { recursive: true });
+ const ids = new Set(board.cuts.flatMap((c) => (typeof c.transition === 'string' ? [c.transition] : c.transition?.inspired_by || [])));
+ for (const id of ids) {
+ const t = byId.get(id);
+ if (!t?.media?.poster) { console.log(`· ${id}: no poster`); continue; }
+ const out = join('transitions', 'posters', `${id}.jpg`);
+ const r = spawnSync('curl', ['-sfL', '-o', out, media(t.media.poster)]);
+ console.log(r.status === 0 ? `✔ ${out}` : `· ${id}: the poster isn't published yet`);
+ }
+} else if (cmd === 'check') {
+ const file = args[0] || 'transitions/board.json';
+ if (!existsSync(file)) die(`no ${file} (SKILL.md step 3)`);
+ const board = JSON.parse(readFileSync(file, 'utf8'));
+ const errors = []; const warnings = [];
+ const cuts = board.cuts || [];
+ if (!cuts.length) errors.push('No cuts: one entry for every change from one scene to the next.');
+ const families = new Map();
+ cuts.forEach((c, i) => {
+ const at = `Cut ${i + 1} (${c.from} → ${c.to})`;
+ if (i > 0 && cuts[i - 1].to !== c.from) errors.push(`${at} doesn't start where cut ${i} ended ("${cuts[i - 1].to}"): the board runs through the scenes in order.`);
+ if (String(c.carrier || '').trim().length < 6) errors.push(`${at}: name the carrier, the object or element that makes the cut happen (a shape, a line, a colour, a camera move, a sound).`);
+ if (String(c.why || '').trim().length < 20) errors.push(`${at}: say why, in a sentence: what the cut means in the story.`);
+ let t = null;
+ if (typeof c.transition === 'string') {
+ t = byId.get(c.transition);
+ if (!t) errors.push(`${at}: "${c.transition}" isn't in the library (node board.mjs list), or mark it new: {"new": "name", "inspired_by": ["id", ...]}.`);
+ } else if (c.transition?.new) {
+ const insp = c.transition.inspired_by || [];
+ if (!insp.length || insp.some((id) => !byId.has(id))) errors.push(`${at}: a new transition names the library transitions that inspired it ("inspired_by": real ids).`);
+ if (!existsSync(join('video', 'src', 'transitions', c.transition.new, 'index.tsx'))) errors.push(`${at}: the new transition "${c.transition.new}" needs its code in video/src/transitions/${c.transition.new}/index.tsx (library format, built on core/).`);
+ t = byId.get(insp[0]);
+ } else errors.push(`${at}: "transition" is a library id, or {"new": "name", "inspired_by": [...]}.`);
+ if (t) {
+ families.set(t.family, (families.get(t.family) || 0) + 1);
+ if (typeof c.transition === 'string') {
+ if (!(c.frames >= t.duration.min && c.frames <= t.duration.max)) errors.push(`${at}: ${c.frames} frames is outside ${t.id}'s range (${t.duration.min}-${t.duration.max}).`);
+ if (t.params.some((p) => p.name === 'color') && !c.params?.color) warnings.push(`${at}: ${t.id} takes "color", the incoming scene's background colour: set it.`);
+ }
+ }
+ if (!Number.isFinite(c.frames) || c.frames < 0) errors.push(`${at}: "frames", the transition's length in frames.`);
+ if (!String(c.lands_on || '').trim()) errors.push(`${at}: "lands_on", the word or beat the cut lands on.`);
+ for (const k of ['a', 'b']) if (!c[k] || !existsSync(c[k])) errors.push(`${at}: "${k}" must be the ${k === 'a' ? 'outgoing' : 'incoming'} style frame's image (missing ${c[k] || 'path'}).`);
+ // The owner's rule: a transition never blanks the screen. Every frame across it still shows the scenes' own elements:
+ // no frame of one solid colour, no blown-out white. Checked on the strip (every 10% of the transition) or the mids.
+ const frames = [...(c.strip || []), ...(c.strip ? [] : c.mids || [])];
+ if (!frames.length) errors.push(`${at}: render "strip", stills every 10% of the transition (SKILL.md step 5), so the check can see every moment of it.`);
+ for (const f of frames) {
+ if (!existsSync(f)) { errors.push(`${at}: missing ${f}`); continue; }
+ const blank = blankness(f, c.a, c.b);
+ if (blank) errors.push(`${at}: ${f} ${blank}. A transition never fills the screen with a colour or a flash: carry it with the elements on screen.`);
+ }
+ });
+ const top = [...families.values()].sort((x, y) => y - x)[0] || 0;
+ if (cuts.length >= 5 && top / cuts.length > 0.7) warnings.push('Most cuts come from one family: vary them by what each cut means (TAXONOMY.md), keeping a coherent vocabulary.');
+ if (families.size > 5) warnings.push(`${families.size} families in one video: pick a smaller vocabulary (2-4) and save the big moves for section breaks.`);
+ for (const w of warnings) console.log(`! ${w}`);
+ if (errors.length) { console.log(`✖ ${errors.length} problem${errors.length === 1 ? '' : 's'}:\n ${errors.join('\n ')}`); process.exit(1); }
+ console.log(`✔ ${cuts.length} cuts, each carried by something and chosen for a reason; families: ${[...families.keys()].join(', ')}`);
+} else if (cmd === 'blank') {
+ // node board.mjs blank <image>...: what the check sees in a frame
+ const a = opt('a'); const b = opt('b'); // the scenes it joins: --a sf01.png --b sf02.png
+ for (const f of args) console.log(`${f}: ${blankness(f, a, b) || 'shows the scene'}`);
+} else if (cmd === 'panels') {
+ const board = JSON.parse(readFileSync(args[0] || 'transitions/board.json', 'utf8'));
+ mkdirSync('out/board', { recursive: true });
+ for (const [i, c] of board.cuts.entries()) {
+ const tiles = [c.a, ...(c.mids || []), c.b];
+ const posterId = typeof c.transition === 'string' ? c.transition : c.transition?.inspired_by?.[0];
+ const poster = posterId && existsSync(join('transitions', 'posters', `${posterId}.jpg`)) ? join('transitions', 'posters', `${posterId}.jpg`) : null;
+ if (poster) tiles.push(poster);
+ for (const f of tiles) if (!existsSync(f)) die(`cut ${i + 1}: missing ${f} (render the in-betweens first: SKILL.md step 5)`);
+ const out = join('out', 'board', `cut-${String(i + 1).padStart(2, '0')}.png`);
+ // One row: the outgoing frame, the real in-betweens, the incoming frame, then the library's poster, dimmed, as the reference.
+ const inputs = tiles.flatMap((f) => ['-i', f]);
+ const scaled = tiles.map((_, k) => `[${k}:v]scale=640:360:force_original_aspect_ratio=decrease,pad=640:360:(ow-iw)/2:(oh-ih)/2:color=0x0B0913${poster && k === tiles.length - 1 ? ',eq=brightness=-0.12:saturation=0.7' : ''},pad=652:360:0:0:color=0x000000[t${k}]`).join(';');
+ const graph = `${scaled};${tiles.map((_, k) => `[t${k}]`).join('')}hstack=inputs=${tiles.length}`;
+ const r = spawnSync('ffmpeg', ['-loglevel', 'error', '-y', ...inputs, '-filter_complex', graph, '-frames:v', '1', out], { encoding: 'utf8' });
+ if (r.status !== 0) die(`ffmpeg: ${r.stderr}`);
+ console.log(`✔ ${out} ${c.from} → ${c.to}: ${typeof c.transition === 'string' ? c.transition : `new "${c.transition.new}"`} (${c.frames}f), carried by ${c.carrier}`);
+ }
+} else die('usage: board.mjs list|use|posters|check|panels (see SKILL.md)');
+
+// Does a transition frame blank the screen? Judged against the two scenes it joins (64x36 samples):
+// blown out: most of the frame near white
+// flooded: most of the frame one colour that is neither scene's own background
+// emptied: far less detail than either scene (the elements are gone: a dip to a plain colour)
+function sample(file) {
+ const r = spawnSync('ffmpeg', ['-loglevel', 'error', '-i', file, '-vf', 'scale=64:36:flags=area', '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'], { maxBuffer: 1 << 20 });
+ if (r.status !== 0 || !r.stdout?.length) return null;
+ const px = [];
+ for (let i = 0; i + 2 < r.stdout.length; i += 3) px.push([r.stdout[i], r.stdout[i + 1], r.stdout[i + 2]]);
+ const median = [0, 1, 2].map((k) => px.map((p) => p[k]).sort((a, b) => a - b)[px.length >> 1]);
+ const luma = px.map((p) => 0.2126 * p[0] + 0.7152 * p[1] + 0.0722 * p[2]);
+ let detail = 0;
+ for (let y = 0; y < 36; y++) for (let x = 0; x < 63; x++) detail += Math.abs(luma[y * 64 + x + 1] - luma[y * 64 + x]);
+ for (let y = 0; y < 35; y++) for (let x = 0; x < 64; x++) detail += Math.abs(luma[(y + 1) * 64 + x] - luma[y * 64 + x]);
+ return { px, median, detail: detail / (64 * 36), white: px.filter((p) => p[0] > 225 && p[1] > 215 && p[2] > 215).length / px.length };
+}
+function dist(a, b) { return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]); }
+
+function blankness(file, a = null, b = null) {
+ const f = sample(file);
+ if (!f) return null;
+ const ends = [a, b].filter(Boolean).map(sample).filter(Boolean);
+ const whiteBase = ends.length ? Math.max(...ends.map((e) => e.white)) : 0;
+ if (f.white > 0.5 && f.white > whiteBase + 0.3) return `is blown out to white (${Math.round(f.white * 100)}% of the frame)`;
+ const cover = f.px.filter((p) => dist(p, f.median) < 30).length / f.px.length;
+ const foreign = ends.length ? ends.every((e) => dist(f.median, e.median) > 40) : true;
+ if (cover > 0.6 && foreign) return `floods with one colour (${Math.round(cover * 100)}% of the frame is rgb(${f.median.join(', ')}), neither scene's own)`;
+ if (ends.length && f.detail < 0.3 * Math.min(...ends.map((e) => e.detail))) return 'has lost the scenes\' elements (almost no detail left)';
+ return null;
+}
diff --git a/pipelines/explainer/PIPELINE.md b/pipelines/explainer/PIPELINE.md
index e37e30a..eac9057 100644
--- a/pipelines/explainer/PIPELINE.md
+++ b/pipelines/explainer/PIPELINE.md
@@ -6,6 +6,7 @@ remembers one thing. The owner reviews each stage in the studio (`.mortiflix/GAT
Skills (read the one a step names before starting it):
- `.claude/skills/motion-design/SKILL.md`: the craft, from style frames to the final.
- `.claude/skills/remotion-motion/SKILL.md`: the Remotion project, stills, renders.
+- `.claude/skills/transition-board/SKILL.md`: every cut, designed and carried, from the transitions library.
- `.claude/skills/voiceover/SKILL.md`: narration and word timing.
- `.claude/skills/music/SKILL.md`: the original score, written to the approved animatic.
- `.claude/skills/final-pass/SKILL.md`: `qc.mjs`, the automated checks plus the frame sheet.
@@ -28,7 +29,8 @@ Skills (read the one a step names before starting it):
| `brief` | questions | Read the brief and any files. Restate it in three lines (what, for whom, the one takeaway) as the note. Ask only questions that change the video, each with a default: tone, the call to action, must-say facts, narration voice (if narrated). |
| `script` | document | Write it (or tidy the owner's own, which is then spoken verbatim). Beats as paragraphs: one idea per beat, each with a one-line visual note in *italics*. Fit the length (`script-fits-length`). Submit `script.md`. |
| `style-frames` | frames | Runs beside the script. Three to five stills at full resolution, each a real moment of the video (opening, the key idea, the ending card), in one coherent look. Submit PNGs labelled `SF01 · Opening` etc. |
-| `animatic` | video | Narration first (voiceover skill), then every beat timed to it with simple motion in the approved look. No music yet: the music step scores this timing. The owner judges pace and order here, not polish. 720p is fine. |
+| `transitions` | frames | The transition-board skill: for every cut between consecutive scenes, the carrier (the object or element that makes it happen), why, a transition from the remotion-transitions library (or a new one inspired by it), its length and the word it lands on. `board.mjs check` passes; submit one panel per cut (outgoing frame, real in-betweens, incoming frame, the library's preview) and `BOARD.md`. The approved board is the cut list from here on. |
+| `animatic` | video | Narration first (voiceover skill), then every beat timed to it with simple motion in the approved look, cut with the approved board's transitions. No music yet: the music step scores this timing. The owner judges pace and order here, not polish. 720p is fine. |
| `music` | video | Skipped when the owner chose no music. Otherwise the music skill, start to finish: the dramatic reading, the spotting map from the animatic's real timing, the blueprint, the score, `strudel.mjs check` at 0 problems, the render, the mix under the voice. Submit the animatic with the cue mixed in, the score alone, and the cue sheet. |
| `build` | internal | The final animation at full quality: easing, transitions, texture, sound design, the mix with the approved score (re-timed only if the animation moved). Through `mfx render`. Run every check (`mfx checks build`), then `mfx step done build --checks checks/build.json`. |
| `final` | video | The final at full resolution with the frame sheet as a second item (and the MIDI pack and stems when the owner asked for them: music skill, step 9). Corrections loop: fix, re-run the checks, submit the next version. |
diff --git a/pipelines/explainer/pipeline.json b/pipelines/explainer/pipeline.json
index 0b1736d..555d778 100644
--- a/pipelines/explainer/pipeline.json
+++ b/pipelines/explainer/pipeline.json
@@ -6,6 +6,7 @@
"shared_skills": [
"motion-design",
"remotion-motion",
+ "transition-board",
"voiceover",
"music",
"final-pass"
@@ -110,6 +111,19 @@
],
"describe": "Three to five finished-quality stills that fix the look. Runs beside the script."
},
+ {
+ "key": "transitions",
+ "name": "Transition board",
+ "review": "frames",
+ "work": [
+ "motion"
+ ],
+ "describe": "How each style frame becomes the next: for every cut, the object that carries it, the reason, a transition from the remotion-transitions library (or a new one inspired by it), and real in-between frames.",
+ "after": [
+ "script",
+ "style-frames"
+ ]
+ },
{
"key": "animatic",
"name": "Animatic",
@@ -119,8 +133,7 @@
"audio"
],
"after": [
- "script",
- "style-frames"
+ "transitions"
],
"describe": "Every beat timed to the narration with simple motion in the approved look. No music yet: the score is written to this timing next."
},
@@ -174,7 +187,8 @@
"animatic": "Timing every beat",
"build": "Animating the final",
"qc": "Watching every frame before you do",
- "deliver": "Packaging your video"
+ "deliver": "Packaging your video",
+ "transitions": "Designing every cut"
},
"checks": [
{
@@ -269,6 +283,14 @@
"music"
],
"how": "In the mix, the music is about 18 dB under the voice while it speaks (sidechain ducking), and the score's busiest writing avoids the narration's busiest moments. Every word stays intelligible: check the loudest music passage under speech."
+ },
+ {
+ "id": "transitions-carried",
+ "title": "Every cut is carried and chosen",
+ "applies_to": [
+ "motion"
+ ],
+ "how": "node .claude/skills/transition-board/board.mjs check passes: every cut names its carrier (the object or element that makes it happen) and why, uses a transition from the remotion-transitions library (or a new one that names the library transitions that inspired it) at a length inside its range, and lands on a named word. The video's cuts match the approved board."
}
]
}
diff --git a/pipelines/social-short/PIPELINE.md b/pipelines/social-short/PIPELINE.md
index 533a791..e3e1fe5 100644
--- a/pipelines/social-short/PIPELINE.md
+++ b/pipelines/social-short/PIPELINE.md
@@ -1,6 +1,6 @@
# Social short
-A 15–45 second short for a feed, usually vertical. People decide in the first second whether to keep watching, and
+A 45 second to 3 minute short for a feed, usually vertical. People decide in the first second whether to keep watching, and
most watch with the sound off. The owner reviews each stage in the studio (`.mortiflix/GATES.md`).
Skills: `motion-design`, `remotion-motion`, `voiceover` (only if the brief wants narration), `final-pass`.
@@ -19,6 +19,7 @@ Skills: `motion-design`, `remotion-motion`, `voiceover` (only if the brief wants
|---|---|---|
| `brief` | questions | Restate the message in one line and the hook you'd open with. Ask about tone, the CTA, music, narration, each with a default. |
| `style-frames` | frames | The on-screen script (as a text item: every line with its time) plus 2–3 full-resolution stills: the hook frame, a middle frame, the CTA card. |
+| `transitions` | frames | The transition-board skill: for every cut between consecutive scenes, the carrier (the object or element that makes it happen), why, a transition from the remotion-transitions library (or a new one inspired by it), its length and the word it lands on. `board.mjs check` passes; submit one panel per cut (outgoing frame, real in-betweens, incoming frame, the library's preview) and `BOARD.md`. The approved board is the cut list from here on. |
| `final` | video | Animate, mix (if there's sound), `qc.mjs` with the brief's size and length, look at the sheet. Submit the video and the sheet. |
## Status lines
diff --git a/pipelines/social-short/pipeline.json b/pipelines/social-short/pipeline.json
index 22d2f3f..59dea7f 100644
--- a/pipelines/social-short/pipeline.json
+++ b/pipelines/social-short/pipeline.json
@@ -1,46 +1,197 @@
{
"slug": "social-short",
"name": "Social short",
- "description": "A 15 to 45 second vertical short for social feeds: one hook, one idea, one call to action. Brief, a style frame, the final.",
+ "description": "A 45 second to 3 minute vertical short for social feeds: one hook, one idea, one call to action. Brief, a style frame, the final.",
"makes": "video",
- "shared_skills": ["motion-design", "remotion-motion", "voiceover", "final-pass"],
+ "shared_skills": [
+ "motion-design",
+ "remotion-motion",
+ "transition-board",
+ "voiceover",
+ "final-pass"
+ ],
"intake": [
- { "id": "message", "label": "What's the one message?", "type": "long", "required": true },
- { "id": "platform", "label": "Where will it run?", "type": "choice", "choices": ["TikTok / Reels / Shorts", "LinkedIn", "X", "Anywhere"], "default": "TikTok / Reels / Shorts" },
- { "id": "length", "label": "Length", "type": "choice", "choices": ["15 s", "30 s", "45 s"], "default": "30 s" },
- { "id": "aspect", "label": "Shape", "type": "choice", "choices": ["9:16", "1:1", "4:5"], "default": "9:16" },
- { "id": "cta", "label": "Call to action", "type": "text" },
- { "id": "brand", "label": "Logo, fonts, colours, references", "type": "files" }
+ {
+ "id": "message",
+ "label": "What's the one message?",
+ "type": "long",
+ "required": true
+ },
+ {
+ "id": "platform",
+ "label": "Where will it run?",
+ "type": "choice",
+ "choices": [
+ "TikTok / Reels / Shorts",
+ "LinkedIn",
+ "X",
+ "Anywhere"
+ ],
+ "default": "TikTok / Reels / Shorts"
+ },
+ {
+ "id": "length",
+ "label": "Length",
+ "type": "choice",
+ "choices": [
+ "45 s",
+ "1 min",
+ "1 min 30 s",
+ "2 min",
+ "3 min"
+ ],
+ "default": "45 s"
+ },
+ {
+ "id": "aspect",
+ "label": "Shape",
+ "type": "choice",
+ "choices": [
+ "9:16",
+ "1:1",
+ "4:5"
+ ],
+ "default": "9:16"
+ },
+ {
+ "id": "cta",
+ "label": "Call to action",
+ "type": "text"
+ },
+ {
+ "id": "brand",
+ "label": "Logo, fonts, colours, references",
+ "type": "files"
+ }
],
"steps": [
- { "key": "brief", "name": "Brief", "review": "questions" },
- { "key": "style-frames", "name": "Hook frames", "review": "frames", "work": ["script", "stills"],
- "describe": "The on-screen script plus two or three stills: the hook (first second), the middle, the CTA card." },
- { "key": "final", "name": "Final", "review": "video", "work": ["motion", "audio"], "delivers": true }
+ {
+ "key": "brief",
+ "name": "Brief",
+ "review": "questions"
+ },
+ {
+ "key": "style-frames",
+ "name": "Hook frames",
+ "review": "frames",
+ "work": [
+ "script",
+ "stills"
+ ],
+ "describe": "The on-screen script plus two or three stills: the hook (first second), the middle, the CTA card."
+ },
+ {
+ "key": "transitions",
+ "name": "Transition board",
+ "review": "frames",
+ "work": [
+ "motion"
+ ],
+ "describe": "How each style frame becomes the next: for every cut, the object that carries it, the reason, a transition from the remotion-transitions library (or a new one inspired by it), and real in-between frames.",
+ "after": [
+ "style-frames"
+ ]
+ },
+ {
+ "key": "final",
+ "name": "Final",
+ "review": "video",
+ "work": [
+ "motion",
+ "audio"
+ ],
+ "delivers": true,
+ "after": [
+ "transitions"
+ ]
+ }
],
"status_lines": {
"brief": "Reading your brief",
"frames": "Designing the hook",
"build": "Animating",
"qc": "Checking every frame",
- "deliver": "Packaging your short"
+ "deliver": "Packaging your short",
+ "transitions": "Designing every cut"
},
"checks": [
- { "id": "spelling-and-facts", "title": "Every word, name and number is right", "applies_to": ["script", "stills", "motion"],
- "how": "Read every on-screen word against the brief. Names, numbers and spelling exactly right." },
- { "id": "hook-in-one-second", "title": "The hook lands in the first second", "applies_to": ["stills", "motion"],
- "how": "Frame 0 already shows the hook's subject or words: no logo intro, no blank or slow fade-in." },
- { "id": "platform-safe-zones", "title": "Clear of the platform's buttons", "applies_to": ["stills", "motion"],
- "how": "For 9:16, no text in the top 12%, the bottom 20% or the right 15% (captions, buttons, profile). Check on the stills and sampled frames." },
- { "id": "text-contrast", "title": "Text is readable on a phone", "applies_to": ["stills", "motion"],
- "how": "Text at least 4% of frame height, 4.5:1 contrast, on screen long enough to read twice (words / 3 + 1 seconds)." },
- { "id": "sound-off", "title": "Works with the sound off", "applies_to": ["script", "motion"],
- "how": "Every spoken idea is also on screen (captions or titles): watch the frame sheet without audio and the message still lands." },
- { "id": "frame-sheet", "title": "Every second looked at", "applies_to": ["motion"],
- "how": "qc.mjs passes (no black, flash or frozen frames unless designed) and you looked at its sheet." },
- { "id": "format", "title": "The right size, rate and length", "applies_to": ["motion"],
- "how": "qc.mjs: the brief's shape at 1080 wide or more, constant 30 fps, H.264 + AAC, duration within 5%." },
- { "id": "loudness", "title": "Loudness and no clipping", "applies_to": ["audio"],
- "how": "qc.mjs: -14 LUFS ±1, true peak ≤ -1 dBTP, nothing distorted when you listen." }
+ {
+ "id": "spelling-and-facts",
+ "title": "Every word, name and number is right",
+ "applies_to": [
+ "script",
+ "stills",
+ "motion"
+ ],
+ "how": "Read every on-screen word against the brief. Names, numbers and spelling exactly right."
+ },
+ {
+ "id": "hook-in-one-second",
+ "title": "The hook lands in the first second",
+ "applies_to": [
+ "stills",
+ "motion"
+ ],
+ "how": "Frame 0 already shows the hook's subject or words: no logo intro, no blank or slow fade-in."
+ },
+ {
+ "id": "platform-safe-zones",
+ "title": "Clear of the platform's buttons",
+ "applies_to": [
+ "stills",
+ "motion"
+ ],
+ "how": "For 9:16, no text in the top 12%, the bottom 20% or the right 15% (captions, buttons, profile). Check on the stills and sampled frames."
+ },
+ {
+ "id": "text-contrast",
+ "title": "Text is readable on a phone",
+ "applies_to": [
+ "stills",
+ "motion"
+ ],
+ "how": "Text at least 4% of frame height, 4.5:1 contrast, on screen long enough to read twice (words / 3 + 1 seconds)."
+ },
+ {
+ "id": "sound-off",
+ "title": "Works with the sound off",
+ "applies_to": [
+ "script",
+ "motion"
+ ],
+ "how": "Every spoken idea is also on screen (captions or titles): watch the frame sheet without audio and the message still lands."
+ },
+ {
+ "id": "frame-sheet",
+ "title": "Every second looked at",
+ "applies_to": [
+ "motion"
+ ],
+ "how": "qc.mjs passes (no black, flash or frozen frames unless designed) and you looked at its sheet."
+ },
+ {
+ "id": "format",
+ "title": "The right size, rate and length",
+ "applies_to": [
+ "motion"
+ ],
+ "how": "qc.mjs: the brief's shape at 1080 wide or more, constant 30 fps, H.264 + AAC, duration within 5%."
+ },
+ {
+ "id": "loudness",
+ "title": "Loudness and no clipping",
+ "applies_to": [
+ "audio"
+ ],
+ "how": "qc.mjs: -14 LUFS \u00b11, true peak \u2264 -1 dBTP, nothing distorted when you listen."
+ },
+ {
+ "id": "transitions-carried",
+ "title": "Every cut is carried and chosen",
+ "applies_to": [
+ "motion"
+ ],
+ "how": "node .claude/skills/transition-board/board.mjs check passes: every cut names its carrier (the object or element that makes it happen) and why, uses a transition from the remotion-transitions library (or a new one that names the library transitions that inspired it) at a length inside its range, and lands on a named word. The video's cuts match the approved board."
+ }
]
}
diff --git a/src/cli.mjs b/src/cli.mjs
index 1e03fc8..e28ec6c 100644
--- a/src/cli.mjs
+++ b/src/cli.mjs
@@ -23,8 +23,8 @@ const HELP = `${C.b('mortiflix')}: a motion design studio on your machine. Claud
${C.b('Getting started')}
mortiflix init [--backend claude-code|anthropic-api|demo] set up the studio (~/Mortiflix, or $MORTIFLIX_STUDIO)
- mortiflix setup the walkthrough: Claude, narration, music, assets, 3D
- mortiflix setup <claude|narration|music|assets|3d> one part of it (mortiflix setup status: where things stand)
+ mortiflix setup the walkthrough: Claude, transitions, narration, music, assets, 3D
+ mortiflix setup <claude|transitions|narration|music|assets|3d> one part (mortiflix setup status: where things stand)
mortiflix keys add or change your keys (Anthropic, ElevenLabs, others)
mortiflix doctor check the tools a pipeline needs
mortiflix demo a full walk-through with placeholder work (free)
@@ -36,6 +36,7 @@ const HELP = `${C.b('mortiflix')}: a motion design studio on your machine. Claud
mortiflix list your projects
mortiflix status <project> steps, versions, the log
mortiflix review [<project>] review what's waiting (approve, notes, answers)
+ mortiflix reopen <project> <step> "what to change" send an approved step back (you changed your mind)
mortiflix pause|resume|cancel <project>
${C.b('The web studio')}
@@ -97,6 +98,12 @@ export async function run(argv = process.argv.slice(2)) {
case 'status': return status(root, pick(root, rest[0]));
case 'review': return review(root, rest[0]);
case 'pause': gates.pause(root, pick(root, rest[0])); return console.log('Paused.');
+ case 'reopen': {
+ const [proj, step, ...words] = rest;
+ if (!step || !words.length) throw new Error('mortiflix reopen <project> <step> "what to change"');
+ gates.reopen(root, pick(root, proj), step, { overall: words.join(' ') });
+ return console.log(`${C.acc('↺')} ${step} goes back for changes. ${C.b('mortiflix run')} makes the next version.`);
+ }
case 'resume': gates.resume(root, pick(root, rest[0])); return console.log('Resumed: it will run on the next `mortiflix run` (or right away under `serve`).');
case 'cancel': gates.cancel(root, pick(root, rest[0])); return console.log('Cancelled.');
case 'serve': return serve(root, a);
@@ -172,11 +179,11 @@ async function init(root, a) {
console.log(` Backend: ${C.b(backend)} ${C.dim(BACKENDS[backend].available(loadConfig(root), root).detail)}`);
if (backend === 'demo') console.log(C.dim(' (No Claude Code login or API key found: the demo backend makes placeholder work. Install Claude Code, or add an API key with `mortiflix keys`.)'));
if (process.stdin.isTTY && !a.yes) {
- console.log(`\n Next, the setup walkthrough: what Mortiflix uses (Claude, narration, music, assets, 3D), why, and what it would`);
+ console.log(`\n Next, the setup walkthrough: what Mortiflix uses (Claude, transitions, narration, music, assets, 3D), why, and what it would`);
console.log(' install. Nothing installs without asking, and you can skip any part.');
if (await confirm(' Set it up now?', true)) await setupWalk(root);
else console.log(` Any time: ${C.b('mortiflix setup')}`);
- } else console.log(`\n Next: ${C.b('mortiflix setup')} walks through Claude, narration, music, assets and 3D.`);
+ } else console.log(`\n Next: ${C.b('mortiflix setup')} walks through Claude, transitions, narration, music, assets and 3D.`);
console.log(`\n Then: ${C.b('mortiflix demo')} for a free walk-through, or ${C.b('mortiflix serve')} to open the studio in your browser.`);
}
@@ -567,6 +574,13 @@ async function setupPart(root, id, st) {
}
return;
}
+ if (id === 'transitions') {
+ if (st.transitions.ok) {
+ console.log(` ${mark(true)} ${st.transitions.detail} (${st.transitions.path})`);
+ if (await confirm(' Update the library to its latest version?', false)) await offerInstall(root, 'transitions', { ask: false });
+ } else await offerInstall(root, 'transitions', { ask: false });
+ return;
+ }
if (id === 'narration') {
const v = voice.voiceConfig(root);
const local = st.gpu;
@@ -652,6 +666,7 @@ async function showSetup(root) {
row(BACKENDS[config.backend].available(config, root).ok, 'Claude', `${config.backend}: ${BACKENDS[config.backend].available(config, root).detail}`);
row(v.engine === 'none' ? null : v.engine === 'elevenlabs' ? Boolean(voice.elevenKey(root)) && Boolean(v.elevenlabs.voice_id) : st.comfyui.ok, 'Narration',
v.engine === 'none' ? 'none' : v.engine === 'elevenlabs' ? `ElevenLabs: ${v.elevenlabs.voice_name || 'no voice chosen'} on ${v.elevenlabs.model_id}${voice.elevenKey(root) ? '' : ', key missing'}` : `this computer: ${st.comfyui.detail}`);
+ row(st.transitions.ok, 'Transitions', st.transitions.ok ? `remotion-transitions: ${st.transitions.detail}` : 'library not installed (mortiflix setup transitions)');
row(st.music.engine === 'none' ? null : st.strudel.ok && st.chrome.ok, 'Music', st.music.engine === 'none' ? 'none' : `Strudel: ${st.strudel.detail}; Chrome: ${st.chrome.ok ? 'found' : 'missing'}${st.music.midi ? '; MIDI pack on' : ''}`);
row(st.assets.sites.length ? st['browser-harness'].ok : null, 'Assets', st.assets.sites.length ? `${st.assets.sites.map((x) => x.url).join(', ')} (browser-harness ${st['browser-harness'].ok ? st['browser-harness'].detail : 'missing'})` : 'no sites: sessions make every visual themselves');
row(st.blender.ok ? st['blender-addons'].ok : null, '3D', st.blender.ok ? `${st.blender.detail}; ${st['blender-addons'].detail}` : 'not set up');
diff --git a/src/gates.mjs b/src/gates.mjs
index cfbe5ce..24f9122 100644
--- a/src/gates.mjs
+++ b/src/gates.mjs
@@ -343,6 +343,44 @@ export function respond(root, id, stepKey, version, { verdict, overall = '', not
});
}
+// The owner changes their mind after approving: the step goes back for changes, with their note, and steps after it
+// that had started (but weren't approved) wait for the new version. The approval stays in the log.
+export function reopen(root, id, stepKey, { overall = '', notes = [] } = {}) {
+ const pp = projectPaths(root, id);
+ const pipeline = projectPipeline(root, id);
+ const step = findStep(pipeline, stepKey);
+ if (step.review === 'internal') refuse(`${stepKey} isn't reviewed by you: reopen the reviewed step before it`);
+ if (!String(overall).trim() && !notes.length) refuse('say what to change');
+ return update(root, id, (p) => {
+ const rec = p.steps?.[stepKey];
+ if (!rec || !['approved', 'done'].includes(rec.state)) refuse(`${stepKey} isn't approved (it's ${rec?.state || 'not started'})`);
+ const version = rec.version;
+ const dir = join(pp.reviews, stepKey, `v${version}`);
+ const before = existsSync(join(dir, 'feedback.json')) ? readJson(join(dir, 'feedback.json')) : null;
+ const feedback = {
+ step: stepKey, version, verdict: 'changes', reopened: true, approved_at: before?.decided_at || rec.decided_at || null,
+ overall: String(overall).slice(0, 4000),
+ notes: notes.map((n, i) => ({ n: i + 1, item: n.item ?? null, text: String(n.text || '').slice(0, 2000) })),
+ answers: before?.answers || [],
+ decided_at: now(),
+ how_to_read_annotations: 'The owner approved this version, then asked for these changes. Answer every note in the next version\'s pin_changes.',
+ };
+ writeJson(join(dir, 'feedback.json'), feedback);
+ mkdirSync(join(pp.work, 'feedback'), { recursive: true });
+ writeJson(join(pp.work, 'feedback', `${stepKey}-v${version}.json`), feedback);
+ p.steps[stepKey] = { ...rec, state: 'changes', decided_at: feedback.decided_at, last_feedback: { version, verdict: 'changes', notes: feedback.notes.length } };
+ // Later steps that depend on it and had started without being approved go back to waiting.
+ const after = new Set([stepKey]);
+ let grew = true;
+ while (grew) { grew = false; for (const s of pipeline.steps) if (!after.has(s.key) && s.after.some((a) => after.has(a))) { after.add(s.key); grew = true; } }
+ for (const k of after) if (k !== stepKey && p.steps[k] && !['approved', 'done', 'skipped'].includes(p.steps[k].state)) delete p.steps[k];
+ if (p.state === 'delivered') p.state = 'queued';
+ settle(p, pipeline);
+ event(root, id, { event: 'REOPENED', actor: 'you', step: stepKey, version, details: String(overall).slice(0, 200) });
+ return { step: stepKey, version, project_state: p.state };
+ });
+}
+
export function answerQuestion(root, id, qid, value) {
const pp = projectPaths(root, id);
const pipeline = projectPipeline(root, id);
diff --git a/src/setup.mjs b/src/setup.mjs
index 31c111f..aa6b735 100644
--- a/src/setup.mjs
+++ b/src/setup.mjs
@@ -2,6 +2,7 @@
// Everything installs into the studio folder (<studio>/tools/) or as the user's own tool (uv), never system-wide,
// and nothing installs without being asked. The choices (music, asset sites) live in config.json.
//
+// transitions the remotion-transitions library (MIT): every cut in every video is chosen from it (or inspired by it)
// strudel Strudel (AGPL, npm) for the music step: it writes and renders the score
// chrome a headless Chrome that Strudel renders in (an existing Chrome/Chromium is reused)
// browser-harness browser-use's browser-harness: sessions use your own Chrome to get assets from sites you name
@@ -35,6 +36,13 @@ export const PARTS = [
why: 'Claude does the work: it writes, designs, animates and checks every step. Mortiflix is the studio around it.',
needs: 'Your Claude Code login (your plan pays), or an Anthropic API key (you pay per token).',
},
+ {
+ id: 'transitions',
+ title: 'Transitions',
+ why: 'Every cut in every video is designed: before the animatic, a transition board shows how each style frame becomes the next, and why (the object or idea that carries the cut).',
+ needs: 'The remotion-transitions library from GitHub (about 5 MB): 50 motion-design transitions in nine families, with a preview of each.',
+ tools: ['transitions'],
+ },
{
id: 'narration',
title: 'Narration',
@@ -111,6 +119,18 @@ async function download(url, file, log) {
// ---- detecting each tool ----
+export const TRANSITIONS_REPO = 'GTKottman/remotion-transitions';
+
+function transitionsStatus(root) {
+ const dir = join(toolsDir(root), 'remotion-transitions');
+ const cat = join(dir, 'catalog.json');
+ if (!existsSync(cat)) return { ok: false, detail: 'not installed' };
+ try {
+ const c = JSON.parse(readFileSync(cat, 'utf8'));
+ return { ok: true, path: dir, count: c.transitions.length, detail: `${c.transitions.length} transitions` };
+ } catch { return { ok: false, detail: 'catalog.json unreadable: reinstall' }; }
+}
+
function strudelStatus(root) {
const dir = join(toolsDir(root), 'strudel');
const pkg = join(dir, 'node_modules', '@strudel', 'web', 'package.json');
@@ -184,6 +204,7 @@ async function comfyStatus(root) {
export async function setupStatus(root) {
const config = loadConfig(root);
return {
+ transitions: transitionsStatus(root),
strudel: strudelStatus(root),
chrome: chromeStatus(root),
'browser-harness': browserHarnessStatus(),
@@ -240,6 +261,21 @@ function saveToolPath(root, key, path) {
// ---- installing ----
+async function installTransitions(root, log) {
+ const dir = join(toolsDir(root), 'remotion-transitions');
+ const tgz = await download(`https://codeload.github.com/${TRANSITIONS_REPO}/tar.gz/HEAD`, join(toolsDir(root), 'downloads', 'remotion-transitions.tar.gz'), log);
+ const fresh = `${dir}.new`;
+ rmSync(fresh, { recursive: true, force: true });
+ mkdirSync(fresh, { recursive: true });
+ await run('tar', ['-xzf', tgz, '-C', fresh, '--strip-components=1'], { log });
+ rmSync(tgz, { force: true });
+ if (!existsSync(join(fresh, 'catalog.json'))) throw new Error('the download has no catalog.json');
+ rmSync(dir, { recursive: true, force: true });
+ const { renameSync } = await import('node:fs');
+ renameSync(fresh, dir);
+ return transitionsStatus(root);
+}
+
async function installStrudel(root, log) {
const dir = join(toolsDir(root), 'strudel');
mkdirSync(dir, { recursive: true });
@@ -504,10 +540,11 @@ export function openBlender(root, args = []) {
return b.path;
}
-const INSTALLERS = { strudel: installStrudel, chrome: installChrome, 'browser-harness': installBrowserHarness, blender: installBlender, 'blender-addons': installAddons, comfyui: installComfy };
+const INSTALLERS = { transitions: installTransitions, strudel: installStrudel, chrome: installChrome, 'browser-harness': installBrowserHarness, blender: installBlender, 'blender-addons': installAddons, comfyui: installComfy };
export const TOOLS = Object.keys(INSTALLERS);
export const TOOL_INFO = {
+ transitions: { name: 'Transitions library', what: 'github.com/GTKottman/remotion-transitions (MIT): 50 transitions for Remotion, a catalog and a preview of each', where: 'tools/remotion-transitions', size: '~5 MB' },
strudel: { name: 'Strudel', what: `@strudel/web ${STRUDEL_VERSION} from npm (AGPL-3.0)`, where: 'tools/strudel', size: '~20 MB' },
chrome: { name: 'Headless Chrome', what: 'Chrome for Testing\'s headless shell, from Google (only if you have no Chrome or Chromium)', where: 'tools/browsers', size: '~100 MB' },
'browser-harness': { name: 'browser-harness', what: 'browser-use/browser-harness, installed with uv (Python 3.12) as your own tool', where: '~/.local/bin', size: '~60 MB' },
@@ -528,6 +565,8 @@ export async function installTool(root, id, { log = () => {} } = {}) {
export function sessionToolsEnv(root) {
const config = loadConfig(root);
const env = { MFX_MUSIC: JSON.stringify(musicConfig(config)), MFX_ASSETS: JSON.stringify(assetsConfig(config)) };
+ const tr = transitionsStatus(root);
+ if (tr.ok) env.MFX_TRANSITIONS = tr.path;
const s = strudelStatus(root);
if (s.ok) env.MFX_STRUDEL = s.path;
const c = chromeStatus(root);
@@ -542,7 +581,7 @@ export const blenderDocsDir = (root) => join(toolsDir(root), 'blender-addons', '
// What the session brief says about this studio's tools (no network calls: ComfyUI is the narration skill's business).
export function setupStatusSync(root) {
const config = loadConfig(root);
- return { strudel: strudelStatus(root), chrome: chromeStatus(root), 'browser-harness': browserHarnessStatus(), blender: blenderStatus(root),
+ return { transitions: transitionsStatus(root), strudel: strudelStatus(root), chrome: chromeStatus(root), 'browser-harness': browserHarnessStatus(), blender: blenderStatus(root),
'blender-addons': addonsStatus(root), music: musicConfig(config), assets: assetsConfig(config) };
}
diff --git a/test/music-setup.test.mjs b/test/music-setup.test.mjs
index f2ec2dd..ad52fe3 100644
--- a/test/music-setup.test.mjs
+++ b/test/music-setup.test.mjs
@@ -148,3 +148,45 @@ drums: cue(note("36 42 36 42 36 42 36 42").s("sine").decay(.1).sustain(0).veloci
assert.equal(run('midi').status, 0);
assert.ok(existsSync(join(dir, 'out/music/midi/CUE-SHEET.md')));
});
+
+test('transition board: every cut is carried, chosen from the library (or inspired by it), in order', (t) => {
+ const lib = mkdtempSync(join(tmpdir(), 'mfx-lib-'));
+ const work = mkdtempSync(join(tmpdir(), 'mfx-board-'));
+ t.after(() => { rmSync(lib, { recursive: true, force: true }); rmSync(work, { recursive: true, force: true }); });
+ const entry = (id, family, params = []) => ({ id, name: id, family, subfamily: 'x', path: `transitions/${family}/x/${id}`, summary: id, uses: [],
+ facets: { structure: 'direct', origin: 'whole-frame', function: ['continuity'] }, duration: { default: 20, min: 10, max: 40 }, requires: [], params, media: {} });
+ writeFileSync(join(lib, 'catalog.json'), JSON.stringify({ mediaBase: 'x', transitions: [entry('crossfade', '02-blend'), entry('liquid-fill', '04-cover', [{ name: 'color' }])] }));
+ mkdirSync(join(work, 'transitions'));
+ // Real frames: the scenes (detailed test patterns on a dark background), an in-between that still shows them, a flood and a flash.
+ const ff = (src, out) => spawnSync('ffmpeg', ['-loglevel', 'error', '-y', '-f', 'lavfi', '-i', src, '-frames:v', '1', join(work, out)]);
+ for (const f of ['a.png', 'b.png', 'c.png', 'mid.png']) ff('testsrc2=s=320x180', f);
+ ff('color=c=0x3D1F8F:s=320x180', 'flood.png');
+ ff('color=c=white:s=320x180', 'flash.png');
+ const tool = join(REPO, 'pipelines/_shared/skills/transition-board/board.mjs');
+ const check = (cuts) => {
+ writeFileSync(join(work, 'transitions', 'board.json'), JSON.stringify({ cuts }));
+ return spawnSync('node', [tool, 'check'], { cwd: work, env: { ...process.env, MFX_TRANSITIONS: lib }, encoding: 'utf8' });
+ };
+ const good = [
+ { from: 'A', to: 'B', a: 'a.png', b: 'b.png', carrier: 'the price tag', why: 'the cost dissolves into the promise', transition: 'liquid-fill', params: { color: '#000' }, frames: 30, lands_on: '"Now"', strip: ['mid.png'] },
+ { from: 'B', to: 'C', a: 'b.png', b: 'c.png', carrier: 'the terminal window', why: 'the same idea, carried on to the next step', transition: 'crossfade', frames: 20, lands_on: '"Then"', strip: ['mid.png'] },
+ ];
+ const ok = check(good);
+ assert.equal(ok.status, 0, ok.stdout + ok.stderr);
+ const bad = check([{ ...good[0], carrier: '', frames: 90 }, { ...good[1], from: 'X', transition: 'warp-drive' }]);
+ assert.equal(bad.status, 1);
+ assert.match(bad.stdout, /name the carrier/);
+ assert.match(bad.stdout, /outside liquid-fill's range/);
+ assert.match(bad.stdout, /doesn't start where cut 1 ended/);
+ assert.match(bad.stdout, /"warp-drive" isn't in the library/);
+ // The screen never goes blank: a flood of a colour neither scene has, or a white flash, fails.
+ const flooded = check([{ ...good[0], strip: ['mid.png', 'flood.png'] }]);
+ assert.match(flooded.stdout, /flood\.png floods with one colour/);
+ assert.match(check([{ ...good[0], strip: ['flash.png'] }]).stdout, /blown out to white/);
+ assert.match(check([{ ...good[0], strip: undefined }]).stdout, /render "strip"/);
+ const invented = check([{ ...good[0], transition: { new: 'price-melt', inspired_by: ['liquid-fill'] } }]);
+ assert.match(invented.stdout, /needs its code in video\/src\/transitions\/price-melt/);
+ mkdirSync(join(work, 'video', 'src', 'transitions', 'price-melt'), { recursive: true });
+ writeFileSync(join(work, 'video', 'src', 'transitions', 'price-melt', 'index.tsx'), 'export default {}');
+ assert.equal(check([{ ...good[0], transition: { new: 'price-melt', inspired_by: ['liquid-fill'] } }]).status, 0);
+});
diff --git a/web/app.js b/web/app.js
index f20de5a..9bf6b9f 100644
--- a/web/app.js
+++ b/web/app.js
@@ -673,7 +673,7 @@ async function setupSection() {
const refresh = async () => { info = await api('/api/setup'); draw(); };
// One tool: its status, what installing it means, an Install button and the live log while it runs.
- const UPDATABLE = ['strudel', 'browser-harness', 'blender-addons']; // the others are reused when found
+ const UPDATABLE = ['transitions', 'strudel', 'browser-harness', 'blender-addons']; // the others are reused when found
const toolRow = (id, label = info.tools[id].name) => {
const st = info.status[id];
const t = info.tools[id];
@@ -709,6 +709,7 @@ async function setupSection() {
h('h2', null, 'Setup'),
h('p', { class: 'meta' }, 'What the studio uses, why, and what it installs. Everything goes into the studio folder (or your own user tools), never system-wide, and nothing installs until you press Install.'),
field(part('claude').title, h('div', null, ...intro('claude'), h('p', { class: 'meta' }, 'Choose below, in "Who makes the videos".'))),
+ field(part('transitions').title, h('div', null, ...intro('transitions'), toolRow('transitions'))),
field(part('narration').title, h('div', null, ...intro('narration'),
h('p', { class: 'meta' }, `This computer: ${st.gpu.reason}`),
st.gpu.fits ? toolRow('comfyui') : null,