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.

9.8 KB
Raw Blame
// The studio's side of the sound engine (doc 16 §4, §7): it starts mortiflix-engine, talks to it in JSON lines over the
// child's stdin / stdout (no network port), and keeps it alive. One engine per studio.
//   requests  {"id": 41, "cmd": "transport.play", "args": {...}}  →  {"id": 41, "ok": true, "result": ...} | {"id": 41, "ok": false, "error": "..."}
//   events    {"ev": "alive" | "clock" | "meters" | "xrun" | "device" | "plugin" | "log", ...}
// Supervision: the engine says "alive" every second; 5 s with no word and no answer to engine.ping → its PID is killed
// and it starts again (after 1 s, 2 s, then 5 s). Three crashes inside 60 s → it stays stopped, with its last log lines.
// Only the PID this supervisor started is ever killed.
import { spawn } from 'node:child_process';
import { createInterface } from 'node:readline';
import { EventEmitter } from 'node:events';
import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, truncateSync } from 'node:fs';
import { dirname, join } from 'node:path';

// What the browser may ask the engine for (sessions reach it only through mfx, never directly).
export const BROWSER_COMMANDS = new Set(['engine.hello', 'device.list', 'device.set', 'transport.play', 'transport.stop', 'transport.seek', 'transport.loop',
  'clock.subscribe', 'meters.subscribe', 'audition.note', 'engine.tone']);

const LOG_MAX = 10 * 1024 * 1024;

export function createEngineSupervisor({
  bin, args = [], env = process.env, logFile = null, lastTouchFile = null,
  heartbeatMs = 5000, checkMs = 1000, backoffMs = [1000, 2000, 5000], maxCrashes = 3, crashWindowMs = 60_000,
  timeoutMs = 5000, restore = null,
} = {}) {
  const ev = new EventEmitter();
  let child = null;
  let pid = null;
  let state = 'stopped';          // stopped | starting | running | restarting | failed
  let nextId = 1;
  const pending = new Map();
  let lastWord = 0;
  let pingSent = 0;
  let timer = null;
  let crashes = [];
  let stopping = false;
  const tail = [];                // the last 20 lines of the engine's log
  let lastFailure = null;
  // Where the engine was, so a restarted one comes back the same (doc 16 §7): the device it had open, the song file,
  // the last heard position and whether it was playing.
  const place = { device: null, song: null, clock: false, seconds: 0, playing: false };
  const heard = (c) => { if (c && typeof c.seconds === 'number') { place.seconds = c.seconds; place.playing = !!c.playing; } };

  const setState = (s, extra = {}) => { state = s; ev.emit('state', { state: s, pid, ...extra }); };
  function log(line) {
    tail.push(line); if (tail.length > 20) tail.shift();
    if (!logFile) return;
    try {
      mkdirSync(dirname(logFile), { recursive: true });
      if (existsSync(logFile) && statSync(logFile).size > LOG_MAX) truncateSync(logFile, 0);
      appendFileSync(logFile, `${line}\n`);
    } catch { /* the log never stops the engine */ }
  }

  function start() {
    if (child) return Promise.resolve();
    stopping = false;
    setState('starting');
    child = spawn(bin, args, { stdio: ['pipe', 'pipe', 'pipe'], env });
    pid = child.pid;
    lastWord = Date.now();
    pingSent = 0;
    const me = child;
    createInterface({ input: me.stdout }).on('line', (line) => {
      let msg;
      try { msg = JSON.parse(line); } catch { return log(`(not a protocol line) ${line}`); }
      lastWord = Date.now();
      if (msg.id !== undefined && pending.has(msg.id)) {
        const p = pending.get(msg.id);
        pending.delete(msg.id);
        clearTimeout(p.timer);
        if (msg.ok) p.resolve(msg.result); else p.reject(new Error(msg.error || 'the engine said no'));
        return;
      }
      if (msg.ev) {
        if (msg.ev === 'clock') heard(msg);
        if (msg.ev === 'log') log(`[${msg.level || 'info'}] ${msg.text}`);
        ev.emit('event', msg);
        ev.emit(msg.ev, msg);
      }
    });
    createInterface({ input: me.stderr }).on('line', (line) => log(line));
    // Node: a process that could not be spawned emits 'error' (not 'spawn'), and 'exit' may or may not follow. With no
    // pid it never ran: handled as an exit (child reset, pending calls refused, the usual restart and give-up), once.
    me.on('error', (e) => { log(`could not start: ${e.message}`); if (me.pid === undefined) onExit(me, null, null); });
    me.stdin.on('error', (e) => log(`could not write to the engine: ${e.message}`)); // EPIPE when it died: never a crash
    me.on('exit', (code, signal) => onExit(me, code, signal));
    clearInterval(timer);
    timer = setInterval(heartbeat, checkMs);
    return call('engine.hello', {}, { timeout: Math.max(timeoutMs, 10_000) }).then((hello) => {
      setState('running', { hello });
      return hello;
    });
  }

  function heartbeat() {
    if (!child || state === 'failed') return;
    const quiet = Date.now() - lastWord;
    if (quiet < heartbeatMs) { pingSent = 0; return; }
    if (!pingSent) {
      pingSent = Date.now();
      call('engine.ping', {}, { timeout: heartbeatMs }).catch(() => {});
      return;
    }
    if (Date.now() - pingSent >= heartbeatMs) {
      log(`no word from the engine for ${Math.round(quiet / 1000)} s: restarting it`);
      killOwn();
    }
  }

  // Kills the PID this supervisor started, and nothing else.
  function killOwn() {
    if (!child || !pid) return;
    try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ }
  }

  function onExit(me, code, signal) {
    if (me !== child) return;
    child = null;
    clearInterval(timer);
    for (const p of pending.values()) { clearTimeout(p.timer); p.reject(new Error('the sound engine stopped')); }
    pending.clear();
    if (stopping) { pid = null; return setState('stopped'); }
    // which plugin it was touching, when it went down
    let touching = null;
    try { if (lastTouchFile && existsSync(lastTouchFile)) touching = readFileSync(lastTouchFile, 'utf8').trim() || null; } catch { touching = null; }
    lastFailure = { code, signal, touching, at: new Date().toISOString() };
    log(`the engine stopped (${signal || `exit ${code}`})${touching ? ` while touching ${touching}` : ''}`);
    const now = Date.now();
    crashes = crashes.filter((t) => now - t < crashWindowMs).concat(now);
    if (crashes.length >= maxCrashes) { pid = null; return setState('failed', { failure: lastFailure, log: [...tail] }); }
    const wait = backoffMs[Math.min(crashes.length - 1, backoffMs.length - 1)];
    setState('restarting', { failure: lastFailure, inMs: wait });
    setTimeout(async () => {
      if (stopping || child) return;
      try {
        await start();
        await comeBack();
        if (restore) await restore(api);
      } catch (e) { log(`restart failed: ${e.message}`); }
    }, wait);
  }

  function call(cmd, args = {}, { timeout = timeoutMs } = {}) {
    if (!child) return Promise.reject(new Error('the sound engine isn\'t running'));
    const id = nextId++;
    return new Promise((resolve, reject) => {
      const t = setTimeout(() => { pending.delete(id); reject(new Error(`the sound engine didn't answer ${cmd} within ${timeout / 1000} s`)); }, timeout);
      pending.set(id, { resolve, reject, timer: t });
      child.stdin.write(JSON.stringify({ id, cmd, args }) + '\n');
    }).then((result) => {
      if (cmd === 'device.set') place.device = args;
      if (cmd === 'song.load' || cmd === 'song.patch') { place.song = args.path || place.song; if (cmd === 'song.load') { place.seconds = Number(args.atSeconds) || 0; place.playing = false; } }
      if (cmd === 'clock.subscribe') place.clock = true;
      if (cmd.startsWith('transport.')) heard(result);
      return result;
    });
  }

  // After a restart: the same device, the song at the last heard position, the clock, and playing again if it was.
  async function comeBack() {
    const { device, song, clock, seconds, playing } = place;
    if (device) await call('device.set', device, { timeout: 15000 });
    if (song) await call('song.load', { path: song, atSeconds: seconds }, { timeout: 120000 });
    if (clock) await call('clock.subscribe', {});
    if (song && device && playing) await call('transport.play', {});
    log(`came back${song ? ` with ${song} at ${seconds.toFixed(3)} s${playing ? ', playing' : ''}` : ''}`);
  }

  // Asks it to quit, then kills its PID if it hasn't after `graceMs`.
  async function stop({ graceMs = 2000 } = {}) {
    stopping = true;
    clearInterval(timer);
    if (!child) { setState('stopped'); return; }
    const me = child;
    const gone = new Promise((r) => me.once('exit', r));
    call('engine.quit', {}, { timeout: graceMs }).catch(() => {});
    const t = setTimeout(() => { if (child === me) killOwn(); }, graceMs);
    await gone;
    clearTimeout(t);
  }

  // Start again after it gave up (the "Start again" button).
  function reset() { crashes = []; if (state === 'failed') return start(); return Promise.resolve(); }

  const api = {
    start, stop, call, reset, on: (name, fn) => { ev.on(name, fn); return () => ev.off(name, fn); },
    get state() { return state; }, get pid() { return pid; }, get log() { return [...tail]; }, get failure() { return lastFailure; }, get place() { return { ...place }; },
  };
  return api;
}

// The studio's one engine (started the first time the music needs it, stopped with the server).
const engines = new Map();
export function enginePaths(root) {
  const run = join(root, 'run', 'daw-engine');
  return { bin: join(root, 'tools', 'daw-engine', 'mortiflix-engine'), run, log: join(run, 'engine.log'), lastTouch: join(run, 'last-touch') };
}
export function engineFor(root, opts = {}) {
  if (engines.has(root)) return engines.get(root);
  const p = enginePaths(root);
  const e = createEngineSupervisor({ bin: opts.bin || process.env.MFX_DAW_ENGINE || p.bin, logFile: p.log, lastTouchFile: p.lastTouch, args: ['--serve'], ...opts });
  engines.set(root, e);
  return e;
}
export async function stopEngines() { await Promise.all([...engines.values()].map((e) => e.stop())); engines.clear(); }