@gentbajko/slopify 2.5.0 → 3.0.1

package/dist/slices/library/used-by.js

@@ -0,0 +1,153 @@
+// "Used by": the templates, schedules and projects that name a Library prompt or intro/outro.
+// Everything refers to the Library by name (a template's form, a schedule's template, a
+// project revision's config), so the match is the name, without regard to case, within the
+// prompt's kind or the entry's category - the same rule the unique indexes and
+// `snapshot.ts` use.
+import { z } from "zod";
+import { liveProject } from "../admission/repo.js";
+// The fields of a Play form or a run config that name Library items. Both shapes carry the
+// same names; a run config holds the intro and outro as `{ name }` and a form as the name.
+const named = z.string().optional().catch(undefined);
+const refsShape = z
+    .object({
+    articlePrompt: named,
+    narrationPrompt: named,
+    thumbnailPrompt: named,
+    descriptionPrompt: named,
+    imagePrompts: z
+        .array(z.object({ name: z.string() }).loose())
+        .optional()
+        .catch(undefined),
+    reference: z.object({ prompt: named }).loose().optional().catch(undefined),
+    shorts: z.object({ prompt: named, imagePrompt: named }).loose().optional().catch(undefined),
+    intro: z
+        .union([z.string(), z.object({ name: z.string() }).loose()])
+        .optional()
+        .catch(undefined),
+    outro: z
+        .union([z.string(), z.object({ name: z.string() }).loose()])
+        .optional()
+        .catch(undefined),
+})
+    .loose();
+// The names a form or config holds for one kind of prompt or category of entry.
+export function namesIn(value, ref) {
+    const parsed = refsShape.safeParse(value);
+    if (!parsed.success)
+        return [];
+    const form = parsed.data;
+    const entryName = (one) => one === undefined ? undefined : typeof one === "string" ? one : one.name;
+    const names = ref.item === "entry"
+        ? [ref.category === "intro" ? entryName(form.intro) : entryName(form.outro)]
+        : ref.kind === "article"
+            ? [form.articlePrompt]
+            : ref.kind === "narration"
+                ? [form.narrationPrompt]
+                : ref.kind === "thumbnail"
+                    ? [form.thumbnailPrompt]
+                    : ref.kind === "description"
+                        ? [form.descriptionPrompt]
+                        : ref.kind === "shorts"
+                            ? [form.shorts?.prompt]
+                            : [
+                                ...(form.imagePrompts ?? []).map((one) => one.name),
+                                form.reference?.prompt,
+                                form.shorts?.imagePrompt,
+                            ];
+    return names.filter((name) => name !== undefined && name.trim() !== "");
+}
+export function uses(value, ref) {
+    const wanted = ref.name.trim().toLowerCase();
+    return namesIn(value, ref).some((name) => name.trim().toLowerCase() === wanted);
+}
+const documentShape = z.object({ form: z.unknown() }).loose();
+function formOf(json) {
+    const parsed = documentShape.safeParse(JSON.parse(json));
+    return parsed.success ? parsed.data.form : undefined;
+}
+export function usedBy(db, ref) {
+    // A name that appears nowhere in the JSON cannot match, so SQL skips those rows before any
+    // is parsed. JSON escapes quotes and backslashes, so only a plain name is pre-filtered.
+    // SQLite's lower() folds ASCII only, so a name with anything else is not pre-filtered.
+    const plain = /^[\x20-\x7e]*$/u.test(ref.name) && !/["\\]/u.test(ref.name)
+        ? ref.name.trim().toLowerCase()
+        : "";
+    const templates = db
+        .prepare(`SELECT t.id,r.name,r.document_json FROM project_templates t
+       JOIN project_template_revisions r ON r.template_id=t.id AND r.version=t.head_version
+       WHERE t.deleted_at IS NULL AND instr(lower(r.document_json),?)>0 ORDER BY lower(r.name),t.id`)
+        .all(plain)
+        .flatMap((row) => {
+        const parsed = templateRow.parse(row);
+        return uses(formOf(parsed.document_json), ref) ? [{ id: parsed.id, name: parsed.name }] : [];
+    });
+    // A schedule runs the template version it was saved with, so that version is what it uses.
+    const schedules = db
+        .prepare(`SELECT s.id,s.name,s.status,r.document_json FROM schedules s
+       JOIN project_template_revisions r ON r.template_id=s.template_id AND r.version=s.template_version
+       WHERE s.deleted_at IS NULL AND s.status IN ('active','paused') AND instr(lower(r.document_json),?)>0
+       ORDER BY lower(s.name),s.id`)
+        .all(plain)
+        .flatMap((row) => {
+        const parsed = scheduleRow.parse(row);
+        return uses(formOf(parsed.document_json), ref)
+            ? [{ id: parsed.id, name: parsed.name, status: parsed.status }]
+            : [];
+    });
+    const revisionRows = db
+        .prepare(`SELECT r.project_id,p.title,r.id AS revision_id,r.config,h.revision_id AS head,
+        (SELECT count(*) FROM project_revisions x WHERE x.project_id=r.project_id) AS total
+       FROM project_revisions r JOIN projects p ON p.id=r.project_id
+       LEFT JOIN project_heads h ON h.project_id=r.project_id
+       WHERE ${liveProject("p")} AND instr(lower(r.config),?)>0
+       ORDER BY p.created_at DESC,p.id,r.created_at`)
+        .all(plain)
+        .map((row) => revisionRow.parse(row));
+    const projects = new Map();
+    for (const row of revisionRows) {
+        if (!uses(JSON.parse(row.config), ref))
+            continue;
+        const seen = projects.get(row.project_id);
+        projects.set(row.project_id, {
+            id: row.project_id,
+            title: row.title,
+            revisions: (seen?.revisions ?? 0) + 1,
+            totalRevisions: row.total,
+            current: (seen?.current ?? false) || row.head === row.revision_id,
+        });
+    }
+    // A project from before revisions existed has none yet; its own config is what it ran with.
+    for (const row of db
+        .prepare(`SELECT p.id,p.title,p.config FROM projects p
+       WHERE ${liveProject("p")}
+       AND NOT EXISTS (SELECT 1 FROM project_revisions r WHERE r.project_id=p.id)
+       AND instr(lower(p.config),?)>0 ORDER BY p.created_at DESC,p.id`)
+        .all(plain)
+        .map((row) => legacyRow.parse(row))) {
+        if (uses(JSON.parse(row.config), ref))
+            projects.set(row.id, {
+                id: row.id,
+                title: row.title,
+                revisions: 0,
+                totalRevisions: 0,
+                current: true,
+            });
+    }
+    return { templates, schedules, projects: [...projects.values()] };
+}
+const templateRow = z.object({ id: z.string(), name: z.string(), document_json: z.string() });
+const scheduleRow = z.object({
+    id: z.string(),
+    name: z.string(),
+    status: z.string(),
+    document_json: z.string(),
+});
+const revisionRow = z.object({
+    project_id: z.string(),
+    title: z.string(),
+    revision_id: z.string(),
+    config: z.string(),
+    head: z.string().nullable(),
+    total: z.number(),
+});
+const legacyRow = z.object({ id: z.string(), title: z.string(), config: z.string() });

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

@@ -0,0 +1,41 @@
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { levelFile, measurable } from "./loudnorm.js";
+import { pieceLufs, pieceTruePeak, spreadOf } from "./model.js";
+// Every narration piece brought to the one common loudness before the join (`levelFile`), each
+// written again as a WAV in `directory` for the join to read in their place. They come out in one format (44.1 kHz mono, which is what the
+// multi-voice join already brings every turn to), so the plain concat can join them too. A piece
+// too short or quiet to measure keeps its own level. Each levelled piece is measured again, so
+// the report says what the levelling did, not what it meant to do.
+const format = { sampleRate: 44100, channels: 1 };
+const goal = { lufs: pieceLufs, truePeak: pieceTruePeak };
+export async function levelPieces(run, files, directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const levelled = [];
+    const before = [];
+    const after = [];
+    let skipped = 0;
+    for (const [index, file] of files.entries()) {
+        run.signal.throwIfAborted();
+        const output = join(directory, `piece-${String(index + 1).padStart(4, "0")}.wav`);
+        const measured = await levelFile(run, file, output, goal, format);
+        levelled.push(output);
+        if (!measurable(measured.before)) {
+            skipped += 1;
+            continue;
+        }
+        before.push(measured.before.integrated);
+        if (measurable(measured.after))
+            after.push(measured.after.integrated);
+    }
+    return {
+        files: levelled,
+        report: {
+            pieces: files.length,
+            skipped,
+            spreadBefore: spreadOf(before),
+            spreadAfter: spreadOf(after),
+            target: pieceLufs,
+        },
+    };
+}

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 → Video and style, 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",
+};