@prestyj/editor 0.7.1

package/dist/tools/compose-thumbnail-variants.js

@@ -0,0 +1,274 @@
+import { resolve as resolvePath, join } from "node:path";
+import { z } from "zod";
+import { resolveApiKey } from "../core/auth/api-keys.js";
+import { loadBrandKit } from "../core/brand-kit.js";
+import { compact, err } from "../core/format.js";
+import { extractAtInterval } from "../core/frames.js";
+import { checkFfmpeg, probeMedia } from "../core/media/ffmpeg.js";
+import { composeThumbnailFrame } from "../core/thumbnail-compose.js";
+import { scoreFrames } from "../core/vision.js";
+import { pickBrandFont } from "./compose-thumbnail.js";
+const ComposeThumbnailVariantsParams = z.object({
+    input: z.string().describe("Source video (relative resolves to cwd)."),
+    outputDir: z.string().describe("Directory for the variant images. Created if missing."),
+    text: z.string().min(1).describe("Headline burned on each variant."),
+    count: z.number().int().min(1).max(5).optional().describe("How many variants. Default 3."),
+    intervalSec: z
+        .number()
+        .positive()
+        .optional()
+        .describe("Sampling interval. Default = totalSec/40 (≈40 candidates over the video)."),
+    minSpacingSec: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Minimum seconds between picked variants. Default 10."),
+    strategy: z
+        .enum(["expression", "label", "mixed"])
+        .optional()
+        .describe("Variant generation strategy. 'mixed' (default) = 3 distinct frames + same label. " +
+        "'expression' = 3 best frames, all same label (vary expression only — face-driven " +
+        "content). 'label' = ONE best frame + 3 LLM-generated label variations (use when the " +
+        "source has only one usable face / product / screen)."),
+    model: z.string().optional().describe("OpenAI model. Default gpt-4o-mini."),
+    detail: z.enum(["low", "high"]).optional().describe("Vision detail. Default low."),
+    fontFile: z.string().optional(),
+    fontSize: z.number().int().positive().optional(),
+    fontColor: z.string().optional(),
+    outlineColor: z.string().optional(),
+    position: z.enum(["top", "center", "bottom"]).optional(),
+    width: z.number().int().positive().optional(),
+});
+/**
+ * compose_thumbnail_variants — generate N thumbnails for A/B testing.
+ *
+ * Samples frames at `intervalSec`, scores via vision rubric, picks the
+ * top-N spaced ≥ minSpacingSec apart, burns the headline. YouTube
+ * native A/B is now standard — variants beat single guesses.
+ *
+ * Strategies:
+ *   - "mixed"      (default): 3 distinct frames, same label.
+ *   - "expression": same as mixed — picked separately for face-driven
+ *     content where the agent wants to emphasise expression variation.
+ *   - "label":     ONE best frame, 3 LLM-generated label variations.
+ *     Use when the source only has one usable visual.
+ */
+export function createComposeThumbnailVariantsTool(cwd) {
+    return {
+        name: "compose_thumbnail_variants",
+        description: "Generate N thumbnail variants for A/B testing. Samples frames across the video, scores " +
+            "each via vision LLM, picks top-N distinct frames (≥minSpacingSec apart), burns the " +
+            "headline. `strategy` controls what varies: 'expression' (default for face-driven " +
+            "content) picks 3 frames with the SAME label; 'label' picks ONE frame + generates 3 " +
+            "distinct labels via LLM (use when only one usable face / product / screen exists); " +
+            "'mixed' = current behaviour (3 frames + same label). Output ordered best-first. " +
+            "Auto-applies brand kit (fonts.heading, colors.primary). YouTube native A/B is now " +
+            "standard — ship variants, not a single guess. Requires OPENAI_API_KEY + ffmpeg. Pair " +
+            "with `generate_youtube_metadata` before publish.",
+        parameters: ComposeThumbnailVariantsParams,
+        async execute(args, ctx) {
+            try {
+                if (!checkFfmpeg())
+                    return err("ffmpeg not on PATH", "install ffmpeg");
+                if (!process.env.OPENAI_API_KEY) {
+                    return err("OPENAI_API_KEY not set", "export OPENAI_API_KEY=...");
+                }
+                const inAbs = resolvePath(cwd, args.input);
+                const outDir = resolvePath(cwd, args.outputDir);
+                const probe = probeMedia(inAbs);
+                if (!probe)
+                    return err(`probe failed for ${inAbs}`, "verify file exists and is media");
+                if (probe.durationSec <= 0)
+                    return err("source has zero duration");
+                const count = Math.min(5, Math.max(1, args.count ?? 3));
+                const minSpacing = Math.max(0, args.minSpacingSec ?? 10);
+                const interval = args.intervalSec && args.intervalSec > 0
+                    ? args.intervalSec
+                    : Math.max(1, probe.durationSec / 40);
+                const strategy = args.strategy ?? "mixed";
+                // Brand-kit fallback: only fill in fontFile / outlineColor when the
+                // caller didn't pass an explicit value.
+                const brand = loadBrandKit(cwd);
+                const brandFont = pickBrandFont(cwd, brand?.fonts?.heading);
+                const fontFile = args.fontFile ?? brandFont;
+                const outlineColor = args.outlineColor ?? brand?.colors?.primary;
+                const brandKitLoaded = brand !== null;
+                // Sample frames across the whole video.
+                const frames = await extractAtInterval(inAbs, interval, probe.durationSec, {
+                    maxWidth: 1280,
+                    signal: ctx.signal,
+                });
+                if (frames.length === 0)
+                    return err("no frames extracted", "lower intervalSec");
+                // Score each frame.
+                const scores = await scoreFrames(frames, {
+                    model: args.model,
+                    detail: args.detail,
+                    signal: ctx.signal,
+                });
+                // Pair scores with their source frames + pick top-N respecting
+                // minSpacingSec.
+                const paired = scores.map((s, i) => ({ frame: frames[i], score: s }));
+                // ── label strategy: 1 frame, 3 LLM-generated labels ────────────
+                if (strategy === "label") {
+                    const top = paired.sort((a, b) => b.score.score - a.score.score)[0];
+                    if (!top)
+                        return err("no variants survived spacing constraint", "lower minSpacingSec");
+                    const labels = await generateLabelVariations(args.text, count, {
+                        model: args.model,
+                        signal: ctx.signal,
+                    });
+                    const variants = [];
+                    for (let i = 0; i < labels.length; i++) {
+                        const outPath = join(outDir, `variant-${i + 1}.jpg`);
+                        await composeThumbnailFrame({
+                            input: inAbs,
+                            output: outPath,
+                            atSec: top.frame.atSec,
+                            text: labels[i],
+                            fontFile,
+                            fontSize: args.fontSize,
+                            fontColor: args.fontColor,
+                            outlineColor,
+                            position: args.position,
+                            width: args.width,
+                            signal: ctx.signal,
+                        }, cwd);
+                        variants.push({
+                            path: outPath,
+                            atSec: +top.frame.atSec.toFixed(2),
+                            score: top.score.score,
+                            why: top.score.why,
+                            label: labels[i],
+                        });
+                    }
+                    return compact({
+                        variants,
+                        count: variants.length,
+                        totalScored: paired.length,
+                        strategy,
+                        brandKitLoaded,
+                    });
+                }
+                // ── mixed / expression strategies: N frames, same label ────────
+                const picks = pickTopSpaced(paired, count, minSpacing);
+                if (picks.length === 0) {
+                    return err("no variants survived spacing constraint", "lower minSpacingSec");
+                }
+                // Burn the headline on each pick.
+                const variants = [];
+                for (let i = 0; i < picks.length; i++) {
+                    const p = picks[i];
+                    const outPath = join(outDir, `variant-${i + 1}.jpg`);
+                    await composeThumbnailFrame({
+                        input: inAbs,
+                        output: outPath,
+                        atSec: p.frame.atSec,
+                        text: args.text,
+                        fontFile,
+                        fontSize: args.fontSize,
+                        fontColor: args.fontColor,
+                        outlineColor,
+                        position: args.position,
+                        width: args.width,
+                        signal: ctx.signal,
+                    }, cwd);
+                    variants.push({
+                        path: outPath,
+                        atSec: +p.frame.atSec.toFixed(2),
+                        score: p.score.score,
+                        why: p.score.why,
+                    });
+                }
+                return compact({
+                    variants,
+                    count: variants.length,
+                    totalScored: paired.length,
+                    strategy,
+                    brandKitLoaded,
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+/**
+ * Greedy top-N selection with minimum spacing. Sort by score desc, walk
+ * the list, accept a candidate only if it's ≥ minSpacingSec away from
+ * every already-accepted pick. Stable — ties preserve input order.
+ *
+ * Pure — exported for testing.
+ */
+export function pickTopSpaced(paired, count, minSpacingSec) {
+    const sorted = [...paired].sort((a, b) => {
+        if (b.score.score !== a.score.score)
+            return b.score.score - a.score.score;
+        return a.frame.atSec - b.frame.atSec;
+    });
+    const kept = [];
+    for (const p of sorted) {
+        if (kept.length >= count)
+            break;
+        const tooClose = kept.some((k) => Math.abs(k.frame.atSec - p.frame.atSec) < minSpacingSec);
+        if (tooClose)
+            continue;
+        kept.push(p);
+    }
+    return kept;
+}
+const LABEL_SYSTEM = `You distill a YouTube headline into thumbnail labels. Given an input headline, output exactly N distinct 2-4-word labels. Each label should attack the same headline from a DIFFERENT angle (e.g. one curiosity-driven, one outcome-driven, one number-driven). Labels render large on a 100x56 mobile-feed thumbnail — no punctuation, no quotes, ALL CAPS preferred when it fits.
+
+Output JSON with this EXACT shape:
+{ "labels": ["...", "...", "..."] }
+
+No prose, no extra keys.`;
+/**
+ * Ask the LLM for N label variations. Pure-ish (network call) — exported
+ * for testing under a mocked fetch.
+ */
+export async function generateLabelVariations(headline, n, opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for compose_thumbnail_variants.");
+    const model = opts.model ?? "gpt-4o-mini";
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: LABEL_SYSTEM },
+            { role: "user", content: `HEADLINE:\n${headline}\n\nN: ${n}` },
+        ],
+        response_format: { type: "json_object" },
+        temperature: 0,
+    };
+    const res = await fetch("https://api.openai.com/v1/chat/completions", {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: opts.signal,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`OpenAI HTTP ${res.status}: ${text.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const content = data.choices[0]?.message?.content;
+    if (!content)
+        throw new Error("compose_thumbnail_variants: empty model response");
+    const parsed = JSON.parse(content);
+    const arr = Array.isArray(parsed.labels) ? parsed.labels : [];
+    const labels = arr
+        .map((v) => String(v ?? "").trim())
+        .filter((v) => v.length > 0)
+        .slice(0, n);
+    // Pad with the headline itself if the model under-delivers, so caller
+    // always gets N entries.
+    while (labels.length < n)
+        labels.push(headline);
+    return labels;
+}
+//# sourceMappingURL=compose-thumbnail-variants.js.map

package/dist/tools/compose-thumbnail-variants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-thumbnail-variants.js","sourceRoot":"","sources":["../../src/tools/compose-thumbnail-variants.ts"],"names":[],"mappings":"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"}

package/dist/tools/compose-thumbnail.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+import { escapeDrawtextValue, pickFont } from "../core/thumbnail-compose.js";
+declare const ComposeThumbnailParams: z.ZodObject<{
+    input: z.ZodString;
+    output: z.ZodString;
+    atSec: z.ZodNumber;
+    text: z.ZodString;
+    fontSize: z.ZodOptional<z.ZodNumber>;
+    fontColor: z.ZodOptional<z.ZodString>;
+    outlineColor: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodEnum<{
+        top: "top";
+        center: "center";
+        bottom: "bottom";
+    }>>;
+    fontFile: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createComposeThumbnailTool(cwd: string): AgentTool<typeof ComposeThumbnailParams>;
+export { escapeDrawtextValue, pickFont };
+/**
+ * Resolve a brand-kit `fonts.heading` value to a readable absolute path.
+ * Returns undefined when the kit doesn't define one or the file is missing.
+ * Pure-ish (touches the filesystem) — exported for testing.
+ */
+export declare function pickBrandFont(cwd: string, heading: string | undefined): string | undefined;
+//# sourceMappingURL=compose-thumbnail.d.ts.map

package/dist/tools/compose-thumbnail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-thumbnail.d.ts","sourceRoot":"","sources":["../../src/tools/compose-thumbnail.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,OAAO,EAAyB,mBAAmB,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAEpG,QAAA,MAAM,sBAAsB;;;;;;;;;;;;;;;iBAyB1B,CAAC;AAEH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,sBAAsB,CAAC,CAqDhG;AAGD,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,CAAC;AAEzC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQ1F"}

package/dist/tools/compose-thumbnail.js

@@ -0,0 +1,101 @@
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { z } from "zod";
+import { loadBrandKit } from "../core/brand-kit.js";
+import { compact, err } from "../core/format.js";
+import { checkFfmpeg } from "../core/media/ffmpeg.js";
+import { safeResolveOutputPath } from "../core/safe-paths.js";
+import { composeThumbnailFrame, escapeDrawtextValue, pickFont } from "../core/thumbnail-compose.js";
+const ComposeThumbnailParams = z.object({
+    input: z.string().describe("Source video."),
+    output: z.string().describe("Thumbnail .jpg or .png."),
+    atSec: z.number().min(0).describe("Frame timestamp."),
+    text: z.string().min(1).describe("Headline text overlay."),
+    fontSize: z.number().int().min(8).optional().describe("Default 96."),
+    fontColor: z.string().optional().describe("Hex RRGGBB. Default 'white'."),
+    outlineColor: z
+        .string()
+        .optional()
+        .describe("Outline hex RRGGBB. Default 'black'. Use empty string to disable."),
+    position: z.enum(["top", "center", "bottom"]).optional().describe("Default 'bottom'."),
+    fontFile: z
+        .string()
+        .optional()
+        .describe("Path to a TTF font file. ffmpeg drawtext requires this on most systems. " +
+        "Default tries common system locations."),
+    width: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Optional output width (height auto). Common: 1280 for YouTube."),
+});
+export function createComposeThumbnailTool(cwd) {
+    return {
+        name: "compose_thumbnail",
+        description: "Pull a frame and burn a text headline on top, in one shot. YouTube/TikTok thumbnail " +
+            "generation. ffmpeg drawtext requires a TTF font path; we try common system locations " +
+            "(macOS Helvetica, DejaVu on Linux, Arial on Windows) when fontFile isn't given. Default " +
+            "is large white text with black outline at the bottom — readable at thumbnail scale.",
+        parameters: ComposeThumbnailParams,
+        async execute(args, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            try {
+                const inAbs = resolvePath(cwd, args.input);
+                const resolved = safeResolveOutputPath(cwd, args.output);
+                // Brand-kit fallback: when fontFile / outlineColor aren't passed, fall
+                // back to the kit so a single tool call can pick up channel defaults.
+                const brand = loadBrandKit(cwd);
+                const brandFont = pickBrandFont(cwd, brand?.fonts?.heading);
+                const brandOutline = brand?.colors?.primary;
+                const fontFile = args.fontFile ?? brandFont;
+                const outlineColor = args.outlineColor ?? brandOutline;
+                const brandKitLoaded = brand !== null;
+                const r = await composeThumbnailFrame({
+                    input: inAbs,
+                    output: resolved.path,
+                    atSec: args.atSec,
+                    text: args.text,
+                    fontFile,
+                    fontSize: args.fontSize,
+                    fontColor: args.fontColor,
+                    outlineColor,
+                    position: args.position,
+                    width: args.width,
+                    signal: ctx.signal,
+                }, cwd);
+                return compact({
+                    ok: true,
+                    path: r.path,
+                    atSec: args.atSec,
+                    fontFile: r.fontFile,
+                    brandKitLoaded,
+                    ...(resolved.redirected ? { redirected: true, reason: resolved.reason } : {}),
+                });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+// Re-exports for backwards compatibility — older tests import these from here.
+export { escapeDrawtextValue, pickFont };
+/**
+ * Resolve a brand-kit `fonts.heading` value to a readable absolute path.
+ * Returns undefined when the kit doesn't define one or the file is missing.
+ * Pure-ish (touches the filesystem) — exported for testing.
+ */
+export function pickBrandFont(cwd, heading) {
+    if (!heading)
+        return undefined;
+    const abs = resolvePath(cwd, heading);
+    try {
+        return existsSync(abs) ? abs : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=compose-thumbnail.js.map

package/dist/tools/compose-thumbnail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-thumbnail.js","sourceRoot":"","sources":["../../src/tools/compose-thumbnail.ts"],"names":[],"mappings":"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"}

package/dist/tools/concat-videos.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build the body for ffmpeg's concat-demuxer list file. Single-quotes the path
+ * and shell-escapes any embedded single quotes (`'` → `'\''`). Match the
+ * convention seen in real-world bash test fixtures (e.g. Xinrea/bili-shadowreplay).
+ */
+export declare function buildConcatListBody(paths: string[]): string;
+import { z } from "zod";
+import type { AgentTool } from "@prestyj/agent";
+declare const ConcatVideosParams: z.ZodObject<{
+    inputs: z.ZodArray<z.ZodString>;
+    output: z.ZodString;
+    lossless: z.ZodOptional<z.ZodBoolean>;
+    videoCodec: z.ZodOptional<z.ZodString>;
+    crf: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createConcatVideosTool(cwd: string): AgentTool<typeof ConcatVideosParams>;
+export {};
+//# sourceMappingURL=concat-videos.d.ts.map

package/dist/tools/concat-videos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat-videos.d.ts","sourceRoot":"","sources":["../../src/tools/concat-videos.ts"],"names":[],"mappings":"AAKA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AACD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAKhD,QAAA,MAAM,kBAAkB;;;;;;iBAatB,CAAC;AAEH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,kBAAkB,CAAC,CA6ExF"}

package/dist/tools/concat-videos.js

@@ -0,0 +1,87 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Build the body for ffmpeg's concat-demuxer list file. Single-quotes the path
+ * and shell-escapes any embedded single quotes (`'` → `'\''`). Match the
+ * convention seen in real-world bash test fixtures (e.g. Xinrea/bili-shadowreplay).
+ */
+export function buildConcatListBody(paths) {
+    return paths.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join("\n");
+}
+import { z } from "zod";
+import { compact, err } from "../core/format.js";
+import { checkFfmpeg, runFfmpeg } from "../core/media/ffmpeg.js";
+import { safeOutputPath } from "../core/safe-paths.js";
+const ConcatVideosParams = z.object({
+    inputs: z.array(z.string().min(1)).min(2).describe("Videos to join in order."),
+    output: z.string().describe("Concatenated output path."),
+    lossless: z
+        .boolean()
+        .optional()
+        .describe("If true, use the ffmpeg concat demuxer (no re-encode — fast, lossless). " +
+        "ALL sources must share codec, resolution, fps, sample rate. If you're not certain, " +
+        "leave false (default) — the filter-based concat re-encodes uniformly."),
+    videoCodec: z.string().optional().describe("When re-encoding: video codec. Default libx264."),
+    crf: z.number().int().min(0).max(51).optional().describe("When re-encoding: CRF. Default 20."),
+});
+export function createConcatVideosTool(cwd) {
+    return {
+        name: "concat_videos",
+        description: "Join videos end-to-end. Two modes: lossless (concat demuxer, requires uniform codec/" +
+            "resolution/fps/sample-rate) and re-encode (filter-based, always works). Common uses: " +
+            "intro + main + outro stitching, multi-take assembly, batch concat for upload.",
+        parameters: ConcatVideosParams,
+        async execute({ inputs, output, lossless, videoCodec, crf }, ctx) {
+            if (!checkFfmpeg())
+                return err("ffmpeg not on PATH", "install ffmpeg");
+            try {
+                const absInputs = inputs.map((p) => resolvePath(cwd, p));
+                const outAbs = safeOutputPath(cwd, output);
+                for (const a of absInputs) {
+                    if (a === outAbs)
+                        return err("output path collides with an input", "pick a different output");
+                }
+                mkdirSync(dirname(outAbs), { recursive: true });
+                if (lossless) {
+                    // concat demuxer: build a list file `file 'path'\n` and feed it.
+                    // The list file is a temp scratch artifact — clean it up no matter
+                    // how this branch exits (success, ffmpeg non-zero, or thrown error).
+                    const listPath = join(tmpdir(), `gg-concat-${Date.now()}.txt`);
+                    const body = buildConcatListBody(absInputs);
+                    writeFileSync(listPath, body, "utf8");
+                    try {
+                        const r = await runFfmpeg(["-f", "concat", "-safe", "0", "-i", listPath, "-c", "copy", outAbs], { signal: ctx.signal });
+                        if (r.code !== 0) {
+                            return err(`ffmpeg concat-demuxer exited ${r.code}`, "sources may differ in codec/res/fps; retry with lossless=false");
+                        }
+                        return compact({ ok: true, path: outAbs, mode: "lossless" });
+                    }
+                    finally {
+                        rmSync(listPath, { force: true });
+                    }
+                }
+                // Filter-based concat (re-encode).
+                const args = [];
+                for (const p of absInputs)
+                    args.push("-i", p);
+                const n = absInputs.length;
+                const filterParts = [];
+                for (let i = 0; i < n; i++)
+                    filterParts.push(`[${i}:v:0][${i}:a:0]`);
+                const filter = `${filterParts.join("")}concat=n=${n}:v=1:a=1[outv][outa]`;
+                args.push("-filter_complex", filter, "-map", "[outv]", "-map", "[outa]", "-c:v", videoCodec ?? "libx264", "-crf", String(crf ?? 20), "-c:a", "aac", "-b:a", "192k", outAbs);
+                const r = await runFfmpeg(args, { signal: ctx.signal });
+                if (r.code !== 0) {
+                    return err(`ffmpeg concat exited ${r.code}`);
+                }
+                return compact({ ok: true, path: outAbs, mode: "re-encode" });
+            }
+            catch (e) {
+                return err(e.message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=concat-videos.js.map

package/dist/tools/concat-videos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat-videos.js","sourceRoot":"","sources":["../../src/tools/concat-videos.ts"],"names":[],"mappings":"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"}

package/dist/tools/concat-videos.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=concat-videos.test.d.ts.map

package/dist/tools/concat-videos.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat-videos.test.d.ts","sourceRoot":"","sources":["../../src/tools/concat-videos.test.ts"],"names":[],"mappings":""}