@docyrus/animaguru 0.19.0 → 0.22.0

package/templates/video/scripts/quiz.mjs

@@ -0,0 +1,126 @@
+/**
+ * A quiz over a film: checkpoints pause it at chosen times to ask one question or a quick round, and a final quiz
+ * follows its end, then the viewer's score. quiz.json sits beside film.config.json and works with a linear film or a
+ * branching story. A quiz film plays as HTML5 only, because its questions wait for a viewer's answers; capture and
+ * review see the film without them.
+ */
+export const QUIZ_FILE = "quiz.json";
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const HEX = /^#[0-9a-f]{6}$/i;
+const EPSILON = 1e-6;
+/** The player's own words on the cards, which `ui` translates for a quiz in another language. */
+export const QUIZ_UI_KEYS = ["check", "final", "progress", "selectAll", "checkAnswer", "correct", "incorrect", "answer", "continue", "next", "seeResults", "watchAgain", "score", "passed", "notPassed", "perfect", "retake", "restart", "complete", "skipped"];
+
+const text = (value, max) => typeof value === "string" && value.trim().length > 0 && value.length <= max;
+
+/**
+ * Checks quiz.json against the film's duration and, for a branching story, its segments; throws an Error naming the
+ * first problem. Returns the quiz.
+ */
+export function validateQuiz(quiz, config, story = null) {
+  const fail = (message) => { throw new Error(`quiz.json: ${message}`); };
+  if (!quiz || typeof quiz !== "object" || Array.isArray(quiz)) fail("expected an object.");
+  if (quiz.version !== 1) fail('set "version": 1.');
+  const duration = Number(config?.duration);
+  const questionIds = new Set();
+  const checkQuestions = (questions, where, max) => {
+    if (!Array.isArray(questions) || questions.length < 1 || questions.length > max) fail(`${where} needs 1 to ${max} questions.`);
+    for (const [index, question] of questions.entries()) {
+      const at = `${where}, question ${index + 1}`;
+      if (!question || typeof question !== "object" || Array.isArray(question)) fail(`${at} must be an object.`);
+      if (question.id !== undefined) {
+        if (typeof question.id !== "string" || !ID.test(question.id)) fail(`${at} needs a lowercase, hyphenated id of up to 40 characters, or none.`);
+        if (questionIds.has(question.id)) fail(`two questions use the id ${question.id}.`);
+        questionIds.add(question.id);
+      }
+      if (!text(question.prompt, 160)) fail(`${at} needs a prompt of up to 160 characters.`);
+      if (!Array.isArray(question.options) || question.options.length < 2 || question.options.length > 6) fail(`${at} needs 2 to 6 options.`);
+      for (const option of question.options) if (!text(option, 100)) fail(`${at} has an option that is not text of up to 100 characters.`);
+      if (new Set(question.options.map((option) => option.trim().toLowerCase())).size !== question.options.length) fail(`${at} has two options with the same text.`);
+      const count = question.options.length;
+      const option = (value) => Number.isInteger(value) && value >= 0 && value < count;
+      if (Array.isArray(question.answer)) {
+        // "Select all that apply": the right options, in order; not every option, or there is nothing to choose.
+        if (!question.answer.length || !question.answer.every(option) || question.answer.some((value, position) => position > 0 && value <= question.answer[position - 1])) fail(`${at} lists its right options (answer) as indices in increasing order, such as [0, 2].`);
+        if (question.answer.length === count) fail(`${at} makes every option right; leave at least one wrong option.`);
+      } else if (!option(question.answer)) fail(`${at} needs answer: the index of the right option (0 is the first), or a list of indices for "select all that apply".`);
+      if (question.explanation !== undefined && !text(question.explanation, 280)) fail(`${at} has an explanation that is not text of up to 280 characters.`);
+    }
+  };
+  const segments = story?.segments ?? null;
+  const checkpoints = quiz.checkpoints ?? [];
+  if (!Array.isArray(checkpoints) || checkpoints.length > 24) fail("list up to 24 checkpoints.");
+  const checkpointIds = new Set();
+  let previous = null;
+  for (const [index, checkpoint] of checkpoints.entries()) {
+    const where = `checkpoint ${index + 1}${checkpoint && typeof checkpoint.id === "string" ? ` (${checkpoint.id})` : ""}`;
+    if (!checkpoint || typeof checkpoint !== "object" || Array.isArray(checkpoint)) fail(`${where} must be an object.`);
+    if (typeof checkpoint.id !== "string" || !ID.test(checkpoint.id)) fail(`${where} needs a lowercase, hyphenated id of up to 40 characters.`);
+    if (checkpointIds.has(checkpoint.id)) fail(`two checkpoints use the id ${checkpoint.id}.`);
+    checkpointIds.add(checkpoint.id);
+    if (!Number.isFinite(checkpoint.at) || checkpoint.at < 0.5 || (Number.isFinite(duration) && checkpoint.at > duration + EPSILON)) fail(`${where} needs at: the second of the film's timeline it pauses at, from 0.5 to the film's duration.`);
+    if (previous && checkpoint.at - previous.at < 2 - EPSILON) fail(`${where} must come at least 2 s after ${previous.id} (${previous.at} s): list checkpoints in time order, or put both rounds of questions in one checkpoint.`);
+    if (checkpoint.title !== undefined && !text(checkpoint.title, 40)) fail(`${where} has a title that is not text of up to 40 characters.`);
+    let from = 0;
+    if (segments) {
+      const segment = checkpointSegment(checkpoint, segments);
+      if (!segment) fail(`${where} is not inside a story segment.`);
+      const choiceAt = segment.choiceAt ?? segment.end;
+      if (segment.choices && checkpoint.at > choiceAt + EPSILON) fail(`${where} comes after ${segment.id}'s choices appear (${choiceAt} s); ask before them.`);
+      from = segment.start;
+    }
+    if (checkpoint.review !== undefined && (!Number.isFinite(checkpoint.review) || checkpoint.review < from - EPSILON || checkpoint.review > checkpoint.at - 0.5)) fail(`${where} needs review: the second Watch again goes back to, at least 0.5 s before its own time${segments ? " and within its story segment" : ""}.`);
+    checkQuestions(checkpoint.questions, where, 5);
+    previous = checkpoint;
+  }
+  if (quiz.final !== undefined) {
+    const final = quiz.final;
+    if (!final || typeof final !== "object" || Array.isArray(final)) fail("final must be an object with questions.");
+    if (final.title !== undefined && !text(final.title, 40)) fail("final has a title that is not text of up to 40 characters.");
+    if (final.pass !== undefined && (!Number.isInteger(final.pass) || final.pass < 1 || final.pass > 100)) fail("final.pass is the percentage of right answers that passes, from 1 to 100.");
+    checkQuestions(final.questions, "the final quiz", 20);
+  }
+  if (!checkpoints.length && quiz.final === undefined) fail("add checkpoints, a final quiz, or both.");
+  if (quiz.theme !== undefined) {
+    if (!quiz.theme || typeof quiz.theme !== "object" || Array.isArray(quiz.theme)) fail("theme must be an object of colors.");
+    for (const [key, value] of Object.entries(quiz.theme)) if (!["accent", "surface", "text"].includes(key) || !HEX.test(value)) fail(`theme.${key} must be accent, surface or text as a six-digit hex color.`);
+  }
+  if (quiz.ui !== undefined) {
+    if (!quiz.ui || typeof quiz.ui !== "object" || Array.isArray(quiz.ui)) fail("ui must be an object of player labels.");
+    for (const [key, value] of Object.entries(quiz.ui)) if (!QUIZ_UI_KEYS.includes(key) || !text(value, 80)) fail(`ui.${key} must be one of ${QUIZ_UI_KEYS.join(", ")}, with up to 80 characters.`);
+  }
+  return quiz;
+}
+
+/** The story segment a checkpoint pauses in: a checkpoint at a segment's end belongs to that segment. */
+export function checkpointSegment(checkpoint, segments) {
+  return segments.find((segment) => checkpoint.at > segment.start + EPSILON && checkpoint.at <= segment.end + EPSILON) ?? null;
+}
+
+/** What the manifest and review say about a valid quiz. */
+export function quizSummary(quiz) {
+  const checkpoints = quiz.checkpoints ?? [];
+  const asked = checkpoints.reduce((total, checkpoint) => total + checkpoint.questions.length, 0);
+  const final = quiz.final?.questions.length ?? 0;
+  return { checkpoints: checkpoints.length, questions: asked + final, final, pass: quiz.final?.pass ?? null };
+}
+
+/** Review notes on a valid quiz: things that work but that a viewer may trip over. */
+export function quizNotes(quiz) {
+  const notes = [];
+  const checkpoints = quiz.checkpoints ?? [];
+  const questions = [...checkpoints.flatMap((checkpoint) => checkpoint.questions), ...(quiz.final?.questions ?? [])];
+  const single = questions.filter((question) => !Array.isArray(question.answer));
+  if (single.length >= 3 && new Set(single.map((question) => question.answer)).size === 1) notes.push(`the right answer is option ${single[0].answer + 1} in every one-answer question; vary it so guessing the position does not work.`);
+  const unexplained = questions.filter((question) => question.explanation === undefined).length;
+  if (unexplained) notes.push(`${unexplained} question${unexplained === 1 ? " has" : "s have"} no explanation; a sentence on why teaches more than "Correct" or "Not quite".`);
+  for (let index = 1; index < checkpoints.length; index++) {
+    const gap = checkpoints[index].at - checkpoints[index - 1].at;
+    if (gap < 8) notes.push(`${checkpoints[index - 1].id} and ${checkpoints[index].id} pause only ${Math.round(gap * 10) / 10} s apart; viewers may feel interrupted.`);
+  }
+  for (const checkpoint of checkpoints) if (checkpoint.questions.length > 3) notes.push(`${checkpoint.id} asks ${checkpoint.questions.length} questions in the middle of the film; consider moving some to the final quiz.`);
+  const long = questions.filter((question) => question.prompt.length > 110 || question.options.some((option) => option.length > 60)).length;
+  if (long) notes.push(`${long} question${long === 1 ? " has" : "s have"} a prompt over 110 characters or an option over 60; check the card on a phone.`);
+  if (quiz.final?.pass !== undefined && quiz.final.questions.length < 3) notes.push(`a pass mark over ${quiz.final.questions.length} final question${quiz.final.questions.length === 1 ? "" : "s"} is coarse; it also counts the checkpoints' questions.`);
+  return notes;
+}

package/templates/video/scripts/review.mjs

@@ -8,6 +8,8 @@ import { workspacePlugin } from "./workspace-plugin.mjs";
 import { analyzeReview, reviewLines } from "./review-analysis.mjs";
 import { inspectAudio } from "./review-audio.mjs";
 import { captureHeadless, takeHeadlessFlag } from "./headless-browser.mjs";
+import { storyNotes, storySummary } from "./story.mjs";
+import { quizNotes, quizSummary } from "./quiz.mjs";
 
 const root=fileURLToPath(new URL("../",import.meta.url));
 const selection=projectArguments(process.argv.slice(2));
@@ -32,9 +34,15 @@ const server=await createServer({configFile:false,root,base:"./",publicDir:conte
         if(typeof frame.image!=="string"||!frame.image.startsWith("data:image/jpeg;base64,"))throw new Error("Expected JPEG review frame.");
         await writeFile(path.join(output,`frame-${String(i).padStart(2,"0")}.jpg`),Buffer.from(frame.image.split(",")[1],"base64"));
       }
-      await writeFile(path.join(output,"report.json"),JSON.stringify({config,samples:report.samples,seekMatches:report.seekMatches,cues:report.cues,analysis,audio},null,2)+"\n");
+      // A branching story is reviewed as its whole timeline, every segment of every path; its graph was checked on load.
+      const story=context.story?{summary:storySummary(context.story),notes:storyNotes(context.story)}:null;
+      // A quiz's cards are HTML over the picture, so review checks the film under them and the questions' shape.
+      const quiz=context.quiz?{summary:quizSummary(context.quiz),notes:quizNotes(context.quiz)}:null;
+      await writeFile(path.join(output,"report.json"),JSON.stringify({config,samples:report.samples,seekMatches:report.seekMatches,cues:report.cues,analysis,audio,...(story?{story}:{}),...(quiz?{quiz}:{})},null,2)+"\n");
       console.log(`${analysis.pass?"Passed":"Failed"}: seek and text-bound checks. ${analysis.warnings.length} reading/layout notes. Frames and report: ${output}`);
       for(const line of reviewLines(analysis))console.log(line);
+      if(story){const{summary}=story;const count=(n,word)=>`${n} ${word}${n===1?"":"s"}`;console.log(`Story: ${count(summary.segments,"segment")}, ${count(summary.decisions,"choice")}, ${count(summary.endings,"ending")}; the shortest playthrough runs ${summary.shortestPlaythrough} s${summary.longestPlaythrough===null?" and a choice can loop back":`, the longest ${summary.longestPlaythrough} s`}, not counting time spent choosing.`);for(const note of story.notes)console.log(`Story note: ${note}`);}
+      if(quiz){const{summary}=quiz;const count=(n,word)=>`${n} ${word}${n===1?"":"s"}`;console.log(`Quiz: ${count(summary.questions,"question")}; ${count(summary.checkpoints,"checkpoint")} ${summary.checkpoints===1?"pauses":"pause"} the film${summary.final?` and the final quiz asks ${summary.final}`:""}${summary.pass===null?"":`; ${summary.pass}% passes`}.`);for(const note of quiz.notes)console.log(`Quiz note: ${note}`);}
       if(audio.status==="measured")console.log(`Audio: ${audio.integratedLufs} LUFS, true peak ${audio.truePeakDb} dBTP.${audio.notes.length?` ${audio.notes.join(" ")}`:""}`);
       console.log("Inspect the frames and moving playback with audio; numerical checks do not establish artistic quality or claim accuracy.");
       response.writeHead(200,{"Content-Type":"application/json"}).end(JSON.stringify(analysis));

package/templates/video/scripts/story.d.mts

@@ -0,0 +1,36 @@
+/** A viewer's choice: its button label and the segment it leads to. */
+export type StoryChoice = { label: string; to: string };
+/**
+ * One stretch of the film's timeline, in seconds. It ends in exactly one way: choices (the viewer picks the next
+ * segment), next (it continues into another segment) or ending (the story ends with this title).
+ */
+export type StorySegment = {
+  id: string; label: string; start: number; end: number;
+  choices?: StoryChoice[];
+  /** Asked above the choices. */
+  prompt?: string;
+  /** When the choices appear, in seconds of the film's timeline; the segment's end by default. */
+  choiceAt?: number;
+  /** Seconds the viewer has to choose before the default choice is taken; without it the player waits. */
+  timeout?: number;
+  /** The choice a timeout takes (an index into choices); the first by default. */
+  default?: number;
+  next?: string;
+  ending?: string;
+};
+export type StoryGraph = {
+  version: number; start: string; segments: StorySegment[];
+  /** The choice and ending panels' colors; otherwise the brand's. */
+  theme?: { accent?: string; surface?: string; text?: string };
+  /** The player's own words on the panels, for a story in another language. */
+  ui?: { theEnd?: string; playAgain?: string; back?: string; choose?: string };
+};
+export type StorySummary = {
+  start: string; segments: number; decisions: number; endings: number;
+  shortestPlaythrough: number; longestPlaythrough: number | null;
+};
+export const STORY_FILE: string;
+export function validateStory(story: unknown, config?: { duration: number }): StoryGraph;
+export function exitsOf(segment: StorySegment): string[];
+export function storySummary(story: StoryGraph): StorySummary;
+export function storyNotes(story: StoryGraph): string[];

package/templates/video/scripts/story.mjs

@@ -0,0 +1,139 @@
+/**
+ * A branching story: the film is one timeline of segments laid end to end, and story.json says where each segment goes
+ * next. The player plays one segment at a time and asks the viewer at a choice; review, frames and capture still see the
+ * whole timeline. A branching story plays as HTML5 only: an MP4 has one path.
+ */
+export const STORY_FILE = "story.json";
+const ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const HEX = /^#[0-9a-f]{6}$/i;
+const EPSILON = 1e-6;
+
+const text = (value, max) => typeof value === "string" && value.trim().length > 0 && value.length <= max;
+
+/** Checks story.json against the film's duration; throws an Error naming the first problem. Returns the story. */
+export function validateStory(story, config) {
+  const fail = (message) => { throw new Error(`story.json: ${message}`); };
+  if (!story || typeof story !== "object" || Array.isArray(story)) fail("expected an object.");
+  if (story.version !== 1) fail('set "version": 1.');
+  if (!Array.isArray(story.segments) || story.segments.length < 2 || story.segments.length > 64) fail("list 2 to 64 segments.");
+  const byId = new Map();
+  for (const [index, segment] of story.segments.entries()) {
+    const where = `segment ${index + 1}${segment && typeof segment.id === "string" ? ` (${segment.id})` : ""}`;
+    if (!segment || typeof segment !== "object") fail(`${where} must be an object.`);
+    if (typeof segment.id !== "string" || !ID.test(segment.id)) fail(`${where} needs a lowercase, hyphenated id of up to 40 characters.`);
+    if (byId.has(segment.id)) fail(`two segments use the id ${segment.id}.`);
+    byId.set(segment.id, segment);
+    if (!text(segment.label, 80)) fail(`${where} needs a label of up to 80 characters.`);
+    if (![segment.start, segment.end].every(Number.isFinite) || segment.end - segment.start < 0.5) fail(`${where} needs a start and an end at least 0.5 s apart, in seconds of the film's timeline.`);
+    const exits = ["choices", "next", "ending"].filter((key) => segment[key] !== undefined);
+    if (exits.length !== 1) fail(`${where} needs exactly one of choices, next or ending.`);
+    if (segment.choices !== undefined) {
+      if (!Array.isArray(segment.choices) || segment.choices.length < 2 || segment.choices.length > 4) fail(`${where} needs 2 to 4 choices.`);
+      for (const choice of segment.choices) {
+        if (!choice || !text(choice.label, 60)) fail(`${where} has a choice without a label of up to 60 characters.`);
+        if (typeof choice.to !== "string") fail(`${where} has a choice without a target segment ("to").`);
+      }
+      if (segment.prompt !== undefined && !text(segment.prompt, 120)) fail(`${where} has a prompt longer than 120 characters.`);
+      if (segment.choiceAt !== undefined && (!Number.isFinite(segment.choiceAt) || segment.choiceAt < segment.start || segment.choiceAt > segment.end)) fail(`${where} shows its choices (choiceAt) outside its own time.`);
+      if (segment.timeout !== undefined && (!Number.isFinite(segment.timeout) || segment.timeout < 3 || segment.timeout > 60)) fail(`${where} needs a timeout of 3 to 60 seconds, or none to wait for the viewer.`);
+      if (segment.default !== undefined && (!Number.isInteger(segment.default) || segment.default < 0 || segment.default >= segment.choices.length)) fail(`${where} names a default choice it does not have.`);
+      if (segment.default !== undefined && segment.timeout === undefined) fail(`${where} has a default choice but no timeout.`);
+    } else if (segment.ending !== undefined && !text(segment.ending, 80)) fail(`${where} needs an ending title of up to 80 characters.`);
+    else if (segment.next !== undefined && (typeof segment.next !== "string" || segment.next === segment.id)) fail(`${where} needs another segment as next.`);
+    for (const key of ["prompt", "choiceAt", "timeout", "default"]) if (segment[key] !== undefined && segment.choices === undefined) fail(`${where} has ${key} but no choices.`);
+  }
+  for (const segment of story.segments) {
+    for (const target of exitsOf(segment)) if (!byId.has(target)) fail(`${segment.id} leads to ${target}, which is not a segment.`);
+  }
+  if (typeof story.start !== "string" || !byId.has(story.start)) fail('set "start" to the id of the first segment the viewer sees.');
+  // The segments tile the film's timeline, so review and frame checks cover every one.
+  const ordered = [...story.segments].sort((a, b) => a.start - b.start);
+  if (Math.abs(ordered[0].start) > EPSILON) fail(`the first segment on the timeline (${ordered[0].id}) must start at 0.`);
+  for (let index = 1; index < ordered.length; index++) {
+    const before = ordered[index - 1], after = ordered[index];
+    if (Math.abs(after.start - before.end) > EPSILON) fail(`${after.id} must start where ${before.id} ends (${before.end} s): segments lie end to end on the timeline, without gaps or overlaps.`);
+  }
+  const duration = Number(config?.duration);
+  if (Number.isFinite(duration) && Math.abs(ordered.at(-1).end - duration) > EPSILON) fail(`the last segment (${ordered.at(-1).id}) ends at ${ordered.at(-1).end} s; set film.config.json's duration to ${ordered.at(-1).end}.`);
+  const reachable = walk(story.start, (id) => exitsOf(byId.get(id)));
+  const unreachable = story.segments.filter((segment) => !reachable.has(segment.id));
+  if (unreachable.length) fail(`no choice leads to ${unreachable.map((segment) => segment.id).join(", ")}.`);
+  const endings = story.segments.filter((segment) => segment.ending !== undefined).map((segment) => segment.id);
+  if (!endings.length) fail("give the story at least one ending.");
+  // Every segment can still reach an ending, so no path traps the viewer in a loop.
+  const into = new Map(story.segments.map((segment) => [segment.id, []]));
+  for (const segment of story.segments) for (const target of exitsOf(segment)) into.get(target).push(segment.id);
+  const finishing = new Set(endings.flatMap((id) => [...walk(id, (current) => into.get(current))]));
+  const trapped = story.segments.filter((segment) => !finishing.has(segment.id));
+  if (trapped.length) fail(`${trapped.map((segment) => segment.id).join(", ")} can never reach an ending.`);
+  if (story.theme !== undefined) {
+    if (!story.theme || typeof story.theme !== "object") fail("theme must be an object of colors.");
+    for (const [key, value] of Object.entries(story.theme)) if (!["accent", "surface", "text"].includes(key) || !HEX.test(value)) fail(`theme.${key} must be accent, surface or text as a six-digit hex color.`);
+  }
+  if (story.ui !== undefined) {
+    if (!story.ui || typeof story.ui !== "object") fail("ui must be an object of player labels.");
+    for (const [key, value] of Object.entries(story.ui)) if (!["theEnd", "playAgain", "back", "choose"].includes(key) || !text(value, 40)) fail(`ui.${key} must be theEnd, playAgain, back or choose, with up to 40 characters.`);
+  }
+  return story;
+}
+
+/** The segments a segment leads to. */
+export function exitsOf(segment) {
+  return segment.choices ? segment.choices.map((choice) => choice.to) : segment.next ? [segment.next] : [];
+}
+function walk(from, next) {
+  const seen = new Set([from]); const queue = [from];
+  while (queue.length) for (const id of next(queue.shift())) if (!seen.has(id)) { seen.add(id); queue.push(id); }
+  return seen;
+}
+
+/**
+ * What the manifest and review say about a valid story: its size, and how long the shortest and longest playthroughs
+ * run, not counting time spent choosing (longest is null when a choice can loop back).
+ */
+export function storySummary(story) {
+  const byId = new Map(story.segments.map((segment) => [segment.id, segment]));
+  const length = (id) => byId.get(id).end - byId.get(id).start;
+  const shortest = new Map([[story.start, length(story.start)]]); const queue = [story.start];
+  // Few segments: relaxing repeatedly is plenty.
+  while (queue.length) {
+    const id = queue.shift();
+    for (const target of exitsOf(byId.get(id))) {
+      const total = shortest.get(id) + length(target);
+      if (total < (shortest.get(target) ?? Infinity)) { shortest.set(target, total); queue.push(target); }
+    }
+  }
+  const endings = story.segments.filter((segment) => segment.ending !== undefined);
+  const longestFrom = new Map(); let cyclic = false;
+  const visiting = new Set();
+  const longest = (id) => {
+    if (longestFrom.has(id)) return longestFrom.get(id);
+    if (visiting.has(id)) { cyclic = true; return 0; }
+    visiting.add(id);
+    const best = length(id) + Math.max(0, ...exitsOf(byId.get(id)).map(longest));
+    visiting.delete(id); longestFrom.set(id, best);
+    return best;
+  };
+  const round = (value) => Math.round(value * 100) / 100;
+  const longestPath = longest(story.start);
+  return {
+    start: story.start, segments: story.segments.length,
+    decisions: story.segments.filter((segment) => segment.choices).length, endings: endings.length,
+    shortestPlaythrough: round(Math.min(...endings.map((segment) => shortest.get(segment.id)))),
+    longestPlaythrough: cyclic ? null : round(longestPath),
+  };
+}
+
+/** Review notes on a valid story: things that work but that a viewer may trip over. */
+export function storyNotes(story) {
+  const notes = [];
+  for (const segment of story.segments) {
+    if (!segment.choices) continue;
+    const at = segment.choiceAt ?? segment.end;
+    if (segment.timeout !== undefined && segment.timeout < 6) notes.push(`${segment.id}: a ${segment.timeout} s timeout leaves little time to read ${segment.choices.length} choices; 8–12 s is usual.`);
+    if (segment.end - at > 15) notes.push(`${segment.id}: the choices show ${Math.round(segment.end - at)} s before the segment ends; viewers who choose early wait for the end.`);
+    const labels = segment.choices.map((choice) => choice.label.trim().toLowerCase());
+    if (new Set(labels).size !== labels.length) notes.push(`${segment.id}: two choices have the same label.`);
+  }
+  return notes;
+}

package/templates/video/scripts/workspace-plugin.mjs

@@ -2,6 +2,8 @@ import { readFile, cp, mkdir, stat } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import path from "node:path";
 import { listAnimations, projectContext, publicFile, readBranding } from "./project-context.mjs";
+import { STORY_FILE } from "./story.mjs";
+import { QUIZ_FILE } from "./quiz.mjs";
 
 const htmlEscape = (value) => String(value).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 export function workspacePlugin(root, { animation, mode = "development" } = {}) {
@@ -16,11 +18,14 @@ export function workspacePlugin(root, { animation, mode = "development" } = {})
       const name = id.slice(virtualPrefix.length);
       const context = await projectContext(root, name);
       const source = (file) => JSON.stringify(`/@fs${file.split(path.sep).join("/")}`);
+      // A branching story's graph and a quiz's questions come from their JSON files, so edits to them reload the player.
+      const story = context.story ? `import story from ${source(path.join(context.projectRoot, STORY_FILE))};\n` : "";
+      const quiz = context.quiz ? `import quiz from ${source(path.join(context.projectRoot, QUIZ_FILE))};\n` : "";
       return `import config from ${source(path.join(context.projectRoot, "film.config.json"))};
 import {Film,chapters} from ${source(path.join(context.projectRoot, "src/film.ts"))};
 import project from ${source(path.join(context.projectRoot, "animaguru.project.json"))};
-import {mountPlayer} from "/runtime/player.ts";
-void mountPlayer({config,Film,chapters,branding:${JSON.stringify(context.branding)},exportEndpoint:${JSON.stringify(`/__animaguru/html?animation=${name}`)},templateLabel:project.templateLabel??project.template??"Choose category & style with your agent"});`;
+${story}${quiz}import {mountPlayer} from "/runtime/player.ts";
+void mountPlayer({config,Film,chapters,${context.story ? "story," : ""}${context.quiz ? "quiz," : ""}branding:${JSON.stringify(context.branding)},exportEndpoint:${JSON.stringify(`/__animaguru/html?animation=${name}`)},templateLabel:project.templateLabel??project.template??"Choose category & style with your agent"});`;
     },
     transformIndexHtml: { order: "pre", handler(html) {
       if (!animation) return html;
@@ -35,13 +40,13 @@ void mountPlayer({config,Film,chapters,branding:${JSON.stringify(context.brandin
         if (url.pathname === "/" && !animation) {
           void (async () => {
             const [animations, brand] = await Promise.all([listAnimations(root), readBranding(root)]);
-            const content = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${htmlEscape(brand.branding.name)} · AnimaGuru workspace</title><style>body{margin:0;background:#edf0f4;color:#111;font:15px system-ui}main{max-width:960px;margin:auto;padding:48px 24px}h1{font-size:32px}a{color:#1d56ad}ul{padding:0;display:grid;gap:14px;list-style:none}li{background:white;border:1px solid #d9dee6;padding:22px;border-radius:14px}code{font-size:13px}p{color:#6b7382;line-height:1.7}</style></head><body><main><p>AnimaGuru · shared video workspace</p><h1>${htmlEscape(brand.branding.name)}</h1><p>One brand. Many animations. Shared player, skills and export tools.</p><ul>${animations.map((item) => `<li><a href="/animations/${item.name}/">${htmlEscape(item.title)}</a><p>${htmlEscape(item.name)} · ${Number(item.duration)}s</p></li>`).join("")}</ul><p>Create your next film: <code>animaguru create animation my-video</code></p><p>Keep logos, fonts and guides in <code>branding/</code>; configure reusable web assets in <code>branding/brand.json</code>.</p></main></body></html>`;
+            const content = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${htmlEscape(brand.branding.name)} · AnimaGuru workspace</title><style>body{margin:0;background:#edf0f4;color:#111;font:15px system-ui}main{max-width:960px;margin:auto;padding:48px 24px}h1{font-size:32px}a{color:#1d56ad}ul{padding:0;display:grid;gap:14px;list-style:none}li{background:white;border:1px solid #d9dee6;padding:22px;border-radius:14px}code{font-size:13px}p{color:#6b7382;line-height:1.7}</style></head><body><main><p>AnimaGuru · shared video workspace</p><h1>${htmlEscape(brand.branding.name)}</h1><p>One brand. Many animations. Shared player, skills and export tools.</p><ul>${animations.map((item) => `<li><a href="/animations/${item.name}/">${htmlEscape(item.title)}</a><p>${htmlEscape(item.name)} · ${item.story ? "branching story" : `${Number(item.duration)}s`}${item.quiz ? " · quiz" : ""}</p></li>`).join("")}</ul><p>Create your next film: <code>animaguru create animation my-video</code></p><p>Keep logos, fonts and guides in <code>branding/</code>; configure reusable web assets in <code>branding/brand.json</code>.</p></main></body></html>`;
             response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }).end(content);
           })().catch((error) => response.writeHead(500).end(error.message)); return;
         }
         if (!match) return next();
         // Film modules and the JSON they import (including the voiceover cue map) go to Vite; everything else is public media.
-        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json", "production/audio/timing.json"].includes(match[2])) return next();
+        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json", "production/audio/timing.json", STORY_FILE, QUIZ_FILE].includes(match[2])) return next();
         void (async () => {
           const context = await projectContext(root, match[1]);
           if (!match[2] || match[2] === "index.html") {

package/templates/video/shared/locales/en/player.json

@@ -28,5 +28,33 @@
   "fullscreenFailed": "Fullscreen is unavailable in this browser.",
   "videoPlayer": "Video player",
   "footer": "Made with AnimaGuru × PixiJS",
-  "footerTagline": "IMAGINE. CREATE. ANIMATE."
+  "footerTagline": "IMAGINE. CREATE. ANIMATE.",
+  "storyHint": "A branching story: viewers choose its path. It plays as HTML5; an MP4 has one path.",
+  "storyNoMp4": "This film is a branching story, so it plays as HTML5 only: an MP4 has one path.",
+  "storyChoose": "What happens next?",
+  "storyEnd": "The end",
+  "storyPlayAgain": "Play again",
+  "storyBack": "Back to the last choice",
+  "quizHint": "A quiz film: it pauses for questions, which viewers answer. It plays as HTML5 only.",
+  "quizNoMp4": "This film has a quiz, so it plays as HTML5 only: its questions wait for a viewer's answers.",
+  "quizCheck": "Quick check",
+  "quizFinal": "Quiz",
+  "quizProgress": "Question {n} of {total}",
+  "quizSelectAll": "Select all that apply.",
+  "quizCheckAnswer": "Check answer",
+  "quizCorrect": "Correct!",
+  "quizIncorrect": "Not quite.",
+  "quizAnswer": "The answer: {answer}.",
+  "quizContinue": "Continue",
+  "quizNext": "Next question",
+  "quizSeeResults": "See your score",
+  "quizWatchAgain": "Watch that part again",
+  "quizScore": "You got {correct} of {total} right",
+  "quizPassed": "You passed!",
+  "quizNotPassed": "{pass}% passes. Watch again or retake the quiz.",
+  "quizPerfect": "A perfect score!",
+  "quizRetake": "Retake the quiz",
+  "quizRestart": "Watch again",
+  "quizComplete": "Quiz complete",
+  "quizSkipped": "{count} not answered"
 }

package/templates/video/src/kit/index.ts

@@ -6,6 +6,7 @@ export * from "./shapes";
 export * from "./textures";
 export * from "./components";
 export * from "./timing";
+export * from "./story";
 export * from "./layout";
 export * from "./film-base";
 export * from "./dark-stage";

package/templates/video/src/kit/story.ts

@@ -0,0 +1,19 @@
+import type { StoryGraph } from "../../scripts/story.mjs";
+
+/**
+ * A branching story's segments for scene code, so scenes follow story.json when a segment is re-timed:
+ * `const beat = storyBeats(story); beat("forest").start`. choiceAt is when that segment's choices appear.
+ */
+export function storyBeats(story: StoryGraph) {
+  const byId = new Map(story.segments.map((segment) => [segment.id, segment]));
+  return (id: string) => {
+    const segment = byId.get(id);
+    if (!segment) throw new Error(`No story segment "${id}". Known segments: ${[...byId.keys()].join(", ")}`);
+    return { ...segment, choiceAt: segment.choiceAt ?? segment.end, length: segment.end - segment.start };
+  };
+}
+
+/** The story's segments in timeline order as the player's chapters (label and transcript line). */
+export function storyChapters(story: StoryGraph) {
+  return [...story.segments].sort((a, b) => a.start - b.start).map((segment) => ({ start: segment.start, end: segment.end, label: segment.label, caption: segment.label }));
+}

package/templates/video/src/main.ts

@@ -1,5 +1,10 @@
 import config from "../film.config.json";
 import { Film, chapters } from "./film";
 import { mountPlayer } from "./player";
+import type { StoryGraph } from "./story";
+import type { Quiz } from "./quiz";
 
-void mountPlayer({ config, Film, chapters });
+// story.json, when the film has one, makes it a branching story; quiz.json adds its questions.
+const [story] = Object.values(import.meta.glob<StoryGraph>("../story.json", { eager: true, import: "default" }));
+const [quiz] = Object.values(import.meta.glob<Quiz>("../quiz.json", { eager: true, import: "default" }));
+void mountPlayer({ config, Film, chapters, story, quiz });

package/templates/video/src/player-types.ts

@@ -1,5 +1,7 @@
 import type { Application, Texture } from "pixi.js";
 import type { ResourceTrack } from "./timeline-model";
+import type { StoryGraph } from "../scripts/story.mjs";
+import type { Quiz } from "../scripts/quiz.mjs";
 
 export type FilmConfig = {
   title: string; slug: string; width: number; height: number; fps: number;
@@ -32,4 +34,8 @@ export type PlayerOptions = {
   branding?: Branding;
   exportEndpoint?: string;
   templateLabel?: string;
+  /** story.json: the film is a branching story whose viewers choose its path. */
+  story?: StoryGraph;
+  /** quiz.json: checkpoints pause the film to ask questions, and a final quiz and the score follow its end. */
+  quiz?: Quiz;
 };