@ossclip/core 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/browser.ts

@@ -19,6 +19,9 @@ export {
   type ContentRect,
   type ContentRectSegment,
 } from "./content-rect";
-export type { CaptionLine, CaptionWord } from "./captions";
+// lineDirection is a VALUE export but stays browser-safe: captions.ts
+// imports types only. CaptionTrack needs it at render time (Urdu field test
+// 2026-08-05 — RTL lines were laying out LTR).
+export { lineDirection, type CaptionLine, type CaptionWord } from "./captions";
 export type { KeptSpan } from "./timemap";
 export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";

package/src/captions.ts

@@ -14,6 +14,26 @@ export interface CaptionLine {
   end: number;
 }
 
+/**
+ * Per-LINE direction from the text itself — the first-strong-character
+ * heuristic (Unicode UAX #9 rules P2/P3), not the transcript's language
+ * code. The Urdu field transcript (2026-08-05) code-switches: lines opening
+ * with a Latin loanword ("Fulfillment …") exist alongside pure Urdu lines,
+ * and first-strong is the standard resolution for exactly that — the line
+ * lays out the way its own leading text reads. Digits and punctuation are
+ * bidi-weak/neutral and skipped, so "2026 میں …" still resolves RTL.
+ */
+const STRONG_RTL = /[\p{Script=Arabic}\p{Script=Hebrew}\p{Script=Syriac}\p{Script=Thaana}\p{Script=Nko}]/u;
+const STRONG_LTR = /\p{L}/u; // checked AFTER the RTL scripts, which are also \p{L}
+
+export function lineDirection(text: string): "rtl" | "ltr" {
+  for (const ch of text) {
+    if (STRONG_RTL.test(ch)) return "rtl";
+    if (STRONG_LTR.test(ch)) return "ltr";
+  }
+  return "ltr";
+}
+
 export interface CaptionOptions {
   maxWordsPerLine?: number;
   maxLineDuration?: number;

package/src/config.ts

@@ -30,6 +30,14 @@ export interface OssclipConfig {
    * user picks one of its "stop asking" answers.
    */
   openEditorAfterProduce?: OpenEditorPref;
+  /**
+   * Opt-in "made with ossclip" wordmark on every produce run, so voluntary
+   * attribution is a one-time config write instead of a flag remembered per
+   * run. DEFAULT OFF for everyone — a forced watermark on an open-source
+   * tool reads as a free-tier limitation, and this is a credit, not one.
+   * `--watermark` / `--no-watermark` win over this per run.
+   */
+  watermark?: boolean;
   browserExecutable?: string;
   /**
    * USD per million tokens, keyed by model id or family substring — overrides
@@ -108,6 +116,12 @@ export function loadConfig(): OssclipConfig {
     openEditorAfterProduce: (process.env.OSSCLIP_OPEN_EDITOR ??
       fileCfg.openEditorAfterProduce) as OpenEditorPref | undefined,
     browserExecutable: process.env.OSSCLIP_BROWSER ?? fileCfg.browserExecutable,
+    // File-only, like `pricing`: an env spelling would arrive as a string,
+    // and "false" is truthy — parse-don't-coerce says no such trap. The
+    // strict `=== true` check lives at the consumer (produce's
+    // resolveWatermark), so a hand-edited non-boolean stays OFF, the safe
+    // default for a credit.
+    watermark: fileCfg.watermark,
     pricing: fileCfg.pricing,
   };
 }

package/src/cover.ts

@@ -59,6 +59,27 @@ export function coverHeadline(text: string, maxWords = COVER_MAX_WORDS): string
   return out.join(" ").replace(/[,;:—–-]+$/, "");
 }
 
+/**
+ * What the cover step should emit.
+ *
+ * "textless" exists because of the Urdu field run 2026-08-05: a run without
+ * `--produce` has no LLM hook text, and the old behavior skipped the cover
+ * entirely — but frame selection needs no text at all, and the
+ * sharpness-scored face frame is a clean thumbnail on its own. Only the
+ * banner needs a headline; the pick does not, so a missing headline demotes
+ * the cover to a bare frame instead of erasing it.
+ */
+export type CoverDecision = "banner" | "textless" | "none";
+
+/**
+ * Pure so the three-way outcome is testable without a video, ffmpeg, or a
+ * beat sheet on disk — the same I/O split as `openCommand()`.
+ */
+export function coverDecision(coverEnabled: boolean, headline: string): CoverDecision {
+  if (!coverEnabled) return "none";
+  return headline.trim() ? "banner" : "textless";
+}
+
 /** Where the face sits in the COVER frame, as fractions of it. */
 export interface CoverFace {
   centerXFrac: number;

package/src/transcribe.ts

@@ -13,6 +13,96 @@ export interface WhisperJson {
 
 const NOISE_TOKEN = /^[[(].*[\])]$/; // [BLANK_AUDIO], (buzzing), [MUSIC] …
 
+/**
+ * How many bytes at the END of `bytes` form the start of a multi-byte UTF-8
+ * character whose continuation bytes are missing (§130: whisper.cpp `-ml 1`
+ * splits byte-level BPE tokens mid-character, so a segment's text can end on
+ * a bare lead byte — the field file ended one segment `0x20 0xD9` and started
+ * the next `0xB9 …`, the two halves of ٹ). 0 when the tail is complete.
+ */
+function utf8DanglingTailLen(bytes: Buffer): number {
+  let i = bytes.length - 1;
+  let cont = 0;
+  while (i >= 0 && cont < 3 && (bytes[i]! & 0xc0) === 0x80) {
+    i--;
+    cont++;
+  }
+  // All continuation bytes: a HEAD fragment, someone else's tail — not ours.
+  if (i < 0) return 0;
+  const lead = bytes[i]!;
+  const need = lead >= 0xf0 ? 4 : lead >= 0xe0 ? 3 : lead >= 0xc0 ? 2 : 1;
+  // ASCII (or a stray byte no neighbor could complete) — nothing dangling.
+  if (need === 1) return 0;
+  return cont < need - 1 ? bytes.length - i : 0;
+}
+
+/**
+ * Repair segments whose text was split MID-CHARACTER by byte-level BPE
+ * (§130). Operates in byte space: `text` values here are latin1-decoded, one
+ * code point per original byte, because the fix must see the real bytes —
+ * reading the file as utf8 first would already have destroyed them (Node
+ * substitutes U+FFFD, and the two halves of the character are gone for good).
+ * A segment ending on an incomplete sequence merges with a following segment
+ * that begins with continuation bytes, spanning both segments' offsets; the
+ * loop re-checks the merged tail so a 3–4 byte character split across three
+ * segments still heals. Only that exact shape merges — a dangling tail whose
+ * neighbor does NOT continue it is unrecoverable and left to decode to
+ * U+FFFD, which parseWhisperJson then folds into a neighboring word.
+ */
+function repairSplitSegments(json: WhisperJson): WhisperJson {
+  const out: WhisperJson["transcription"] = [];
+  for (const seg of json.transcription ?? []) {
+    const prev = out[out.length - 1];
+    const bytes = Buffer.from(seg.text, "latin1");
+    if (
+      prev &&
+      bytes.length > 0 &&
+      (bytes[0]! & 0xc0) === 0x80 &&
+      utf8DanglingTailLen(Buffer.from(prev.text, "latin1")) > 0
+    ) {
+      prev.text += seg.text;
+      prev.offsets = {
+        from: Math.min(prev.offsets.from, seg.offsets.from),
+        to: Math.max(prev.offsets.to, seg.offsets.to),
+      };
+    } else {
+      out.push({ ...seg, offsets: { ...seg.offsets } });
+    }
+  }
+  return {
+    ...json,
+    transcription: out.map((s) => ({
+      ...s,
+      text: Buffer.from(s.text, "latin1").toString("utf8"),
+    })),
+  };
+}
+
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
+
+/**
+ * Parse whisper.cpp's `-oj` output from its raw BYTES. The file is not
+ * guaranteed to be valid UTF-8 (§130): with `-ml 1` a multi-byte character
+ * can be split across two segments' text fields at the byte level, and a
+ * plain `readFile(path, "utf8")` silently replaces both halves with U+FFFD —
+ * which is exactly the `��اپک` that shipped into the Urdu field captions
+ * (Urdu field test 2026-08-05). Valid files take the strict-decode path and
+ * behave byte-identically to before; invalid ones round-trip through latin1
+ * (byte-transparent, and UTF-8 continuation bytes are ≥0x80 so JSON's ASCII
+ * structure is untouched) so the split can be healed with the bytes intact.
+ */
+export function parseWhisperOutput(raw: Buffer): Transcript {
+  let text: string | null = null;
+  try {
+    text = STRICT_UTF8.decode(raw);
+  } catch {
+    // Invalid UTF-8: the token-split shape. Fall through to byte repair —
+    // but only for DECODE failures; JSON syntax errors below still throw.
+  }
+  if (text !== null) return parseWhisperJson(JSON.parse(text) as WhisperJson);
+  return parseWhisperJson(repairSplitSegments(JSON.parse(raw.toString("latin1")) as WhisperJson));
+}
+
 /**
  * Convert whisper.cpp `-ml 1` segments (≈ one token each) into words.
  * Tokens beginning with whitespace start a new word; bare continuations
@@ -36,6 +126,26 @@ export function parseWhisperJson(json: WhisperJson): Transcript {
       words.push({ text, start, end });
     }
   }
+  // U+FFFD is never displayable speech — it is a byte the split repair could
+  // not heal (§130: the field file also holds a lone lead byte whose
+  // continuation whisper never emitted at all, mid-word between "ی" and "ج"),
+  // and shipping it paints a literal � caption. Strip it from mixed words; a
+  // word left EMPTY by the strip folds its time span into a neighbor instead
+  // of vanishing — the span still belongs to speech.
+  for (let i = words.length - 1; i >= 0; i--) {
+    const w = words[i]!;
+    if (!w.text.includes("�")) continue;
+    const cleaned = w.text.replaceAll("�", "");
+    if (cleaned) {
+      w.text = cleaned;
+      continue;
+    }
+    const prev = words[i - 1];
+    const next = words[i + 1];
+    if (prev) prev.end = Math.max(prev.end, w.end);
+    else if (next) next.start = Math.min(next.start, w.start);
+    words.splice(i, 1);
+  }
   // Whisper occasionally emits zero-length or inverted stamps; repair minimally.
   for (let i = 0; i < words.length; i++) {
     const w = words[i]!;
@@ -51,17 +161,36 @@ export interface WhisperOptions {
   modelPath: string;
   /** Output base path; whisper writes `${outBase}.json`. */
   outBase: string;
+  /**
+   * Language code passed as `-l` (e.g. "ur", "de", "auto"). whisper.cpp
+   * defaults to English when the flag is absent, which decodes garbage out of
+   * a non-English fine-tune (Urdu field test 2026-08-05: ggml-medium-urdu
+   * needed `-l ur` to emit Urdu script at all). Left unset, the spawned args
+   * stay byte-identical to what English-suffixed models always got.
+   */
+  language?: string;
 }
 
-export async function runWhisper(opts: WhisperOptions, wavPath: string): Promise<Transcript> {
-  await run(opts.whisperPath, [
+/**
+ * Pure arg construction, split from the spawn the same way openCommand() is
+ * split from openInBrowser(): the `-l` conditional is exactly the kind of
+ * branch that must be testable without a whisper binary on the box.
+ */
+export function whisperArgs(opts: WhisperOptions, wavPath: string): string[] {
+  const args = [
     "-m", opts.modelPath,
     "-f", wavPath,
     "-oj",
     "-of", opts.outBase,
     "-ml", "1",
     "--no-prints",
-  ]);
-  const json = JSON.parse(await readFile(`${opts.outBase}.json`, "utf8")) as WhisperJson;
-  return parseWhisperJson(json);
+  ];
+  if (opts.language !== undefined) args.push("-l", opts.language);
+  return args;
+}
+
+export async function runWhisper(opts: WhisperOptions, wavPath: string): Promise<Transcript> {
+  await run(opts.whisperPath, whisperArgs(opts, wavPath));
+  // Bytes, not "utf8": the utf8 read is where the §130 split characters died.
+  return parseWhisperOutput(await readFile(`${opts.outBase}.json`));
 }