@viralspin/mcp 0.1.0 → 0.2.2

package/dist/tools/timeline-edit.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keepWindowsTool = exports.removeSpansTool = exports.getTranscriptTool = exports.trimSilencesTool = exports.renderProjectTool = exports.reorderScenesTool = exports.removeSpanTool = exports.trimClipTool = void 0;
+/**
+ * Granular timeline edit verbs for a HOSTED Swap & Refine project (a narrative
+ * job). These widen Claude's editing vocabulary beyond swap — trim a cutaway,
+ * cut a span out of the cut, and reorder the A-roll's backbone scenes — each
+ * mapped to an already-deployed narrative endpoint, so the edit lands in the
+ * same project the web editor shows (and streams in live via realtime).
+ *
+ * All are hosted-only: they take a `job_id` (or VIRALSPIN_HOSTED_JOB_ID). There
+ * is no local-engine equivalent for these ops.
+ */
+const hosted_js_1 = require("../hosted.js");
+function fmt(sec) {
+    const m = Math.floor(sec / 60);
+    const s = Math.round(sec % 60);
+    return `${m}:${s.toString().padStart(2, "0")}`;
+}
+exports.trimClipTool = {
+    name: "trim_clip",
+    description: "Shorten (or restore) how long ONE B-roll cutaway stays on screen in a hosted Swap & Refine project, " +
+        "freeing that time back to the A-roll. Audio-safe — total video length is preserved. " +
+        "Get the segment id from suggest_clips. Instant timeline edit by default (no render); call render_project when done.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            segment_id: { type: "string", description: "The cutaway to trim (from suggest_clips)." },
+            duration_sec: { type: "number", description: "New on-screen duration in seconds (e.g. 1.5)." },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+        required: ["segment_id", "duration_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_clip is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.setClipDuration)(jobId, args.segment_id, args.duration_sec);
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Trimmed segment ${args.segment_id} to ${args.duration_sec}s and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Trimmed segment ${args.segment_id} to ${args.duration_sec}s (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.removeSpanTool = {
+    name: "remove_span",
+    description: "Cut a span of time [from_sec, to_sec] out of a hosted Swap & Refine video — e.g. a duplicated opening " +
+        "sentence or a dead pause. The backbone A-roll is trimmed and the rest shifts up; reuses cached B-roll. " +
+        "Re-renders; streams into the editor.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            from_sec: { type: "number", description: "Start of the span to remove (seconds)." },
+            to_sec: { type: "number", description: "End of the span to remove (seconds)." },
+        },
+        required: ["from_sec", "to_sec"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_span is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        if (!(args.to_sec > args.from_sec))
+            return "to_sec must be greater than from_sec.";
+        await (0, hosted_js_1.removeSpan)(jobId, args.from_sec, args.to_sec, true);
+        return (`Removing ${fmt(args.from_sec)}–${fmt(args.to_sec)} and re-rendering.\n` +
+            `Updating live: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.reorderScenesTool = {
+    name: "reorder_scenes",
+    description: "See or reorder the A-roll's backbone scenes in a hosted Swap & Refine project. " +
+        "Call with no `order` to LIST the scenes (id + label + time) — the reorderable building blocks. " +
+        "Call with `order` (the scene ids in the new running order; omit ids to drop them) to apply it and re-render.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            order: {
+                type: "array",
+                items: { type: "string" },
+                description: "New running order as scene ids. Any scene id omitted here is removed from the cut. Omit `order` entirely to just list the scenes.",
+            },
+            render: { type: "boolean", description: "Re-render now (costs credits). Default false = instant timeline-only edit." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "reorder_scenes is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const { scenes } = await (0, hosted_js_1.detectScenes)(jobId);
+        if (!scenes.length)
+            return `No backbone scenes detected for project ${jobId} yet. Open it: ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        if (!args.order || !args.order.length) {
+            const lines = [...scenes]
+                .sort((a, b) => a.order - b.order)
+                .map((s) => `- ${s.id}${s.label ? ` — "${s.label}"` : ""}${s.src_start != null ? ` (${fmt(s.src_start)}${s.src_end != null ? `–${fmt(s.src_end)}` : ""})` : ""}`);
+            return [
+                `Backbone scenes in ${(0, hosted_js_1.editorUrl)(jobId)} :`,
+                ...lines,
+                ``,
+                `Reorder with: reorder_scenes(job_id: "${jobId}", order: ["${scenes[0].id}", …]). Omit a scene id to drop it.`,
+            ].join("\n");
+        }
+        const known = new Set(scenes.map((s) => s.id));
+        const wanted = args.order.filter((id) => known.has(id));
+        if (!wanted.length)
+            return "None of the given ids matched this project's scenes — call reorder_scenes with no `order` to list valid ids.";
+        const payload = scenes.map((s) => {
+            const idx = wanted.indexOf(s.id);
+            return { id: s.id, order: idx === -1 ? 9999 : idx, removed: idx === -1 };
+        });
+        await (0, hosted_js_1.saveSceneOrder)(jobId, payload);
+        const dropped = scenes.length - wanted.length;
+        if (args.render) {
+            await (0, hosted_js_1.rerender)(jobId);
+            return `Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} and started a re-render. ${(0, hosted_js_1.editorUrl)(jobId)}`;
+        }
+        return (`Reordered to ${wanted.length} scene(s)${dropped ? ` (dropped ${dropped})` : ""} (instant, no render). ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `Call render_project(job_id: "${jobId}") when the cut is final.`);
+    },
+};
+exports.renderProjectTool = {
+    name: "render_project",
+    description: "Bake the current hosted Swap & Refine timeline into a final MP4 — the ONE cloud render after a batch of " +
+        "instant timeline edits (swap_clip / trim_clip / reorder_scenes). Captions, hook, overlays and motion are " +
+        "applied here. Costs a render/credits. Returns immediately; the finished preview lands on the project, then " +
+        "publish with publish_now or schedule_post.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "render_project is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        await (0, hosted_js_1.rerender)(jobId);
+        return (`Rendering the final cut for project ${jobId}.\n` +
+            `Watch it in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}\n` +
+            `When it finishes, publish with publish_now or schedule_post.`);
+    },
+};
+exports.trimSilencesTool = {
+    name: "trim_silences",
+    description: "Edit out the dead air / empty pauses in a hosted Swap & Refine project. Reads the transcript word " +
+        "timings, finds the silent gaps between spoken words (plus a long lead-in / trailing pause), and removes " +
+        "them to tighten the cut. It re-cuts the A-roll once per gap, so it can take a couple of minutes on a " +
+        "long clip — it does the BIGGEST gaps first (capped by max_cuts). Needs a transcribed talking-head A-roll.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            min_gap_sec: { type: "number", description: "Smallest pause to treat as dead air (default 0.7s). Lower = tighter." },
+            max_cuts: { type: "number", description: "Safety cap on how many gaps to remove this pass (default 12, biggest first)." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "trim_silences is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const minGap = args.min_gap_sec ?? 0.7;
+        const maxCuts = args.max_cuts ?? 12;
+        const PAD = 0.1;
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        const words = Array.isArray(tl.words) ? tl.words : [];
+        if (words.length < 2) {
+            return "No transcript word-timings on this project, so I can't detect silences (needs a transcribed talking-head A-roll).";
+        }
+        const total = Number(tl.total_duration_sec) || Number(words[words.length - 1]?.end) || 0;
+        const gaps = [];
+        // long lead-in pause
+        const firstStart = Number(words[0]?.start) || 0;
+        if (firstStart >= minGap + PAD)
+            gaps.push({ from: PAD, to: +(firstStart - PAD).toFixed(2), len: firstStart });
+        // gaps between words
+        for (let i = 0; i < words.length - 1; i++) {
+            const a = Number(words[i]?.end), b = Number(words[i + 1]?.start);
+            if (!Number.isFinite(a) || !Number.isFinite(b))
+                continue;
+            const len = b - a;
+            if (len >= minGap)
+                gaps.push({ from: +(a + PAD).toFixed(2), to: +(b - PAD).toFixed(2), len });
+        }
+        // trailing pause
+        const lastEnd = Number(words[words.length - 1]?.end) || 0;
+        if (total - lastEnd >= minGap + PAD)
+            gaps.push({ from: +(lastEnd + PAD).toFixed(2), to: +total.toFixed(2), len: total - lastEnd });
+        const valid = gaps.filter((g) => g.to - g.from >= 0.2);
+        if (!valid.length)
+            return `No silences ≥ ${minGap}s found — the cut is already tight.`;
+        // biggest gaps first (within the cap), then remove latest→earliest so each
+        // removal doesn't invalidate the earlier gaps' timestamps.
+        const chosen = [...valid].sort((a, b) => b.len - a.len).slice(0, maxCuts).sort((a, b) => b.from - a.from);
+        let removed = 0;
+        let ok = 0;
+        for (const g of chosen) {
+            try {
+                await (0, hosted_js_1.removeSpan)(jobId, g.from, g.to, false);
+                removed += g.to - g.from;
+                ok++;
+            }
+            catch (e) {
+                process.stderr.write(`[trim_silences] span ${g.from}-${g.to} failed: ${e instanceof Error ? e.message : e}\n`);
+            }
+        }
+        if (!ok)
+            return "Couldn't trim the silences — the backend rejected the spans. The project may not allow span removal yet.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const more = valid.length > chosen.length ? ` (${valid.length - chosen.length} smaller pause(s) left — run again or lower min_gap_sec)` : "";
+        return (`Trimmed ${ok} silent gap(s) — about ${removed.toFixed(1)}s of dead air${more} — and started a re-render.\n` +
+            `Watch it tighten in the editor: ${(0, hosted_js_1.editorUrl)(jobId)}`);
+    },
+};
+exports.getTranscriptTool = {
+    name: "get_transcript",
+    description: "Get the timestamped transcript of a hosted Swap & Refine project so YOU (the agent) can spot what to cut " +
+        "— bad takes, restarts ('let me start over'), repeated sentences, filler — or which moments are worth " +
+        "highlighting in a long talking/narrated video. Returns spoken segments with start/end times. Then act: " +
+        "remove_spans to cut bad parts, or keep_windows to keep only the highlight moments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "The Swap & Refine project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+        },
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "get_transcript is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const tl = job.timeline || {};
+        let segs = [];
+        if (Array.isArray(tl.transcript) && tl.transcript.length) {
+            segs = tl.transcript.map((s) => ({ a: Number(s.start_sec ?? s.start ?? 0), b: Number(s.end_sec ?? s.end ?? 0), text: String(s.text ?? "").trim() }));
+        }
+        else if (Array.isArray(tl.words) && tl.words.length) {
+            // group words into phrases on pauses > 0.5s
+            let cur = null;
+            for (const w of tl.words) {
+                const a = Number(w.start), b = Number(w.end), t = String(w.word ?? w.text ?? "");
+                if (!Number.isFinite(a))
+                    continue;
+                if (cur && a - cur.b > 0.5) {
+                    segs.push(cur);
+                    cur = null;
+                }
+                if (!cur)
+                    cur = { a, b, text: t };
+                else {
+                    cur.b = b;
+                    cur.text += (t.startsWith("'") ? "" : " ") + t;
+                }
+            }
+            if (cur)
+                segs.push(cur);
+        }
+        if (!segs.length)
+            return "No transcript on this project (needs a transcribed talking-head/narrated A-roll).";
+        const lines = segs.map((s) => `[${s.a.toFixed(1)}–${s.b.toFixed(1)}] ${s.text}`);
+        return [
+            `Transcript for ${jobId} (spot restarts / repeats / filler to cut, or highlight moments to keep):`,
+            ...lines,
+            ``,
+            `Cut bad spans: remove_spans(job_id: "${jobId}", spans: [{from_sec, to_sec}, …]).`,
+            `Keep only highlights: keep_windows(job_id: "${jobId}", windows: [{from_sec, to_sec}, …]).`,
+        ].join("\n");
+    },
+};
+/** Remove several spans (latest→earliest so earlier coords stay valid), one render. */
+async function removeMany(jobId, spans) {
+    const ordered = [...spans].filter((s) => s.to - s.from >= 0.15).sort((a, b) => b.from - a.from);
+    let ok = 0, removed = 0;
+    for (const s of ordered) {
+        try {
+            await (0, hosted_js_1.removeSpan)(jobId, +s.from.toFixed(2), +s.to.toFixed(2), false);
+            removed += s.to - s.from;
+            ok++;
+        }
+        catch (e) {
+            process.stderr.write(`[removeMany] ${s.from}-${s.to} failed: ${e instanceof Error ? e.message : e}\n`);
+        }
+    }
+    return { ok, removed };
+}
+exports.removeSpansTool = {
+    name: "remove_spans",
+    description: "Cut SEVERAL time spans out of a hosted project in one pass (e.g. bad takes / restarts you found via " +
+        "get_transcript), then re-render once. Spans are seconds of the current cut. Re-cuts the A-roll per span, " +
+        "so several takes a minute or two.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            spans: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "Spans to cut, each { from_sec, to_sec }.",
+            },
+        },
+        required: ["spans"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "remove_spans is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const spans = (args.spans || []).filter((s) => s && s.to_sec > s.from_sec).map((s) => ({ from: +s.from_sec, to: +s.to_sec }));
+        if (!spans.length)
+            return "No valid spans (each needs to_sec > from_sec).";
+        const { ok, removed } = await removeMany(jobId, spans);
+        if (!ok)
+            return "Couldn't remove the spans — the backend rejected them.";
+        await (0, hosted_js_1.rerender)(jobId);
+        return `Removed ${ok} span(s) — about ${removed.toFixed(1)}s — and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};
+exports.keepWindowsTool = {
+    name: "keep_windows",
+    description: "Turn a long video into a highlight reel: KEEP only the given time windows and cut everything else, then " +
+        "re-render. Great for 'find the worth-highlighting moments in this 10-min recording' — get_transcript, " +
+        "pick the punchy windows, then keep_windows. Windows are seconds of the current cut.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "Project. Omit to use VIRALSPIN_HOSTED_JOB_ID." },
+            windows: {
+                type: "array",
+                items: { type: "object", properties: { from_sec: { type: "number" }, to_sec: { type: "number" } }, required: ["from_sec", "to_sec"] },
+                description: "The moments to KEEP, each { from_sec, to_sec }. Everything outside them is cut.",
+            },
+        },
+        required: ["windows"],
+    },
+    async execute(args) {
+        const jobId = (0, hosted_js_1.hostedJobId)(args.job_id);
+        if (!jobId)
+            return "keep_windows is for hosted projects — pass `job_id` (or set VIRALSPIN_HOSTED_JOB_ID).";
+        const wins = (args.windows || []).filter((w) => w && w.to_sec > w.from_sec).map((w) => ({ from: +w.from_sec, to: +w.to_sec })).sort((a, b) => a.from - b.from);
+        if (!wins.length)
+            return "No valid windows to keep (each needs to_sec > from_sec).";
+        const job = await (0, hosted_js_1.getJob)(jobId);
+        const total = Number(job.timeline?.total_duration_sec) || wins[wins.length - 1].to;
+        // complement = everything outside the kept windows
+        const cuts = [];
+        if (wins[0].from > 0.15)
+            cuts.push({ from: 0, to: wins[0].from });
+        for (let i = 0; i < wins.length - 1; i++) {
+            if (wins[i + 1].from - wins[i].to > 0.15)
+                cuts.push({ from: wins[i].to, to: wins[i + 1].from });
+        }
+        if (total - wins[wins.length - 1].to > 0.15)
+            cuts.push({ from: wins[wins.length - 1].to, to: total });
+        if (!cuts.length)
+            return "The windows already cover the whole video — nothing to cut.";
+        const { ok, removed } = await removeMany(jobId, cuts);
+        if (!ok)
+            return "Couldn't trim to the windows — the backend rejected the spans.";
+        await (0, hosted_js_1.rerender)(jobId);
+        const kept = wins.reduce((s, w) => s + (w.to - w.from), 0);
+        return `Kept ${wins.length} highlight window(s) (~${kept.toFixed(1)}s), cut ~${removed.toFixed(1)}s, and started a re-render.\n${(0, hosted_js_1.editorUrl)(jobId)}`;
+    },
+};