@gentbajko/slopify 2.5.0 → 3.0.1

package/dist/slices/narration/blocks.js

@@ -0,0 +1,352 @@
+import { remark } from "remark";
+import remarkGfm from "remark-gfm";
+// The article as it will be spoken, block by block, for "Describe tables and figures in the
+// narration". Flattening the Markdown (`article/plain.ts`) keeps the words of prose but has
+// nothing to say about a table, a picture, an equation or a program: it drops them or reads
+// their bare cells. Here the document is walked instead, and every block a listener cannot
+// follow read aloud is kept whole for the text model to describe in a sentence or four
+// (`narration/describe.ts`); everything else becomes plain spoken text.
+//
+// Deterministic: the same Markdown always gives the same blocks, so a description is cached by
+// its block and an unchanged article never asks for one again. The article's end matter (the
+// sources and the pronunciation glossary) is cut off before this runs (`article/split.ts`), as
+// it is for the flattened text, so neither is ever narrated.
+export const describedKinds = ["table", "figure", "diagram", "math", "code"];
+// Private-use characters around an equation's number while the document is parsed, so an
+// underscore or asterisk inside an equation is never read as emphasis.
+const open = "\uE000";
+const close = "\uE001";
+const placeholder = /\uE000(\d+)\uE001/g;
+export function narrationBlocks(markdown, options = {}) {
+    const { text: protectedText, math } = protectMath(markdown);
+    const tree = remark().use(remarkGfm).parse(protectedText);
+    const walker = new Walker(protectedText, math, options);
+    walker.blocks(tree.children);
+    return walker.out;
+}
+export function describedBlocks(blocks) {
+    return blocks.filter((block) => block.kind !== "text");
+}
+// The narration: the text blocks as they are and each described block as its spoken passage,
+// one paragraph each, in the flattened text's own shape. Null while any passage is unknown.
+export function spokenNarration(blocks, passage) {
+    const paragraphs = [];
+    for (const block of blocks) {
+        const text = block.kind === "text" ? block.text : passage(block);
+        if (text === null)
+            return null;
+        const clean = text.trim();
+        if (clean !== "")
+            paragraphs.push(clean);
+    }
+    return paragraphs.length === 0 ? "" : `${paragraphs.join("\n\n")}\n`;
+}
+function protectMath(markdown) {
+    // Code keeps its dollars: a shell variable is not an equation.
+    const code = [];
+    const visit = (node) => {
+        if ((node.type === "code" || node.type === "inlineCode") && node.position) {
+            code.push([node.position.start.offset ?? 0, node.position.end.offset ?? 0]);
+            return;
+        }
+        if ("children" in node)
+            for (const child of node.children)
+                visit(child);
+    };
+    visit(remark().use(remarkGfm).parse(markdown));
+    const math = [];
+    const pattern = /\$\$([\s\S]+?)\$\$|\\\[([\s\S]+?)\\\]|\\\(([\s\S]+?)\\\)|(?<![\\$\w])\$(?![\s$])([^$\n]+?)(?<![\s\\])\$(?![\w$])/g;
+    const text = markdown.replace(pattern, (written, a, b, c, d, at) => {
+        if (code.some(([from, to]) => at < to && at + written.length > from))
+            return written;
+        const tex = String(a ?? b ?? c ?? d ?? "").trim();
+        math.push({ tex, written, display: a !== undefined || b !== undefined });
+        return `${open}${String(math.length - 1)}${close}`;
+    });
+    return { text, math };
+}
+class Walker {
+    markdown;
+    math;
+    options;
+    out = [];
+    section = null;
+    described = 0;
+    constructor(markdown, math, options) {
+        this.markdown = markdown;
+        this.math = math;
+        this.options = options;
+    }
+    blocks(nodes) {
+        for (let at = 0; at < nodes.length; at++) {
+            const node = nodes[at];
+            if (node === undefined)
+                continue;
+            switch (node.type) {
+                case "heading": {
+                    const text = this.spoken(node.children).replace(placeholder, (_all, n) => {
+                        const tex = this.math[Number(n)]?.tex ?? "";
+                        return readable(tex) ?? tex;
+                    });
+                    this.section = text.trim() || this.section;
+                    this.text(text);
+                    break;
+                }
+                case "paragraph": {
+                    if (node.children.some((child) => child.type === "image")) {
+                        // A caption or legend written under the picture belongs to it.
+                        const captions = [];
+                        while (captions.length < 2) {
+                            const next = nodes[at + captions.length + 1];
+                            if (next?.type !== "paragraph" || !isCaption(next, this.markdown))
+                                break;
+                            captions.push(next);
+                        }
+                        at += captions.length;
+                        this.figure(node, captions);
+                        break;
+                    }
+                    this.paragraph(node);
+                    break;
+                }
+                case "list":
+                    this.list(node);
+                    break;
+                case "blockquote":
+                    this.quote(node);
+                    break;
+                case "table":
+                    this.describe("table", this.source(node));
+                    break;
+                case "code":
+                    this.code(node);
+                    break;
+                case "html":
+                    this.html(node);
+                    break;
+                // A footnote's text, a link definition, a rule and front matter are never spoken.
+                default:
+                    break;
+            }
+        }
+    }
+    text(text) {
+        const clean = tidy(text);
+        if (clean !== "")
+            this.out.push({ kind: "text", text: clean });
+    }
+    describe(kind, source, extra = {}) {
+        this.described += 1;
+        this.out.push({
+            kind,
+            index: this.described,
+            source: source.trim(),
+            section: this.section,
+            ...(extra.image === undefined ? {} : { image: extra.image }),
+            ...(extra.lang === undefined ? {} : { lang: extra.lang }),
+            ...(extra.inline === undefined ? {} : { inline: extra.inline }),
+        });
+    }
+    paragraph(node) {
+        const raw = this.spoken(node.children);
+        const only = /^\s*\uE000(\d+)\uE001\s*$/.exec(raw);
+        const alone = only === null ? undefined : this.math[Number(only[1])];
+        if (alone !== undefined) {
+            this.describe("math", alone.written);
+            return;
+        }
+        const spans = [...raw.matchAll(placeholder)].map((match) => this.math[Number(match[1])]);
+        if (spans.some((span) => span === undefined || span.display || readable(span.tex) === null)) {
+            // Said in words by the model, the rest of the paragraph with it.
+            this.describe("math", this.source(node), { inline: true });
+            return;
+        }
+        this.text(raw.replace(placeholder, (_all, n) => readable(this.math[Number(n)]?.tex ?? "") ?? ""));
+    }
+    figure(node, captions) {
+        const image = node.children.find((child) => child.type === "image");
+        const lines = [];
+        for (const child of node.children)
+            if (child.type === "image" && child.alt?.trim())
+                lines.push(`Alt text: ${child.alt.trim()}`);
+        const beside = tidy(this.restore(this.spoken(node.children.filter((child) => child.type !== "image"))));
+        if (beside !== "")
+            lines.push(`Caption: ${beside}`);
+        for (const caption of captions) {
+            const text = tidy(this.restore(this.spoken(caption.children)));
+            if (text !== "")
+                lines.push(`Caption: ${text}`);
+        }
+        this.describe("figure", lines.join("\n") || "A picture with no caption.", {
+            ...(image?.url ? { image: image.url } : {}),
+        });
+    }
+    html(node) {
+        // An article pasted from the web may carry its figures as HTML.
+        const img = /<img\b[^>]*>/i.exec(node.value);
+        if (img === null)
+            return;
+        const attribute = (name) => new RegExp(`\\b${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i")
+            .exec(img[0])
+            ?.slice(2)
+            .find(Boolean);
+        const caption = /<figcaption[^>]*>([\s\S]*?)<\/figcaption>/i.exec(node.value)?.[1];
+        const lines = [
+            ...(attribute("alt")?.trim() ? [`Alt text: ${attribute("alt")?.trim() ?? ""}`] : []),
+            ...(caption?.trim() ? [`Caption: ${tidy(caption.replace(/<[^>]+>/g, " "))}`] : []),
+        ];
+        const src = attribute("src");
+        this.describe("figure", lines.join("\n") || "A picture with no caption.", {
+            ...(src ? { image: src } : {}),
+        });
+    }
+    code(node) {
+        const lang = node.lang?.trim().toLowerCase() ?? "";
+        const source = this.restore(this.source(node));
+        const named = lang === "" ? {} : { lang };
+        if (lang === "mermaid" ||
+            (["", "text", "txt", "ascii", "plain"].includes(lang) && isDrawing(node.value)))
+            this.describe("diagram", source, named);
+        else if (["math", "latex", "tex", "katex"].includes(lang))
+            this.describe("math", source);
+        else if (this.options.code !== "skip")
+            this.describe("code", source, named);
+    }
+    quote(node) {
+        const start = this.out.length;
+        this.blocks(node.children);
+        // The quoted words are spoken in quotation marks, which a voice reads as a quote.
+        for (let at = start; at < this.out.length; at++) {
+            const block = this.out[at];
+            if (block?.kind === "text")
+                this.out[at] = { kind: "text", text: `“${block.text}”` };
+        }
+    }
+    list(node) {
+        const items = [];
+        const flush = () => {
+            if (items.length > 0)
+                this.text(this.sentences(items.splice(0), node.ordered === true));
+        };
+        for (const item of node.children) {
+            const words = [];
+            for (const child of item.children) {
+                if (child.type === "paragraph" && !child.children.some((one) => one.type === "image")) {
+                    const raw = this.spoken(child.children);
+                    if (!raw.includes(open)) {
+                        words.push(raw);
+                        continue;
+                    }
+                }
+                // A table, a picture or a nested list inside an item is its own block, after the
+                // item's words.
+                if (words.length > 0)
+                    items.push(tidy(words.splice(0).join(" ")));
+                flush();
+                this.blocks([child]);
+            }
+            if (words.length > 0)
+                items.push(tidy(words.join(" ")));
+        }
+        flush();
+    }
+    sentences(items, ordered) {
+        const english = this.options.language === undefined || this.options.language === "en";
+        const kept = items.filter((item) => item !== "");
+        if (!english || kept.length < 2)
+            return kept.map(sentence).join(" ");
+        if (ordered)
+            return kept
+                .map((item, at) => sentence(`${at === 0 ? "First" : at === kept.length - 1 ? "Finally" : "Then"}, ${item}`))
+                .join(" ");
+        // Short items read as one sentence, "a, b and c"; longer ones one sentence each.
+        if (kept.every((item) => item.split(/\s+/).length <= 5 && !/[.!?;:,—–]/.test(item))) {
+            const joined = `${kept.slice(0, -1).join(", ")} and ${kept.at(-1) ?? ""}`;
+            return sentence(joined.charAt(0).toUpperCase() + joined.slice(1));
+        }
+        return kept.map(sentence).join(" ");
+    }
+    // The words of inline Markdown: link text without its address, no footnote markers, no
+    // bare URLs. Equations stay as placeholders for the caller to decide on.
+    spoken(nodes) {
+        return nodes.map((node) => this.inline(node)).join("");
+    }
+    inline(node) {
+        switch (node.type) {
+            case "text":
+            case "inlineCode":
+                return node.value;
+            case "emphasis":
+            case "strong":
+            case "delete":
+                return this.spoken(node.children);
+            case "link": {
+                const text = this.spoken(node.children);
+                return isAddress(text, node.url) ? "" : text;
+            }
+            case "linkReference": {
+                const text = this.spoken(node.children);
+                return /^\s*\^?\d+\s*$/.test(text) ? "" : text;
+            }
+            case "image":
+            case "imageReference":
+                return node.alt ?? "";
+            case "break":
+                return "\n";
+            default:
+                return "";
+        }
+    }
+    source(node) {
+        const from = node.position?.start.offset;
+        const to = node.position?.end.offset;
+        return from === undefined || to === undefined
+            ? ""
+            : this.restore(this.markdown.slice(from, to));
+    }
+    restore(text) {
+        return text.replace(placeholder, (_all, n) => this.math[Number(n)]?.written ?? "");
+    }
+}
+function isCaption(node, markdown) {
+    if (node.children.length === 1 && node.children[0]?.type === "emphasis")
+        return true;
+    const from = node.position?.start.offset ?? 0;
+    const head = markdown.slice(from, from + 40).replace(/^[*_\s]+/, "");
+    return /^(figure|fig\.|chart|graph|diagram|image|legend|caption|source)\b/i.test(head);
+}
+// An ASCII or box-drawing chart in a plain fence: box characters, or lines that are mostly
+// rules and bars.
+function isDrawing(value) {
+    if (/[─│┌┐└┘├┤┬┴┼═║╔╗╚╝▲▼►◄█░▒▓]/.test(value))
+        return true;
+    const lines = value.split("\n").filter((line) => line.trim() !== "");
+    return (lines.filter((line) => /[-+|*]{3,}|[|+].*[|+]/.test(line)).length >=
+        Math.max(3, lines.length / 2));
+}
+// A link whose text is its own address, or any bare URL: nothing a listener can use.
+function isAddress(text, url) {
+    const clean = text.trim();
+    return clean === "" || clean === url || /^(https?:\/\/|www\.|mailto:)/i.test(clean);
+}
+const greek = /\\(alpha|beta|gamma|delta|epsilon|zeta|eta|theta|iota|kappa|lambda|mu|nu|xi|pi|rho|sigma|tau|upsilon|phi|chi|psi|omega|Gamma|Delta|Theta|Lambda|Xi|Pi|Sigma|Phi|Psi|Omega)\b/g;
+// A short inline symbol read as it is written ("$T$" is "T", "$\alpha$" is "alpha"), or null
+// when it is a formula to be said in words.
+function readable(tex) {
+    const plain = tex.replace(greek, (_all, name) => name.toLowerCase()).trim();
+    return plain.length <= 20 && /^[\p{L}\p{N}\s.,%]*$/u.test(plain) ? plain : null;
+}
+function sentence(text) {
+    const clean = text.trim();
+    return clean === "" || /[.!?…:;]["”’)]?$/.test(clean) ? clean : `${clean}.`;
+}
+// Footnote markers and bare addresses out, then the spacing they leave behind.
+function tidy(text) {
+    return text
+        .replace(/\s?\[(?:\^?[\w-]+)(?:\s*[,–-]\s*\^?\d+)*\](?!\()/g, (marker) => /\[\^|\[\d/.test(marker) ? "" : marker)
+        .replace(/\s?\b(?:https?:\/\/|www\.)[^\s)]+/g, "")
+        .replace(/[ \t]+([.,;:!?])/g, "$1")
+        .replace(/[ \t]{2,}/g, " ")
+        .replace(/\(\s*\)/g, "")
+        .trim();
+}

package/dist/slices/narration/chunk.js

@@ -20,9 +20,20 @@ export function chunkNarration(text, chunking) {
     }
 }
 // What "N words" counts: runs of non-space. Exported because it is half of the rule -
-// a test that asserts a chunk fits in N has to count the same way the cut did.
+// a test that asserts a chunk fits in N has to count the same way the cut did. Chinese,
+// Japanese, Thai and the other scripts written without spaces are counted by the platform's
+// own word breaker instead, or a whole paragraph would be one "word"; text without them
+// (every English narration) is counted exactly as before.
+const unspaced = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}]/u;
 export function wordsIn(text) {
-    return text.split(/\s+/).filter((word) => word !== "").length;
+    if (!unspaced.test(text))
+        return text.split(/\s+/).filter((word) => word !== "").length;
+    const segmenter = new Intl.Segmenter("en", { granularity: "word" });
+    let count = 0;
+    for (const part of segmenter.segment(text))
+        if (part.isWordLike === true)
+            count += 1;
+    return count;
 }
 export function sameChunking(left, right) {
     const a = left ?? defaultChunking;
@@ -52,11 +63,12 @@ function sentenceRuns(text, budget, measure) {
     // The provider-specific planning layer applies any hard request limit afterwards.
     return nonEmpty(chunks);
 }
-// ceiling: segmented as English. `Intl.Segmenter` is the platform's own sentence breaker
-// (ICU ships with Node), so no dependency and no regex full of abbreviations; the locale
-// is fixed because a run carries no language and the default one varies by machine. The
-// upgrade is a language on the run configuration, passed through to here.
-function* sentences(text) {
+// `Intl.Segmenter` is the platform's own sentence breaker (ICU ships with Node), so no
+// dependency and no regex full of abbreviations. Its sentence rules are Unicode's (UAX #29)
+// for every language: "。", "！", "।", "؟" and "¿…?" end or open sentences whatever the
+// locale, so the project language needs no locale here, and "en" keeps it the same on every
+// machine (the default locale varies).
+export function* sentences(text) {
     // Built per call rather than held at module scope: the standards forbid a module-level
     // singleton, and constructing one costs microseconds against a call that just read an
     // article off disk.

package/dist/slices/narration/concat.js

@@ -46,10 +46,10 @@ export async function joinNarration(deps, input) {
     const first = input.files[0];
     if (first === undefined) {
         // The stage refuses an empty narration before it gets here, so this is a bug.
-        throw new Error("Slopify hit an internal error (there is no narration audio to join). Retry stage; if it happens again, use Download diagnostics in Settings and report it.");
+        throw new Error("Slopify hit an internal error (there is no narration audio to join). Try again; if it happens again, use Download diagnostics in Settings and report it.");
     }
     mkdirSync(dirname(input.output), { recursive: true, mode: 0o700 });
-    if (input.files.length === 1) {
+    if (input.files.length === 1 && input.reencode !== true) {
         // Whole-text mode, and any run whose article is one paragraph: there is nothing to
         // join, and re-encoding the only chunk would lose quality for no reason.
         input.signal.throwIfAborted();

package/dist/slices/narration/describe.js

@@ -0,0 +1,45 @@
+import { withLanguage } from "../../kernel/ports/languages.js";
+const instructions = {
+    table: "Describe this table for a listener in 1–4 sentences in the narration's language and tone; give the pattern and the notable values, not every cell; never read it row by row.",
+    figure: "Describe this figure for a listener in 1–3 sentences in the narration's language and tone, from its caption, alt text and legend (and the attached picture, when there is one): say what it shows and what to take from it. Never say that a figure shows something without saying what; explain colours or symbols only through what they stand for.",
+    diagram: "Describe this diagram or chart for a listener in 1–3 sentences in the narration's language and tone: what it connects or compares and what it tells us. Never read labels, arrows or axis ticks one by one.",
+    math: "Say what this equation means for a listener in 1–3 sentences in the narration's language and tone: how the quantities depend on each other (for example, “evaporation grows with temperature and falls with humidity”), not symbol by symbol. A single short symbol may be read as it is.",
+    code: "Summarise what this code does for a listener in one or two sentences in the narration's language and tone, naming the language when it helps (for example, “a Rust function that carves river channels by lowering the terrain along the flow”). Never read code, symbols or names of variables aloud.",
+};
+const inlineMath = "Rewrite this paragraph so it can be read aloud, in the narration's language and tone: keep its words, but say each formula's meaning in words rather than symbol by symbol. A single short symbol may be read as it is.";
+const answerRules = "Answer with the spoken passage only: plain sentences a narrator reads out, no Markdown, no lists, no headings, no quotation marks around the whole answer, no preamble such as “Here is”.";
+export function describeInstruction(block) {
+    return block.kind === "math" && block.inline === true ? inlineMath : instructions[block.kind];
+}
+export function describeMessages(block, style, language) {
+    const guidance = style.trim();
+    const system = [
+        describeInstruction(block),
+        answerRules,
+        ...(guidance === ""
+            ? []
+            : [
+                `Style guidance for the narration (follow its tone; ignore anything about formats or cues):\n${guidance}`,
+            ]),
+    ].join("\n\n");
+    const user = [
+        ...(block.section === null ? [] : [`Section: ${block.section}`]),
+        ...(block.lang === undefined ? [] : [`Language of the code: ${block.lang}`]),
+        block.source,
+    ].join("\n\n");
+    return withLanguage([
+        { role: "system", content: system },
+        { role: "user", content: user },
+    ], language);
+}
+// The passage as the narration says it: one paragraph, no Markdown a voice would read out.
+export function spokenPassage(answer) {
+    return answer
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6})\s+/gm, "")
+        .replace(/[*_`#|]/g, "")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/^["“](.*)["”]$/s, "$1")
+        .trim();
+}

package/dist/slices/narration/pauses-model.js

@@ -0,0 +1,63 @@
+// Pauses between sentences. Some voices (Inworld's TTS-2 among them) run one sentence into the
+// next with barely a breath, so a narration sounds rushed. With a minimum set, the join finds
+// the quiet after each sentence in every narration piece and lengthens it to at least that
+// long by adding silence in the middle of it (`pauses.ts`): an existing pause is never
+// shortened and a word is never cut. It happens in the join, before the word timing reads the
+// narration, so the captions, the word-by-word highlights, the cuts, the shorts' clips, the
+// chapters and the M4B's marks are timed on the paced narration and stay in step with it.
+//
+// A paragraph's minimum is separate and 0 (the sentence minimum only) unless set: the pause
+// between paragraphs is mostly the narration prompt's and the voice's to make.
+//
+// Browser-safe: Play and Edit project read these limits. A run without either has neither on
+// its config, which is what every project saved before them was, and the joins keep their
+// fingerprints then.
+// ceiling: a quarter second reads brisk, 0.35 to 0.45 natural or documentary, 0.5 to 0.8 an
+// audiobook's relaxed pace, and above 0.8 sleep content; beyond 2 s it stops sounding like a
+// pause between sentences.
+export const defaultSentencePauseSeconds = 0.4;
+export const pauseSecondsMax = 2;
+export const pauseSecondsStep = 0.05;
+// What a run's config asks for; undefined when neither minimum is set.
+export function pausesOf(config) {
+    const sentenceSeconds = config.sentencePauseSeconds ?? 0;
+    const paragraphSeconds = config.paragraphPauseSeconds ?? 0;
+    return sentenceSeconds > 0 || paragraphSeconds > 0
+        ? { sentenceSeconds, paragraphSeconds }
+        : undefined;
+}
+export function pauseProblem(value, name) {
+    const steps = value / pauseSecondsStep;
+    return Number.isFinite(value) &&
+        value >= 0 &&
+        value <= pauseSecondsMax &&
+        Math.abs(steps - Math.round(steps)) < 1e-6
+        ? undefined
+        : `The pause between ${name} must be between 0 and ${String(pauseSecondsMax)} seconds, in steps of ${String(pauseSecondsStep)}. Change it under Play → Video and style, or Edit project → Pauses and volume.`;
+}
+export function pauseFields(config) {
+    const fields = [];
+    if (config.sentencePauseSeconds !== undefined) {
+        const problem = pauseProblem(config.sentencePauseSeconds, "sentences");
+        if (problem !== undefined)
+            fields.push({ field: "sentencePauseSeconds", message: problem });
+    }
+    if (config.paragraphPauseSeconds !== undefined) {
+        const problem = pauseProblem(config.paragraphPauseSeconds, "paragraphs");
+        if (problem !== undefined)
+            fields.push({ field: "paragraphPauseSeconds", message: problem });
+    }
+    return fields;
+}
+// Play's typed pauses as a run's config holds them: absent text is the default (the sentence
+// default, no paragraph minimum), a value of 0 is left off, and text that is not a number is
+// NaN, which the rule refuses in place.
+export function pausesOfForm(form) {
+    const typed = (raw, fallback) => raw === undefined || raw.trim() === "" ? fallback : Number(raw.trim().replace(",", "."));
+    const sentence = typed(form.sentencePause, defaultSentencePauseSeconds);
+    const paragraph = typed(form.paragraphPause, 0);
+    return {
+        ...(sentence === 0 ? {} : { sentencePauseSeconds: sentence }),
+        ...(paragraph === 0 ? {} : { paragraphPauseSeconds: paragraph }),
+    };
+}