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.
// The node graph as the app draws it (doc 35), the loose preview's edit list (doc 36), the voice & music lanes
// (doc 34) and the Mortiflix Studio hand-off plan (doc 38): all read from the one canvas graph (src/canvas.mjs).
//
// The owner's own things live beside the graph in state/<id>/canvas/:
// layout.json node positions (free placement like Blender) and the film order (the chain; reorder = rewire)
// picks.json which version plays, when it isn't the newest
// mix.json per line / cue: level, ducking, hand-set timing, voice, length in bars
// edit-app.json what the app imported (node → clip), so a new version is swapped in, never rebuilt
import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, rmSync, statSync } from 'node:fs';
import { spawn } from 'node:child_process';
import { join } from 'node:path';
import { canvasView, canvasPaths, loadGraph, nodeAction, requestNewPiece, CanvasError, readBeats, mediaUnfinished } from '../canvas.mjs';
import { beatNames } from './beatnames.mjs';
import { projectPaths, loadProject, event } from '../projects.mjs';
import { withLock, writeJson } from '../studio.mjs';
import { listAssets } from './assets.mjs';
import { cuePlan } from './theme.mjs';
import { boothStatus } from '../booth.mjs';
import { syncVoiceWords } from './script.mjs';
import { creditRate } from './voicecost.mjs';
import { voiceConfig } from '../voice/index.mjs';
import { writtenForms } from './stills.mjs';
import { captionText, moneyHints } from './captionform.mjs';
// Older versions handed to Edit per piece (the newest ones): two of a shot, one of a voice line or the music (a 26 min
// film put 494 in the bin: three per shot plus each line's take as MP3 and again as WAV).
const OLDER_KEPT = { shot: 2, line: 1, music: 1, cue: 1, transition: 1 };
// Version files are named by their content, so whether one is cut off (a video stopped mid-write, an empty or
// half-written WAV) never changes: asked once. Such a version is left out everywhere (graph, Edit's older versions).
const unfinishedSeen = new Map();
function unfinished(path) {
if (!unfinishedSeen.has(path)) {
if (unfinishedSeen.size > 20000) unfinishedSeen.clear();
unfinishedSeen.set(path, mediaUnfinished(path));
}
return unfinishedSeen.get(path);
}
// The words as spoken: a line's voice directions ("[warm, a little smile] …") are for the voice, not the captions.
export const spoken = (words) => String(words || '').replace(/\[[^\]\n]{0,200}\]\s*/g, '').trim();
const readOr = (f, d) => { try { return JSON.parse(readFileSync(f, 'utf8')); } catch { return d; } };
const files = (root, id) => {
const cp = canvasPaths(root, id);
return { ...cp, layout: join(cp.dir, 'layout.json'), picks: join(cp.dir, 'picks.json'), mix: join(cp.dir, 'mix.json'), app: join(cp.dir, 'edit-app.json') };
};
const save = (f, v) => { mkdirSync(join(f, '..'), { recursive: true }); writeJson(f, v); };
const round3 = (x) => Math.round(x * 1000) / 1000;
const NODE_ID = /^[a-z][a-z0-9-]{1,23}$/;
export const loadLayout = (root, id) => readOr(files(root, id).layout, { positions: {}, film_order: null });
export const loadPicks = (root, id) => readOr(files(root, id).picks, {});
export const loadMix = (root, id) => readOr(files(root, id).mix, { lines: {}, cues: {} });
// The film order: the owner's chain when they rewired it, then any shot that came later, in the AI's order.
export function filmOrder(g, layout) {
const shots = g.order.shots;
const mine = (layout.film_order || []).filter((s) => shots.includes(s));
return [...mine, ...shots.filter((s) => !mine.includes(s))];
}
const plays = (n, picks) => {
const v = picks[n.id] && n.versions?.some((x) => x.v === picks[n.id]) ? picks[n.id] : n.current;
return n.versions?.find((x) => x.v === v) || null;
};
// Tidy rows, only for nodes the owner never moved (doc 35 + owner answer 3: then they stay where dropped).
function defaultPos(g, film) {
const pos = {};
film.forEach((s, i) => { pos[s] = [i * 300, 0]; });
for (const t of g.order.transitions) { const n = g.nodes[t]; const a = film.indexOf(n?.from); if (a >= 0) pos[t] = [a * 300 + 230, 40]; }
const perBeat = {};
for (const l of g.order.lines) { const n = g.nodes[l]; const s = film.find((x) => g.nodes[x]?.beat === n?.beat); const k = perBeat[n?.beat] = (perBeat[n?.beat] || 0) + 1; pos[l] = [(s ? film.indexOf(s) : 0) * 300 + (k - 1) * 40, 260 + (k - 1) * 30]; }
g.order.frames.forEach((f, i) => { pos[f] = [i * 300, -260]; });
g.order.beats.forEach((b, i) => { pos[b] = [i * 300, -420]; });
return pos;
}
// A PNG still per shot version (its first frame, made once with ffmpeg in the background, two at a time): graph.get
// names it (`still`) as soon as the file exists, and the node area and the chat show it. A picture version is its own
// still. A frame that can't be made is not tried again while the service runs.
const VIDEO = /\.(mp4|mov|mkv|webm|m4v|avi)$/i;
const PICTURE = /\.(png|jpe?g|webp)$/i;
const stills = { queue: [], running: 0, failed: new Set(), queued: new Set() };
export function stillFor(state, node, v) {
if (node.kind !== 'shot' || !v?.path) return null;
if (PICTURE.test(v.path)) return v.path;
if (!VIDEO.test(v.path)) return null;
const file = join(state, 'stills', `${String(node.id).replace(/[^a-z0-9_-]/gi, '')}-v${Number(v.v) || 0}.png`);
if (existsSync(file)) return file;
if (!stills.failed.has(file) && !stills.queued.has(file) && existsSync(v.path)) {
stills.queued.add(file);
stills.queue.push({ src: v.path, at: Math.max(0, Number(v.from_sec) || 0), file });
nextStill();
}
return null;
}
function nextStill() {
while (stills.running < 2 && stills.queue.length) {
const job = stills.queue.shift();
stills.running++;
const part = `${job.file}.part.png`;
try { mkdirSync(join(job.file, '..'), { recursive: true }); } catch { /* the spawn reports it */ }
let p;
try {
p = spawn('ffmpeg', ['-y', '-loglevel', 'error', '-ss', String(job.at), '-i', job.src, '-frames:v', '1', '-vf', 'scale=480:-2', part], { stdio: 'ignore' });
} catch { p = null; }
const done = (ok) => {
stills.running--;
stills.queued.delete(job.file);
try { if (ok && existsSync(part)) renameSync(part, job.file); else { stills.failed.add(job.file); rmSync(part, { force: true }); } } catch { stills.failed.add(job.file); }
nextStill();
};
if (!p) { done(false); continue; }
p.on('error', () => done(false));
p.on('close', (code) => done(code === 0));
}
}
// Waits until every queued still is made (tests).
export async function stillsSettled(timeoutMs = 20_000) {
const t0 = Date.now();
while ((stills.running || stills.queue.length) && Date.now() - t0 < timeoutMs) await new Promise((r) => setTimeout(r, 50));
}
// The graph for the node area: every node with its beat number and colour, state, versions (absolute paths), which
// version plays, position, the owner's mix settings, the assets it uses; the edges; the film order.
export function graphView(root, id) {
const g = canvasView(root, id);
const state = projectPaths(root, id).state;
const layout = loadLayout(root, id);
const picks = loadPicks(root, id);
const mix = loadMix(root, id);
const assets = listAssets(root, id).yours;
const film = filmOrder(g, layout);
const beatNo = Object.fromEntries(g.order.beats.map((b, i) => [b, i + 1]));
const dpos = defaultPos(g, film);
// the beats' short names (the script's, the AI's, else a title from the words): nodes, ribbon, bins, markers
let names = {};
try { names = beatNames(root, id, readBeats(projectPaths(root, id).work, [])); } catch { /* no script yet */ }
const nodes = Object.values(g.nodes).map((n) => {
const p = plays(n, picks);
return {
...n,
...(n.kind === 'beat' && names[n.id] ? { name: names[n.id].name, name_from: names[n.id].from } : {}),
beat_no: n.beat ? beatNo[n.beat] ?? null : null,
// a version copied while its video was still being written (before 439e1d1) is a cut-off file: left out
versions: (n.versions || []).map((v) => ({ ...v, path: v.file ? join(state, v.file) : null })).filter((v) => !(v.path && unfinished(v.path)))
.map((v) => ({ ...v, still: stillFor(state, n, v) })),
plays: p?.v ?? null,
pos: layout.positions[n.id] || null,
default_pos: dpos[n.id] || null,
mix: (n.kind === 'line' ? mix.lines[n.id] : n.kind === 'cue' ? mix.cues[n.id] : null) || null,
uses: assets.filter((a) => a.used_in.some((u) => u.node === n.id)).map((a) => a.id),
};
});
const edges = [];
// Film order: shot → transition → shot where the board has a transition for that cut, else shot → shot.
for (let i = 0; i + 1 < film.length; i++) {
const [a, b] = [film[i], film[i + 1]];
const t = g.order.transitions.find((x) => g.nodes[x]?.from === a && g.nodes[x]?.to === b);
if (t) edges.push({ from: a, to: t, kind: 'next' }, { from: t, to: b, kind: 'next' });
else edges.push({ from: a, to: b, kind: 'next' });
}
for (const l of g.order.lines) { const n = g.nodes[l]; for (const s of film.filter((x) => g.nodes[x]?.beat === n.beat)) edges.push({ from: l, to: s, kind: 'says' }); }
for (const s of film) { const n = g.nodes[s]; if (n?.look) edges.push({ from: n.look, to: s, kind: 'look' }); }
for (const a of assets) for (const u of a.used_in) edges.push({ from: a.id, to: u.node, kind: 'uses' });
for (const c of g.order.cues) { const n = g.nodes[c]; for (const s of film.filter((x) => g.nodes[x]?.beat === n.beat)) edges.push({ from: c, to: s, kind: 'under' }); }
// each shot's place and length in the film as the preview, Voice & music and Edit play it (the node area showed a
// version's whole file length: "0:43" for a 0:36 film)
try {
const tl = shotTimeline(root, id, { order: { ...g.order, film }, nodes });
for (const sh of tl.shots) { const n = nodes.find((x) => x.id === sh.node); if (n) Object.assign(n, { film_start: sh.start_sec, film_sec: sh.dur_sec }); }
} catch { /* the nodes keep their own lengths */ }
return {
project: id, rev: g.rev, fps: g.fps, colours: g.colours, problems: g.problems, open_edits: g.open_edits,
order: { ...g.order, film },
beats: g.order.beats.map((b, i) => ({ id: b, no: i + 1, title: g.nodes[b]?.title || '', name: names[b]?.name || '', colour: g.nodes[b]?.colour || null })),
nodes, edges,
// your own files are input nodes too: where you dropped them (node.move takes asset ids)
assets: assets.map((a) => ({ ...a, pos: layout.positions[a.id] || null })),
};
}
// Free placement: positions as {nodeId: [x, y]} (finite numbers), merged into what's saved. null removes one.
export function moveNodes(root, id, positions) {
if (!positions || typeof positions !== 'object') throw new CanvasError('positions: {node: [x, y]}');
const f = files(root, id);
mkdirSync(f.dir, { recursive: true });
return withLock(f.lock, () => {
const layout = loadLayout(root, id);
const known = new Set([...Object.keys(loadGraph(root, id)?.nodes || {}), ...(loadProject(root, id).assets || []).map((a) => a.id)]);
let n = 0;
for (const [nid, p] of Object.entries(positions).slice(0, 5000)) {
if (!known.has(nid)) continue;
if (p === null) { delete layout.positions[nid]; n++; continue; }
if (!Array.isArray(p) || p.length !== 2 || !p.every((x) => Number.isFinite(x) && Math.abs(x) < 1e7)) continue;
layout.positions[nid] = [Math.round(p[0] * 10) / 10, Math.round(p[1] * 10) / 10];
n++;
}
save(f.layout, layout);
return { moved: n };
});
}
// Reorder = rewire the chain (doc 35): the owner's film order, every shot once. Nothing is remade.
export function reorder(root, id, order) {
const g = canvasView(root, id);
if (!Array.isArray(order)) throw new CanvasError('order: the shot ids in film order');
const shots = new Set(g.order.shots);
const clean = [...new Set(order.map(String))].filter((s) => shots.has(s));
if (!clean.length) throw new CanvasError('no shots in that order');
const f = files(root, id);
const out = withLock(f.lock, () => {
const layout = loadLayout(root, id);
layout.film_order = [...clean, ...g.order.shots.filter((s) => !clean.includes(s))];
save(f.layout, layout);
return layout.film_order;
});
event(root, id, { event: 'REORDERED', actor: 'you', details: out.map((s) => s.toUpperCase()).join(' ') });
return { film: out };
}
// Which version plays (an older one picked from the versions); null goes back to the newest.
export function pickVersion(root, id, nid, v) {
const g = canvasView(root, id);
const n = g.nodes[nid];
if (!n) throw new CanvasError(`no piece ${nid}`);
if (v !== null && !n.versions.some((x) => x.v === v)) throw new CanvasError(`${n.label} has no v${v}`);
const f = files(root, id);
// picking the newest is "the newest": a remake later plays (run 2: v2 picked when it was the newest stayed on
// after the remakes, and Edit got the old shot)
const newest = v !== null && v === n.current;
withLock(f.lock, () => { const p = loadPicks(root, id); if (v === null || newest) delete p[nid]; else p[nid] = v; save(f.picks, p); });
event(root, id, { event: 'VERSION_PICKED', actor: 'you', details: `${n.label} v${v ?? n.current}` });
return { node: nid, plays: v ?? n.current };
}
// A new shot: Duplicate (like this one) or Insert (after this one, from words). A session makes it; it joins the film
// right after `after`.
export function newShot(root, id, { op, after, text }) {
const g = canvasView(root, id);
const base = g.nodes[after];
if (!base || base.kind !== 'shot') throw new CanvasError(`${after} isn't a shot`);
const taken = new Set([...Object.keys(g.nodes), ...readOr(canvasPaths(root, id).edits, { edits: [] }).edits.map((e) => e.node)]);
let k = 1;
while (taken.has(`s${String(k).padStart(2, '0')}`)) k++;
const nid = `s${String(k).padStart(2, '0')}`;
const words = op === 'duplicate'
? `Duplicate ${base.label}: a new shot ${nid.toUpperCase()} like it, right after it in the film.${text ? ` ${text}` : ''} Write it as scene "${nid}" (beat ${base.beat || 'none'}) with its own file in out/scenes.json.`
: `Insert a new shot ${nid.toUpperCase()} right after ${base.label}: ${text}. Write it as scene "${nid}" (beat ${base.beat || 'none'}) with its own file in out/scenes.json.`;
if (op !== 'duplicate' && !String(text || '').trim()) throw new CanvasError('say what the new shot shows');
const edit = requestNewPiece(root, id, { node: nid, kind: 'shot', label: nid.toUpperCase(), beat: base.beat || null, op, after, text: words });
const layout = loadLayout(root, id);
const film = filmOrder(g, layout);
film.splice(film.indexOf(after) + 1, 0, nid);
const f = files(root, id);
withLock(f.lock, () => { const l = loadLayout(root, id); l.film_order = film; save(f.layout, l); });
return { edit, node: nid };
}
// ---------------------------------------------------------------------------------------- times and media
function bpmOf(root, id) {
const bp = readOr(join(projectPaths(root, id).work, 'music', 'blueprint.json'), null);
const [num] = String(bp?.meter || '4/4').split('/').map(Number);
return { bpm: Number(bp?.bpm) || 120, beats: num || 4 };
}
// Each shot of the film with its time and the best media it has (doc 36: its own piece of the animatic, else its
// look's still held for the length, else a beat card).
export function shotTimeline(root, id, gv = graphView(root, id)) {
const byId = Object.fromEntries(gv.nodes.map((n) => [n.id, n]));
const lineSec = (beat) => gv.nodes.filter((n) => n.kind === 'line' && n.beat === beat && n.end_sec != null && n.start_sec != null).reduce((s, n) => s + (n.end_sec - n.start_sec), 0);
let t = 0;
const shots = [];
for (const sid of gv.order.film) {
const n = byId[sid];
if (!n || n.state === 'cut' || n.missing) continue;
const v = n.versions.find((x) => x.v === n.plays);
const beat = n.beat ? byId[n.beat] : null;
const shotsInBeat = gv.order.film.filter((x) => byId[x]?.beat === n.beat && byId[x]?.state !== 'cut').length || 1;
let media;
let dur;
if (v?.path) {
dur = round3((v.to_sec ?? 0) - (v.from_sec ?? 0)) || 2;
media = { kind: /\.(png|jpe?g|webp|svg|gif)$/i.test(v.path) ? 'still' : 'video', path: v.path, from_sec: v.from_sec ?? 0, to_sec: v.to_sec ?? null };
} else {
dur = round3(((beat?.target_sec ?? null) || lineSec(n.beat) || 3) / shotsInBeat);
const look = n.look ? byId[n.look] : null;
const still = look?.versions.find((x) => x.v === look.plays);
media = still?.path ? { kind: 'still', path: still.path, look: look.id } : { kind: 'card', text: n.title || beat?.title || n.label, colour: n.colour?.hex || null };
}
shots.push({ node: sid, label: n.label, title: n.title || '', beat: n.beat || null, beat_no: n.beat_no, colour: n.colour || null, state: n.state, version: n.plays, start_sec: 0, dur_sec: dur, media, at: Number.isFinite(n.at_sec) ? n.at_sec : null });
}
// Shots with their place in the animatic (the film as the AI timed it, voice included): each plays until the next
// one's place, also a shot remade alone into its own longer file (run 2: S03 and S05 remade kept their whole
// length and pushed every later shot, 7 s by the end)
for (let i = 0; i + 1 < shots.length; i++) {
const a = shots[i];
const gap = a.at !== null && shots[i + 1].at !== null ? round3(shots[i + 1].at - a.at) : null;
if (gap !== null && gap > 0.2 && gap < a.dur_sec && a.media.to_sec != null) {
a.dur_sec = gap;
a.media.to_sec = round3((a.media.from_sec ?? 0) + gap);
}
}
// Shots cut from one animatic whose ranges overlap (the AI's cuts carry a transition): each plays until the next one
// starts, so the film keeps the animatic's timing and the voice stays on its pictures (run 2: placed back to back
// whole, the overlaps added 8 s and the last lines played over the wrong shots)
for (let i = 0; i + 1 < shots.length; i++) {
const a = shots[i].media;
const b = shots[i + 1].media;
if (a.kind === 'video' && b.kind === 'video' && a.path === b.path && b.from_sec > a.from_sec && a.to_sec != null && b.from_sec < a.to_sec) {
a.to_sec = b.from_sec;
shots[i].dur_sec = round3(b.from_sec - a.from_sec);
}
}
for (const sh of shots) { sh.start_sec = round3(t); t += sh.dur_sec; delete sh.at; }
return { shots, length_sec: round3(t) };
}
// What speech-to-text heard in a line's kept take (voice/clips/<id>.json), so the owner can check the words:
// `heard` is null and `checked` false when nothing listened (a voice with no speech-to-text, or the owner's own take);
// `words_ok` is the check's verdict when it ran.
function heardOf(work, lineId, changedAt) {
return { ...heardCheck(work, lineId), words_changed: wordsChanged(work, lineId, changedAt) };
}
// The script's words for a line changed after its kept take was made (script.edit no longer remakes it): Voice shows
// "words changed" and Remake line until a new take lands. The voice cache knows the words a take was made with
// (sound/voice/lines/<id>.json); without it, a script change newer than the take's clip.
function wordsChanged(work, lineId, changedAt) {
const said = changedAt.said?.[lineId];
if (said !== undefined) return said !== changedAt.words?.[lineId];
const at = changedAt[lineId];
if (!at) return false;
try {
return Date.parse(at) > statSync(join(work, 'voice', 'clips', `${lineId}.wav`)).mtimeMs;
} catch { return false; }
}
function heardCheck(work, lineId) {
try {
const j = JSON.parse(readFileSync(join(work, 'voice', 'clips', `${lineId}.json`), 'utf8'));
const heard = typeof j.transcript === 'string' ? j.transcript.slice(0, 2000) : null;
return { heard, checked: heard !== null, words_ok: heard !== null ? j.pass !== false : null };
} catch { return { heard: null, checked: false, words_ok: null }; }
}
// Voice clips at their times (hand-set start wins), music with its cues' times.
export function soundTimeline(root, id, gv, shots) {
const mix = loadMix(root, id);
const work = projectPaths(root, id).work;
const beatStart = {};
for (const s of shots) if (s.beat && beatStart[s.beat] === undefined) beatStart[s.beat] = s.start_sec;
const cursor = {};
const changedAt = {};
try {
for (const b of JSON.parse(readFileSync(join(work, 'script', 'beats.json'), 'utf8')).beats || []) for (const l of b.lines || []) if (l.changed_at) changedAt[l.id] = l.changed_at;
} catch { /* no script yet */ }
try {
changedAt.words = {};
changedAt.said = {};
for (const l of JSON.parse(readFileSync(join(work, 'voice', 'lines.json'), 'utf8'))) {
changedAt.words[l.id] = l.text ?? l.script;
const m = join(work, 'sound', 'voice', 'lines', `${l.id}.json`);
const clip = join(work, 'voice', 'clips', `${l.id}.wav`);
// a take made after the cache (New take, Remake line) is newer than what the cache says was said
if (existsSync(m) && !(existsSync(clip) && statSync(clip).mtimeMs > statSync(m).mtimeMs + 1000)) changedAt.said[l.id] = JSON.parse(readFileSync(m, 'utf8')).text;
}
} catch { /* no voice lines yet */ }
const voice = gv.nodes.filter((n) => n.kind === 'line' && !n.missing && n.state !== 'cut').sort((a, b) => a.order - b.order).map((n) => {
const v = n.versions.find((x) => x.v === n.plays);
const m = mix.lines[n.id] || {};
const len = n.end_sec != null && n.start_sec != null ? round3(n.end_sec - n.start_sec) : null;
const at = m.start_sec ?? n.start_sec ?? ((beatStart[n.beat] ?? 0) + (cursor[n.beat] || 0));
cursor[n.beat] = (cursor[n.beat] || 0) + (len || 0);
return { node: n.id, label: n.label, words: n.title, beat: n.beat, beat_no: n.beat_no, colour: n.colour, state: n.state, version: n.plays, path: v?.path || null, start_sec: round3(at), dur_sec: len, gain_db: m.gain_db ?? 0, voice: m.voice ?? null, timing_locked: m.start_sec !== undefined, ...heardOf(work, n.id, changedAt) };
});
const music = gv.nodes.find((n) => n.id === 'music' && !n.missing);
const mv = music?.versions.find((x) => x.v === music.plays);
const { bpm, beats } = bpmOf(root, id);
const barSec = (60 / bpm) * beats;
const cues = gv.nodes.filter((n) => n.kind === 'cue' && !n.missing).sort((a, b) => a.order - b.order).map((n) => {
const m = mix.cues[n.id] || {};
const start = n.bars ? round3((n.bars[0] - 1) * barSec) : null;
// a cue the score doesn't tie to a beat takes the beat it starts in, so its clip has that beat's colour in Edit
// (run 2: every cue was the same green, hard to tell which music goes with which scene)
const at = !n.beat && start !== null ? (shots || []).find((sh) => start >= sh.start_sec - 0.05 && start < sh.start_sec + sh.dur_sec) : null;
const beat = n.beat || at?.beat || null;
return { node: n.id, label: n.label, title: n.title, beat, beat_no: n.beat_no ?? at?.beat_no ?? null, colour: n.colour || at?.colour || null, state: n.state, bars: n.bars || null,
start_sec: start, end_sec: n.bars ? round3(n.bars[1] * barSec) : null, gain_db: m.gain_db ?? 0, duck_db: m.duck_db ?? null, len_bars: m.len_bars ?? null };
});
return { voice, music: mv?.path ? { node: 'music', path: mv.path, version: music.plays, start_sec: 0 } : null, cues, bpm, beats_per_bar: beats };
}
// The loose preview's edit list (doc 36): scope all | from | shot | beat, around `node`.
export function previewPlan(root, id, { scope = 'all', node = null } = {}) {
const gv = graphView(root, id);
const { shots, length_sec } = shotTimeline(root, id, gv);
const sound = soundTimeline(root, id, gv, shots);
let range = [0, length_sec];
if (scope !== 'all') {
const n = gv.nodes.find((x) => x.id === node);
if (!n) throw new CanvasError(`${scope} needs a node`);
const beat = n.kind === 'beat' ? n.id : n.beat;
const sel = scope === 'beat' ? shots.filter((s) => s.beat === beat) : scope === 'shot' ? shots.filter((s) => s.node === node) : shots.slice(Math.max(0, shots.findIndex((s) => s.node === node || (n.kind !== 'shot' && s.beat === beat))));
if (!sel.length) throw new CanvasError(`nothing to play for ${node}`);
range = scope === 'from' ? [sel[0].start_sec, length_sec] : [sel[0].start_sec, round3(sel.at(-1).start_sec + sel.at(-1).dur_sec)];
}
return { rev: gv.rev, scope, node, range, length_sec, fps: gv.fps || 30, shots, ...sound };
}
// ------------------------------------------------------------------------------------- voice & music settings
export function setMix(root, id, nid, patch = {}) {
const g = canvasView(root, id);
const n = g.nodes[nid];
if (!n || !['line', 'cue', 'music'].includes(n.kind)) throw new CanvasError(`${nid} isn't a voice line or a music cue`);
const f = files(root, id);
const out = withLock(f.lock, () => {
const mix = loadMix(root, id);
const box = n.kind === 'line' ? mix.lines : mix.cues;
const m = { ...(box[nid] || {}) };
const num = (v, lo, hi) => (Number.isFinite(Number(v)) ? Math.min(hi, Math.max(lo, Math.round(Number(v) * 10) / 10)) : undefined);
if (patch.gain_db !== undefined) m.gain_db = num(patch.gain_db, -60, 12);
if (n.kind === 'line') {
// times to the millisecond: rounded to tenths, a first ±0.1 s on a line starting at 3.05 s moved it 0.15 s (run 2)
const sec = (v) => (Number.isFinite(Number(v)) ? Math.min(36000, Math.max(0, Math.round(Number(v) * 1000) / 1000)) : undefined);
if (patch.start_sec === null) delete m.start_sec;
else if (patch.start_sec !== undefined) m.start_sec = sec(patch.start_sec);
if (patch.nudge_sec !== undefined) m.start_sec = sec((m.start_sec ?? n.start_sec ?? 0) + Number(patch.nudge_sec));
if (patch.voice !== undefined) m.voice = patch.voice ? String(patch.voice).slice(0, 120) : null;
} else {
if (patch.duck_db !== undefined) m.duck_db = patch.duck_db === null ? null : num(patch.duck_db, -40, 0);
if (patch.len_bars !== undefined) m.len_bars = patch.len_bars === null ? null : num(patch.len_bars, 1, 512);
}
for (const k of Object.keys(m)) if (m[k] === undefined) delete m[k];
box[nid] = m;
save(f.mix, mix);
return m;
});
event(root, id, { event: 'MIX_SET', actor: 'you', details: `${n.label}: ${JSON.stringify(out).slice(0, 200)}` });
// A new voice or a new length is real work: it goes to the AI as a Fix on that piece.
let edit = null;
if (n.kind === 'line' && patch.voice) edit = nodeAction(root, id, nid, { action: 'fix', text: `Read this line with the voice "${String(patch.voice).slice(0, 120)}".` }).edit;
if (n.kind === 'cue' && patch.len_bars) edit = nodeAction(root, id, nid, { action: 'fix', text: `Make ${n.label} ${out.len_bars} bars long (ripple what follows, doc 19 §5).` }).edit;
return { node: nid, mix: out, edit };
}
// Stage 4's two lanes: lines (with booth takes) and cues (the plan before the score, the sections after).
export function voiceMusicView(root, id) {
// the voice lines say the script's current words before anything is shown (a scene Fix rewrote them: RUN-BUGS Dir3)
try { syncVoiceWords(root, id); } catch (e) { console.error(`voice words sync ${id}: ${e.message}`); }
const gv = graphView(root, id);
const { shots, length_sec } = shotTimeline(root, id, gv);
const sound = soundTimeline(root, id, gv, shots);
let booth = { takes: [] };
try { booth = boothStatus(root, id); } catch { /* no lines yet */ }
const voice = sound.voice.map((l) => ({ ...l, takes: (booth.takes || []).filter((t) => t.line_id === l.node).map((t, _i, all) => ({ take: t.take_no, kept: t.kept, status: !t.kept && all.some((o) => o.kept) ? 'superseded' : 'ready', seconds: t.duration_ms / 1000, flags: t.flags, source: t.source })) }));
const scored = new Map(sound.cues.map((c) => [c.node, c]));
// Once the score exists its sections are the cues: the one-cue-per-beat plan's unscored entries go (a 26 min score in
// 28 sections showed 42 more "planned" cues over the music, and the lanes said 70 cues where the stage said 28).
const plan = cuePlan(root, id, gv).filter((c) => !scored.size || scored.has(c.id)).map((c) => (scored.has(c.id) ? { ...c, ...scored.get(c.id), state: gv.nodes.find((n) => n.id === c.id)?.state || 'ready', scored: true } : { ...c, node: c.id, scored: false, state: 'planned' }));
const extra = sound.cues.filter((c) => !plan.some((p) => p.node === c.node)).map((c) => ({ ...c, id: c.node, scored: true }));
// credits per character ElevenLabs bills (measured, svc/voicecost.mjs): the screen's own estimates use it
let credit_rate = 1;
try { credit_rate = creditRate(root, voiceConfig(root).elevenlabs?.model_id); } catch { /* list price */ }
return { rev: gv.rev, length_sec, shots, voice, cues: [...plan, ...extra], music: sound.music, bpm: sound.bpm, beats_per_bar: sound.beats_per_bar, credit_rate };
}
// ------------------------------------------------------------------------------------------ into Edit
// A voice line as subtitles: its spoken words cut into captions of at most two lines of SUB_LINE characters, ending at
// a sentence or clause where one fits, each starting at its first word and ending at the next caption (or the line's
// end). `t`: the line's entry in voice/timing.json ({ start, words: [{ text, start, end }] } in voice-track time);
// without word times (or when the counts differ) times are shared by characters.
export const SUB_LINE = 52;
// One line each, small, at the very bottom edge (SUB_STYLE): the animatic keeps its own words 5 % inside the frame
// (the text-safe check), so the strip below is almost always free (run 3: two-line subtitles in the usual place
// covered credits, MIU strings and equations in a third of the film).
export const SUB_LINES = 1;
export const SUB_STYLE = { size: 38, margin: 0.008 };
export function subtitles(l, t, form = (x) => x) {
const text = spoken(l.words);
const words = text.split(/\s+/).filter(Boolean);
const start = l.start_sec; const end = round3(l.start_sec + l.dur_sec);
if (!words.length) return [];
const fits = (ws) => { // two lines at most, filled greedily
let lines = 1; let len = 0;
for (const w of ws) { if (w.length > SUB_LINE && len === 0) continue; if (len && len + 1 + w.length > SUB_LINE) { lines++; len = w.length; } else len += (len ? 1 : 0) + w.length; }
return lines <= SUB_LINES;
};
// sentences first; a sentence too long for one caption is cut into the fewest parts that fit, of even length,
// at a comma where one is near; then a short sentence joins its neighbour when they fit together
const sentences = [];
let cur = [];
for (const w of words) { cur.push(w); if (/[.?!]["”’)]?$/.test(w)) { sentences.push(cur); cur = []; } }
if (cur.length) sentences.push(cur);
const len = (ws) => ws.join(' ').length;
const split = (ws) => {
if (fits(ws)) return [ws];
for (let parts = Math.max(2, Math.ceil(len(ws) / (SUB_LINES * SUB_LINE))); parts <= ws.length; parts++) {
const cuts = [];
let at = 0; const ends = ws.map((w) => (at += w.length + 1) - 1);
for (let k = 1; k < parts; k++) {
const target = len(ws) * k / parts;
let best = null;
for (let i = 1; i < ws.length; i++) {
if (cuts.length && i <= cuts.at(-1)) continue;
const score = Math.abs(ends[i - 1] - target) - (/[,;:—)]$/.test(ws[i - 1]) ? 12 : 0);
if (best === null || score < best[1]) best = [i, score];
}
if (best) cuts.push(best[0]);
}
const out = []; let from = 0;
for (const c of [...cuts, ws.length]) { out.push(ws.slice(from, c)); from = c; }
if (out.every((x) => x.length && fits(x))) return out;
}
return ws.map((w) => [w]);
};
const chunks = [];
for (const sen of sentences.flatMap(split)) {
const prev = chunks.at(-1);
if (prev && (len(sen) < 24 || len(prev) < 24) && fits([...prev, ...sen])) prev.push(...sen); else chunks.push([...sen]);
}
// each caption's first word: its index in the line, then its time
const firsts = []; let n = 0;
for (const c of chunks) { firsts.push(n); n += c.length; }
const tw = Array.isArray(t?.words) ? t.words : [];
const exact = tw.length === words.length && Number.isFinite(t?.start);
const total = text.length;
const timeOf = (wi) => {
if (exact && Number.isFinite(tw[wi]?.start)) return round3(start + (tw[wi].start - t.start));
const chars = words.slice(0, wi).join(' ').length + (wi ? 1 : 0);
if (tw.length && Number.isFinite(t?.start)) { const j = Math.min(tw.length - 1, Math.round(wi * tw.length / words.length)); if (Number.isFinite(tw[j]?.start)) return round3(start + (tw[j].start - t.start)); }
return round3(start + (end - start) * chars / total);
};
// two even lines when it doesn't fit on one
const wrap = (ws) => {
if (len(ws) <= SUB_LINE || SUB_LINES < 2) return ws.join(' ');
let best = null;
// even lines, but a break after a sentence or clause wins when it's nearly as even
for (let i = 1; i < ws.length; i++) { const m = Math.max(len(ws.slice(0, i)), len(ws.slice(i))) + (/[.?!]["”’)]?$/.test(ws[i - 1]) ? 0 : /[,;:—)]$/.test(ws[i - 1]) ? 4 : 10); if (len(ws.slice(0, i)) <= SUB_LINE && len(ws.slice(i)) <= SUB_LINE && (!best || m < best[1])) best = [i, m]; }
return best ? `${ws.slice(0, best[0]).join(' ')}\n${ws.slice(best[0]).join(' ')}` : ws.join(' ');
};
const out = chunks.map((c, i) => ({ node: l.node, part: i + 1, text: form(wrap(c)), start_sec: i === 0 ? start : timeOf(firsts[i]), end_sec: end }));
for (let i = 0; i + 1 < out.length; i++) out[i].end_sec = out[i + 1].start_sec;
return out.filter((c) => c.end_sec > c.start_sec);
}
const SIZES = { '16:9': [1920, 1080], '9:16': [1080, 1920], '1:1': [1080, 1080], '4:5': [1080, 1350] };
// Everything the app needs to build the Mortiflix Studio project once, in-process (doc 38 §1): the sequence, bins, tracks,
// clips (absolute paths, in/out, start, label colour), markers, captions, your assets, older versions, cut shots.
export function handoffPlan(root, id) {
const project = loadProject(root, id);
const gv = graphView(root, id);
const { shots, length_sec } = shotTimeline(root, id, gv);
const sound = soundTimeline(root, id, gv, shots);
const byId = Object.fromEntries(gv.nodes.map((n) => [n.id, n]));
const [width, height] = SIZES[String(project.intake?.answers?.aspect || '16:9').trim()] || SIZES['16:9'];
const beatBin = (beat) => (beat ? `Shots/${byId[beat] ? `${byId[beat].beat_no ?? ''} ${String(byId[beat].name || byId[beat].title || '').slice(0, 40)}`.trim() : beat}` : 'Shots');
const label = (n) => n?.colour?.label || null;
const clips = [];
for (const s of shots) clips.push({ node: s.node, kind: 'shot', track: 'V1', bin: beatBin(s.beat), name: `${s.label} · ${s.title}`.slice(0, 80), label: label(s), version: s.version, start_sec: s.start_sec, dur_sec: s.dur_sec, media: s.media, preview: s.media.kind !== 'video' });
const film = gv.order.film;
for (const tid of gv.order.transitions) {
const t = byId[tid];
if (!t || t.state === 'cut' || t.missing) continue;
const at = shots.find((x) => x.node === t.to);
if (!at || film.indexOf(t.from) + 1 !== film.indexOf(t.to)) continue;
const kind = String(t.title || 'Cut');
const native = /^(cut|crossfade|cross dissolve|dissolve|dip to black)$/i.test(kind.trim());
clips.push({ node: tid, kind: 'transition', native, transition: native ? (/dip/i.test(kind) ? 'Dip to Black' : /cut/i.test(kind) ? 'Cut' : 'Cross Dissolve') : kind, at_sec: at.start_sec, from: t.from, to: t.to, version: t.plays, name: `${t.label} · ${kind}`, label: null, bin: native ? null : 'Transitions' });
}
for (const l of sound.voice) if (l.path) clips.push({ node: l.node, kind: 'line', track: 'A1', bin: 'Voice', name: `${l.label} · ${spoken(l.words).slice(0, 60)}`, label: label(l), version: l.version, start_sec: l.start_sec, dur_sec: l.dur_sec, gain_db: l.gain_db, media: { kind: 'audio', path: l.path } });
if (sound.music) clips.push({ node: 'music', kind: 'music', track: 'A2', bin: 'Music', name: 'Music', label: null, version: sound.music.version, start_sec: 0, dur_sec: null, media: { kind: 'audio', path: sound.music.path }, cues: sound.cues.map((c) => ({ node: c.node, start_sec: c.start_sec, end_sec: c.end_sec, gain_db: c.gain_db, duck_db: c.duck_db, label: label(c) })) });
// v3: the Voice step's music cues (ElevenLabs) and the Sound step's approved sounds are clips of their own
// (2026-11-02, d4fd: the Finish summary said "no music · no effects" over a film with both)
const workDir = projectPaths(root, id).work;
if (!sound.music) {
for (const c of readOr(join(workDir, 'music', 'cues.json'), { cues: [] }).cues || []) {
if (!c.file || c.state === 'stale' || !existsSync(join(workDir, c.file))) continue;
clips.push({ node: `music-${c.id}`, kind: 'music', track: 'A2', bin: 'Music', name: `Music ${c.id}${c.mood ? ` · ${String(c.mood).slice(0, 40)}` : ''}`, label: null, version: 1, start_sec: c.from_sec, dur_sec: Math.max(0, (c.to_sec ?? c.from_sec) - c.from_sec), gain_db: c.gain_db ?? null, media: { kind: 'audio', path: join(workDir, c.file) } });
}
}
for (const c of readOr(join(workDir, 'sound', 'sfx-plan.json'), { cues: [] }).cues || []) {
const f = c.file && existsSync(c.file) ? c.file : c.library_file && existsSync(c.library_file) ? c.library_file : null;
if (c.status === 'cut' || !f) continue;
clips.push({ node: `sfx-${c.id}`, kind: 'sfx', track: 'A3', bin: 'Sounds', name: `${c.what || c.id}`.slice(0, 80), label: null, version: 1, start_sec: c.at_sec, dur_sec: c.dur_sec, gain_db: c.gain_db ?? 0, media: { kind: 'audio', path: f } });
}
const assets = listAssets(root, id).yours;
// the newest few older versions of each piece (run 2: 240 of them, every one a whole animatic, went into Edit)
const older = gv.nodes.flatMap((n) => n.versions.filter((v) => v.path && v.v !== n.plays).slice(-(OLDER_KEPT[n.kind] ?? 1)).map((v) => ({ node: n.id, version: v.v, name: `${n.label} v${v.v}`, label: label(n), path: v.path, from_sec: v.from_sec ?? null, to_sec: v.to_sec ?? null })));
const cut = gv.nodes.filter((n) => n.kind === 'shot' && n.state === 'cut').map((n) => { const v = n.versions.find((x) => x.v === n.plays); return v?.path ? { node: n.id, version: v.v, name: `${n.label} · ${n.title || ''}`.slice(0, 80), label: label(n), path: v.path, from_sec: v.from_sec ?? null, to_sec: v.to_sec ?? null } : null; }).filter(Boolean);
const markers = [];
for (const b of gv.beats) { const s = shots.find((x) => x.beat === b.id); if (s) markers.push({ kind: 'chapter', node: b.id, time_sec: s.start_sec, name: `${b.no} ${String(b.name || b.title).slice(0, 60)}`, label: b.colour?.label || null, comment: b.title }); }
for (const c of sound.cues) if (c.start_sec !== null) markers.push({ kind: 'comment', node: c.node, time_sec: c.start_sec, name: `${c.label} · ${c.title || ''}`.trim(), label: label(c) });
// Subtitles: each voice line split into short captions (two lines of at most 42 characters), each timed by the
// line's word timings (run 3: one caption per line put a whole paragraph over the picture). A line moved over the
// next one ends its last caption where the next begins (a caption track holds one caption at a time).
const timing = readOr(join(projectPaths(root, id).work, 'voice', 'timing.json'), { lines: [] });
const timed = Object.fromEntries((Array.isArray(timing?.lines) ? timing.lines : []).filter((t) => t?.id).map((t) => [t.id, t]));
// in the script's written form ("Character.AI", "20 million", "$8–9 million"), timed by the spoken words
const work = projectPaths(root, id).work;
const forms = writtenForms(work);
let scriptText = ''; try { scriptText = readFileSync(join(work, 'script.md'), 'utf8'); } catch { /* none */ }
const money = moneyHints(scriptText);
const captions = sound.voice.filter((l) => l.dur_sec).flatMap((l) => subtitles(l, timed[l.node], (x) => captionText(x, forms, money)))
.sort((a, b) => a.start_sec - b.start_sec);
for (let i = 0; i + 1 < captions.length; i++) if (captions[i].end_sec > captions[i + 1].start_sec) captions[i].end_sec = captions[i + 1].start_sec;
for (let i = captions.length - 1; i >= 0; i--) if (!(captions[i].end_sec > captions[i].start_sec)) captions.splice(i, 1);
const tracks = ['V2 Your assets', 'V1 Shots', 'A1 Voice', 'A2 Music', 'A3 Sounds', 'C1 Captions'].filter((t) => (t.startsWith('V1')) || (t.startsWith('A1') && sound.voice.some((l) => l.path)) || (t.startsWith('A2') && clips.some((c) => c.kind === 'music')) || (t.startsWith('A3') && clips.some((c) => c.kind === 'sfx')) || (t.startsWith('C1') && captions.length) || (t.startsWith('V2') && false));
return {
format: 'mortiflix.handoff', version: 1, project: id, title: project.title, rev: gv.rev, fcproj: handoffFcproj(root, id, project.title),
sequence: { name: project.title, width, height, fps: gv.fps || 30, length_sec },
tracks, bins: ['Shots', ...new Set(clips.filter((c) => c.bin?.startsWith('Shots/')).map((c) => c.bin)), 'Transitions', 'Voice', 'Music', 'Music stems', 'Sounds', 'Your assets', 'Older versions', 'Cut on the board'],
clips, markers, captions, caption_style: SUB_STYLE,
your_assets: assets.map((a) => ({ id: a.id, name: a.name, kind: a.kind, path: a.path, bin: `Your assets/${a.kind}`, used_in: a.used_in })),
older_versions: older, cut_on_board: cut,
notes: `Mortiflix project ${id}, graph rev ${gv.rev}. Click a clip, then ask in the Mortiflix panel.`,
previews: shots.filter((s) => s.media.kind !== 'video').length,
};
}
// Where the app saves the Mortiflix Studio project: the one it saved before, else beside the project's record
// (`<studio>/state/<id>/edit/<title>.mortiflix`, the title kept to letters, digits, space, `-`, `_` and `.`).
export function handoffFcproj(root, id, title) {
const saved = loadHandoff(root, id)?.fcproj;
if (saved) return saved;
const name = Array.from(String(title || '')).filter((c) => /[\p{L}\p{N} ._-]/u.test(c)).join('').trim().slice(0, 120) || 'Mortiflix';
return join(projectPaths(root, id).state, 'edit', `${name}.mortiflix`);
}
// What the app imported (doc 38 "done once"): saved so later versions are swapped in, never rebuilt.
export function saveHandoff(root, id, map) {
if (!map || typeof map !== 'object' || !Array.isArray(map.clips)) throw new CanvasError('handoff.done needs {clips: [{node, version, clip?, item?}]}');
const clean = { project: id, rev: Number(map.rev) || null, fcproj: map.fcproj ? String(map.fcproj).slice(0, 2000) : null, made_at: new Date().toISOString(),
clips: map.clips.slice(0, 20_000).filter((c) => c && NODE_ID.test(String(c.node || '')) || c?.node === 'music').map((c) => ({ node: String(c.node), version: Number(c.version) || null, clip: c.clip ?? null, item: c.item ?? null })) };
save(files(root, id).app, clean);
event(root, id, { event: 'EDIT_IMPORTED', actor: 'you', details: `${clean.clips.length} clips into the app` });
return clean;
}
export const loadHandoff = (root, id) => readOr(files(root, id).app, null);
// Pieces whose playing version is newer than the one in the app: the app swaps each in (clip.replaceFromBin).
export function handoffSwaps(root, id) {
const map = loadHandoff(root, id);
if (!map) return { imported: false, swaps: [] };
const gv = graphView(root, id);
const byId = Object.fromEntries(gv.nodes.map((n) => [n.id, n]));
const swaps = [];
for (const c of map.clips) {
const n = byId[c.node];
if (!n || n.plays === null || n.plays === c.version) continue;
const v = n.versions.find((x) => x.v === n.plays);
if (v?.path) swaps.push({ node: n.id, from_version: c.version, version: n.plays, clip: c.clip, item: c.item, path: v.path, from_sec: v.from_sec ?? null, to_sec: v.to_sec ?? null, name: `${n.label} v${n.plays}` });
}
return { imported: true, swaps, rev: gv.rev };
}
export function markSwapped(root, id, nid, version, { clip = undefined, item = undefined } = {}) {
const f = files(root, id);
const map = loadHandoff(root, id);
if (!map) throw new CanvasError('nothing is in Mortiflix Studio yet');
const c = map.clips.find((x) => x.node === nid);
if (!c) throw new CanvasError(`${nid} isn't in Mortiflix Studio`);
c.version = Number(version) || c.version;
if (clip !== undefined) c.clip = clip;
if (item !== undefined) c.item = item;
save(f.app, map);
event(root, id, { event: 'EDIT_UPDATED', actor: 'studio', details: `${nid} v${c.version} swapped into the app` });
return c;
}
export function findNodes(root, id, query) {
const q = String(query || '').toLowerCase().trim();
if (!q) return [];
return graphView(root, id).nodes.filter((n) => !n.missing && [n.id, n.label, n.title].some((x) => String(x || '').toLowerCase().includes(q))).slice(0, 50).map((n) => ({ id: n.id, kind: n.kind, label: n.label, title: n.title, beat_no: n.beat_no }));
}
export const hasHandoff = (root, id) => existsSync(files(root, id).app);