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.

19.4 KB
Raw Blame
// The script in one quick call. A full session spent fourteen steps on it (open the start files, write, fix with sed,
// split into beats, submit, tick the checklist), each step re-reading everything before it: ~650k tokens for a page
// of words. Here the studio hands one lean Claude Code call everything the script needs (the brief and its answers,
// the owner's chat, the pipeline's script rules, the last version and its notes) and gets the beats back as JSON
// (web search allowed, for the facts); the studio writes script.md and script/beats.json, counts the length itself,
// and submits. Anything it can't do honestly (an owner's own script in input/, a check it can't report, a length
// that won't fit) goes to a normal session, as before.
import { runAs } from './models.mjs';
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, appendFileSync } from 'node:fs';
import { join } from 'node:path';
import { paths, writeJson } from './studio.mjs';
import { loadProject, projectPaths, projectPipeline } from './projects.mjs';
import { stepView, stepChecks, submit, submissions } from './gates.mjs';
import { chatHistory } from './svc/chat.mjs';
import { serviceBrief } from './svc/brief.mjs';
import { listAssets } from './svc/assets.mjs';
import { speechPace } from './svc/pace.mjs';
import { narratorVoice } from './svc/voicecast.mjs';

export const WORDS_PER_MINUTE = 120; // only when no voice has been measured yet: scriptPace() is the real one
// Words a minute this project's narrator really speaks (pauses included), from the takes the studio made (svc/pace.mjs).
export function scriptPace(root, id) {
  try { return speechPace(root, { voiceId: narratorVoice(root, id).voice_id }).wpm; } catch { return WORDS_PER_MINUTE; }
}
const QUICK_CHECKS = ['spelling-and-facts', 'script-fits-length'];

// The script step, when it's the only work a session would do now and the quick call can do it; otherwise null.
export function quickScriptStep(root, id, config) {
  if (config.quickScript === false) return null;
  const project = loadProject(root, id);
  const pipeline = projectPipeline(root, id);
  const step = pipeline.steps.find((s) => s.key === 'script');
  if (!step || step.review !== 'document') return null;
  const runnable = stepView(project, pipeline).filter((s) => ['ready', 'working', 'changes'].includes(s.state));
  if (runnable.length !== 1 || runnable[0].key !== 'script') return null;
  if (project.mfx && Object.keys(project.mfx).some((k) => k.endsWith('_wanted'))) return null;
  // The owner's own script is tidied by a session (it's spoken verbatim).
  const input = join(projectPaths(root, id).work, 'input');
  if (existsSync(input) && readdirSync(input).length) return null;
  if (stepChecks(root, id, 'script').some((c) => !QUICK_CHECKS.includes(c.id))) return null;
  return runnable[0];
}

// "60 s", "90 seconds", "2 min", "1:30", "20-30 min" (the upper end) → seconds; null when it says no length.
export function lengthSeconds(text) {
  const s = String(text || '').toLowerCase();
  let m = /(\d+):(\d{2})/.exec(s);
  if (m) return Number(m[1]) * 60 + Number(m[2]);
  m = /(\d+(?:\.\d+)?)(?:\s*(?:-|–|to)\s*(\d+(?:\.\d+)?))?\s*(s\b|sec|seconds?|m\b|min|minutes?)/.exec(s);
  if (!m) return null;
  const n = Number(m[2] || m[1]);
  return /^m/.test(m[3]) ? n * 60 : n;
}

export const countWords = (text) => (String(text).match(/[\p{L}\p{N}][\p{L}\p{N}'’.-]*/gu) || []).length;

const SCHEMA = {
  type: 'object',
  required: ['title', 'intro', 'beats', 'note', 'facts_note'],
  properties: {
    title: { type: 'string', description: 'the script heading, e.g. "The Golden Braid"' },
    intro: { type: 'string', description: 'two or three lines under the heading: length, voice, tone, pronunciations' },
    beats: {
      type: 'array',
      items: {
        type: 'object',
        required: ['name', 'words', 'visual'],
        properties: {
          name: { type: 'string', description: 'a short title, 2-4 words' },
          words: { type: 'string', description: 'exactly what the narrator says, nothing else' },
          visual: { type: 'string', description: 'one line: what is on screen' },
        },
      },
    },
    note: { type: 'string', description: 'for the owner: what this version is, the flow, and what to look at' },
    facts_note: { type: 'string', description: 'every name, date and number checked, and against what' },
    pin_changes: {
      type: 'array',
      items: { type: 'object', required: ['note', 'change', 'status'], properties: { note: { type: 'integer' }, change: { type: 'string' }, status: { type: 'string', enum: ['done', 'partly', 'not_done'] } } },
    },
  },
};

export function scriptPrompt(root, id, view, { targetSec, tooLong = null } = {}) {
  const project = loadProject(root, id);
  const pp = projectPaths(root, id);
  const subs = submissions(root, id);
  const brief = subs.filter((s) => s.step === 'brief').at(-1);
  const pipelineMd = existsSync(join(pp.work, 'pipeline', 'PIPELINE.md')) ? readFileSync(join(pp.work, 'pipeline', 'PIPELINE.md'), 'utf8') : '';
  const checks = stepChecks(root, id, 'script');
  const since = brief?.submitted_at || '';
  const chat = chatHistory(root, id, { limit: 500 }).filter((r) => ['user', 'action'].includes(r.role) && r.at >= since && !r.edit).slice(-40);
  const last = subs.filter((s) => s.step === 'script').at(-1);
  const parts = [
    `You write the script for "${project.title}", a ${projectPipeline(root, id).makes} made in the Mortiflix studio for its owner. Answer with the JSON asked for, nothing else. Use web search only to check a fact you aren't sure of.`,
    `## What the owner asked for (the new-project form)\n${JSON.stringify(project.intake?.answers || {}, null, 1)}`,
  ];
  parts.push(...studioContext(root, id));
  if (brief) parts.push(`## The brief, as the studio read it\n${brief.note}`);
  if (brief?.feedback) parts.push(`## The owner's answers to the brief\n${(brief.feedback.answers || []).map((a) => `- ${a.text} → ${a.answer}${a.used_default ? ' (default)' : ''}`).join('\n')}${brief.feedback.overall ? `\nOverall: ${brief.feedback.overall}` : ''}`);
  if (chat.length) parts.push(`## The owner's words in the chat since then (newest last; they win over the answers above)\n${chat.map((r) => `- ${r.text}`).join('\n')}`);
  for (const s of subs.filter((x) => !['brief', 'script'].includes(x.step) && x.feedback?.verdict === 'approve')) {
    const text = s.items.filter((it) => it.kind === 'text' && it.text).map((it) => it.text).join('\n\n').slice(0, 20_000);
    if (text) parts.push(`## Approved ${s.step} v${s.version}\n${text}`);
  }
  parts.push(`## The pipeline (follow its rules for the script step)\n${pipelineMd}`);
  parts.push(`## Checks the script must pass\n${checks.map((c) => `- ${c.id}: ${c.how}`).join('\n')}`);
  const wpm = scriptPace(root, id);
  parts.push(`## Length\n${targetSec ? `Target ${targetSec} s: about ${Math.round((targetSec / 60) * wpm)} spoken words at ${wpm} a minute (this voice's measured pace, pauses included), within 10%, with room for the holds.` : 'No length was given: choose the length the topic needs to be covered well.'}${tooLong ? `\nYour last try was ${tooLong.words} words (${tooLong.sec} s): bring it inside the target.` : ''}`);
  if (view.state === 'changes' && last) {
    const text = last.items.filter((it) => it.kind === 'text').map((it) => it.text).join('\n\n');
    parts.push(`## Version ${last.version} (the owner asked for changes)\n${text}\n\n## The owner's notes on it\n${last.feedback?.overall ? `Overall: ${last.feedback.overall}\n` : ''}${(last.feedback?.notes || []).map((n) => `${n.n}. ${n.paragraph !== undefined ? `(paragraph ${n.paragraph}) ` : ''}${n.text}`).join('\n')}\nAnswer every note in pin_changes (note number, what you changed, done/partly/not_done).`);
  }
  parts.push('Beats: one idea each, in order. `words` is exactly what is spoken; `visual` is one line on what we see. Never imitate a real brand that isn\'t the owner\'s own.');
  return parts.join('\n\n');
}

// What a session's CLAUDE.md also gives it: the preset's look and voice, the music theme, the owner's taste.
function studioContext(root, id) {
  const out = [];
  const svc = serviceBrief(root, id);
  if (svc) out.push(svc);
  const taste = existsSync(join(root, 'TASTE.md')) ? readFileSync(join(root, 'TASTE.md'), 'utf8').trim() : '';
  if (taste) out.push(`## The owner's taste (learned across projects)\n${taste}`);
  return out;
}

export function scriptMarkdown(s, version) {
  const beats = s.beats.map((b, i) => `### B${String(i + 1).padStart(2, '0')} · ${b.name.trim()}\n*${b.visual.trim().replace(/\*/g, '')}*\n\n${b.words.trim()}`);
  return `# ${s.title.trim()} · Script v${version}\n\n${s.intro.trim()}\n\n---\n\n${beats.join('\n\n')}\n`;
}

function tickChecklist(work, line, section = 'Script') {
  const f = join(work, 'checklist.md');
  if (!existsSync(f)) return;
  const lines = readFileSync(f, 'utf8').split('\n');
  const at = lines.findIndex((l) => new RegExp(`^##\\s+${section}\\b`, 'i').test(l));
  if (at < 0) return;
  for (let i = at + 1; i < lines.length && !/^##\s/.test(lines[i]); i++) lines[i] = lines[i].replace(/^- \[ \]/, '- [x]');
  let end = at + 1;
  while (end < lines.length && !/^##\s/.test(lines[end]) && lines[end].trim()) end++;
  lines.splice(end, 0, `- [x] ${line}`);
  writeFileSync(f, lines.join('\n'));
}

// Write the script with one call through `run` (the claude-code backend's run), submit it, and return the run's
// result. `fallback()` runs a normal session; it is used whenever the quick call can't finish the job.
export async function quickScript({ root, id, view, run, runArgs, config, onActivity, fallback }) {
  const pp = projectPaths(root, id);
  const intake = loadProject(root, id).intake?.answers || {};
  const targetSec = lengthSeconds(intake.length);
  const wpm = scriptPace(root, id);
  const dir = join(paths(root).run, 'quick');
  mkdirSync(dir, { recursive: true });
  const quickConfig = { ...config, claudeArgs: ['--tools', 'WebSearch WebFetch', '--allowedTools', 'WebSearch WebFetch', '--json-schema', JSON.stringify(SCHEMA)] };
  let total = { input_tokens: 0, output_tokens: 0 };
  let last = null;
  let tooLong = null;
  onActivity({ kind: 'info', text: 'Writing the script in one call.' });
  for (let attempt = 0; attempt < 2; attempt++) {
    const r = await runAs(run, 'script', { ...runArgs, workdir: dir, prompt: scriptPrompt(root, id, view, { targetSec, tooLong }), config: quickConfig });
    last = r;
    if (runArgs.signal?.aborted) return r;
    total = { input_tokens: total.input_tokens + (r.usage?.input_tokens || 0), output_tokens: total.output_tokens + (r.usage?.output_tokens || 0) };
    if (!r.ok) break;
    const s = r.structured;
    if (!s || !Array.isArray(s.beats) || !s.beats.length || s.beats.some((b) => !String(b.words || '').trim())) { last = { ...r, ok: false, error: 'the script call gave no beats' }; break; }
    const words = s.beats.reduce((n, b) => n + countWords(b.words), 0);
    const sec = Math.round((words / wpm) * 600) / 10;
    if (targetSec && Math.abs(sec - targetSec) > targetSec * 0.1) { tooLong = { words, sec }; continue; }
    const version = view.version + 1;
    writeFileSync(join(pp.work, 'script.md'), scriptMarkdown(s, version));
    mkdirSync(join(pp.work, 'script'), { recursive: true });
    writeJson(join(pp.work, 'script', 'beats.json'), {
      beats: s.beats.map((b, i) => ({ id: `b${String(i + 1).padStart(2, '0')}`, name: b.name.trim(), words: b.words.trim(), visual: b.visual.trim(), target_sec: Math.round((countWords(b.words) / wpm) * 600) / 10 })),
    });
    const lengthNote = `${words} words ÷ ${wpm} per minute = ${sec} s${targetSec ? `, inside ${Math.round(targetSec * 0.9)}–${Math.round(targetSec * 1.1)} s (${targetSec} s ± 10%)` : ' (no target length in the brief)'}; counted by the studio.`;
    try {
      submit(root, id, 'script', {
        note: s.note,
        questions: [],
        items: [{ path: 'script.md', label: `Script v${version}` }],
        error_checks: [
          { id: 'spelling-and-facts', result: 'pass', note: s.facts_note },
          { id: 'script-fits-length', result: 'pass', note: lengthNote },
        ].filter((c) => stepChecks(root, id, 'script').some((n) => n.id === c.id)),
        pin_changes: s.pin_changes || [],
      });
    } catch (e) {
      return fallback(`the script was refused: ${e.message}`);
    }
    tickChecklist(pp.work, `Script submitted v${version} (${words} words, ~${sec} s, ${s.beats.length} beats) by the quick script call: waiting on owner`);
    appendFileSync(join(pp.work, 'JOURNAL.md'), `\n- ${new Date().toISOString()} · Script v${version} written in one quick call and submitted (${words} words, ~${sec} s, ${s.beats.length} beats).\n`);
    return { ...last, usage: total };
  }
  const r = await fallback(`the quick script didn't work (${last?.ok ? `${tooLong.words} words, ${tooLong.sec} s, off the target` : last?.error || 'no answer'})`);
  return { ...r, usage: { input_tokens: total.input_tokens + (r.usage?.input_tokens || 0), output_tokens: total.output_tokens + (r.usage?.output_tokens || 0) } };
}

// ---- the brief, the same way ----
// A full session spent five steps on it (182k tokens, almost all the same context re-read): look in input/, search the
// web twice, write notes, submit, tick the checklist. Here one call gets the new-project answers, the preset, the
// owner's taste and chat, and the pipeline's brief rules, may search the web, and returns the restatement and the
// questions; the studio submits them. Files to read (input/, the owner's assets) go to a session.

export function quickBriefStep(root, id, config) {
  if (config.quickScript === false) return null;
  const project = loadProject(root, id);
  const pipeline = projectPipeline(root, id);
  const step = pipeline.steps.find((s) => s.key === 'brief');
  if (!step || step.review !== 'questions') return null;
  const runnable = stepView(project, pipeline).filter((s) => ['ready', 'working', 'changes'].includes(s.state));
  if (runnable.length !== 1 || runnable[0].key !== 'brief') return null;
  if (project.mfx && Object.keys(project.mfx).some((k) => k.endsWith('_wanted'))) return null;
  if ((project.intake?.files || []).length) return null;
  const input = join(projectPaths(root, id).work, 'input');
  if (existsSync(input) && readdirSync(input).length) return null;
  try { if (listAssets(root, id).length) return null; } catch { /* no assets */ }
  if (stepChecks(root, id, 'brief').length) return null;
  return runnable[0];
}

export const BRIEF_SCHEMA = {
  type: 'object',
  required: ['note', 'questions'],
  properties: {
    note: { type: 'string', description: 'for the owner: the brief restated in three lines (what, for whom, the one takeaway), then a line on the questions' },
    questions: {
      type: 'array',
      items: {
        type: 'object',
        required: ['id', 'text', 'choices', 'default'],
        properties: {
          id: { type: 'string', description: 'short, lowercase, e.g. tone' },
          text: { type: 'string' },
          choices: { type: 'array', items: { type: 'string' }, description: '2-4 choices; empty for an own-words answer' },
          default: { type: 'string', description: 'one of the choices, word for word (or the suggested words when there are no choices)' },
        },
      },
    },
    research_notes: { type: 'string', description: 'Markdown: what the web search found that the script will need, with source links; empty if nothing' },
    pin_changes: {
      type: 'array',
      items: { type: 'object', required: ['note', 'change', 'status'], properties: { note: { type: 'integer' }, change: { type: 'string' }, status: { type: 'string', enum: ['done', 'partly', 'not_done'] } } },
    },
  },
};

export function briefPrompt(root, id, view) {
  const project = loadProject(root, id);
  const pp = projectPaths(root, id);
  const pipeline = projectPipeline(root, id);
  const pipelineMd = existsSync(join(pp.work, 'pipeline', 'PIPELINE.md')) ? readFileSync(join(pp.work, 'pipeline', 'PIPELINE.md'), 'utf8') : '';
  const last = submissions(root, id).filter((s) => s.step === 'brief').at(-1);
  const parts = [
    `You read the brief for "${project.title}", a ${pipeline.makes} made in the Mortiflix studio for its owner. Answer with the JSON asked for, nothing else. Search the web only for facts that change which questions to ask.`,
    `## What the owner asked for (the new-project form)\n${JSON.stringify(project.intake?.answers || {}, null, 1)}`,
    ...studioContext(root, id),
  ];
  parts.push(`## The pipeline (follow its rules for the brief step)\n${pipelineMd}`);
  if (view.state === 'changes' && last) {
    parts.push(`## Version ${last.version} (the owner asked for changes)\n${last.note}\n${JSON.stringify(last.questions)}\n\n## The owner's notes on it\n${last.feedback?.overall ? `Overall: ${last.feedback.overall}\n` : ''}${(last.feedback?.notes || []).map((n) => `${n.n}. ${n.text}`).join('\n')}\nAnswer every note in pin_changes (note number, what you changed, done/partly/not_done).`);
  }
  parts.push('Questions: only ones that change the video, each with a default the owner can just accept. Never imitate a real brand that isn\'t the owner\'s own: if the topic is someone else\'s brand, one question says how you\'ll keep it generic.');
  return parts.join('\n\n');
}

export async function quickBrief({ root, id, view, run, runArgs, config, onActivity, fallback }) {
  const pp = projectPaths(root, id);
  const dir = join(paths(root).run, 'quick');
  mkdirSync(dir, { recursive: true });
  onActivity({ kind: 'info', text: 'Reading the brief in one call.' });
  const r = await runAs(run, 'brief', { ...runArgs, workdir: dir, prompt: briefPrompt(root, id, view), config: { ...config, claudeArgs: ['--tools', 'WebSearch WebFetch', '--allowedTools', 'WebSearch WebFetch', '--json-schema', JSON.stringify(BRIEF_SCHEMA)] } });
  if (runArgs.signal?.aborted) return r;
  const s = r.ok ? r.structured : null;
  let why = !r.ok ? r.error || 'no answer' : !s?.note?.trim() || !Array.isArray(s.questions) || !s.questions.length ? 'no questions came back' : null;
  if (!why) {
    const version = view.version + 1;
    const items = [];
    if (String(s.research_notes || '').trim()) {
      mkdirSync(join(pp.work, 'research'), { recursive: true });
      writeFileSync(join(pp.work, 'research', 'brief-notes.md'), `${s.research_notes.trim()}\n`);
      items.push({ path: 'research/brief-notes.md', label: 'Early research notes' });
    }
    const questions = s.questions.map((q) => {
      const choices = (q.choices || []).map(String).filter((c) => c.trim()).slice(0, 12);
      // the default word for word as one of its choices (a different case or spacing is the same choice)
      const same = choices.find((c) => c.trim().toLowerCase() === String(q.default || '').trim().toLowerCase());
      return { id: q.id, text: q.text, ...(choices.length ? { choices } : {}), default: same ?? q.default };
    });
    try {
      submit(root, id, 'brief', { note: s.note, questions, items, error_checks: [], pin_changes: s.pin_changes || [] });
      tickChecklist(pp.work, `Brief submitted v${version} (${questions.length} questions) by the quick brief call: waiting on owner`, 'Brief');
      appendFileSync(join(pp.work, 'JOURNAL.md'), `\n- ${new Date().toISOString()} · Brief v${version} read in one quick call and submitted (${questions.length} questions).\n`);
      return r;
    } catch (e) {
      why = `the brief was refused: ${e.message}`;
    }
  }
  const f = await fallback(`the quick brief didn't work (${why})`);
  return { ...f, usage: { input_tokens: (r.usage?.input_tokens || 0) + (f.usage?.input_tokens || 0), output_tokens: (r.usage?.output_tokens || 0) + (f.usage?.output_tokens || 0) } };
}