@docyrus/animaguru 0.19.0 → 0.20.0

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;
 };

package/templates/video/src/player.ts

@@ -5,9 +5,11 @@ import { publicAsset } from "./assets";
 import { downloadHtml, downloadUrl } from "./download";
 import { loadFonts } from "./kit/fonts";
 import type { ResourceTimeline } from "./resource-timeline";
+import { StoryMap, StoryOverlay, type StorySegment, type StoryView } from "./story";
+import { QuizOverlay, QuizRun, quizCopy } from "./quiz";
 import "./style.css";
 
-export async function mountPlayer({ config, Film, chapters, branding, exportEndpoint, templateLabel }: PlayerOptions) {
+export async function mountPlayer({ config, Film, chapters, branding, exportEndpoint, templateLabel, story: storyGraph, quiz: quizData }: PlayerOptions) {
   const root = document.querySelector<HTMLDivElement>("#app")!;
   // All variable copy is inserted as text, including agent-authored film titles.
   root.innerHTML = `<header class="masthead"><a class="brand" href="https://animaguru.com" target="_blank" rel="noreferrer"><img src="${publicAsset("brand/logo-mark.svg")}" alt=""/><strong>AnimaGuru</strong><span data-copy="studio"></span></a><span class="template" data-copy="template"></span></header>
@@ -31,6 +33,24 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
   const capture = params.has("capture");
   const exporting = !embed && params.has("export");
   const autoplay = embed && params.get("autoplay") === "1" && !matchMedia("(prefers-reduced-motion: reduce)").matches;
+  // A branching story plays one segment at a time and asks the viewer at its choices. Capture and review see its whole
+  // timeline as one film; an MP4 has one path, so a story never exports one.
+  let story: StoryMap | null = null;
+  // A quiz pauses the film at its checkpoints and follows its end with a final round and the score. Capture and review
+  // see the film without it; its questions wait for a viewer's answers, so a quiz never exports an MP4. visited: the story segments played since the last restart, whose questions count.
+  let quiz: QuizRun | null = null;
+  const visited = new Set<string>();
+  if (storyGraph || quizData) {
+    document.querySelector<HTMLElement>('[data-copy="exportHint"]')!.textContent = storyGraph ? copy.storyHint : copy.quizHint;
+    try {
+      if (exporting) throw new Error(storyGraph ? copy.storyNoMp4 : copy.quizNoMp4);
+      if (storyGraph && !capture && !params.has("review")) story = new StoryMap(storyGraph, config.duration);
+      if (quizData && !capture && !params.has("review")) quiz = new QuizRun(quizData, config.duration, story ? { segments: story.graph.segments, visited } : undefined);
+    } catch (error) {
+      status.textContent = error instanceof Error ? error.message : copy.failed; element("loading")?.remove(); console.error(error);
+      return;
+    }
+  }
   const loop = embed && params.get("loop") === "1";
   if (capture) document.body.classList.add("capture");
   if (embed) document.body.classList.add("embed");
@@ -71,6 +91,34 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     const initialMuted = autoplay || capture || exporting;
     if (audio) { audio.crossOrigin = "anonymous"; audio.src = publicAsset(String(config.audio)); audio.preload = "auto"; audio.muted = initialMuted; audio.addEventListener("error", audioFailure); }
     let time = Math.max(0, Math.min(Number(params.get("t")) || 0, config.duration));
+    // ?segment=ID starts a story at that segment; ?t= at that time of the timeline.
+    let segment: StorySegment | null = story ? story.graph.segments.find((item) => item.id === params.get("segment")) ?? (params.has("t") ? story.at(time) : story.first) : null;
+    if (segment && !params.has("t")) time = segment.start;
+    if (segment) visited.add(segment.id);
+    /** The choice taken while its segment still plays; the story follows it when the segment ends. */
+    let picked: number | null = null;
+    /** Seconds a timed choice has been on screen. */
+    let waited = 0;
+    /** The story is at an ending. */
+    let finished = false;
+    /** The segments the viewer chose at, for going back. */
+    const path: string[] = [];
+    /** A story's final quiz and score have shown at an ending in this playthrough. */
+    let quizEnded = false;
+    const overlay = story ? new StoryOverlay(element("canvas-host"), story.graph, {
+      theEnd: story.graph.ui?.theEnd ?? copy.storyEnd, playAgain: story.graph.ui?.playAgain ?? copy.storyPlayAgain,
+      back: story.graph.ui?.back ?? copy.storyBack, choose: story.graph.ui?.choose ?? copy.storyChoose,
+    }, branding, { choose, restart: () => { void restart(); }, back: () => { void back(); } }) : null;
+    const quizOverlay = quiz ? new QuizOverlay(element("canvas-host"), quiz.quiz, quizCopy(copy, quiz.quiz.ui), branding, {
+      pick, check: checkAnswer, next: () => { void nextQuestion(); }, watchAgain: () => { void watchAgain(); }, retake: retakeQuiz, finish: () => { void finishQuiz(); },
+    }) : null;
+    const span = () => segment ? { start: segment.start, end: segment.end } : { start: 0, end: config.duration };
+    const atEnd = () => time >= span().end - 0.0005;
+    const choosing = () => Boolean(story && segment?.choices && time >= story.choiceAt(segment) - 0.0005);
+    // A quiz card covers the story's panels until it closes.
+    const storyView = (): StoryView => !segment || quiz?.panel ? { kind: "none" }
+      : finished ? { kind: "ending", segment, canGoBack: path.length > 0 }
+      : choosing() ? { kind: "choices", segment, picked, remaining: segment.timeout ? 1 - waited / segment.timeout : null } : { kind: "none" };
     let playing = false;
     let muted = initialMuted;
     let last = performance.now();
@@ -78,32 +126,53 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     let playbackRequest = 0;
     let resources: ResourceTimeline | undefined;
     const update = () => {
-      playButton.textContent = playing ? copy.pause : time >= config.duration ? copy.replay : copy.play;
+      // A story's transport covers the segment playing, not the whole timeline of every path.
+      const { start: from, end: to } = span();
+      playButton.textContent = playing ? copy.pause : (segment ? finished : time >= config.duration) ? copy.replay : copy.play;
+      // A question showing holds the film: it continues once the viewer answers.
+      const asking = Boolean(quiz?.asking);
+      playButton.disabled = asking || Boolean(segment?.choices && !playing && atEnd() && picked === null);
+      timeline.disabled = asking;
       playButton.setAttribute("aria-label", playButton.textContent);
-      element("time").textContent = `${format(time)} / ${format(config.duration)}`;
-      timeline.value = String(time);
-      timeline.setAttribute("aria-valuetext", `${format(time)} / ${format(config.duration)}`);
+      element("time").textContent = `${format(time - from)} / ${format(to - from)}`;
+      timeline.max = String(to - from);
+      timeline.value = String(time - from);
+      timeline.setAttribute("aria-valuetext", `${format(time - from)} / ${format(to - from)}`);
       soundButton.textContent = !audio ? copy.noAudio : muted ? copy.unmute : copy.mute;
       soundButton.disabled = !audio;
       soundButton.setAttribute("aria-pressed", String(Boolean(audio) && !muted));
       captionsButton.setAttribute("aria-pressed", String(film.captions));
       resources?.update({ time, playing, captions: film.captions, muted });
+      overlay?.render(storyView());
+      if (quiz) quizOverlay?.render(quiz.view());
     };
     const render = (seconds: number) => {
+      // A story holding at a segment's end shows that segment's last frame, not the next segment's first.
+      const at = segment ? Math.min(seconds, segment.end - 0.001) : seconds;
       // Seeking and frame capture are serialized so decoded video frames cannot race.
-      renderQueue = renderQueue.then(() => film.render(seconds));
+      renderQueue = renderQueue.then(() => film.render(at));
       return renderQueue;
     };
     function pause() { playbackRequest++; playing = false; audio?.pause(); update(); }
     async function seek(seconds: number) {
       if (!Number.isFinite(seconds)) throw new Error("Seek time must be finite.");
       time = Math.max(0, Math.min(seconds, config.duration)); pause();
+      // A seek closes a quiz card unanswered; its checkpoint asks again when the film next reaches it.
+      quiz?.close();
+      // A seek stays in the story's segment while it can, up to its end; another time of the timeline enters its segment.
+      if (story && segment && !(time >= segment.start && time <= segment.end)) { segment = story.at(time); visited.add(segment.id); }
+      if (segment) { picked = null; waited = 0; finished = segment.ending !== undefined && atEnd(); }
       if (audio) audio.currentTime = time;
       await render(time); update();
     }
     async function play() {
-      if (exporting) return;
-      if (time >= config.duration) await seek(0);
+      if (exporting || quiz?.asking) return;
+      // Play over the score replays the film, or the story from its start.
+      quiz?.close();
+      if (segment) {
+        if (finished) { await restart(); return; }
+        if (segment.choices && picked === null && atEnd()) return;
+      } else if (time >= config.duration) await seek(0);
       const request = ++playbackRequest;
       if (audio) {
         audio.currentTime = time;
@@ -117,6 +186,82 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
       muted = value; audio.muted = muted; update();
     }
     function toggleSound() { setMuted(!muted); }
+    /** Plays a story segment from a time (its start by default); a choice shown at the segment's very end waits there. */
+    async function enter(target: StorySegment, at = target.start) {
+      segment = target; time = at; picked = null; waited = 0; finished = false; visited.add(target.id);
+      if (audio) audio.currentTime = time;
+      await render(time);
+      if (atEnd()) { pause(); return; }
+      if (playing) { last = performance.now(); update(); } else await play();
+    }
+    /** What a segment does at its end: continue, go where the viewer chose, wait for a choice, or end the story. */
+    async function arrive() {
+      if (!story || !segment) return;
+      if (segment.next) await enter(story.get(segment.next));
+      else if (segment.choices) {
+        if (picked !== null) await take(picked);
+        else { playbackRequest++; playing = false; audio?.pause(); }
+      } else {
+        finished = true; pause();
+        // A quiz's final round and score come before the story's ending card, once a playthrough.
+        if (quiz && !quizEnded) { quizEnded = true; if (quizEnd()) update(); }
+      }
+    }
+    function choose(index: number) {
+      if (!segment?.choices?.[index] || picked !== null || !choosing() || quiz?.panel) return;
+      picked = index;
+      // A choice made while the segment plays waits for its end, so the segment finishes as it was cut.
+      if (!playing || atEnd()) void take(index); else update();
+    }
+    async function take(index: number) {
+      path.push(segment!.id);
+      await enter(story!.get(segment!.choices![index].to));
+    }
+    async function restart() { path.length = 0; quiz?.reset(); visited.clear(); quizEnded = false; await enter(story!.first); }
+    /** Back to the last choice the viewer made, with its choices showing. */
+    async function back() {
+      const id = path.pop();
+      if (!id) { await restart(); return; }
+      const decision = story!.get(id);
+      await enter(decision, story!.choiceAt(decision));
+    }
+    /** A quiz event for a page hosting the film: each answer, and the score when the quiz is complete. */
+    const emit = (type: "answer" | "complete", detail: object | null) => window.dispatchEvent(new CustomEvent("animaguru:quiz", { detail: { type, ...detail } }));
+    function pick(index: number) {
+      if (!quiz?.pick(index)) return;
+      if (quiz.answered) emit("answer", quiz.lastAnswer);
+      update();
+    }
+    function checkAnswer() { if (quiz?.check()) { emit("answer", quiz.lastAnswer); update(); } }
+    /** The final quiz, or the score, at the film's end or a story's ending; false when the viewer met no question. */
+    function quizEnd() {
+      if (!quiz?.openEnd()) return false;
+      if (quiz.panel?.kind === "results") emit("complete", quiz.score());
+      return true;
+    }
+    /** After an answer: the next question, the score, or back to the film where the checkpoint paused it. */
+    async function nextQuestion() {
+      const step = quiz?.advance();
+      if (step === "results") emit("complete", quiz!.score());
+      update();
+      if (step !== "closed") return;
+      if (segment) { if (atEnd()) await arrive(); else await play(); }
+      else if (time >= config.duration - 0.0005) { if (quizEnd()) update(); }
+      else await play();
+    }
+    /** Back to the part a checkpoint covers, which asks again when the film reaches it. */
+    async function watchAgain() {
+      const panel = quiz?.panel;
+      if (panel?.kind !== "checkpoint") return;
+      quiz!.arm(panel.checkpoint);
+      await seek(quiz!.reviewTime(panel.checkpoint)); await play();
+    }
+    function retakeQuiz() { quiz?.retake(); update(); }
+    /** The score's last button: a story's ending card, or the film again from the start with every question fresh. */
+    async function finishQuiz() {
+      if (segment) { quiz?.close(); update(); return; }
+      quiz?.reset(); await seek(0); await play();
+    }
     function setCaptions(value: boolean) { film.captions = value; void render(time); update(); }
     const fullscreenButton = element<HTMLButtonElement>("fullscreen");
     function showFullscreen() {
@@ -141,8 +286,8 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     let resumeAfterScrub = false;
     async function scrub(seconds: number, done = true) {
       resumeAfterScrub ||= playing;
-      await seek(seconds);
-      if (done && resumeAfterScrub) { resumeAfterScrub = false; await play(); }
+      await seek(segment ? Math.max(segment.start, Math.min(segment.end, seconds)) : seconds);
+      if (done && resumeAfterScrub) { resumeAfterScrub = false; if (!finished) await play(); }
     }
     async function saveFrame() {
       pause(); await render(time);
@@ -211,11 +356,21 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
       app.canvas.addEventListener("dblclick", () => { void fullscreen(); });
     }
     element("save").addEventListener("click", () => { closeDownloads(true); void saveFrame(); });
-    timeline.addEventListener("input", () => { void scrub(Number(timeline.value), false); });
-    timeline.addEventListener("change", () => { void scrub(Number(timeline.value)); });
+    timeline.addEventListener("input", () => { void scrub(span().start + Number(timeline.value), false); });
+    timeline.addEventListener("change", () => { void scrub(span().start + Number(timeline.value)); });
     document.addEventListener("visibilitychange", () => { if (document.hidden && !exporting) pause(); });
     document.addEventListener("keydown", (event) => {
-      if (exporting || event.target instanceof HTMLElement && event.target.closest("button,input,a,summary,textarea,select,[contenteditable]")) return;
+      const target = event.target instanceof HTMLElement ? event.target : null;
+      if (exporting || target?.closest("input,textarea,select,[contenteditable]")) return;
+      // Number keys answer a question or pick a story's choice, also with focus on one of their buttons.
+      if (quiz?.asking && /^[1-6]$/.test(event.key)) { event.preventDefault(); pick(Number(event.key) - 1); return; }
+      if (segment && !quiz?.panel && /^[1-4]$/.test(event.key)) { choose(Number(event.key) - 1); return; }
+      if (target?.closest("button,a,summary")) return;
+      if (quiz?.asking) {
+        if (event.key === "Enter") { event.preventDefault(); if (quiz.answered) void nextQuestion(); else checkAnswer(); }
+        // The film waits for the answer: the play and seek keys do nothing.
+        if (["Space", "ArrowRight", "ArrowLeft"].includes(event.code)) { event.preventDefault(); return; }
+      }
       if (event.code === "Space") { event.preventDefault(); if (playing) pause(); else void play(); }
       if (event.code === "ArrowRight") { event.preventDefault(); void scrub(time + 5); }
       if (event.code === "ArrowLeft") { event.preventDefault(); void scrub(time - 5); }
@@ -227,11 +382,22 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     async function tick(now: number) {
       try {
         if (playing) {
-          time = Math.min(config.duration, audio && !audio.paused ? audio.currentTime : time + (now - last) / 1000);
-          await render(time);
-          if (time >= config.duration) { if (loop) { await seek(0); await play(); } else pause(); }
+          const end = span().end, from = time;
+          time = Math.min(end, audio && !audio.paused ? audio.currentTime : time + (now - last) / 1000);
+          // A checkpoint the film passes stops it on its own frame and asks.
+          const due = quiz?.due(from, time, segment ? span() : undefined);
+          if (due) { time = due.at; pause(); quiz!.open(due); await render(time); }
+          else {
+            await render(time);
+            if (time >= end) { if (segment) await arrive(); else if (quizEnd()) pause(); else if (loop) { await seek(0); await play(); } else pause(); }
+          }
           update();
         }
+        // A timed choice counts down while the film plays on and while it holds on the segment's last frame.
+        if (segment?.timeout !== undefined && picked === null && choosing() && (playing || atEnd()) && !quiz?.panel && !document.hidden) {
+          waited += (now - last) / 1000;
+          if (waited >= segment.timeout) choose(segment.default ?? 0); else if (!playing) update();
+        }
         last = now;
         requestAnimationFrame((next) => { void tick(next); });
       } catch (error) { pause(); status.textContent = copy.failed; console.error(error); }
@@ -241,8 +407,18 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     element("loading")?.remove();
     const api = {
       ready: true, width: config.width, height: config.height, duration: config.duration, fps: config.fps, language: config.language, languages: [{ code: config.language, name: config.language }], canvas: app.canvas,
-      get state() { return { time, playing, muted, captions: film.captions, audio: { configured: Boolean(audio), readyState: audio?.readyState ?? 0, error: audio?.error?.code ?? null } }; },
+      get state() {
+        return { time, playing, muted, captions: film.captions, audio: { configured: Boolean(audio), readyState: audio?.readyState ?? 0, error: audio?.error?.code ?? null },
+          // waiting: the segment has ended and only a choice continues the story, so play does nothing.
+          ...(segment ? { story: { segment: segment.id, start: segment.start, end: segment.end, choosing: choosing() && picked === null, waiting: Boolean(segment.choices && !playing && atEnd() && picked === null), ended: finished } } : {}),
+          // open: a quiz card shows; asking: it asks a question, so play and seeking wait for the answer.
+          ...(quiz ? { quiz: { open: Boolean(quiz.panel), asking: quiz.asking, card: quiz.panel?.kind ?? null, score: quiz.score() } } : {}) };
+      },
       resources: film.resources,
+      // A branching story: its graph, the path taken, and the viewer's actions.
+      ...(story ? { story: { graph: story.graph, get path() { return [...path]; }, choose, back, restart, async goTo(id: string) { path.length = 0; await enter(story!.get(id)); } } } : {}),
+      // A quiz: its questions, the viewer's actions on the card, and the score so far.
+      ...(quiz ? { quiz: { data: quiz.quiz, pick, check: checkAnswer, next: nextQuestion, retake: retakeQuiz, reset() { quiz!.reset(); update(); }, get score() { return quiz!.score(); } } } : {}),
       get texts() { return film.texts; },
       get cues() { return film.cues; },
       seek, play, pause, setMuted, setCaptions, saveFrame,