@mineo71/showtime 0.2.1 → 0.4.0

package/src/timeline/frames.ts

@@ -1,4 +1,4 @@
-import { outputDurationMs, outputToSource, sourceToOutput } from './timemap';
+import { outputDurationMs, outputToSource, segLength, sourceToOutput } from './timemap';
 import type { StepEvent, Timeline } from './types';
 
 export interface SegmentPlan {
@@ -6,6 +6,7 @@ export interface SegmentPlan {
   durationInFrames: number;
   /** source frame where this segment starts */
   trimBefore: number;
+  /** 0: a hold, showing the `trimBefore` frame throughout */
   speed: number;
 }
 
@@ -20,8 +21,17 @@ export function introFrames(t: Timeline): number {
   return t.intro ? toFrames(t.intro.durationMs, t.fps) : 0;
 }
 
+export function outroFrames(t: Timeline): number {
+  return t.outro ? toFrames(t.outro.durationMs, t.fps) : 0;
+}
+
+/** First frame after the video (where the outro starts). */
+export function videoEndFrame(t: Timeline): number {
+  return introFrames(t) + toFrames(outputDurationMs(t.segments), t.fps);
+}
+
 export function totalFrames(t: Timeline): number {
-  return Math.max(1, introFrames(t) + toFrames(outputDurationMs(t.segments), t.fps));
+  return Math.max(1, videoEndFrame(t) + outroFrames(t));
 }
 
 export function segmentPlan(t: Timeline): SegmentPlan[] {
@@ -30,7 +40,7 @@ export function segmentPlan(t: Timeline): SegmentPlan[] {
   let outMs = 0;
   for (const s of t.segments) {
     const startF = toFrames(outMs, t.fps);
-    outMs += (s.srcEndMs - s.srcStartMs) / s.speed;
+    outMs += segLength(s);
     const endF = toFrames(outMs, t.fps);
     if (endF > startF) {
       plan.push({ fromFrame: intro + startF, durationInFrames: endF - startF, trimBefore: toFrames(s.srcStartMs, t.fps), speed: s.speed });
@@ -48,7 +58,7 @@ export function sourceMsAtFrame(t: Timeline, frame: number): number | null {
 
 export function qaShots(t: Timeline, steps: StepEvent[]): Shot[] {
   const intro = introFrames(t);
-  const last = totalFrames(t) - 1;
+  const last = Math.max(0, videoEndFrame(t) - 1);
   const shots: Shot[] = [];
   if (t.intro) shots.push({ frame: Math.floor(intro / 2), name: '00-intro' });
   steps.forEach((s, i) => {
@@ -56,5 +66,6 @@ export function qaShots(t: Timeline, steps: StepEvent[]): Shot[] {
     const frame = Math.min(last, intro + toFrames(sourceToOutput(t.segments, mid), t.fps));
     shots.push({ frame, name: `${String(i + 1).padStart(2, '0')}-${s.sceneId}-${s.index + 1}-${s.do}` });
   });
+  if (t.outro) shots.push({ frame: videoEndFrame(t) + Math.round(outroFrames(t) * 0.6), name: '99-outro' });
   return shots;
 }

package/src/timeline/layout.ts

@@ -1,3 +1,5 @@
+import type { Aspect, CameraKey, Rect } from './types';
+
 export interface Box {
   x: number;
   y: number;
@@ -8,6 +10,21 @@ export interface Box {
 /** Height of the browser bar, in stage (viewport) pixels. */
 export const BROWSER_BAR = 44;
 
+export const OUTPUT_SIZES: Record<Aspect, { width: number; height: number }> = {
+  '16:9': { width: 1920, height: 1080 },
+  '9:16': { width: 1080, height: 1920 },
+  '1:1': { width: 1080, height: 1080 },
+};
+
+/** In 9:16 the window (bar included) is this many times taller than wide. */
+const PORTRAIT_WINDOW = 1.3;
+
+/** The window on screen, and the size the viewport is drawn at inside it (larger when cropped). */
+export interface View extends Box {
+  bar: number;
+  content: { width: number; height: number };
+}
+
 /**
  * Where the recorded viewport sits inside the output frame. `bar` (stage px) reserves room for a
  * browser bar above it; the returned box is the viewport, `bar` the bar height in output px.
@@ -27,3 +44,56 @@ export function windowLayout(
   const top = Math.round((output.height - height - barPx) / 2);
   return { x: Math.round((output.width - width) / 2), y: top + barPx, width, height, bar: barPx };
 }
+
+/**
+ * The window for an aspect ratio. 16:9 fits the whole viewport (the 0.3 layout). 1:1 fills the
+ * padded square and 9:16 uses a tall window in the middle; in both the viewport covers the window,
+ * so it is cropped and the camera decides what shows.
+ */
+export function viewLayout(
+  output: { width: number; height: number },
+  stage: { width: number; height: number },
+  padding: number,
+  bar = 0,
+  aspect: Aspect = '16:9',
+): View {
+  if (aspect === '16:9') {
+    const w = windowLayout(output, stage, padding, bar);
+    return { ...w, content: { width: w.width, height: w.height } };
+  }
+  const width = Math.round(output.width * (1 - 2 * padding));
+  const total = aspect === '9:16' ? Math.round(width * PORTRAIT_WINDOW) : Math.round(output.height * (1 - 2 * padding));
+  const k = Math.max(width / stage.width, total / (stage.height + bar));
+  const barPx = Math.round(bar * k);
+  const top = Math.round((output.height - total) / 2);
+  return {
+    x: Math.round((output.width - width) / 2),
+    y: top + barPx,
+    width,
+    height: total - barPx,
+    bar: barPx,
+    content: { width: Math.round(stage.width * k), height: Math.round(stage.height * k) },
+  };
+}
+
+/** How much of the content shows at camera scale 1, per axis (1 = all of it). */
+export const visibleFraction = (v: View) => ({ x: Math.min(1, v.width / v.content.width), y: Math.min(1, v.height / v.content.height) });
+
+const r2 = (v: number) => Math.round(v * 100) / 100;
+
+/** Where a stage rect (CSS px) lands in the output: through the camera, inside the window viewport. */
+export function projectRect(
+  r: Rect,
+  cam: Pick<CameraKey, 'scale' | 'cx' | 'cy'>,
+  stage: { width: number; height: number },
+  win: Box & { content?: { width: number; height: number } },
+): Rect {
+  const w = (win.content?.width ?? win.width) * cam.scale;
+  const h = (win.content?.height ?? win.height) * cam.scale;
+  return {
+    x: r2(win.x + win.width / 2 + (r.x / stage.width - cam.cx) * w),
+    y: r2(win.y + win.height / 2 + (r.y / stage.height - cam.cy) * h),
+    width: r2((r.width / stage.width) * w),
+    height: r2((r.height / stage.height) * h),
+  };
+}

package/src/timeline/narration.ts

@@ -0,0 +1,160 @@
+import { insertHolds, sourceToOutput, type Hold } from './timemap';
+import type { Click, Cue, Segment, Sound } from './types';
+
+export type { Cue, Sound };
+
+/** Silence after a line before the next narrated step starts. */
+export const NARRATION_GAP_MS = 400;
+/** Two subtitle lines of 42 characters. */
+export const CUE_MAX_CHARS = 84;
+const LINE_CHARS = 42;
+/** Keystroke sounds closer than this (output time) are dropped, so sped-up typing doesn't buzz. */
+export const KEY_MIN_GAP_MS = 40;
+
+/** `scene#n`, 1-based: how lint, errors and the voice cache name a step. */
+export const stepKey = (sceneId: string, index: number) => `${sceneId}#${index + 1}`;
+
+export interface Line {
+  /** source ms the step starts */
+  startMs: number;
+  durationMs: number;
+}
+
+/** Something moving on screen over (startMs, endMs), source ms. */
+export interface Span {
+  startMs: number;
+  endMs: number;
+}
+
+/** The latest time in [lo, hi] that no span is moving through, or `hi` when there is none. */
+export function stillPoint(lo: number, hi: number, busy: Span[]): number {
+  let t = hi;
+  for (;;) {
+    const moving = busy.find((b) => b.startMs < t && t < b.endMs);
+    if (!moving) return t;
+    t = moving.startMs;
+    if (t < lo) return hi;
+  }
+}
+
+/**
+ * Holds that let every line finish (plus a gap) before the next narrated step starts, or before
+ * the video ends. `lines` are in source order; each hold sits at the last moment of its window
+ * when nothing in `busy` is moving, so the freeze never stops a camera move or a fade halfway.
+ */
+export function narrationHolds(lines: Line[], segments: Segment[], endMs: number, busy: Span[] = []): Hold[] {
+  const holds: Hold[] = [];
+  lines.forEach((line, i) => {
+    const next = lines[i + 1];
+    const until = next ? next.startMs : endMs;
+    const available = sourceToOutput(segments, until) - sourceToOutput(segments, line.startMs);
+    const short = line.durationMs + NARRATION_GAP_MS - available;
+    if (short <= 0) return;
+    // After the line's own start (a hold at its start would delay the line itself).
+    const lo = line.startMs + 1;
+    const hi = Math.max(lo, next ? next.startMs - 1 : endMs);
+    holds.push({ atMs: stillPoint(lo, hi, busy), holdMs: Math.round(short) });
+  });
+  return holds;
+}
+
+/** Segments with the narration holds in place. */
+export const withNarration = (segments: Segment[], lines: Line[], endMs: number, busy: Span[] = []) =>
+  insertHolds(segments, narrationHolds(lines, segments, endMs, busy));
+
+/** Greedily join pieces with spaces into chunks of at most CUE_MAX_CHARS. */
+function pack(pieces: string[]): string[] {
+  const out: string[] = [];
+  let cur = '';
+  for (const p of pieces) {
+    if (!cur) cur = p;
+    else if (cur.length + 1 + p.length <= CUE_MAX_CHARS) cur += ` ${p}`;
+    else {
+      out.push(cur);
+      cur = p;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/** A sentence as cue texts: whole if it fits, else at commas, else between words. */
+function sentenceChunks(sentence: string): string[] {
+  if (sentence.length <= CUE_MAX_CHARS) return [sentence];
+  const out: string[] = [];
+  let clauses: string[] = [];
+  for (const clause of sentence.split(/(?<=[,;:])\s+/)) {
+    if (clause.length <= CUE_MAX_CHARS) {
+      clauses.push(clause);
+      continue;
+    }
+    out.push(...pack(clauses), ...pack(clause.split(' ')));
+    clauses = [];
+  }
+  return [...out, ...pack(clauses)];
+}
+
+/** Subtitle cues for one line, timed in proportion to their length and back to back. */
+export function subtitleCues(text: string, atMs: number, durationMs: number): Cue[] {
+  // Sentences first, long ones split at commas or words; then short neighbours share a cue, so
+  // a two-word sentence doesn't flash by on its own.
+  const chunks = pack(
+    text
+      .trim()
+      .replace(/\s+/g, ' ')
+      .split(/(?<=[.!?…])\s+/)
+      .flatMap(sentenceChunks),
+  );
+  const total = chunks.reduce((n, c) => n + c.length, 0);
+  let done = 0;
+  return chunks.map((chunk) => {
+    const startMs = atMs + Math.round((durationMs * done) / total);
+    done += chunk.length;
+    return { startMs, endMs: atMs + Math.round((durationMs * done) / total), text: chunk };
+  });
+}
+
+const stamp = (ms: number) => {
+  const t = Math.max(0, Math.round(ms));
+  const pad = (n: number, w = 2) => String(n).padStart(w, '0');
+  return `${pad(Math.floor(t / 3_600_000))}:${pad(Math.floor(t / 60_000) % 60)}:${pad(Math.floor(t / 1000) % 60)},${pad(t % 1000, 3)}`;
+};
+
+/** Break a cue over two lines at the space nearest its middle. */
+function wrap(text: string): string {
+  if (text.length <= LINE_CHARS) return text;
+  let best = -1;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === ' ' && (best < 0 || Math.abs(i - text.length / 2) < Math.abs(best - text.length / 2))) best = i;
+  }
+  return best < 0 ? text : `${text.slice(0, best)}\n${text.slice(best + 1)}`;
+}
+
+/** SubRip text; `offsetMs` shifts video-relative cues to file time (the intro card). */
+export function toSrt(cues: Cue[], offsetMs: number): string {
+  return cues.map((c, i) => `${i + 1}\n${stamp(c.startMs + offsetMs)} --> ${stamp(c.endMs + offsetMs)}\n${wrap(c.text)}\n`).join('\n');
+}
+
+export interface Typing {
+  startMs: number;
+  endMs: number;
+  chars: number;
+}
+
+/**
+ * Click and keystroke sounds in output time. Takes without a keystroke log (before 0.4) spread
+ * each `type` step's keys evenly over its typing time.
+ */
+export function soundEvents(ev: { clicks: Click[]; keys?: number[] }, typing: Typing[], segments: Segment[]): Sound[] {
+  const keys =
+    ev.keys ?? typing.flatMap((t) => Array.from({ length: t.chars }, (_, i) => t.startMs + ((t.endMs - t.startMs) * (i + 0.5)) / t.chars));
+  const out: Sound[] = ev.clicks.map((c) => ({ kind: 'click', atMs: sourceToOutput(segments, c.tMs) }));
+  let last = -Infinity;
+  for (const k of [...keys].sort((a, b) => a - b)) {
+    const atMs = sourceToOutput(segments, k);
+    if (atMs - last < KEY_MIN_GAP_MS) continue;
+    out.push({ kind: 'key', atMs });
+    last = atMs;
+  }
+  return out.sort((a, b) => a.atMs - b.atMs);
+}

package/src/timeline/timemap.ts

@@ -28,15 +28,50 @@ export function buildSegments(durationMs: number, spans: SpeedSpan[]): Segment[]
   return out;
 }
 
+export interface Hold {
+  /** source ms whose frame stays on screen */
+  atMs: number;
+  holdMs: number;
+}
+
+/** Output length of one segment. */
+export const segLength = (s: Segment): number => (s.speed === 0 ? (s.holdMs ?? 0) : (s.srcEndMs - s.srcStartMs) / s.speed);
+
+/** Insert still-frame holds, splitting the segment each one falls in; holds at one point merge. */
+export function insertHolds(segments: Segment[], holds: Hold[]): Segment[] {
+  const at = new Map<number, number>();
+  for (const h of holds) if (h.holdMs > 0) at.set(h.atMs, (at.get(h.atMs) ?? 0) + h.holdMs);
+  const points = [...at.keys()].sort((a, b) => a - b);
+  const hold = (t: number): Segment => ({ srcStartMs: t, srcEndMs: t, speed: 0, holdMs: at.get(t) });
+  const out: Segment[] = [];
+  let p = 0;
+  for (const s of segments) {
+    if (s.speed === 0) {
+      out.push(s);
+      continue;
+    }
+    let start = s.srcStartMs;
+    for (; p < points.length && points[p] < s.srcEndMs; p++) {
+      const t = Math.max(points[p], start);
+      if (t > start) out.push({ ...s, srcStartMs: start, srcEndMs: t });
+      out.push(hold(points[p]));
+      start = t;
+    }
+    out.push({ ...s, srcStartMs: start });
+  }
+  for (; p < points.length; p++) out.push(hold(points[p]));
+  return out;
+}
+
 export function outputDurationMs(segments: Segment[]): number {
-  return segments.reduce((acc, s) => acc + (s.srcEndMs - s.srcStartMs) / s.speed, 0);
+  return segments.reduce((acc, s) => acc + segLength(s), 0);
 }
 
 export function outputToSource(segments: Segment[], tOutMs: number): number {
   let acc = 0;
   for (const s of segments) {
-    const len = (s.srcEndMs - s.srcStartMs) / s.speed;
-    if (tOutMs < acc + len) return s.srcStartMs + Math.max(0, tOutMs - acc) * s.speed;
+    const len = segLength(s);
+    if (tOutMs < acc + len) return s.speed === 0 ? s.srcStartMs : s.srcStartMs + Math.max(0, tOutMs - acc) * s.speed;
     acc += len;
   }
   return segments.length ? segments[segments.length - 1].srcEndMs : 0;
@@ -45,8 +80,8 @@ export function outputToSource(segments: Segment[], tOutMs: number): number {
 export function sourceToOutput(segments: Segment[], tSrcMs: number): number {
   let acc = 0;
   for (const s of segments) {
-    if (tSrcMs < s.srcEndMs) return acc + Math.max(0, tSrcMs - s.srcStartMs) / s.speed;
-    acc += (s.srcEndMs - s.srcStartMs) / s.speed;
+    if (s.speed !== 0 && tSrcMs < s.srcEndMs) return acc + Math.max(0, tSrcMs - s.srcStartMs) / s.speed;
+    acc += segLength(s);
   }
   return acc;
 }

package/src/timeline/types.ts

@@ -60,12 +60,16 @@ export interface TakeEvents {
   moves: Move[];
   clicks: Click[];
   idle: Interval[];
+  /** keystroke times (human-paced typing); missing in takes recorded before 0.4 */
+  keys?: number[];
 }
 
 export interface Segment {
   srcStartMs: number;
   srcEndMs: number;
+  /** 0 for a hold: the frame at srcStartMs (= srcEndMs) stays on screen for `holdMs` */
   speed: number;
+  holdMs?: number;
 }
 
 export interface CameraKey {
@@ -81,6 +85,8 @@ export interface Caption {
   startMs: number;
   endMs: number;
   text: string;
+  /** Bottom unless the step's target would sit under a bottom caption. */
+  position: 'bottom' | 'top';
 }
 
 export interface Spotlight {
@@ -89,23 +95,60 @@ export interface Spotlight {
   rect: Rect;
 }
 
+/** A subtitle cue, in output ms from the start of the video. */
+export interface Cue {
+  startMs: number;
+  endMs: number;
+  text: string;
+}
+
+export interface Sound {
+  kind: 'click' | 'key';
+  /** output ms from the start of the video */
+  atMs: number;
+}
+
+export interface NarrationLine {
+  /** `scene#n` */
+  where: string;
+  text: string;
+  /** output ms from the start of the video */
+  atMs: number;
+  durationMs: number;
+}
+
 export type ResolvedStyle = Style;
 
-/** The renderer contract. All overlay times are source ms. */
+export type Aspect = '16:9' | '9:16' | '1:1';
+
+/** The renderer contract. Overlay times are source ms; sound and subtitle times are output ms from the video start. */
 export interface Timeline {
   version: 1;
   fps: number;
+  aspect: Aspect;
   output: { width: number; height: number };
   stage: { width: number; height: number };
   video: { src: string; durationMs: number };
   intro: { title: string; subtitle?: string; durationMs: number } | null;
   /** Browser window around the take, or null for the bare viewport. */
   chrome: { address: string; dark: boolean } | null;
+  /** Closing card after the video. */
+  outro: { title: string; subtitle?: string; url?: string; durationMs: number } | null;
+  /** Logo for the intro and outro cards, as a data URI. */
+  logo: string | null;
   segments: Segment[];
   camera: CameraKey[];
   moves: Move[];
   clicks: Click[];
   captions: Caption[];
   spotlights: Spotlight[];
+  narration: NarrationLine[];
+  subtitles: Cue[];
+  /** Subtitles drawn on the video (captions then sit at the top). */
+  subtitlesBurned: boolean;
+  sounds: Sound[];
+  music: { volume: number } | null;
+  /** The mixed soundtrack, relative to the renderer's public folder; set by the pipeline. */
+  audio: { src: string } | null;
   style: ResolvedStyle;
 }