@gentbajko/slopify 2.5.0 → 3.0.0

package/dist/slices/loudness/loudnorm.js

@@ -0,0 +1,164 @@
+import { renameSync } from "node:fs";
+import { z } from "zod";
+import { runFfmpeg } from "../video/ffmpeg.js";
+// ceiling: below -70 LUFS (the filter's absolute gate) or under 0.4 s (one measuring block)
+// there is nothing to measure: a piece that quiet or short is left as it is.
+const silentBelow = -70;
+const measuredJson = z.object({
+    input_i: z.string(),
+    input_tp: z.string(),
+    input_lra: z.string(),
+    input_thresh: z.string(),
+    target_offset: z.string(),
+});
+function measureFilter(goal) {
+    return `loudnorm=I=${goal.lufs.toFixed(1)}:TP=${goal.truePeak.toFixed(1)}:LRA=11:print_format=json`;
+}
+// The first pass: decode, measure, write nothing. `input` is ffmpeg input arguments, so a
+// filter graph (the video's mix) can be measured as well as a file.
+export function measureArgs(input, goal, chain = "") {
+    return [
+        "-hide_banner",
+        "-nostdin",
+        // loudnorm prints its JSON at the info level.
+        "-loglevel",
+        "info",
+        "-nostats",
+        ...input,
+        "-af",
+        `${chain === "" ? "" : `${chain},`}${measureFilter(goal)}`,
+        "-f",
+        "null",
+        "-",
+    ];
+}
+// The second pass: the gain that lands the file on the level, the peak limiter where the gain
+// would push the peaks over the ceiling, and the file's sample rate. Unity for a file there was
+// nothing to measure in.
+export function gainFilter(goal, measured, sampleRate) {
+    const resample = `aresample=${String(sampleRate)}`;
+    if (measured === undefined || !measurable(measured))
+        return resample;
+    const gain = goal.lufs - measured.integrated;
+    const limit = Number.isFinite(measured.truePeak) && measured.truePeak + gain > goal.truePeak
+        ? `,aresample=192000,alimiter=limit=${(10 ** (goal.truePeak / 20)).toFixed(4)}:attack=5:release=50:level=false`
+        : "";
+    return `volume=${gain.toFixed(2)}dB${limit},${resample}`;
+}
+export function measurable(measured) {
+    return Number.isFinite(measured.integrated) && measured.integrated > silentBelow;
+}
+// The last JSON block loudnorm printed. Its numbers are strings, and "-inf" for silence.
+export function parseMeasured(stderr) {
+    const start = stderr.lastIndexOf("{");
+    const end = stderr.lastIndexOf("}");
+    if (start < 0 || end < start)
+        return undefined;
+    let raw;
+    try {
+        raw = JSON.parse(stderr.slice(start, end + 1));
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = measuredJson.safeParse(raw);
+    if (!parsed.success)
+        return undefined;
+    const number = (text) => {
+        const value = Number(text);
+        return Number.isNaN(value) ? Number.NEGATIVE_INFINITY : value;
+    };
+    return {
+        integrated: number(parsed.data.input_i),
+        truePeak: number(parsed.data.input_tp),
+        range: number(parsed.data.input_lra),
+        threshold: number(parsed.data.input_thresh),
+        offset: number(parsed.data.target_offset),
+    };
+}
+// Measure `input` (ffmpeg input arguments, `chain` an optional filter before the measurement).
+export async function measure(run, input, goal, chain = "") {
+    let stderr = "";
+    await runFfmpeg({
+        bin: run.bin,
+        args: measureArgs(input, goal, chain),
+        signal: run.signal,
+        log: run.log,
+        onProgress: () => { },
+        onStderr: (text) => {
+            stderr += text;
+        },
+    });
+    const measured = parseMeasured(stderr);
+    if (measured === undefined)
+        throw new Error("Slopify couldn't measure the loudness of the narration (ffmpeg printed no measurement). Try again; if it happens again, turn off Level the volume in Edit project → Pauses and volume, then use Download diagnostics in Settings and report it.");
+    return measured;
+}
+export async function measureFile(run, path, goal) {
+    return measure(run, ["-i", path], goal);
+}
+// One file measured and written again at `goal`, as WAV at `sampleRate` with `channels`
+// channels (32-bit float, so nothing clips between here and the encode). Returns what the first
+// pass measured.
+export async function normalizeFile(run, input, output, goal, format) {
+    // The channels are set before anything is measured: a stereo file mixed down to mono is
+    // louder per channel (the mix keeps its loudness, so each sample is about 3 dB higher), and
+    // the gain and the peak ceiling have to hold for what is written.
+    const channels = `aformat=channel_layouts=${format.channels === 1 ? "mono" : "stereo"}`;
+    const measured = await measure(run, ["-i", input], goal, channels);
+    await runFfmpeg({
+        bin: run.bin,
+        args: [
+            "-hide_banner",
+            "-nostdin",
+            "-loglevel",
+            "error",
+            "-nostats",
+            "-y",
+            "-i",
+            input,
+            "-map",
+            "0:a:0",
+            "-af",
+            `${channels},${gainFilter(goal, measured, format.sampleRate)}`,
+            "-c:a",
+            "pcm_f32le",
+            "-f",
+            "wav",
+            output,
+        ],
+        signal: run.signal,
+        log: run.log,
+        onProgress: () => { },
+    });
+    return measured;
+}
+// ceiling: within a fifth of a LU of the level no one hears the difference.
+const correctAbove = 0.2;
+// One file brought to `goal` (`normalizeFile`), measured again, and corrected once when the
+// limiter left it more than a fifth of a LU under the level. Returns the first measurement and
+// the last.
+export async function levelFile(run, input, output, goal, format) {
+    const before = await normalizeFile(run, input, output, goal, format);
+    let after = await measureFile(run, output, goal);
+    if (measurable(after) && Math.abs(after.integrated - goal.lufs) > correctAbove) {
+        const corrected = `${output}.corrected.wav`;
+        await normalizeFile(run, output, corrected, goal, format);
+        renameSync(corrected, output);
+        after = await measureFile(run, output, goal);
+    }
+    return { before, after };
+}
+// A finished file's sound brought to its master target.
+export async function masterFile(run, input, output, goal, format) {
+    await levelFile(run, input, output, goal, format);
+}
+// What a finished file measures, for its output (`MasterReport`).
+export async function masterReport(run, file, goal) {
+    const check = await measureFile(run, file, goal);
+    return {
+        target: goal.lufs,
+        integrated: Math.round(check.integrated * 10) / 10,
+        truePeak: Math.round(check.truePeak * 10) / 10,
+    };
+}

package/dist/slices/loudness/model.js

@@ -0,0 +1,153 @@
+// Loudness normalization ("Level the volume"). Text-to-speech comes back at a different
+// loudness per voice and even per request, so a joined narration jumps. With the setting on:
+// - every narration piece (a chunk, an intro or outro part, a speaker's turn) is measured and
+//   brought to one common loudness before the pieces are joined (`loudnorm.ts`), in a step of
+//   its own beside the plain join (`recipe-audio.ts`), so the word timing, which reads the
+//   plain join, and everything written from it are never made again for a volume change;
+// - every finished file is mastered to a target: the long video and the shorts to the video
+//   target, the audio files (the audio-only WAV, an audiobook's MP3 and M4B) to their own.
+// The ambient bed and the shorts' music are mixed before the master and ducked by the levelled
+// voice, so they keep their place under it.
+//
+// Browser-safe: Play, Edit project and Settings convert the same numbers.
+//
+// A run without the setting has no `loudness` at all, which is what every project saved before
+// it was, and every recipe leaves it out of its fingerprint then.
+// YouTube and Spotify play everything back at about -14 LUFS, so a video mastered there is
+// neither turned down nor left quiet. Audiobook shops ask for about -18 to -20 LUFS with more
+// headroom, so the listening files sit lower.
+export const recommendedVideoLufs = -14;
+export const recommendedAudioFilesLufs = -18;
+export const defaultLoudness = {
+    enabled: true,
+    videoLufs: recommendedVideoLufs,
+    audioFilesLufs: recommendedAudioFilesLufs,
+};
+// The peak ceilings, in dBTP (true peak, between the samples). The video's leaves room for the
+// lossy AAC encode; the audio files' is what audiobook shops ask for.
+export const videoTruePeak = -1.5;
+export const audioFilesTruePeak = -3;
+// The master aims this far under the ceiling: a lossy encode (the video's AAC, the MP3 and
+// M4B) lifts the peaks by up to about 0.7 dB at the bitrates Slopify writes, and what is
+// measured is the finished file.
+export const encodeHeadroom = 1;
+// The common level every narration piece is brought to before the join. Fixed, so changing the
+// Volume only masters the finished files again and never re-joins the narration. ceiling: a
+// voice's peaks run 14 to 18 dB over its loudness, so -20 LUFS leaves room for nearly all of
+// them under -2 dBTP; the master then lifts the whole to the target.
+export const pieceLufs = -20;
+export const pieceTruePeak = -2;
+// The Volume control is in dB from the recommended level: 0 dB is the recommendation. Below
+// -10 dB a video sounds broken next to others; above +4 dB the peak ceiling squashes the voice.
+export const loudnessDbMin = -10;
+export const loudnessDbMax = 4;
+export const loudnessDbStep = 0.5;
+// The master a run's file of this kind gets, or undefined while the setting is off.
+export function masterGoal(config, target) {
+    const settings = config.loudness;
+    if (settings === undefined || !usesLoudness(config))
+        return undefined;
+    return {
+        lufs: target === "video" ? settings.videoLufs : settings.audioFilesLufs,
+        truePeak: truePeakOf(target) - encodeHeadroom,
+    };
+}
+export function recommendedLufs(target) {
+    return target === "video" ? recommendedVideoLufs : recommendedAudioFilesLufs;
+}
+export function truePeakOf(target) {
+    return target === "video" ? videoTruePeak : audioFilesTruePeak;
+}
+// dB from the recommended level, and back. Stored is the LUFS; the dB is what is shown.
+export function dbOfLufs(lufs, target) {
+    return round(lufs - recommendedLufs(target), 2);
+}
+export function lufsOfDb(db, target) {
+    return round(recommendedLufs(target) + db, 2);
+}
+// Loudness as a share of the recommended level, the way a volume knob reads: -6 dB is about
+// half as loud, +6 dB about twice. An amplitude ratio, so it matches what the gain does.
+export function percentOfDb(db) {
+    return Math.round(10 ** (db / 20) * 100);
+}
+export function dbOfPercent(percent) {
+    return round(20 * Math.log10(percent / 100), 2);
+}
+// Typed dB snapped to the control's step and range; undefined for text that is not a number.
+export function snapDb(db) {
+    if (!Number.isFinite(db))
+        return undefined;
+    const snapped = Math.round(db / loudnessDbStep) * loudnessDbStep;
+    return Math.min(loudnessDbMax, Math.max(loudnessDbMin, snapped));
+}
+export function loudnessProblem(lufs, target) {
+    const db = lufs - recommendedLufs(target);
+    return Number.isFinite(db) &&
+        Number.isInteger(round(db / loudnessDbStep, 6)) &&
+        db >= loudnessDbMin - 1e-9 &&
+        db <= loudnessDbMax + 1e-9
+        ? undefined
+        : `The volume must be between ${String(loudnessDbMin)} dB and +${String(loudnessDbMax)} dB of the recommended level, in steps of ${String(loudnessDbStep)} dB. Change it under Level the volume (Play → Outputs → Export, Edit project → Pauses and volume, or Settings → General).`;
+}
+export function loudnessFields(settings) {
+    if (settings === undefined)
+        return [];
+    const fields = [];
+    const video = loudnessProblem(settings.videoLufs, "video");
+    if (video !== undefined)
+        fields.push({ field: "loudness.videoLufs", message: video });
+    const files = loudnessProblem(settings.audioFilesLufs, "audioFiles");
+    if (files !== undefined)
+        fields.push({ field: "loudness.audioFilesLufs", message: files });
+    return fields;
+}
+// Whether a run levels and masters its sound: the setting is on and there is a narration.
+export function usesLoudness(config) {
+    return config.loudness !== undefined && config.sources.audio !== "off";
+}
+// The settings for a new run from the app-wide default; undefined when it is off.
+export function loudnessOfDefault(value) {
+    return value.enabled
+        ? { videoLufs: value.videoLufs, audioFilesLufs: value.audioFilesLufs }
+        : undefined;
+}
+export function loudnessOfForm(form, fallback) {
+    if (!(form?.enabled ?? fallback.enabled))
+        return undefined;
+    return {
+        videoLufs: form?.videoLufs ?? fallback.videoLufs,
+        audioFilesLufs: form?.audioFilesLufs ?? fallback.audioFilesLufs,
+    };
+}
+// "0 dB (recommended, -14 LUFS)", "-6 dB (50%, -20 LUFS)".
+export function loudnessLabel(lufs, target) {
+    const db = dbOfLufs(lufs, target);
+    const lufsText = `${formatNumber(lufs)} LUFS`;
+    if (db === 0)
+        return `0 dB (recommended, ${lufsText})`;
+    return `${db > 0 ? "+" : ""}${formatNumber(db)} dB (${String(percentOfDb(db))}%, ${lufsText})`;
+}
+// The loudest minus the quietest; 0 for fewer than two.
+export function spreadOf(values) {
+    if (values.length < 2)
+        return 0;
+    return round(Math.max(...values) - Math.min(...values), 1);
+}
+export function reportText(report) {
+    const pieces = `${String(report.pieces)} ${report.pieces === 1 ? "piece" : "pieces"}`;
+    const skipped = report.skipped === 0
+        ? ""
+        : ` (${String(report.skipped)} too short or quiet to measure, left as they were)`;
+    return `Levelled ${pieces} to ${formatNumber(report.target)} LUFS${skipped}: the spread was ${formatNumber(report.spreadBefore)} LU, now ${formatNumber(report.spreadAfter)} LU.`;
+}
+// "Mastered to -14 LUFS: measured -14.1 LUFS, peaks -1.6 dBTP".
+export function masterText(report) {
+    return `Mastered to ${formatNumber(report.target)} LUFS: measured ${formatNumber(report.integrated)} LUFS, peaks ${formatNumber(report.truePeak)} dBTP`;
+}
+function round(value, places) {
+    const scale = 10 ** places;
+    return Math.round(value * scale) / scale;
+}
+function formatNumber(value) {
+    return String(round(value, 1)).replace("-", "−");
+}

package/dist/slices/model-upkeep/model.js

@@ -0,0 +1,10 @@
+// The model-upkeep vocabulary, free of the database so the browser can import it too.
+// The four model choices a run makes, and the catalogue list each one comes from.
+export const usageSlots = ["llm", "audio", "images", "animate"];
+export const usageKinds = ["template", "schedule", "draft", "project"];
+export const slotLabels = {
+    llm: "Text model",
+    audio: "Voice model",
+    images: "Image model",
+    animate: "Animation model",
+};

package/dist/slices/model-upkeep/switch.js

@@ -0,0 +1,217 @@
+import { transact } from "../../kernel/db/tx.js";
+import { projectById, stagesOf, updateProjectConfig } from "../admission/repo.js";
+import { draftRow } from "../play-drafts/repo.js";
+import { documentOf, saveDraft } from "../play-drafts/service.js";
+import { templateById } from "../project-templates/repo.js";
+import { updateTemplate } from "../project-templates/service.js";
+import { ensureBaseline, saveRevision } from "../revisions/index.js";
+import { currentRevisionId } from "../revisions/repo.js";
+import { configChoices, formChoices, retiredModelUsage, retiredStatus, } from "./usage.js";
+function keepThinking(catalogue, provider, model, thinking) {
+    if (thinking === undefined)
+        return {};
+    const row = catalogue.llm.find((entry) => entry.provider === provider && entry.id === model);
+    return row?.llm.thinking?.[thinking] === undefined ? {} : { thinking };
+}
+function matches(choice, from) {
+    return choice !== undefined && choice.provider === from.provider && choice.model === from.model;
+}
+// The form with one model choice replaced, or undefined when the form no longer picks `from`
+// there (it was changed meanwhile, so there is nothing to switch).
+export function switchForm(form, catalogue, request) {
+    if (!matches(formChoices(form)[request.slot], request.from))
+        return undefined;
+    const { to } = request;
+    switch (request.slot) {
+        case "llm": {
+            const { thinking, ...rest } = form.llm;
+            return {
+                ...form,
+                llm: { ...rest, model: to, ...keepThinking(catalogue, rest.provider, to, thinking) },
+            };
+        }
+        case "audio":
+            return { ...form, audio: { ...form.audio, model: to } };
+        case "images":
+            return { ...form, images: { ...form.images, model: to } };
+        case "animate":
+            return form.videoEdit === undefined
+                ? undefined
+                : { ...form, videoEdit: { ...form.videoEdit, animateModel: to } };
+    }
+}
+export function switchConfig(config, catalogue, request) {
+    if (!matches(configChoices(config)[request.slot], request.from))
+        return undefined;
+    const { to } = request;
+    switch (request.slot) {
+        case "llm": {
+            if (config.llm === undefined)
+                return undefined;
+            const { thinking, ...rest } = config.llm;
+            return {
+                ...config,
+                llm: { ...rest, model: to, ...keepThinking(catalogue, rest.provider, to, thinking) },
+            };
+        }
+        case "audio":
+            return config.audio === undefined
+                ? undefined
+                : { ...config, audio: { ...config.audio, model: to } };
+        case "images":
+            return config.images === undefined
+                ? undefined
+                : { ...config, images: { ...config.images, model: to } };
+        case "animate":
+            return config.videoEdit === undefined
+                ? undefined
+                : { ...config, videoEdit: { ...config.videoEdit, animateModel: to } };
+    }
+}
+const changedMeanwhile = "This changed while you were looking at it. Reload Settings → Models to see what still uses a retired model.";
+// One click on "Switch to <model>": changes that one choice and nothing else. A template gets a
+// new version, and the schedules that ran its latest version follow it to the new one.
+export async function switchRetiredModel(deps, catalogue, request) {
+    if (retiredStatus(catalogue, request.slot, {
+        provider: request.from.provider,
+        model: request.to,
+    }) !== null)
+        return {
+            ok: false,
+            message: `${request.to} is not an active model of this provider. Reload Settings → Models and use the suggested switch, or choose a model yourself in the ${request.kind}.`,
+        };
+    switch (request.kind) {
+        case "template":
+            return switchTemplate(deps, catalogue, request, request.id);
+        case "schedule": {
+            const row = deps.db
+                .prepare("SELECT s.template_id AS templateId,s.template_version AS version,t.head_version AS head FROM schedules s JOIN project_templates t ON t.id=s.template_id WHERE s.id=? AND s.deleted_at IS NULL")
+                .get(request.id);
+            if (row === undefined)
+                return { ok: false, message: changedMeanwhile };
+            if (row.version !== row.head)
+                return {
+                    ok: false,
+                    message: "This schedule runs an older version of its template. In Library → Schedules, choose Edit, pick the template again so it runs the latest version, then save.",
+                };
+            return switchTemplate(deps, catalogue, request, String(row.templateId));
+        }
+        case "draft":
+            return switchDraft(deps, catalogue, request);
+        case "project":
+            return switchProject(deps, catalogue, request);
+    }
+}
+function switchTemplate(deps, catalogue, request, templateId) {
+    return transact(deps.db, () => {
+        const template = templateById(deps.db, templateId);
+        if (template === undefined)
+            return { ok: false, message: changedMeanwhile };
+        const form = switchForm(template.document.form, catalogue, request);
+        if (form === undefined)
+            return { ok: true, changed: false };
+        const saved = updateTemplate(deps, {
+            id: template.id,
+            name: template.name,
+            document: { ...template.document, form },
+            baseVersion: template.version,
+            mutationId: deps.uuid(),
+        });
+        if (!saved.ok)
+            return {
+                ok: false,
+                message: saved.reason === "missing-prompt"
+                    ? `The template "${template.name}" uses a prompt or intro/outro that was deleted, so it cannot be saved. Open it in Library → Templates, choose another, and save.`
+                    : changedMeanwhile,
+            };
+        deps.db
+            .prepare("UPDATE schedules SET template_version=?,version=version+1,updated_at=? WHERE template_id=? AND template_version=? AND deleted_at IS NULL AND status IN ('active','paused')")
+            .run(saved.value.version, deps.clock.now().toISOString(), template.id, template.version);
+        return { ok: true, changed: true };
+    });
+}
+function switchDraft(deps, catalogue, request) {
+    const row = draftRow(deps.db, request.id);
+    const document = row === undefined ? null : documentOf(row);
+    if (row === undefined || document === null || row.state !== "active")
+        return { ok: false, message: changedMeanwhile };
+    const form = switchForm(document.form, catalogue, request);
+    if (form === undefined)
+        return { ok: true, changed: false };
+    const saved = saveDraft({ ...deps, uuid: deps.uuid }, {
+        id: row.id,
+        baseVersion: row.version,
+        mutationId: deps.uuid(),
+        document: { ...document, form },
+    });
+    return saved.ok ? { ok: true, changed: true } : { ok: false, message: changedMeanwhile };
+}
+async function switchProject(deps, catalogue, request) {
+    const project = projectById(deps.db, request.id);
+    if (project === undefined)
+        return { ok: false, message: changedMeanwhile };
+    if (stagesOf(deps.db, project.id).some((stage) => stage.state === "running"))
+        return {
+            ok: false,
+            message: "This project is running. Wait for it to finish or pause it, then switch.",
+        };
+    if (currentRevisionId(deps.db, project.id) === undefined) {
+        // A project never edited has no saved versions yet: its configuration is the run itself.
+        const config = switchConfig(project.config, catalogue, request);
+        if (config === undefined)
+            return { ok: true, changed: false };
+        updateProjectConfig(deps.db, project.id, config, deps.clock.now().toISOString());
+        return { ok: true, changed: true };
+    }
+    const baseline = await ensureBaseline(deps, project.id);
+    if (!baseline.ok)
+        return { ok: false, message: changedMeanwhile };
+    const { revision } = baseline.view;
+    const config = switchConfig(revision.config, catalogue, request);
+    if (config === undefined)
+        return { ok: true, changed: false };
+    // The same save Edit project makes: a new version with only the model changed.
+    const saved = await saveRevision(deps, {
+        projectId: project.id,
+        baseRevisionId: revision.id,
+        idempotencyKey: deps.uuid(),
+        edit: { config, content: revision.content },
+    });
+    return saved.ok
+        ? { ok: true, changed: true }
+        : {
+            ok: false,
+            message: `Slopify could not save the new model on "${project.title}"${saved.reason === "conflict"
+                ? " because the project changed meanwhile"
+                : "fields" in saved && saved.fields?.[0] !== undefined
+                    ? ` (${saved.fields[0].message})`
+                    : ""}. Open the project, choose Edit project and change it under Providers.`,
+        };
+}
+// "Switch all": every listed use that has a suggestion and no reason to hold back, one by one.
+export async function switchAllRetired(deps, catalogue) {
+    let switched = 0;
+    const failed = [];
+    // Templates first: switching one also moves the schedules that follow it.
+    const order = ["template", "schedule", "draft", "project"];
+    const usages = [...retiredModelUsage(deps.db, catalogue)].sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind));
+    for (const usage of usages) {
+        if (usage.blocked !== null || usage.replacement === null)
+            continue;
+        const result = await switchRetiredModel(deps, catalogue, requestOf(usage));
+        if (!result.ok)
+            failed.push({ key: usage.key, message: result.message });
+        else if (result.changed)
+            switched++;
+    }
+    return { switched, failed };
+}
+export function requestOf(usage) {
+    return {
+        kind: usage.kind,
+        id: usage.id,
+        slot: usage.slot,
+        from: { provider: usage.provider, model: usage.model },
+        to: usage.replacement?.id ?? "",
+    };
+}