@hajimism/dek 0.1.0

package/src/core/timeline.ts

@@ -0,0 +1,216 @@
+import { type Cue, splitSentences } from "./cue.ts";
+import { DekError } from "./error.ts";
+import type { Position } from "./step.ts";
+
+export type PauseConfig = {
+  sentence: number;
+  beat: number;
+};
+
+export const DEFAULT_PAUSE: PauseConfig = {
+  sentence: 350,
+  beat: 700,
+};
+
+export type Utterance = {
+  text: string;
+  kana: string;
+  durationMs: number;
+};
+
+type TimelineSentence = {
+  text: string;
+  kana: string;
+  start: number;
+  end: number;
+};
+
+type TimelineBeat = {
+  position: Position;
+  start: number;
+  end: number;
+  sentences: TimelineSentence[];
+  /** How far the screen change leads the voice. Absent in hand-written timelines. */
+  lead?: number;
+};
+
+/** Per-beat overrides from voice.toml. `pause` replaces `pause.beat` after the beat. */
+export type BeatTiming = {
+  lead?: number;
+  pause?: number;
+};
+
+export type Timeline = {
+  audio: string;
+  durationMs: number;
+  beats: TimelineBeat[];
+};
+
+/** Screen changes lead the voice so a transition settles as the first word lands. */
+export const DEFAULT_LEAD_MS = 300;
+
+export type ScheduledGo = {
+  at: number;
+  position: Position;
+};
+
+export type VoiceSchedule = {
+  timeline: Timeline;
+  pauseAfterMs: number[];
+  leadingMs: number;
+};
+
+export function scheduleVoice(
+  cues: Cue[],
+  utterances: Iterable<Utterance>,
+  pause: PauseConfig = DEFAULT_PAUSE,
+  audio = "",
+  timing: (position: Position) => BeatTiming = () => ({}),
+): VoiceSchedule {
+  const queue = [...utterances];
+  let next = 0;
+  const take = (text: string): Utterance => {
+    const utterance = queue[next];
+    if (!utterance || utterance.text !== text) {
+      throw new DekError(`missing utterance for ${JSON.stringify(text)}`, {
+        hint: "run `dekc voice`",
+      });
+    }
+    next += 1;
+    return utterance;
+  };
+
+  const beats: TimelineBeat[] = [];
+  const pauseAfterMs: number[] = [];
+  let leadingMs = 0;
+  let t = 0;
+  let previousEnd = 0;
+  let previousSlide = -1;
+  let lastClipIndex = -1;
+
+  for (const cue of cues) {
+    const texts = cue.paragraphs.flatMap(splitSentences);
+    const override = timing(cue.position);
+    const lead = override.lead ?? DEFAULT_LEAD_MS;
+    const beatPause = override.pause ?? pause.beat;
+    const sameSlide = cue.position.slideIndex === previousSlide;
+    previousSlide = cue.position.slideIndex;
+    if (texts.length === 0) {
+      // Silence after speech belongs to its slide: a silent beat fills it, a silent arrival waits it out.
+      const start = sameSlide ? previousEnd : t;
+      const end = start + beatPause;
+      if (end > t) {
+        const extra = end - t;
+        if (lastClipIndex >= 0) {
+          pauseAfterMs[lastClipIndex] = (pauseAfterMs[lastClipIndex] ?? 0) + extra;
+        } else {
+          leadingMs += extra;
+        }
+        t = end;
+      }
+      beats.push({ position: cue.position, start, end, sentences: [], lead });
+      previousEnd = end;
+      continue;
+    }
+
+    const sentences: TimelineSentence[] = [];
+    const start = t;
+    for (const [index, text] of texts.entries()) {
+      const utterance = take(text);
+      sentences.push({
+        text,
+        kana: utterance.kana,
+        start: t,
+        end: t + utterance.durationMs,
+      });
+      t += utterance.durationMs;
+      if (index < texts.length - 1) {
+        pauseAfterMs.push(pause.sentence);
+        t += pause.sentence;
+      } else {
+        pauseAfterMs.push(beatPause);
+        t += beatPause;
+      }
+      lastClipIndex = pauseAfterMs.length - 1;
+    }
+    const end = sentences[sentences.length - 1]?.end ?? start;
+    beats.push({ position: cue.position, start, end, sentences, lead });
+    previousEnd = end;
+  }
+
+  return {
+    timeline: {
+      audio,
+      durationMs: t,
+      beats,
+    },
+    pauseAfterMs,
+    leadingMs,
+  };
+}
+
+/**
+ * When each beat's screen change fires: its lead ahead of the voice, but never
+ * before the previous change, so a long lead cannot send the screen back.
+ */
+export function playbackSchedule(timeline: Timeline): ScheduledGo[] {
+  let previousAt = 0;
+  return timeline.beats.map((beat) => {
+    const lead = Math.max(0, beat.lead ?? DEFAULT_LEAD_MS);
+    const at = Math.max(previousAt, beat.start - lead);
+    previousAt = at;
+    return { at, position: beat.position };
+  });
+}
+
+export function timelineSeconds(timeline: Timeline): number {
+  return Math.round(timeline.durationMs / 1000);
+}
+
+export function slideTimeRange(
+  timeline: Timeline,
+  slideIndex: number,
+): { start: number; end: number } | undefined {
+  const beats = timeline.beats.filter((beat) => beat.position.slideIndex === slideIndex);
+  if (beats.length === 0) {
+    return undefined;
+  }
+  const start = beats[0]?.start ?? 0;
+  const next = timeline.beats.find((beat) => beat.position.slideIndex > slideIndex);
+  const end = next?.start ?? timeline.durationMs;
+  return { start, end };
+}
+
+export function slideVideoSeconds(timeline: Timeline, slideIndex: number): number | undefined {
+  const range = slideTimeRange(timeline, slideIndex);
+  if (!range) {
+    return undefined;
+  }
+  return Math.round((range.end - range.start) / 1000);
+}
+
+export function sliceTimeline(timeline: Timeline, slideIndex: number): Timeline {
+  const range = slideTimeRange(timeline, slideIndex);
+  if (!range) {
+    throw new DekError(`no timeline beats for slide ${slideIndex}`, {
+      hint: "run `dekc voice`",
+    });
+  }
+  const offset = range.start;
+  return {
+    audio: timeline.audio,
+    durationMs: Math.max(0, range.end - offset),
+    beats: timeline.beats
+      .filter((beat) => beat.position.slideIndex === slideIndex)
+      .map((beat) => ({
+        ...beat,
+        start: beat.start - offset,
+        end: beat.end - offset,
+        sentences: beat.sentences.map((sentence) => ({
+          ...sentence,
+          start: sentence.start - offset,
+          end: sentence.end - offset,
+        })),
+      })),
+  };
+}

package/src/core/timing.ts

@@ -0,0 +1,88 @@
+import type { DekConfig } from "./config.ts";
+
+type SectionBodies = {
+  body: string;
+  beats: Array<{ body: string }>;
+};
+
+function stripBlockquotes(markdown: string): string {
+  return markdown
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*>/.test(line))
+    .join("\n");
+}
+
+export function joinSectionBodies(section: SectionBodies, separator: string): string {
+  return [section.body, ...section.beats.map((beat) => beat.body)].filter(Boolean).join(separator);
+}
+
+export function speechText(section: SectionBodies): string {
+  return joinSectionBodies(section, "\n");
+}
+
+export function formatSectionScript(section: SectionBodies): string {
+  return joinSectionBodies(section, "\n\n");
+}
+
+function speechChars(text: string): number {
+  return stripBlockquotes(text).replace(/\s+/g, "").length;
+}
+
+function estimateSeconds(text: string, config: DekConfig): number {
+  const stripped = stripBlockquotes(text);
+  const cjk = [...stripped.matchAll(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu)]
+    .length;
+  const rest = stripped.replace(/[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/gu, " ");
+  const words = rest.split(/\s+/).filter(Boolean).length;
+  const cjkMinutes = config.cjkPerMinute > 0 ? cjk / config.cjkPerMinute : 0;
+  const latinMinutes = config.latinPerMinute > 0 ? words / config.latinPerMinute : 0;
+  return Math.round((cjkMinutes + latinMinutes) * 60);
+}
+
+export function parseDurationSeconds(duration?: string): number | undefined {
+  if (!duration) {
+    return undefined;
+  }
+  const match = duration.match(/^(\d+)m$/);
+  if (!match) {
+    return undefined;
+  }
+  return Number(match[1]) * 60;
+}
+
+export function formatClock(totalSeconds: number): string {
+  const seconds = Math.max(0, Math.floor(totalSeconds));
+  const minutes = Math.floor(seconds / 60);
+  return `${minutes}:${String(seconds % 60).padStart(2, "0")}`;
+}
+
+export type TimedSection = {
+  slug: string;
+  estimateSeconds: number;
+  budgetSeconds?: number;
+};
+
+export function sectionTiming(
+  sections: Array<{ slug: string; body: string; beats: Array<{ body: string }> }>,
+  duration: string | undefined,
+  config: DekConfig,
+): TimedSection[] {
+  const rows = sections.map((section) => {
+    const text = speechText(section);
+    return {
+      slug: section.slug,
+      chars: speechChars(text),
+      estimateSeconds: estimateSeconds(text, config),
+    };
+  });
+  const totalChars = rows.reduce((sum, row) => sum + row.chars, 0);
+  const durationSeconds = parseDurationSeconds(duration);
+
+  return rows.map((row) => ({
+    slug: row.slug,
+    estimateSeconds: row.estimateSeconds,
+    ...(durationSeconds !== undefined && totalChars > 0
+      ? { budgetSeconds: Math.round((durationSeconds * row.chars) / totalChars) }
+      : {}),
+  }));
+}

package/src/core/toml-keys.ts

@@ -0,0 +1,349 @@
+/** One key segment as written on its line: `a`, `"b/c"`, or `'d'`. */
+type KeySegment = { start: number; end: number; key: string; quote: string };
+
+/** One key or table header of a TOML file, where it is written. */
+export type TomlKey = {
+  /** `[table]`, `[[array]]`, a `key =` line, or a key inside an inline table `{ key = … }`. */
+  kind: "table" | "array" | "key" | "inline";
+  /** The full dotted path: the table it is under, then the key. */
+  path: string[];
+  /** The path as written on the line; for a key, without the table it is under. */
+  segments: KeySegment[];
+  /** 0-based index of the line in `source.split("\n")`; `line` is 1-based. */
+  index: number;
+  line: number;
+};
+
+/**
+ * Every key and table header in a TOML file, in order, with where each is written: the one reader
+ * dek.toml lint, `dekc mv`, and `dekc ref` share. It reads `[table]`, `[[array]]`, (dotted) keys, and
+ * one-line inline tables, and steps over comments and multi-line strings.
+ */
+export function scanTomlKeys(source: string): TomlKey[] {
+  const lines = source.split("\n");
+  const keys: TomlKey[] = [];
+  let table: string[] = [];
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? "";
+    const header = readHeader(line);
+    if (header) {
+      table = names(header.segments);
+      keys.push(keyAt(header.kind, table, header.segments, index));
+      continue;
+    }
+    // Blank lines, comments, and anything else that is not `key = value` fail here.
+    const assignment = readAssignment(line, 0);
+    if (!assignment) {
+      continue;
+    }
+    const path = [...table, ...names(assignment.segments)];
+    keys.push(keyAt("key", path, assignment.segments, index));
+    if (line[assignment.value] === "{") {
+      inlineKeys(line, assignment.value, path, index, keys);
+    }
+    index = valueLastLine(lines, index, assignment.value);
+  }
+  return keys;
+}
+
+function keyAt(
+  kind: TomlKey["kind"],
+  path: string[],
+  segments: KeySegment[],
+  index: number,
+): TomlKey {
+  return { kind, path, segments, index, line: index + 1 };
+}
+
+function names(segments: KeySegment[]): string[] {
+  return segments.map((segment) => segment.key);
+}
+
+/** A `[table]` or `[[array]]` header line. */
+function readHeader(line: string): { kind: "table" | "array"; segments: KeySegment[] } | undefined {
+  const open = skipSpace(line, 0);
+  if (line[open] !== "[") {
+    return undefined;
+  }
+  const kind = line[open + 1] === "[" ? "array" : "table";
+  const path = readKeyPath(line, open + (kind === "array" ? 2 : 1));
+  return path && line[path.end] === "]" ? { kind, segments: path.segments } : undefined;
+}
+
+/** A `key =` from `from`; `value` is where its value starts. */
+function readAssignment(
+  line: string,
+  from: number,
+): { segments: KeySegment[]; value: number } | undefined {
+  const path = readKeyPath(line, from);
+  if (!path || line[path.end] !== "=") {
+    return undefined;
+  }
+  return { segments: path.segments, value: skipSpace(line, path.end + 1) };
+}
+
+/** The keys of the inline table opening at `open`, nested ones too; returns the index past it. */
+function inlineKeys(
+  line: string,
+  open: number,
+  prefix: string[],
+  index: number,
+  keys: TomlKey[],
+): number {
+  let i = skipSpace(line, open + 1);
+  while (i < line.length && line[i] !== "}") {
+    const assignment = readAssignment(line, i);
+    if (!assignment) {
+      return line.length;
+    }
+    const path = [...prefix, ...names(assignment.segments)];
+    keys.push(keyAt("inline", path, assignment.segments, index));
+    const { value } = assignment;
+    i = skipSpace(
+      line,
+      line[value] === "{" ? inlineKeys(line, value, path, index, keys) : skipValue(line, value),
+    );
+    if (line[i] === ",") {
+      i = skipSpace(line, i + 1);
+    }
+  }
+  return i + 1;
+}
+
+const NESTING: Record<string, number> = { "[": 1, "{": 1, "]": -1, "}": -1 };
+const VALUE_ENDS = new Set([",", "#", "]", "}"]);
+
+/** The index past one value on a line: a string, an array or inline table, or a bare word. */
+function skipValue(line: string, from: number): number {
+  let depth = 0;
+  let i = from;
+  while (i < line.length) {
+    const ch = line[i] ?? "";
+    if (depth === 0 && VALUE_ENDS.has(ch)) {
+      return i;
+    }
+    depth += NESTING[ch] ?? 0;
+    i = isQuote(ch) ? skipString(line, i) : i + 1;
+  }
+  return i;
+}
+
+/**
+ * The line the value starting at `start` ends on: its own, unless it opens a multi-line string it
+ * does not close there. An unclosed one runs to the end of the file.
+ */
+function valueLastLine(lines: string[], index: number, start: number): number {
+  const line = lines[index] ?? "";
+  const delimiter = tripleQuote(line, start);
+  if (!delimiter || line.includes(delimiter, start + 3)) {
+    return index;
+  }
+  const close = lines.findIndex((next, i) => i > index && next.includes(delimiter));
+  return close === -1 ? lines.length - 1 : close;
+}
+
+/** Reads `a . "b" . 'c'` from `from`; `end` is the first non-space after it. */
+function readKeyPath(
+  line: string,
+  from: number,
+): { segments: KeySegment[]; end: number } | undefined {
+  const segments: KeySegment[] = [];
+  let i = skipSpace(line, from);
+  for (;;) {
+    const segment = readKeySegment(line, i);
+    if (!segment) {
+      return undefined;
+    }
+    segments.push(segment);
+    i = skipSpace(line, segment.end);
+    if (line[i] !== ".") {
+      return { segments, end: i };
+    }
+    i = skipSpace(line, i + 1);
+  }
+}
+
+/**
+ * One key segment. A quoted key with an escape keeps its raw text as `key`,
+ * so it matches nothing a caller renames.
+ */
+function readKeySegment(line: string, i: number): KeySegment | undefined {
+  const quote = line[i] ?? "";
+  if (isQuote(quote)) {
+    const end = skipString(line, i);
+    return end > line.length
+      ? undefined
+      : { start: i, end, key: line.slice(i + 1, end - 1), quote };
+  }
+  const bare = /^[A-Za-z0-9_-]+/.exec(line.slice(i));
+  return bare ? { start: i, end: i + bare[0].length, key: bare[0], quote: "" } : undefined;
+}
+
+/** The index past the string opening at `open`; past the end of the line when it does not close. */
+function skipString(line: string, open: number): number {
+  const quote = line[open];
+  let j = open + 1;
+  while (j < line.length && line[j] !== quote) {
+    j += quote === '"' && line[j] === "\\" ? 2 : 1;
+  }
+  return j + 1;
+}
+
+function isQuote(ch: string | undefined): boolean {
+  return ch === '"' || ch === "'";
+}
+
+/** The `"""` or `'''` opening a multi-line string at `at`, if one does. */
+function tripleQuote(line: string, at: number): string | undefined {
+  const delimiter = line.slice(at, at + 3);
+  return delimiter === '"""' || delimiter === "'''" ? delimiter : undefined;
+}
+
+function skipSpace(line: string, i: number): number {
+  let j = i;
+  while (line[j] === " " || line[j] === "\t") {
+    j++;
+  }
+  return j;
+}
+
+/**
+ * Renames the keys directly under one TOML table in place, keeping the rest
+ * of the file byte for byte. It leaves values alone; a layout it does not
+ * rewrite, such as an inline table, is left unchanged for the caller to
+ * detect.
+ */
+export function renameTableKeys(
+  source: string,
+  table: string,
+  rename: (key: string) => string | undefined,
+): string {
+  const lines = source.split("\n");
+  for (const key of scanTomlKeys(source)) {
+    if (key.path[0] !== table || key.path.length < 2) {
+      continue;
+    }
+    // The segment naming the key under `table`: the second of the full path, wherever it is written.
+    const at = key.segments.length - (key.path.length - 1);
+    if (key.kind !== "inline" && at >= 0) {
+      lines[key.index] = renameSegment(lines[key.index] ?? "", key.segments[at], rename);
+    }
+  }
+  return lines.join("\n");
+}
+
+function renameSegment(
+  line: string,
+  segment: KeySegment | undefined,
+  rename: (key: string) => string | undefined,
+): string {
+  const next = segment && rename(segment.key);
+  if (!segment || next === undefined || next === segment.key) {
+    return line;
+  }
+  return `${line.slice(0, segment.start)}${segment.quote}${next}${segment.quote}${line.slice(segment.end)}`;
+}
+
+/** Where a `[table]` is: its header line, the line of the next header, and the keys between. */
+type Section = { header: number; end: number; keys: TomlKey[] };
+
+/**
+ * Sets one string key directly under a TOML table, or removes it when `value`
+ * is undefined, keeping every other line byte for byte. A missing table is
+ * added at the end; a table left with no keys and nothing but blank lines is
+ * removed.
+ */
+export function setTableKey(
+  source: string,
+  table: string,
+  key: string,
+  value: string | undefined,
+): string {
+  const lines = source.split("\n");
+  const section = findSection(scanTomlKeys(source), table, lines.length);
+  const entry = `${JSON.stringify(key)} = ${JSON.stringify(value)}`;
+  if (!section) {
+    return value === undefined ? source : appendTable(source, table, entry);
+  }
+  const found = section.keys.find(
+    (scanned) => scanned.segments.length === 1 && scanned.segments[0]?.key === key,
+  )?.index;
+  if (value === undefined) {
+    return found === undefined ? source : removeKey(lines, section, found);
+  }
+  if (found === undefined) {
+    const last = section.keys.at(-1);
+    const after = last ? valueSpan(lines, last.index).last : section.header;
+    lines.splice(after + 1, 0, entry);
+  } else {
+    replaceValue(lines, found, JSON.stringify(value));
+  }
+  return lines.join("\n");
+}
+
+function findSection(scanned: TomlKey[], table: string, lineCount: number): Section | undefined {
+  const header = scanned.find(
+    (entry) => entry.kind === "table" && entry.path.length === 1 && entry.path[0] === table,
+  )?.index;
+  if (header === undefined) {
+    return undefined;
+  }
+  const end =
+    scanned.find(
+      (entry) => (entry.kind === "table" || entry.kind === "array") && entry.index > header,
+    )?.index ?? lineCount;
+  const keys = scanned.filter(
+    (entry) => entry.kind === "key" && entry.index > header && entry.index < end,
+  );
+  return { header, end, keys };
+}
+
+function appendTable(source: string, table: string, entry: string): string {
+  const body = source.replace(/\n+$/, "");
+  return `${body}${body ? "\n\n" : ""}[${table}]\n${entry}\n`;
+}
+
+/** Removes the key on line `found`, and its table too when nothing but blank lines would remain. */
+function removeKey(lines: string[], section: Section, found: number): string {
+  const { header, end } = section;
+  const { last } = valueSpan(lines, found);
+  const rest = [...lines.slice(header + 1, found), ...lines.slice(last + 1, end)];
+  if (rest.some((line) => line.trim() !== "")) {
+    lines.splice(found, last - found + 1);
+    return lines.join("\n");
+  }
+  const atEnd = end === lines.length;
+  lines.splice(header, end - header);
+  const joined = lines.join("\n");
+  return atEnd ? `${joined.replace(/\n+$/, "")}\n` : joined;
+}
+
+/** Where the value of the key on line `index` starts, and the line it ends on. */
+function valueSpan(lines: string[], index: number): { start: number; last: number } {
+  const line = lines[index] ?? "";
+  const start = readAssignment(line, 0)?.value ?? line.length;
+  return { start, last: valueLastLine(lines, index, start) };
+}
+
+/** Replaces the value of the key on line `index`, keeping its indent and a trailing comment. */
+function replaceValue(lines: string[], index: number, value: string): void {
+  const { start, last } = valueSpan(lines, index);
+  // A multi-line value collapses onto its first line.
+  const text = lines.slice(index, last + 1).join("\n");
+  const replaced = `${text.slice(0, start)}${value}${text.slice(valueEnd(text, start))}`;
+  lines.splice(index, last - index + 1, replaced);
+}
+
+/** The index past the value at `start`: a whole string, or a bare value up to its comment. */
+function valueEnd(text: string, start: number): number {
+  const delimiter = tripleQuote(text, start);
+  if (delimiter) {
+    const close = text.indexOf(delimiter, start + 3);
+    return close === -1 ? text.length : close + 3;
+  }
+  if (isQuote(text[start])) {
+    return skipString(text, start);
+  }
+  const comment = text.indexOf("#", start);
+  return start + text.slice(start, comment === -1 ? text.length : comment).trimEnd().length;
+}