@gentbajko/slopify 0.1.0

package/dist/slices/narration/concat.js

@@ -0,0 +1,79 @@
+import { copyFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { probeDurationMs, runFfmpeg } from "../video/ffmpeg.js";
+// The concat demuxer's script format. A path is single-quoted, and the one character that
+// can end the quoting is spelled out, so a folder with an apostrophe in it cannot become
+// two arguments. A quoted line can also never be read as the `#` comment the format has.
+export function concatListText(files) {
+    return `${files.map((file) => `file '${file.replaceAll("'", "'\\''")}'`).join("\n")}\n`;
+}
+export function concatArgs(listPath, output) {
+    return [
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        "-nostats",
+        "-y",
+        "-f",
+        "concat",
+        // The script names absolute paths this app built, never anything a user typed.
+        "-safe",
+        "0",
+        "-i",
+        listPath,
+        // Only the audio: a provider that ships cover art in its mp3 would otherwise put a
+        // video stream in the narration.
+        "-map",
+        "0:a:0",
+        // Re-encoded rather than stream-copied. A copy joins frame runs that each carry their
+        // own encoder delay and padding, which is the click and the drift at every join:
+        // three chunks of 1200, 700 and 450 ms copy to 2409 ms and decode to 2350 ms through
+        // here, exactly the sum. §Q68 hands that number to the video timeline, so it has to
+        // be the real one. No `-ar`: §Q65 keeps the provider's own sample rate.
+        // ceiling: one re-encode at the bitrate the adapters ask the providers for. Storing
+        // the chunks as wav and encoding once at the end would avoid even that generation,
+        // and costs about ten times the disk while a stage is running.
+        "-c:a",
+        "libmp3lame",
+        "-b:a",
+        "128k",
+        output,
+    ];
+}
+// The body audio and its measured duration. §Q68: the duration is measured, never
+// estimated, because `logic/11` builds the video timeline out of it.
+export async function joinNarration(deps, input) {
+    const first = input.files[0];
+    if (first === undefined) {
+        // The stage refuses an empty narration before it gets here (§Q67), so this is a bug.
+        throw new Error("there are no audio chunks to join");
+    }
+    mkdirSync(dirname(input.output), { recursive: true, mode: 0o700 });
+    if (input.files.length === 1) {
+        // 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();
+        copyFileSync(first, input.output);
+    }
+    else {
+        mkdirSync(dirname(input.listPath), { recursive: true, mode: 0o700 });
+        writeFileSync(input.listPath, concatListText(input.files), { mode: 0o600 });
+        try {
+            await runFfmpeg({
+                bin: deps.bin,
+                args: concatArgs(input.listPath, input.output),
+                signal: input.signal,
+                log: deps.log,
+                onProgress: () => { },
+            });
+        }
+        finally {
+            rmSync(input.listPath, { force: true });
+        }
+    }
+    // Measured off a full decode of the file that was written, not off the parts: a
+    // container header can carry an estimate, and `logic/11` step 1 adds this number to the
+    // gaps to get the length of the video.
+    return probeDurationMs(deps.bin, input.output, input.signal, deps.log);
+}

package/dist/slices/narration/run.js

@@ -0,0 +1,280 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { insertPiece, piecesOf, setPiece } from "../../kernel/runner/piece-repo.js";
+import { entryModes } from "../admission/model.js";
+import { projectById, setStageProgress, stagesOf } from "../admission/repo.js";
+import { entryCategories } from "../library/model.js";
+import { outputFileName, outputPath } from "../storage/layout.js";
+import { insertOutput, outputsOf } from "../storage/repo.js";
+import { probeDurationMs } from "../video/ffmpeg.js";
+import { chunkNarration, defaultChunking } from "./chunk.js";
+import { joinNarration } from "./concat.js";
+// §Q67, verbatim: an empty narration source is an "immediate stage failure 'nothing to
+// narrate', no retries". Thrown from the slice rather than from a provider call, so the
+// attempt wrapper never sees it and nothing is retried.
+export const nothingToNarrate = "nothing to narrate";
+// What a chunk piece carries between runs: the text that was sent, and the file it came
+// back as once the provider answered. That is the whole of the resume of §Q66.
+const chunkPayload = z.object({ text: z.string(), file: z.string().optional() });
+// What the article stage left on its `segment` pieces (`logic/07` step 5).
+const segmentPayload = z.object({
+    category: z.enum(entryCategories),
+    name: z.string(),
+    mode: z.enum(entryModes),
+    text: z.string(),
+});
+// The chunk audio sits in a folder of its own under the project. It is not an output:
+// §Q65's invariant makes the concatenated body plus the picked intro and outro "the
+// project's only audio outputs", so the pieces name these files and the boot reconcile
+// keeps them by that name (`slices/storage/reconcile.ts`).
+const chunkDir = "audio-chunks";
+export async function runNarration(deps, context, providers) {
+    const { projectId } = context.stage;
+    const project = projectById(deps.db, projectId);
+    if (project === undefined) {
+        throw new Error(`project ${projectId} has no row`);
+    }
+    const choice = project.config.audio;
+    if (choice === undefined) {
+        // Admission refuses a run whose audio is Generate without a provider and a voice
+        // (`logic/04`), so reaching here is a bug in admission rather than something the user
+        // did.
+        throw new Error("the run has no TTS provider or voice");
+    }
+    // Read once, before anything is written: the segment steps below ask it what a previous
+    // run already stored, and the body step is the only thing that adds to it.
+    const outputs = outputsOf(deps.db, projectId);
+    // Step 2. The end matter is already out of this text: the article stage cut it into
+    // files of its own (§Q63, `logic/07` step 4), so nothing here can narrate a sources list.
+    const chunking = project.config.chunking ?? defaultChunking;
+    const texts = chunkNarration(narrationSource(deps, outputs, projectId), chunking);
+    if (texts.length === 0) {
+        throw new Error(nothingToNarrate);
+    }
+    const files = await speakChunks(deps, context, providers, choice, plan(deps, context, texts));
+    await storeBody(deps, context, choice, files, outputs);
+    await speakSegments(deps, context, providers, choice, outputs);
+    deps.log.write("info", "narration.done", {
+        projectId,
+        stage: "audio",
+        detail: `${String(texts.length)} chunks in ${chunking.mode} mode`,
+    });
+}
+// The narration source of §Q37 and `logic/07` step 4: the plain-text article, written by
+// the article stage or pasted in by a user whose article stage was set to Provide.
+function narrationSource(deps, outputs, projectId) {
+    const article = outputs.find((output) => output.role === "article_txt");
+    if (article === undefined) {
+        throw new Error(nothingToNarrate);
+    }
+    return readFileSync(outputPath(deps.paths, projectId, article.path), "utf8");
+}
+// The chunk list, planned once and kept. A retry after a failure finds the rows the first
+// run wrote and narrates only the ones that did not finish (§Q66).
+function plan(deps, context, texts) {
+    const existing = piecesOf(deps.db, context.stage.id, "chunk");
+    if (existing.length > 0) {
+        return existing;
+    }
+    const planned = texts.map((text, index) => ({
+        id: deps.ids.next(),
+        stageId: context.stage.id,
+        kind: "chunk",
+        idx: index + 1,
+        state: "pending",
+        payload: JSON.stringify({ text }),
+    }));
+    transact(deps.db, () => {
+        for (const piece of planned) {
+            insertPiece(deps.db, piece);
+        }
+    });
+    return planned;
+}
+// Step 3: "Synthesize every chunk in parallel". §Q66: a chunk a previous run finished is
+// not spoken again, and one that fails fails the whole stage while its siblings finish
+// and keep their audio for the next resume.
+async function speakChunks(deps, context, providers, choice, pieces) {
+    const { projectId } = context.stage;
+    const total = pieces.length;
+    let done = pieces.filter((piece) => finished(deps, projectId, piece)).length;
+    report(deps, context, done, total);
+    const outcomes = await Promise.all(pieces.map(async (piece) => {
+        const carried = chunkOf(piece);
+        const kept = finished(deps, projectId, piece);
+        if (kept !== undefined) {
+            return { ok: true, file: kept };
+        }
+        const file = `${chunkDir}/${String(piece.idx).padStart(3, "0")}.mp3`;
+        setPiece(deps.db, piece.id, "running", piece.payload);
+        try {
+            const spoken = await providers.forPiece(piece.id).tts({
+                provider: choice.provider,
+                voiceId: choice.voice,
+                text: carried.text,
+            });
+            write(deps, projectId, file, spoken.bytes);
+            // The file is on disk before the row says so: a crash between the two leaves a
+            // file the reconcile collects, where the other order would leave a `done` chunk
+            // whose audio never existed and a concat that fails on every retry.
+            setPiece(deps.db, piece.id, "done", JSON.stringify({ text: carried.text, file }));
+            done += 1;
+            report(deps, context, done, total);
+            return { ok: true, file };
+        }
+        catch (error) {
+            // A cancel is not this chunk failing: `logic/13` §Q112 counts an aborted call as
+            // nothing, and the resume runs a `pending` chunk exactly as a failed one.
+            setPiece(deps.db, piece.id, context.signal.aborted ? "pending" : "failed", piece.payload);
+            return { ok: false, error };
+        }
+    }));
+    const files = [];
+    for (const outcome of outcomes) {
+        if (!outcome.ok) {
+            throw outcome.error;
+        }
+        files.push(outcome.file);
+    }
+    return files;
+}
+// Steps 4 and 6: one body file, in chunk order, with its measured duration on the row.
+async function storeBody(deps, context, choice, files, outputs) {
+    const { projectId } = context.stage;
+    if (outputs.some((output) => output.role === "audio_body")) {
+        // A retry that failed on a segment last time: the body is already joined and measured,
+        // and joining it again would insert a second row for the same file.
+        return;
+    }
+    const name = outputFileName("audio_body", 1, ".mp3", "audio");
+    const durationMs = await joinNarration({ bin: deps.ffmpeg, log: deps.log }, {
+        files: files.map((file) => outputPath(deps.paths, projectId, file)),
+        listPath: outputPath(deps.paths, projectId, `${chunkDir}/concat.txt`),
+        output: outputPath(deps.paths, projectId, name),
+        signal: context.signal,
+    });
+    // `logic/13` §Q113 protects an output already stored, not one about to be: a cancel
+    // landing between ffmpeg exiting and the row below leaves nothing recorded.
+    context.signal.throwIfAborted();
+    store(deps, projectId, "audio_body", name, durationMs, choice);
+    counted(deps, "body", durationMs, choice);
+}
+// Step 5: "each picked segment's text is one TTS request with the same provider and
+// voice, stored as its own audio file with its duration; body chunking does not apply to
+// them" (§Q93). The text is whatever the article stage wrote onto the segment piece: an
+// LLM-mode entry's answer, or a text-mode entry's rendered body, spoken verbatim.
+async function speakSegments(deps, context, providers, choice, outputs) {
+    const { projectId } = context.stage;
+    for (const piece of segmentPieces(deps, projectId)) {
+        const segment = segmentOf(piece);
+        const role = segment.category === "intro" ? "audio_intro" : "audio_outro";
+        if (outputs.some((output) => output.role === role)) {
+            // Spoken by a previous run of this stage; §Q66's resume keeps it.
+            continue;
+        }
+        const text = segment.text.trim();
+        if (text === "") {
+            // §Q67's rule, applied to a segment: there is nothing to say, and silently dropping
+            // an intro the user picked would lose it without telling anyone.
+            throw new Error(`the ${segment.category} segment has ${nothingToNarrate}`);
+        }
+        const spoken = await providers.forPiece(piece.id).tts({
+            provider: choice.provider,
+            voiceId: choice.voice,
+            text,
+        });
+        const name = outputFileName(role, 1, ".mp3", "audio");
+        write(deps, projectId, name, spoken.bytes);
+        // Measured the same way the body is, because `logic/11` step 1 adds all three and the
+        // gaps to get the length of the video (§Q68).
+        const durationMs = await probeDurationMs(deps.ffmpeg, outputPath(deps.paths, projectId, name), context.signal, deps.log);
+        context.signal.throwIfAborted();
+        store(deps, projectId, role, name, durationMs, choice);
+        counted(deps, segment.category, durationMs, choice);
+    }
+}
+// The segment pieces belong to the *article* stage, which is where `logic/07` step 5
+// writes them, so they are read under its id and never under this stage's own. They stay
+// there because `logic/12` is what depends on it: a Re-run audio (step 2) and the audio
+// re-run an article edit cascades into (step 1) both clear the audio stage's pieces, and
+// only the article stage ever writes an entry text - so an intro kept on this stage's row
+// would be thrown away by the first re-narration and never written again.
+function segmentPieces(deps, projectId) {
+    const article = stagesOf(deps.db, projectId).find((stage) => stage.kind === "article");
+    if (article === undefined) {
+        // Admission writes all six stage rows with the project (`logic/04` step 6), so a
+        // project without an article stage is a bug rather than a run the user configured.
+        throw new Error(`project ${projectId} has no article stage`);
+    }
+    return piecesOf(deps.db, article.id, "segment");
+}
+// logic/16 step 3: "audio seconds from the measured duration per segment". The measured
+// one, not the text's length: `logic/08` §Q68 puts the real duration on the row and
+// `logic/11` builds the timeline from it. No model is named because the TTS port carries
+// none - the same reason `store` above leaves it off the output row.
+function counted(deps, segment, durationMs, choice) {
+    deps.count("stage.completed", {
+        stage: "audio",
+        segment,
+        provider: choice.provider,
+        audioSeconds: durationMs / 1000,
+    });
+}
+// Step 5: "k of N chunks narrated". Written as well as emitted, so a page opened mid-stage
+// reads the count off the row rather than waiting for the next chunk.
+function report(deps, context, done, total) {
+    setStageProgress(deps.db, context.stage.id, done, total);
+    context.emit({
+        type: "stage.progress",
+        projectId: context.stage.projectId,
+        stage: "audio",
+        current: done,
+        total,
+    });
+}
+// A chunk counts as finished only when its audio is still on disk: the row and the file
+// are written one after the other, and the boot reconcile can remove a file whose row
+// survived. Answering "done" for a missing file would fail the concat instead.
+function finished(deps, projectId, piece) {
+    const file = chunkOf(piece).file;
+    if (file === undefined) {
+        return undefined;
+    }
+    return existsSync(outputPath(deps.paths, projectId, file)) ? file : undefined;
+}
+function write(deps, projectId, path, bytes) {
+    const target = outputPath(deps.paths, projectId, path);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, bytes, { mode: 0o600 });
+}
+// §Q68: the provider and the voice are stored with the audio they made. The model is not:
+// the TTS port carries no model, so every request went to the adapter's own, and writing
+// the run's dropdown value here would record something that was never sent.
+function store(deps, projectId, role, path, durationMs, choice) {
+    insertOutput(deps.db, {
+        id: deps.ids.next(),
+        projectId,
+        stageKind: "audio",
+        role,
+        path,
+        originalFilename: null,
+        bytes: statSync(outputPath(deps.paths, projectId, path)).size,
+        durationMs,
+        meta: { provider: choice.provider, voice: choice.voice },
+        createdAt: deps.clock.now().toISOString(),
+    });
+}
+function chunkOf(piece) {
+    if (piece.payload === null) {
+        throw new Error(`chunk ${piece.id} has no payload`);
+    }
+    return chunkPayload.parse(JSON.parse(piece.payload));
+}
+function segmentOf(piece) {
+    if (piece.payload === null) {
+        throw new Error(`segment ${piece.id} has no payload`);
+    }
+    return segmentPayload.parse(JSON.parse(piece.payload));
+}

package/dist/slices/reruns/cascade.js

@@ -0,0 +1,66 @@
+import { stageKinds } from "../../kernel/pipeline.js";
+import { deps as graph } from "../../kernel/runner/graph.js";
+// The stages to redo, in pipeline order, each with how much of itself it throws away.
+export function redoPlan(input) {
+    const stale = staleStages(input);
+    return stageKinds
+        .filter((kind) => stale.has(kind) && redoable(stateOf(input.stages, kind)))
+        .map((kind) => ({ stage: kind, clears: clearsOf(input.action, kind) }));
+}
+function staleStages(input) {
+    const { action } = input;
+    switch (action.kind) {
+        case "rerun":
+            return withDependents([action.stage]);
+        case "article-edit": {
+            // §Q101, in its own words: "audio, LLM-mode intro/outro text, LLM-written
+            // thumbnail, and video re-run; prompt-based images are untouched". The video comes
+            // along as a dependent of the audio, so it is never named here.
+            const roots = ["audio"];
+            if (input.thumbnailSource === "prompt_by_llm") {
+                roots.push("thumbnail");
+            }
+            return withDependents(roots);
+        }
+        case "image-deleted":
+            // Step 5: the image is "removed from the set; video re-renders". The remaining
+            // images stand, so the images stage itself is not redone.
+            return withDependents(["video"]);
+        case "image-regenerated":
+            return withDependents(["images"]);
+    }
+}
+// `logic/01` forbids `provided` → `running` and `skipped` → `running`, so a stage whose
+// output the user supplied or switched off is stepped over. The walk above still passes
+// through it: re-running the article with a provided audio must reach the video.
+function redoable(state) {
+    return state !== "provided" && state !== "skipped";
+}
+function clearsOf(action, kind) {
+    // §Q106: "the previous video stays downloadable until the new render finishes". Clearing
+    // the video's outputs here would take it away the moment the user pressed Re-render - or
+    // for the whole of a re-narration, when the video comes along as a dependent. It is kept
+    // instead, and `slices/video/run.ts` replaces the file and the rows in one swap once
+    // ffmpeg has exited cleanly. A render that fails or is canceled leaves the old one
+    // standing, which is exactly what §Q106 promises.
+    if (kind === "video") {
+        return "nothing";
+    }
+    return action.kind === "image-regenerated" && kind === "images" ? "nothing" : "all";
+}
+// The transitive closure of the dependents of `roots` over `kernel/runner/graph.ts`. The
+// graph has six nodes, so one pass per node closes it whatever the edges are.
+function withDependents(roots) {
+    const found = new Set(roots);
+    for (let pass = 0; pass < stageKinds.length; pass += 1) {
+        for (const kind of stageKinds) {
+            if (graph[kind].some((dependency) => found.has(dependency))) {
+                found.add(kind);
+            }
+        }
+    }
+    return found;
+}
+function stateOf(stages, kind) {
+    return stages.find((stage) => stage.kind === kind)?.state ?? "pending";
+}