@gentbajko/slopify 0.1.0

package/dist/slices/telemetry/usage.js

@@ -0,0 +1,82 @@
+export function usageOf(input) {
+    return {
+        machineId: input.machineId,
+        appVersion: input.appVersion,
+        counters: counters(input.events),
+        byStage: byStage(input.events),
+    };
+}
+function counters(events) {
+    let videosMade = 0;
+    let audioSeconds = 0;
+    let imagesMade = 0;
+    let tokensUsed = 0;
+    let projects = 0;
+    for (const event of events) {
+        if (event.type === "project.created") {
+            projects += 1;
+        }
+        // One event per completed render (logic/16 step 3), which is the same rule the
+        // collector counts `videos_made` by, so the local page and the public board agree.
+        if (event.payload.stage === "video") {
+            videosMade += 1;
+        }
+        audioSeconds += event.payload.audioSeconds ?? 0;
+        imagesMade += event.payload.images ?? 0;
+        tokensUsed += (event.payload.tokensIn ?? 0) + (event.payload.tokensOut ?? 0);
+    }
+    return { videosMade, audioSeconds, imagesMade, tokensUsed, projects };
+}
+// §Q128 counts tokens "with provider and model names, per stage", so the table groups by
+// all three. Rows with no tokens are left out: the table's two number columns would both
+// read zero, and the render and the image calls that produce them report no usage at all.
+//
+// ceiling: this is a per-stage table, not a per-model one. The user deferred the per-model
+// breakdown on the public counters on 2026-09-03; the payload already carries the provider
+// and the model, so it stays a grouping change when it is asked for.
+function byStage(events) {
+    const rows = new Map();
+    for (const event of events) {
+        const row = tokensOf(event.payload);
+        if (row === undefined) {
+            continue;
+        }
+        // JSON rather than a joined string: a model id is the provider's own and may hold
+        // any character, and two different rows must never collide into one.
+        const key = JSON.stringify([row.stage, row.provider, row.model]);
+        const seen = rows.get(key);
+        rows.set(key, seen === undefined
+            ? row
+            : {
+                ...seen,
+                tokensIn: seen.tokensIn + row.tokensIn,
+                tokensOut: seen.tokensOut + row.tokensOut,
+            });
+    }
+    // Sorted by tokens out, as the screen asks. The tiebreaks below it are there so the same
+    // log always produces the same table: a rundown that reshuffles between reads is
+    // unreadable, and Map insertion order would follow whichever stage happened to finish
+    // first in a fan-out.
+    return [...rows.values()].toSorted((left, right) => right.tokensOut - left.tokensOut ||
+        right.tokensIn - left.tokensIn ||
+        left.stage.localeCompare(right.stage) ||
+        left.provider.localeCompare(right.provider) ||
+        (left.model ?? "").localeCompare(right.model ?? ""));
+}
+function tokensOf(payload) {
+    const tokensIn = payload.tokensIn ?? 0;
+    const tokensOut = payload.tokensOut ?? 0;
+    if (payload.stage === undefined || payload.provider === undefined) {
+        return undefined;
+    }
+    if (tokensIn + tokensOut === 0) {
+        return undefined;
+    }
+    return {
+        stage: payload.stage,
+        provider: payload.provider,
+        model: payload.model ?? null,
+        tokensIn,
+        tokensOut,
+    };
+}

package/dist/slices/thumbnail/by-llm.js

@@ -0,0 +1,30 @@
+export function thumbnailMessages(brief) {
+    const values = Object.entries(brief.values);
+    return [
+        {
+            role: "user",
+            content: [
+                brief.instruction,
+                "",
+                `Video title: ${brief.title}`,
+                "",
+                "Keyword values for this run:",
+                "",
+                values.length === 0
+                    ? "(none)"
+                    : values.map(([name, value]) => `${name}: ${value}`).join("\n"),
+                "",
+                `Aspect ratio of the thumbnail: ${brief.format}`,
+                "",
+                "The article this video narrates:",
+                "",
+                brief.article,
+            ].join("\n"),
+        },
+    ];
+}
+// §Q82: "empty output is a failed attempt". Returned as the sentence the stage would show
+// rather than thrown, because the wrapper's `check` hook is what makes it a retry.
+export function writtenPrompt(text) {
+    return text.trim() === "" ? "the LLM wrote no thumbnail prompt" : undefined;
+}

package/dist/slices/thumbnail/run.js

@@ -0,0 +1,200 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { insertPiece, piecesOf, setPiece } from "../../kernel/runner/piece-repo.js";
+import { projectById } from "../admission/repo.js";
+import { outputFileName, outputPath } from "../storage/layout.js";
+import { insertOutput, outputsOf } from "../storage/repo.js";
+import { storeText } from "../storage/staging.js";
+import { noTokens, plusUsage } from "../telemetry/model.js";
+import { thumbnailMessages, writtenPrompt } from "./by-llm.js";
+// The `prompt_written` sub-step of §Q82, persisted for resume: the prompt the LLM wrote
+// and the messages that asked for it, so a resumed run reproduces the record without
+// asking again.
+const writtenPayload = z.object({ prompt: z.string(), sent: z.string() });
+export async function runThumbnail(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 source = project.config.sources.thumbnail;
+    if (source !== "from_prompt" && source !== "prompt_by_llm") {
+        // Off is `skipped` and Provide is `provided` at project creation (`logic/01` step 1),
+        // so the runner never starts this stage for either.
+        throw new Error(`the thumbnail stage cannot run with its source set to ${source}`);
+    }
+    const choice = project.config.images;
+    if (choice === undefined) {
+        // Admission requires the image provider whenever the thumbnail is generated
+        // (`logic/04` step 2), so reaching here is a bug in admission rather than the user's.
+        throw new Error("the run has no image provider or model");
+    }
+    const written = source === "from_prompt" ? undefined : await byLlm(deps, context, providers, project);
+    const prompt = written?.prompt ?? fromTemplate(project);
+    await make(deps, context, providers, project, choice, prompt);
+    // logic/16 step 3 counts tokens "with provider and model names, per stage", and a
+    // payload names one provider. This stage can use two - the LLM that writes the prompt
+    // (`logic/10`) and the image model that draws it - so the event names the one whose
+    // usage it reports, because provider and model are shown beside the token columns on
+    // the Usage page. A thumbnail from a picked template makes no LLM call, so it names the
+    // image model that made it and reports the zero of step 3.
+    deps.count("stage.completed", {
+        stage: "thumbnail",
+        provider: written?.provider ?? choice.provider,
+        model: written?.model ?? choice.model,
+        ...(written?.tokens ?? noTokens),
+        thumbnails: 1,
+    });
+    deps.log.write("info", "thumbnail.done", {
+        projectId,
+        stage: "thumbnail",
+        detail: source === "from_prompt" ? "from the picked prompt" : "from the prompt the LLM wrote",
+    });
+}
+// `logic/09` step 4: the rendered thumbnail template goes to the image provider as it is.
+function fromTemplate(project) {
+    const rendered = project.config.rendered.thumbnailPrompt;
+    if (rendered === undefined) {
+        throw new Error("the run has no rendered thumbnail prompt");
+    }
+    return rendered;
+}
+// `logic/10` steps 1 to 3. §Q82: a written prompt already on the project is reused, so a
+// manual retry redoes only the image call and the wording the user is looking at does not
+// change under them.
+async function byLlm(deps, context, providers, project) {
+    const kept = piecesOf(deps.db, context.stage.id, "prompt_written")[0];
+    const llm = project.config.llm;
+    if (kept !== undefined && kept.state === "done") {
+        // §Q82: the wording the user is looking at does not change under them. No call was
+        // made, so this run counts none - the run that wrote the prompt already did.
+        return {
+            prompt: payloadOf(kept).prompt,
+            ...(llm === undefined ? {} : named(llm)),
+            tokens: noTokens,
+        };
+    }
+    if (llm === undefined) {
+        // §Q81 makes the LLM row required when the thumbnail source is Prompt by LLM.
+        throw new Error("the run has no LLM provider or model");
+    }
+    const messages = thumbnailMessages(brief(deps, project));
+    const answer = await providers.llm({
+        provider: llm.provider,
+        model: llm.model,
+        messages,
+        // §Q82: an empty answer is a failed attempt, and the wrapper is what retries it.
+        check: (given) => writtenPrompt(given.text),
+    });
+    // Step 3 and §Q83: the image prompt is exactly the LLM's output, never edited by the app.
+    const prompt = answer.text.trim();
+    keepWritten(deps, context, kept?.id, prompt, messages);
+    // The messages sent are stored beside the article stage's, per stage (`logic/14` step 2).
+    storeText(deps, {
+        projectId: context.stage.projectId,
+        stageKind: "thumbnail",
+        role: "instructions",
+        text: instructionsText(messages),
+    });
+    return { prompt, ...named(llm), tokens: plusUsage(noTokens, answer.usage) };
+}
+function named(choice) {
+    return { provider: choice.provider, model: choice.model };
+}
+function brief(deps, project) {
+    const instruction = project.config.rendered.thumbnailPrompt;
+    if (instruction === undefined) {
+        throw new Error("the run has no rendered thumbnail prompt");
+    }
+    return {
+        instruction,
+        title: project.title,
+        values: project.config.values,
+        format: project.format,
+        article: articleText(deps, project.id),
+    };
+}
+// §Q79's invariant: the stage never starts without an article on the project. The runner's
+// graph holds the other half - the thumbnail waits on the article stage - so a project
+// with no article row here is a stage that started against a run that never wrote one.
+function articleText(deps, projectId) {
+    const article = outputsOf(deps.db, projectId).find((output) => output.role === "article_txt");
+    if (article === undefined) {
+        throw new Error("the project has no article for the thumbnail prompt to be written from");
+    }
+    return readFileSync(outputPath(deps.paths, projectId, article.path), "utf8");
+}
+// The one row is keyed by `idx` within the stage, so a stage that runs again replaces what
+// it wrote rather than colliding with it.
+function keepWritten(deps, context, existing, prompt, messages) {
+    const payload = JSON.stringify({ prompt, sent: instructionsText(messages) });
+    if (existing === undefined) {
+        insertPiece(deps.db, {
+            id: deps.ids.next(),
+            stageId: context.stage.id,
+            kind: "prompt_written",
+            idx: 1,
+            state: "done",
+            payload,
+        });
+        return;
+    }
+    setPiece(deps.db, existing, "done", payload);
+}
+// `logic/09` step 4: one call, the same aspect rule as the slideshow, stored apart from it
+// with the prompt text, the provider and the model.
+async function make(deps, context, providers, project, choice, prompt) {
+    const { projectId } = context.stage;
+    if (outputsOf(deps.db, projectId).some((output) => output.role === "thumbnail")) {
+        // §Q82's `image-done` sub-step: a retry that failed after the image landed keeps it.
+        return;
+    }
+    const made = await providers.image({
+        provider: choice.provider,
+        model: choice.model,
+        prompt,
+        aspect: project.format,
+    });
+    const name = outputFileName("thumbnail", 1, made.mime === "image/png" ? ".png" : ".jpg", "thumbnail");
+    write(deps, projectId, name, made);
+    // `logic/13` §Q113 protects an output already stored, not one about to be: a cancel
+    // landing between the write and the row leaves a file the boot reconcile collects.
+    context.signal.throwIfAborted();
+    const output = {
+        id: deps.ids.next(),
+        projectId,
+        stageKind: "thumbnail",
+        role: "thumbnail",
+        path: name,
+        originalFilename: null,
+        bytes: made.bytes.byteLength,
+        durationMs: null,
+        // §Q76 and §Q80. There is no `index`: §Q72 keeps the thumbnail out of the slideshow,
+        // and the render reads that list by role.
+        meta: {
+            promptName: project.config.thumbnailPrompt ?? "",
+            prompt,
+            provider: choice.provider,
+            model: choice.model,
+        },
+        createdAt: deps.clock.now().toISOString(),
+    };
+    // No `image.landed`: §Q72 keeps the thumbnail out of the slideshow, and that event's
+    // `index` is a place in it. The stage reaching `done` is what tells the page.
+    insertOutput(deps.db, output);
+}
+function write(deps, projectId, name, made) {
+    const target = outputPath(deps.paths, projectId, name);
+    mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+    writeFileSync(target, made.bytes, { mode: 0o600 });
+}
+function instructionsText(messages) {
+    return `=== Thumbnail prompt ===\n\n${messages.map((message) => message.content).join("\n\n")}\n`;
+}
+function payloadOf(piece) {
+    if (piece.payload === null) {
+        throw new Error(`the written thumbnail prompt ${piece.id} has no payload`);
+    }
+    return writtenPayload.parse(JSON.parse(piece.payload));
+}

package/dist/slices/video/ffmpeg.js

@@ -0,0 +1,230 @@
+import { spawn } from "node:child_process";
+import { zoomBy, zoomFrom, zoomTo } from "./plan.js";
+// Hand-rolled per the standards: the filtergraph is the load-bearing part of this slice
+// and a wrapper would hide it. Every value goes into an argument array, never a shell
+// string, so a title or a filename cannot become a command.
+// zoompan works on a still that has been pre-scaled, because it steps the zoom in
+// sub-pixel increments and a source at output resolution visibly jitters (logic/11 §Q85
+// asks for a smooth linear zoom). Four times the frame is enough at 115%.
+const prescale = 4;
+const sampleRate = 44100;
+const channelLayout = "stereo";
+// `bundled` is ffmpeg-static's export. It is typed as unknown because the package is
+// CommonJS with `module.exports = <path or null>` while its shipped .d.ts declares an ES
+// default, which node16 resolution cannot map onto one another; narrowing here is
+// cheaper and more honest than overriding someone else's types.
+export function resolveFfmpeg(env, bundled) {
+    const override = env.SLOPIFY_FFMPEG?.trim();
+    if (override !== undefined && override !== "") {
+        return override;
+    }
+    if (typeof bundled === "string" && bundled !== "") {
+        return bundled;
+    }
+    // Never PATH: a Slopify that quietly rendered with whichever ffmpeg the machine
+    // happens to carry would not be testing the binary it ships with.
+    throw new Error("No ffmpeg binary is available. Slopify ships one through ffmpeg-static; if this " +
+        "platform has no build, point SLOPIFY_FFMPEG at an ffmpeg executable.");
+}
+export function renderArgs(plan) {
+    const inputs = [];
+    for (const slot of plan.images) {
+        inputs.push("-i", slot.path);
+    }
+    const audioAt = [];
+    for (const segment of plan.audio) {
+        audioAt.push(plan.images.length + audioAt.length);
+        if (segment.path === null) {
+            inputs.push("-f", "lavfi", "-t", seconds(segment.seconds), "-i", `anullsrc=r=${sampleRate}:cl=${channelLayout}`);
+            continue;
+        }
+        inputs.push("-i", segment.path);
+    }
+    return [
+        "-hide_banner",
+        "-nostdin",
+        "-loglevel",
+        "error",
+        // Progress on stdout keeps stderr free to carry only what went wrong.
+        "-progress",
+        "pipe:1",
+        "-nostats",
+        "-y",
+        ...inputs,
+        "-filter_complex",
+        filterGraph(plan, audioAt),
+        "-map",
+        "[v]",
+        "-map",
+        "[a]",
+        "-c:v",
+        "libx264",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-movflags",
+        "+faststart",
+        plan.output,
+    ];
+}
+function filterGraph(plan, audioAt) {
+    const chains = [];
+    const wide = plan.width * prescale;
+    const tall = plan.height * prescale;
+    plan.images.forEach((slot, at) => {
+        chains.push(`[${at}:v]trim=end_frame=1,setpts=PTS-STARTPTS,` +
+            // logic/11 step 4: cover the frame and centre-crop, never letterbox.
+            `scale=${wide}:${tall}:force_original_aspect_ratio=increase,crop=${wide}:${tall},` +
+            `zoompan=z='${zoomExpression(slot)}':d=${slot.frames}:` +
+            `x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':` +
+            `s=${plan.width}x${plan.height}:fps=${plan.fps},setsar=1[v${at}]`);
+    });
+    chains.push(`${plan.images.map((_slot, at) => `[v${at}]`).join("")}concat=n=${plan.images.length}:v=1:a=0[v]`);
+    audioAt.forEach((input, at) => {
+        // The segments come from different files and the silence from lavfi, so they are
+        // brought to one format before concat, which refuses to join mismatched streams.
+        chains.push(`[${input}:a]aformat=sample_fmts=fltp:sample_rates=${sampleRate}:channel_layouts=${channelLayout}[a${at}]`);
+    });
+    chains.push(`${audioAt.map((_input, at) => `[a${at}]`).join("")}concat=n=${audioAt.length}:v=0:a=1[a]`);
+    return chains.join(";");
+}
+// §Q85: odd images 100% → 115%, even images 115% → 100%, linear over the slot. `on` is
+// zoompan's output frame counter, 0 to d-1, and a one-frame slot has no span to divide
+// by, so it holds the zoom it starts at.
+function zoomExpression(slot) {
+    const span = slot.frames - 1;
+    if (slot.zoom === "in") {
+        return span < 1 ? String(zoomFrom) : `${zoomFrom}+${zoomBy}*on/${span}`;
+    }
+    return span < 1 ? String(zoomTo) : `${zoomTo}-${zoomBy}*on/${span}`;
+}
+function seconds(value) {
+    return value.toFixed(3);
+}
+// ffmpeg's `-progress` writes `out_time_ms` in microseconds, and has since long before
+// it added the correctly named `out_time_us`; both keys carry the same number. Either
+// reads `N/A` until the first frame is muxed.
+const progressKey = /^out_time_(?:us|ms)=(\d+)$/;
+export function progressMsOf(line) {
+    const matched = progressKey.exec(line.trim());
+    const microseconds = matched?.[1];
+    return microseconds === undefined ? undefined : Math.floor(Number(microseconds) / 1000);
+}
+// ceiling: the last 20 lines of stderr are kept. logic/11 §Q89 shows the renderer's error
+// verbatim, and ffmpeg's useful complaint is always at the end of what it wrote.
+const stderrLines = 20;
+export function runFfmpeg(run) {
+    return new Promise((resolve, reject) => {
+        if (run.signal.aborted) {
+            reject(new Error("the render was canceled before it started"));
+            return;
+        }
+        const child = spawn(run.bin, [...run.args], { stdio: ["ignore", "pipe", "pipe"] });
+        const errors = [];
+        let pending = "";
+        // A throw out of a stream listener is an uncaughtException, not a rejection: it would
+        // leave this promise unsettled forever while the child kept writing the output file.
+        // Reporting progress is advisory, so a caller that throws is logged and ignored.
+        const guarded = (what, work) => {
+            try {
+                work();
+            }
+            catch (error) {
+                run.log.write("warn", what, { detail: messageOf(error) });
+            }
+        };
+        const report = (line) => {
+            const elapsed = progressMsOf(line);
+            if (elapsed !== undefined) {
+                guarded("video.progress", () => {
+                    run.onProgress(elapsed);
+                });
+            }
+        };
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            guarded("video.progress.read", () => {
+                pending += chunk;
+                const lines = pending.split("\n");
+                pending = lines.pop() ?? "";
+                for (const line of lines) {
+                    report(line);
+                }
+            });
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            guarded("video.stderr.read", () => {
+                for (const line of chunk.split("\n")) {
+                    if (line.trim() !== "") {
+                        errors.push(line.trim());
+                    }
+                }
+                errors.splice(0, Math.max(0, errors.length - stderrLines));
+            });
+        });
+        const stop = () => {
+            child.kill("SIGKILL");
+        };
+        run.signal.addEventListener("abort", stop, { once: true });
+        child.on("error", (error) => {
+            run.signal.removeEventListener("abort", stop);
+            reject(new Error(`ffmpeg could not be started: ${error.message}`));
+        });
+        child.on("close", (code, signal) => {
+            run.signal.removeEventListener("abort", stop);
+            // ffmpeg's last progress block need not end in a newline, and probeDurationMs
+            // derives its whole answer from these lines, so the remainder is read before the
+            // promise settles.
+            report(pending);
+            if (run.signal.aborted) {
+                reject(new Error("the render was canceled"));
+                return;
+            }
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(failure(code, signal, errors)));
+        });
+    });
+}
+// The duration the plan is built from, and the one a test reads back off the finished
+// mp4. Taken from a full decode rather than the container header, because a provided
+// variable-bitrate mp3 can carry a header duration that is only an estimate.
+export async function probeDurationMs(bin, file, signal, log) {
+    let last = 0;
+    await runFfmpeg({
+        bin,
+        args: [
+            "-hide_banner",
+            "-nostdin",
+            "-loglevel",
+            "error",
+            "-progress",
+            "pipe:1",
+            "-nostats",
+            "-i",
+            file,
+            "-f",
+            "null",
+            "-",
+        ],
+        signal,
+        log,
+        onProgress: (elapsedMs) => {
+            last = Math.max(last, elapsedMs);
+        },
+    });
+    return last;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function failure(code, signal, errors) {
+    const ended = code === null ? `killed by ${signal ?? "a signal"}` : `exited with code ${code}`;
+    return errors.length === 0
+        ? `ffmpeg ${ended} and wrote nothing to its error stream`
+        : `ffmpeg ${ended}: ${errors.join(" / ")}`;
+}

package/dist/slices/video/plan.js

@@ -0,0 +1,71 @@
+// logic/11 step 5: 30 fps, 1920×1080 for 16:9 and 1080×1920 for 9:16.
+export const fps = 30;
+const frames = {
+    "16:9": { width: 1920, height: 1080 },
+    "9:16": { width: 1080, height: 1920 },
+};
+// §Q85: 100% → 115%, linear, centred, alternating per image. The three are written out
+// rather than derived from one another, because they are formatted into an ffmpeg
+// expression and 1.15 - 1 is not 0.15 in binary floating point.
+export const zoomFrom = 1;
+export const zoomTo = 1.15;
+export const zoomBy = 0.15;
+export function planRender(input) {
+    if (input.images.length === 0) {
+        // logic/04 §Q31 makes an image source mandatory, so an empty set is a bug upstream.
+        throw new Error("a render needs at least one image");
+    }
+    const frame = frames[input.format];
+    const audio = timeline(input);
+    const totalSeconds = audio.reduce((sum, segment) => sum + segment.seconds, 0);
+    const totalFrames = Math.max(input.images.length, Math.round(totalSeconds * fps));
+    return {
+        width: frame.width,
+        height: frame.height,
+        fps,
+        gapSeconds: input.gapSeconds,
+        audio,
+        images: slots(input.images, totalFrames),
+        totalFrames,
+        totalSeconds,
+        output: input.output,
+    };
+}
+// logic/11 step 1: intro, gap, body, gap, outro, with a gap only where the segment on
+// the other side of it exists.
+function timeline(input) {
+    const segments = [];
+    const gap = { kind: "gap", path: null, seconds: input.gapSeconds };
+    // A gap shorter than one frame is no gap. The renderer formats a segment's length to
+    // milliseconds, so anything under that would become `-t 0.000`: an anullsrc input with
+    // no samples that still had to be counted in the audio concat.
+    const audible = input.gapSeconds >= 1 / fps;
+    if (input.intro !== undefined) {
+        segments.push({ kind: "intro", path: input.intro.path, seconds: input.intro.seconds });
+        if (audible) {
+            segments.push(gap);
+        }
+    }
+    segments.push({ kind: "body", path: input.body.path, seconds: input.body.seconds });
+    if (input.outro !== undefined) {
+        if (audible) {
+            segments.push(gap);
+        }
+        segments.push({ kind: "outro", path: input.outro.path, seconds: input.outro.seconds });
+    }
+    return segments;
+}
+// logic/11 step 2: the slot is the total divided by the image count, and the last image
+// absorbs the frame rounding. §Q100: one image fills the whole length.
+// ceiling: every slot holds at least one frame, so a run with more images than the
+// timeline has frames renders slightly longer than its audio rather than failing.
+function slots(paths, totalFrames) {
+    const each = Math.max(1, Math.floor(totalFrames / paths.length));
+    return paths.map((path, at) => ({
+        path,
+        index: at + 1,
+        frames: at === paths.length - 1 ? Math.max(1, totalFrames - each * at) : each,
+        // §Q85: odd images zoom in, even images zoom out.
+        zoom: at % 2 === 0 ? "in" : "out",
+    }));
+}