@gentbajko/slopify 3.0.2 → 3.0.4

package/dist/slices/loudness/line-level.js

@@ -0,0 +1,138 @@
+import { rmSync, writeFileSync } from "node:fs";
+import { runFfmpeg } from "../video/ffmpeg.js";
+// Level the volume, line by line, for a narration with several speakers. The pieces are levelled
+// before they are joined (`level-pieces.ts`), but a piece is one request to the voice provider,
+// and with native dialogue one request speaks several people's lines. Its average hides them: a
+// narrator with a few loud words averages the same as a character who speaks up throughout, and
+// the character sits 2 dB above the narrator all the way. Once the words are timed, each line's
+// typical level (the median of its 400 ms momentary loudness while it speaks) is brought to
+// within `withinLu` of the narrator's; the gain changes in the pause between two lines, so no
+// word is cut into and nothing moves in time, and the captions keep their timing.
+// ceiling: how far from the narrator's typical level a line may stay.
+export const withinLu = 1;
+// ceiling: the most a line is moved either way; a line further off than this is left to the
+// listener rather than turned into noise or distortion.
+const gainCapDb = 10;
+// A momentary reading under this is a pause, not speech.
+const speechFloor = -45;
+// The first readings of a line still hold the line before it (the window is 400 ms long).
+const settleSeconds = 0.4;
+// Consecutive words by one speaker, from the timed words, in `offset`'s time (the file's own).
+export function linesOf(words, offset) {
+    const lines = [];
+    for (const word of words) {
+        if (word.speaker === undefined)
+            continue;
+        const last = lines.at(-1);
+        if (last !== undefined && last.speaker === word.speaker)
+            lines[lines.length - 1] = { ...last, end: word.end - offset };
+        else
+            lines.push({ speaker: word.speaker, start: word.start - offset, end: word.end - offset });
+    }
+    return lines;
+}
+// Each line's gain in dB, and the time it starts at: the middle of the pause before the line.
+export function lineGains(lines, frames, narrator = "narrator") {
+    const typical = lines.map((line) => {
+        const spoken = (from) => frames
+            .filter((frame) => frame.t >= from && frame.t <= line.end && frame.momentary > speechFloor)
+            .map((frame) => frame.momentary)
+            .sort((a, b) => a - b);
+        // A short line has too few settled readings; its whole span is the best there is.
+        const settled = spoken(line.start + settleSeconds);
+        const readings = settled.length >= 3 ? settled : spoken(line.start);
+        return readings.length === 0 ? undefined : readings[Math.floor(readings.length / 2)];
+    });
+    const median = (values) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
+    const known = (values) => values.filter((value) => value !== undefined);
+    const reference = median(known(typical.filter((_value, at) => lines[at]?.speaker === narrator))) ??
+        median(known(typical));
+    if (reference === undefined)
+        return [];
+    return lines.map((line, at) => {
+        const level = typical[at];
+        const off = level === undefined ? 0 : level - reference;
+        const gain = off > withinLu ? withinLu - off : off < -withinLu ? -withinLu - off : 0;
+        const before = lines[at - 1];
+        return {
+            at: before === undefined ? 0 : (before.end + line.start) / 2,
+            gainDb: Math.max(-gainCapDb, Math.min(gainCapDb, Math.round(gain * 100) / 100)),
+        };
+    });
+}
+// ffmpeg's EBU R128 readings, ten a second, as its verbose log prints them.
+export function parseFrames(stderr) {
+    const frames = [];
+    for (const match of stderr.matchAll(/t:\s*([0-9.]+)\s+TARGET:[^\n]*?\sM:\s*(-?[0-9.]+)/g))
+        frames.push({ t: Number(match[1]), momentary: Number(match[2]) });
+    return frames;
+}
+// `input` levelled line by line into `output` (16-bit PCM WAV). `words` are timed on a timeline
+// where the file starts at `offset` seconds. False, with nothing written, when there is nothing
+// to level: no speakers in the words, or every line already within `withinLu`.
+export async function levelLines(run, input, output, words, offset) {
+    const lines = linesOf(words, offset);
+    if (new Set(lines.map((line) => line.speaker)).size < 2)
+        return false;
+    let stderr = "";
+    await runFfmpeg({
+        bin: run.bin,
+        args: [
+            "-hide_banner",
+            "-nostdin",
+            "-v",
+            "verbose",
+            "-nostats",
+            "-i",
+            input,
+            "-af",
+            "ebur128",
+            "-f",
+            "null",
+            "-",
+        ],
+        signal: run.signal,
+        log: run.log,
+        onProgress: () => { },
+        onStderr: (text) => {
+            stderr += text;
+        },
+    });
+    const gains = lineGains(lines, parseFrames(stderr));
+    if (gains.every((one) => one.gainDb === 0))
+        return false;
+    // The gain for each line, set at its start by a timed command to the volume filter.
+    const commands = `${output}.lines.txt`;
+    writeFileSync(commands, gains
+        .map((one) => `${Math.max(0, one.at).toFixed(3)} volume@lines volume ${(10 ** (one.gainDb / 20)).toFixed(5)};`)
+        .join("\n"), { mode: 0o600 });
+    try {
+        await runFfmpeg({
+            bin: run.bin,
+            args: [
+                "-hide_banner",
+                "-nostdin",
+                "-loglevel",
+                "error",
+                "-nostats",
+                "-y",
+                "-i",
+                input,
+                "-af",
+                `asendcmd=f=${commands.replaceAll("\\", "/").replaceAll(":", "\\\\:")},volume@lines=volume=1:precision=float:eval=frame`,
+                "-c:a",
+                "pcm_s16le",
+                "-f",
+                "wav",
+                output,
+            ],
+            signal: run.signal,
+            log: run.log,
+            onProgress: () => { },
+        });
+    }
+    finally {
+        rmSync(commands, { force: true });
+    }
+    return true;
+}

package/dist/slices/narration/pauses.js

@@ -1,23 +1,37 @@
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { numberForms } from "../../kernel/ports/number-words.js";
 import { measureFile } from "../loudness/loudnorm.js";
 import { pieceLufs, pieceTruePeak } from "../loudness/model.js";
 import { probeDurationMs, runFfmpeg } from "../video/ffmpeg.js";
 import { sentences } from "./chunk.js";
-// The sentence ends inside a text, not counting its last.
+// How long a stretch of text takes to say, in letters. Digits count as their words ("1982" as
+// "nineteen eighty two", English's being a fair measure for any language's), an IPA spelling's
+// slashes and stress marks count nothing, and a run of spacing counts one. Counted as written,
+// a paragraph full of years and issue numbers put its end seconds early.
+export function spokenLength(text) {
+    return Array.from(text
+        .replace(/\d[\d,]*(?:\.\d+)?(?:s|st|nd|rd|th)?\b/gi, (raw) => numberForms(raw)[0] ?? raw)
+        .replace(/[/ˈˌː]/g, "")
+        .replace(/\s+/g, " ")).length;
+}
+// The sentence ends inside a text, not counting its last. A name's initial ("Mary J. Blake")
+// ends no sentence, whatever the sentence splitter makes of its full stop.
 export function textBoundaries(text) {
     const parts = [...sentences(text)];
-    const total = Array.from(text).length;
+    const total = parts.reduce((sum, part) => sum + spokenLength(part), 0);
     if (parts.length < 2 || total === 0)
         return [];
     const boundaries = [];
     let offset = 0;
     for (const part of parts.slice(0, -1)) {
-        offset += Array.from(part).length;
+        offset += spokenLength(part);
         const trailing = /\s*$/.exec(part)?.[0] ?? "";
         // Only a real sentence: text that is only spacing is no sentence of its own.
         if (part.trim() === "")
             continue;
+        if (/(?:^|[\s("'])\p{Lu}\.\s*$/u.test(part))
+            continue;
         boundaries.push({
             ratio: offset / total,
             kind: /\n[ \t\r]*\n/.test(trailing) || /\n/.test(trailing) ? "paragraph" : "sentence",
@@ -54,6 +68,12 @@ const windowShare = 0.2;
 const durationWeight = 3;
 // A stretch this near either end of the piece is the piece's own lead-in or tail.
 const edgeSeconds = 0.02;
+// ceiling: a stretch shorter than this share of the voice's usual sentence pause (the median of
+// its as many longest stretches as the piece has sentence ends) is a breath between words, and
+// never a sentence end. The words only say roughly where an end is: a voice's pace swings with
+// its delivery cues, and one narration put a paragraph end 17 seconds after where its words
+// did. Lengthening a breath there cut "sixty-two" in two.
+const breathShare = 0.4;
 export function planPauses(input) {
     const { durationSeconds, silences, boundaries, settings } = input;
     const leadingSilence = silences.find((one) => one.start <= edgeSeconds);
@@ -65,7 +85,13 @@ export function planPauses(input) {
     const speechStart = leading;
     const speechEnd = Math.max(speechStart, durationSeconds - trailing);
     const speech = speechEnd - speechStart;
-    const inner = silences.filter((one) => one !== leadingSilence && one !== trailingSilence);
+    const between = silences.filter((one) => one !== leadingSilence && one !== trailingSilence);
+    const longest = between
+        .map((one) => one.end - one.start)
+        .sort((a, b) => b - a)
+        .slice(0, boundaries.length);
+    const usual = longest[Math.floor((longest.length - 1) / 2)] ?? 0;
+    const inner = between.filter((one) => one.end - one.start >= usual * breathShare);
     if (speech <= 0 || inner.length === 0 || boundaries.length === 0)
         return { inserts: [], leading, trailing };
     const window = Math.max(windowSeconds, speech * windowShare);

package/dist/slices/rebuild/recipe-build.js

@@ -3,6 +3,7 @@ import { audioRecipes } from "./recipe-audio.js";
 import { documentRecipes } from "./recipe-document.js";
 import { editPlan } from "./recipe-edit.js";
 import { exportRecipes } from "./recipe-exports.js";
+import { linePlan } from "./recipe-lines.js";
 import { masterPlan } from "./recipe-loudness.js";
 import { resourceIdentity } from "./recipe-model.js";
 import { imageReference, referenceRecipe } from "./recipe-reference.js";
@@ -11,6 +12,12 @@ import { shortsRecipes } from "./recipe-shorts.js";
 import { textRecipes } from "./recipe-text.js";
 import { thumbnailRecipes, visualAssets, visualRecipes } from "./recipe-visual.js";
 import { youtubeRecipes } from "./recipe-youtube.js";
+// The video's sound: mastered, and on a multi-voice run levelled line by line first.
+function withLines(master, lines) {
+    return lines.keys.length === 0
+        ? master
+        : { values: [...master.values, ...lines.values], keys: [...master.keys, ...lines.keys] };
+}
 export function buildRecipes(context) {
     const text = textRecipes(context);
     const audio = audioRecipes(context, text);
@@ -31,6 +38,6 @@ export function buildRecipes(context) {
         ...shortsRecipes(context, exports, drawnFrom, audio.cards ?? [], masterPlan(context, audio.levels, "video")),
         ...thumbnail,
         ...documentRecipes(context, text, thumbnail),
-        ...visualAssets(context, visualRecipes(context.config, context.content, audio.mediaFingerprint, captions?.fingerprint ?? null, (images) => editPlan(context, exports, youtube, images, audio.cards ?? []), drawnFrom, timing === undefined ? null : resourceIdentity(context, timing), masterPlan(context, audio.levels, "video"))),
+        ...visualAssets(context, visualRecipes(context.config, context.content, audio.mediaFingerprint, captions?.fingerprint ?? null, (images) => editPlan(context, exports, youtube, images, audio.cards ?? []), drawnFrom, timing === undefined ? null : resourceIdentity(context, timing), withLines(masterPlan(context, audio.levels, "video"), linePlan(context, timing)))),
     ]);
 }

package/dist/slices/rebuild/recipe-exports.js

@@ -7,6 +7,7 @@ import { audioExportArgs } from "../video/audio-export-args.js";
 import { editNeedsTiming } from "../video/edit-settings.js";
 import { usesVoices } from "../voices/model.js";
 import { portraitValues } from "../voices/portraits.js";
+import { linePlan, linesLevelled } from "./recipe-lines.js";
 import { masterPlan } from "./recipe-loudness.js";
 import { recipe, resourceIdentity, } from "./recipe-model.js";
 export function exportRecipes(context, audio) {
@@ -16,6 +17,42 @@ export function exportRecipes(context, audio) {
     const recipes = [];
     // Level the volume: the listening files are mastered to the audio files' target.
     const master = masterPlan(context, audio.levels, "audioFiles");
+    const captions = config.subtitles !== undefined && config.subtitles.mode !== "off";
+    // The YouTube description's chapters, the shorts' clips and captions, a short's own
+    // captions, and the video's cuts, chapter cards and chapter openers use the same word timing,
+    // so it runs for them even with captions off; only the caption files below wait for captions.
+    // A multi-voice run with Level the volume on levels its speakers line by line from it too.
+    const voices = usesVoices(config) ? config.voices : undefined;
+    const lined = linesLevelled(config);
+    const timed = captions ||
+        usesYoutubeDescription(config) ||
+        usesShorts(config) ||
+        usesShortMode(config) ||
+        editNeedsTiming(config) ||
+        reviewsNarration(config) ||
+        voices?.audioFiles === true ||
+        lined;
+    const timing = timed
+        ? recipe(context, "subtitles:timing", "video", {
+            kind: "local",
+            version: 1,
+            operation: timingOperation(projectLanguage(config)),
+            // The lead-in moves every word, so the edge silence is part of the timing.
+            values: [
+                audio.timeline,
+                config.silenceGapSeconds,
+                // The project language; an English project reads "en" here as it always did.
+                config.language ?? config.subtitles?.language ?? "en",
+                config.edgeSilenceSeconds,
+                // Each word learns its speaker and turn on a multi-voice run.
+                ...(voices === undefined ? [] : ["voice-words-v1"]),
+            ],
+        }, audio.keys)
+        : undefined;
+    const lines = linePlan(context, timing);
+    // The timing goes ahead of what waits for it; any other run keeps its old order.
+    if (lined && timing !== undefined)
+        recipes.push(timing);
     if (config.sources.video === "off")
         recipes.push(recipe(context, "export:wav", "video", {
             kind: "local",
@@ -25,37 +62,13 @@ export function exportRecipes(context, audio) {
                 audio.mediaFingerprint,
                 audioExportArgs([{ kind: "body", path: "$body", seconds: 0 }], "$output"),
                 ...master.values,
+                ...lines.values,
             ],
-        }, [...audio.keys, ...master.keys]));
-    const captions = config.subtitles !== undefined && config.subtitles.mode !== "off";
-    // The YouTube description's chapters, the shorts' clips and captions, a short's own
-    // captions, and the video's cuts, chapter cards and chapter openers use the same word timing,
-    // so it runs for them even with captions off; only the caption files below wait for captions.
-    const voices = usesVoices(config) ? config.voices : undefined;
-    if (!captions &&
-        !usesYoutubeDescription(config) &&
-        !usesShorts(config) &&
-        !usesShortMode(config) &&
-        !editNeedsTiming(config) &&
-        !reviewsNarration(config) &&
-        voices?.audioFiles !== true)
+        }, [...audio.keys, ...master.keys, ...lines.keys]));
+    if (timing === undefined)
         return recipes;
-    const timing = recipe(context, "subtitles:timing", "video", {
-        kind: "local",
-        version: 1,
-        operation: timingOperation(projectLanguage(config)),
-        // The lead-in moves every word, so the edge silence is part of the timing.
-        values: [
-            audio.timeline,
-            config.silenceGapSeconds,
-            // The project language; an English project reads "en" here as it always did.
-            config.language ?? config.subtitles?.language ?? "en",
-            config.edgeSilenceSeconds,
-            // Each word learns its speaker and turn on a multi-voice run.
-            ...(voices === undefined ? [] : ["voice-words-v1"]),
-        ],
-    }, audio.keys);
-    recipes.push(timing);
+    if (!lined)
+        recipes.push(timing);
     if (voices?.audioFiles === true)
         recipes.push(recipe(context, "voices:files", "video", {
             kind: "local",
@@ -67,6 +80,7 @@ export function exportRecipes(context, audio) {
                 (audio.sections ?? []).map((section) => [section.title, section.firstTurn]),
                 config.title,
                 ...master.values,
+                ...lines.values,
                 // The book's title and chapter become the files' album and track tags; a project
                 // that is no chapter of a book keeps the values it always had.
                 ...(voices.book === undefined

package/dist/slices/rebuild/recipe-lines.js

@@ -0,0 +1,17 @@
+import { usesLoudness } from "../loudness/model.js";
+import { usesVoices } from "../voices/model.js";
+// Level the volume line by line (`loudness/line-level.ts`): a multi-voice run with Level the
+// volume on. Its sound waits for the word timing, which says where each speaker's line is.
+export function linesLevelled(config) {
+    return usesVoices(config) && usesLoudness(config) && config.sources.audio === "generate";
+}
+// What levelling line by line adds to a recipe that plays the sound: it waits for the word
+// timing. No fingerprint value: the levelling follows from the narration and its timing, which
+// the recipe already carries, so a project made before it (and the bundled samples) keeps its
+// files, and whatever is rendered from now on is levelled. A change to how lines are levelled
+// (`withinLu`) is the time to add one, and to rebuild the samples.
+export function linePlan(context, timing) {
+    if (!linesLevelled(context.config) || timing === undefined)
+        return { values: [], keys: [] };
+    return { values: [], keys: [timing.key] };
+}

package/dist/slices/rebuild/runtime-export.js

@@ -11,10 +11,12 @@ import { runFfmpeg } from "../video/ffmpeg.js";
 import { planRender } from "../video/plan.js";
 import { renderSlideshow } from "../video/slideshow.js";
 import { writePortraits } from "../voices/portraits.js";
+import { linesLevelled } from "./recipe-lines.js";
 import { exportBed } from "./runtime-export-bed.js";
 import { exportEdit } from "./runtime-export-edit.js";
 import { exportSnapshot, retainedOutput, revisionAudio, } from "./runtime-export-inputs.js";
 import { executeShortExport } from "./runtime-export-short.js";
+import { lineLevelledAudio } from "./runtime-lines.js";
 import { preparedResult, preparedText, publishResult } from "./runtime-publication.js";
 export async function executeExportRecipe(deps, context, piece) {
     if (deps.db
@@ -38,7 +40,15 @@ export async function executeExportRecipe(deps, context, piece) {
     const pending = allocateAsset(deps, context.work.projectId, filename);
     const prepared = [];
     let directory;
+    // A multi-voice run's body narration levelled line by line (`runtime-lines.ts`), here
+    // until the export is written.
+    const linesDirectory = linesLevelled(view.revision.config)
+        ? mkdtempSync(join(projectDir(deps.paths, context.work.projectId), "lines-"))
+        : undefined;
     try {
+        const sound = linesDirectory === undefined
+            ? audio
+            : await lineLevelledAudio(deps, context, view, audio, linesDirectory);
         const captions = snapshot.view.outputs.filter((row) => row.selected && row.available && row.state === "ready" && row.workKey === "subtitles:files");
         const burn = !wav && view.revision.config.subtitles?.mode === "burn-in";
         if (burn)
@@ -54,7 +64,7 @@ export async function executeExportRecipe(deps, context, piece) {
                 : "off";
         const config = view.revision.config;
         const segment = (kind) => {
-            const row = audio.find((one) => one.kind === kind);
+            const row = sound.find((one) => one.kind === kind);
             return row?.path === null || row === undefined
                 ? undefined
                 : { path: row.path, seconds: row.seconds };
@@ -125,7 +135,7 @@ export async function executeExportRecipe(deps, context, piece) {
             try {
                 await runFfmpeg({
                     bin: deps.ffmpeg,
-                    args: audioExportArgs(audio, mixed),
+                    args: audioExportArgs(sound, mixed),
                     signal: context.signal,
                     log: deps.log,
                     onProgress,
@@ -201,6 +211,8 @@ export async function executeExportRecipe(deps, context, piece) {
         discardPreparedAssets(deps, [pending, ...prepared.map((one) => one.asset)]);
         if (directory !== undefined)
             rmSync(directory, { recursive: true, force: true });
+        if (linesDirectory !== undefined)
+            rmSync(linesDirectory, { recursive: true, force: true });
     }
 }
 // The project's images in slideshow order, as files.

package/dist/slices/rebuild/runtime-lines.js

@@ -0,0 +1,36 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { levelLines } from "../loudness/line-level.js";
+import { outputPath } from "../storage/layout.js";
+import { linesLevelled } from "./recipe-lines.js";
+import { wordsSchema } from "./runtime-subtitles.js";
+// The sound a multi-voice run plays, with its body narration levelled line by line
+// (`loudness/line-level.ts`) into `directory`, for the video, the audio export and the audio
+// files alike. The words are timed on the timeline these segments lay out, so the body starts
+// at the seconds of the segments before it. Anything else plays as it was.
+export async function lineLevelledAudio(deps, context, view, audio, directory) {
+    if (!linesLevelled(view.revision.config))
+        return audio;
+    const timing = view.outputs.find((row) => row.selected &&
+        row.available &&
+        row.state === "ready" &&
+        row.workKey === "subtitles:timing" &&
+        row.output.role === "subtitle_words");
+    if (timing === undefined)
+        throw new Error("The narration's word timing, which evens out the speakers' volume, is missing. Use More → Render the video again in the Video section, then Try again.");
+    const { words } = wordsSchema.parse(JSON.parse(readFileSync(outputPath(deps.paths, context.work.projectId, timing.output.path), "utf8")));
+    const run = { bin: deps.ffmpeg, log: deps.log, signal: context.signal };
+    const levelled = [];
+    let offset = 0;
+    for (const segment of audio) {
+        if (segment.kind === "body" && segment.path !== null) {
+            const target = join(directory, "body-lines.wav");
+            const done = await levelLines(run, segment.path, target, words, offset);
+            levelled.push(done ? { ...segment, path: target } : segment);
+        }
+        else
+            levelled.push(segment);
+        offset += segment.seconds;
+    }
+    return levelled;
+}

package/dist/slices/rebuild/runtime-subtitles.js

@@ -283,9 +283,12 @@ export function describeMismatch(chunks, segment, mismatch) {
     const expected = mismatch.expected === "" ? "the end of the text" : `"${mismatch.expected}…"`;
     const heard = mismatch.heard === "" ? "no more speech" : `"${mismatch.heard.toLowerCase()}…"`;
     const fix = chunk === undefined
-        ? "Check that part of the narration, regenerate it in Edit project → Narration, then Continue the run."
-        : `In Edit project → Narration, regenerate narration chunk ${String(at + 1)}, then Continue the run.`;
-    return `Subtitles stopped matching the audio at ${where}. The text expected ${expected} but the audio has ${heard} The recording there probably skips or changes words. ${fix}`;
+        ? `Listen at ${clock(mismatch.at)}: if words are missing or wrong, regenerate that part in Edit project → Narration, then Continue the run.`
+        : `Listen at ${clock(mismatch.at)}: if words are missing or wrong, regenerate narration chunk ${String(at + 1)} in Edit project → Narration, then Continue the run.`;
+    // A voice that reads a year, an abbreviation or a name its own way reads it the same way
+    // again, so a remake would cost a chunk and fail here once more.
+    const same = "If it says them right, only another way (a year, an abbreviation or a name read its own way), regenerating gives the same reading: use Download diagnostics in Settings and report it.";
+    return `Subtitles stopped matching the audio at ${where}. The text expected ${expected} but the audio has ${heard} The recording there probably skips or changes words. ${fix} ${same}`;
 }
 function comparable(text) {
     return text

package/dist/slices/rebuild/runtime-voices.js

@@ -10,6 +10,7 @@ import { runFfmpeg } from "../video/ffmpeg.js";
 import { audioChapters, audioFileArgs, ffmetadata } from "../voices/audio-files.js";
 import { turnStarts } from "../voices/timing.js";
 import { exportSnapshot, revisionAudio } from "./runtime-export-inputs.js";
+import { lineLevelledAudio } from "./runtime-lines.js";
 import { preparedResult, publishResult } from "./runtime-publication.js";
 import { wordsSchema } from "./runtime-subtitles.js";
 // The listening files of a multi-voice run: the MP3 and the M4B of the narration timeline,
@@ -64,9 +65,11 @@ export async function executeVoicesRecipe(deps, context, piece) {
         let sound = audio;
         if (goal !== undefined) {
             const mixed = join(directory, "mix.wav");
+            // A multi-voice run's speakers levelled line by line first (`runtime-lines.ts`).
+            const levelled = await lineLevelledAudio(deps, context, view, audio, directory);
             await runFfmpeg({
                 bin: deps.ffmpeg,
-                args: audioExportArgs(audio, mixed),
+                args: audioExportArgs(levelled, mixed),
                 signal: context.signal,
                 log: deps.log,
                 onProgress: () => { },

package/dist/tutorials/Editing-a-Project.md

@@ -68,14 +68,14 @@ When the project was narrated as one whole request (Chunking set to the whole ar
 | **Replace image N** | Uses your own picture in its place. |
 | **Move image N earlier** / **later** | Changes the order. |
 | **Delete image N** | Removes it. Deleting the last image also turns Images and Video off. |
-| **Regenerate image N after review** | Draws the image again from its prompt, one paid image call, with a new result. The current image stays until the new one is made. |
+| **Regenerate image N** | Marks the image to be drawn again from its prompt, one paid image call, with a new result, when you save. The image says it is marked, and **Keep image N** takes the mark off. The current image stays until the new one is made. |
 | **Add generated image** | Adds a new image with an empty prompt at the end. |
 | **Add provided image** | Adds your own picture at the end. |
 | **Add a video clip** | Adds a clip (MP4, MOV, M4V, WebM or MKV). It plays muted in an image's place, trimmed, slowed (to half speed at most) or looped to fit. |
 
 A project holds at most 60 images, or 240 with **More images for long videos** on.
 
-The **Regenerate** button on an image in the project's Images section does the same thing: it opens Edit project with the change applied to the draft, and saving marks the image outdated.
+The **Regenerate** button on an image in the project's Images section, and **Regenerate all** beside Download all, do it without the settings: they ask once, then make the new images straight away. The video keeps the old images, marked outdated, until you remake it, so you can regenerate several images and render the video once. If the settings have unsaved changes of their own, the images are marked there instead, to go with them when you save.
 
 ### Image prompts and More images for long videos
 

package/dist/tutorials/Play-Narration.md

@@ -61,7 +61,7 @@ Has the text model add delivery directions and sounds, such as a sigh or a laugh
 | --- | --- | --- |
 | **Narration Preparation** | Pick a narration prompt from the Library, or **Off**. One text-model call per narration chunk and per intro or outro entry. | Off |
 
-It needs the Inworld TTS-2 model. With another model, the field says "Choose Inworld TTS-2 or turn preparation Off." With several speakers it works per speaker: each turn of a speaker on Inworld TTS-2 is prepared on its own, with the speaker's name and role, so every voice gets its own cues. At least one speaker must use TTS-2; turns of speakers on other voices are spoken as written. See [Multiple Voices](Multiple-Voices). When preparation is on, the row offers **Choose text generation under Article** to jump to the text model.
+It needs the Inworld TTS-2 model. With another model, the field says "Choose Inworld TTS-2 or turn preparation Off." With several speakers it works per speaker: each turn of a speaker on Inworld TTS-2 is prepared on its own, with the speaker's name and role, so every voice gets its own cues. At least one speaker must use TTS-2; turns of speakers on other voices are spoken as written. See [Multiple Voices](Multiple-Voices). Preparation is written by the text model: when nothing earlier needs one (a pasted article, say), **Text generation** appears in this row.
 
 ### Pronunciation Glossary
 

package/dist/tutorials/Play-Overview.md

@@ -104,7 +104,7 @@ If you have the same draft open in another tab or window and it was saved there,
 | Row | What it holds | Details |
 | --- | --- | --- |
 | **Title and keywords** | The title pattern and every keyword value | This page |
-| **Article** | Article source, article prompt, text generation (LLM, model, thinking), research | [Play Title and Article](Play-Title-and-Article) |
+| **Article** | Article source, article prompt, text generation (LLM, model, thinking) when the article or research is written, research | [Play Title and Article](Play-Title-and-Article) |
 | **Narration** | Narration source, TTS, model, voice, speakers, Audio Advanced (chunking, intro, outro, preparation, glossary, aliases, tables and figures) | [Play Narration](Play-Narration) |
 | **Images** | Images source, provider, model, effort, image prompts, establishing image, more images for long videos | [Play Images](Play-Images) |
 | **Video and style** | Video source, seconds per image, zoom, motion, cuts, the Look, ambient sound, pauses and volume, silence, frame format, captions, preview text | [Play Video and Style](Play-Video-and-Style) |

package/dist/tutorials/Play-Title-and-Article.md

@@ -52,7 +52,7 @@ Include everything that should be read, headings too. Headings become chapters.
 
 One text model writes everything this run needs in words: the article, the research, the thumbnail's image prompt, intro and outro entries set to LLM, Narration Preparation, table and figure descriptions, the YouTube description and picking shorts. Each is a separate call, counted in usage.
 
-The **Text generation** section appears under the Article row whenever the run needs a text model. **Settings** beside it opens Settings, where you set the default for new drafts.
+The **Text generation** section appears whenever the run needs a text model, in the row of the first thing that needs it, and its line says what it is used for. It is under **Article** when the article or research is written for you; under **Narration** when only the narration needs it, such as an audiobook whose speakers are worked out from a book you pasted; and under **Outputs** when only the YouTube description, the shorts or the thumbnail prompt need it. There is one text model per run, wherever it shows. **Settings** beside it opens Settings, where you set the default for new drafts.
 
 | Option | What it does | Default |
 | --- | --- | --- |

package/dist/tutorials/Project-Page.md

@@ -109,9 +109,9 @@ A section for a stage that is switched off says "*Article* is off for this run."
 
 ### Re-run a whole stage
 
-Each stage section has its own **More actions for ...** menu (the three dots in the section head) with the rare, whole-stage actions:
+Each stage section's head has a button for making that whole stage again, named for what it makes:
 
-| Menu item | What it does |
+| Button | What it does |
 | --- | --- |
 | **Research again** | Fresh research, then the affected article, narration, thumbnail and exports. |
 | **Write the article again** | A fresh article, then the affected narration, thumbnail and exports. |