@kenkaiiii/gg-editor 0.6.7 → 0.7.1

package/dist/core/clip-scoring.js

@@ -0,0 +1,165 @@
+/**
+ * Clip scoring — does this arbitrary window earn the watch?
+ *
+ * `analyze_hook` only scores the first 3 seconds (the algorithmic
+ * checkpoint). Once you're past the hook, the next questions are:
+ *
+ *   - Hook       — does the OPENER (first ~5s) earn the watch?
+ *   - Flow       — does the middle stay engaging without dragging?
+ *   - Engagement — emotional intensity, curiosity gap, payoff.
+ *   - Trend      — is the topic something currently shareable?
+ *
+ * One LLM call: transcript window in (and optional sample frames),
+ * structured 0-1 scores out, weighted total 0-100. Pure-ish — the
+ * scoring rubric, prompt template, parser and weighting all live here so
+ * `find_viral_moments` can reuse the engine without going through the
+ * tool wrapper.
+ */
+import { readFileSync } from "node:fs";
+import { resolveApiKey } from "./auth/api-keys.js";
+const DEFAULT_WEIGHTS = {
+    hook: 30,
+    flow: 25,
+    engagement: 30,
+    trend: 15,
+};
+const CLIP_SYSTEM = `You are a short-form video selector. Your job is to score a CLIP (transcript ± sample frames) on its potential to go viral as a standalone Short / Reel / TikTok.
+
+Output a JSON object with these EXACT keys (no extras, no prose):
+{
+  "hook":       <0..1>,
+  "flow":       <0..1>,
+  "engagement": <0..1>,
+  "trend":      <0..1>,
+  "why": "<≤160 char rationale: name the strongest + weakest dimension>"
+}
+
+Scoring rubric:
+
+hook        — Does the OPENING line earn the watch?
+  1.0 = strong scroll-stop opener (question, claim, shocking number, named subject);
+  0.5 = neutral lead; 0.0 = throat-clear / "so basically..." / dead air.
+
+flow        — Does the clip stay engaging across its full duration?
+  1.0 = every beat earns its time, no dragging, payoff lands;
+  0.5 = some slack but recovers; 0.0 = meanders / repeats / loses thread.
+
+engagement  — Emotional intensity, curiosity gap, surprise, payoff.
+  1.0 = strong emotional beat (laugh / shock / tension / aha);
+  0.5 = mildly interesting; 0.0 = flat informational.
+
+trend       — Topic currency. Does it intersect with what's currently
+  trending / evergreen-shareable on short-form?
+  1.0 = on-trend (AI, money, dating, fitness, productivity, gaming meta, current events);
+  0.5 = niche but proven shareable; 0.0 = obscure / dated / business-jargon.
+
+Be honest. A technically-clean but flat clip should score 0.3-0.4, not 0.6+.`;
+/**
+ * Robust parser — tolerates prose around the JSON, missing keys, and
+ * out-of-range numbers. Mirrors `parseHookVisionResponse`.
+ */
+export function parseClipScoreResponse(content) {
+    const start = content.indexOf("{");
+    const end = content.lastIndexOf("}");
+    if (start < 0 || end < start) {
+        throw new Error("clip-scoring: no JSON object in response");
+    }
+    const parsed = JSON.parse(content.slice(start, end + 1));
+    return {
+        hook: clamp01(num(parsed.hook, 0)),
+        flow: clamp01(num(parsed.flow, 0)),
+        engagement: clamp01(num(parsed.engagement, 0)),
+        trend: clamp01(num(parsed.trend, 0)),
+        why: String(parsed.why ?? "").slice(0, 240),
+    };
+}
+/**
+ * Combine the four 0-1 dimensions into a single 0-100 score, using the
+ * default (or caller-supplied) weights.
+ */
+export function combineClipScore(vision, durationSec, weights = {}) {
+    const w = { ...DEFAULT_WEIGHTS, ...weights };
+    const wSum = w.hook + w.flow + w.engagement + w.trend;
+    const raw = w.hook * vision.hook +
+        w.flow * vision.flow +
+        w.engagement * vision.engagement +
+        w.trend * vision.trend;
+    const score = Math.round((raw / wSum) * 100);
+    return {
+        score,
+        hook: vision.hook,
+        flow: vision.flow,
+        engagement: vision.engagement,
+        trend: vision.trend,
+        why: vision.why,
+        durationSec,
+    };
+}
+/**
+ * Run the LLM scoring pass. Frames are optional — transcript-only is
+ * the cheap default; pass frames when visual energy matters.
+ *
+ * Pure-ish: the only side effects are the OpenAI fetch and reading
+ * frame files off disk. Used directly by both the tool wrapper and
+ * `find_viral_moments`.
+ */
+export async function scoreClipInternal(transcriptText, startSec, endSec, framePaths = [], opts = {}) {
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey)
+        throw new Error("OPENAI_API_KEY required for score_clip.");
+    const durationSec = Math.max(0, endSec - startSec);
+    const detail = opts.detail ?? "low";
+    const model = opts.model ?? "gpt-4o-mini";
+    const userContent = [
+        {
+            type: "text",
+            text: `CLIP WINDOW: ${startSec.toFixed(2)}s → ${endSec.toFixed(2)}s ` +
+                `(${durationSec.toFixed(2)}s).\n\nTRANSCRIPT:\n${transcriptText.trim() || "(empty)"}`,
+        },
+    ];
+    for (const p of framePaths) {
+        const mime = p.toLowerCase().endsWith(".png") ? "image/png" : "image/jpeg";
+        const b64 = readFileSync(p).toString("base64");
+        userContent.push({
+            type: "image_url",
+            image_url: { url: `data:${mime};base64,${b64}`, detail },
+        });
+    }
+    const body = {
+        model,
+        messages: [
+            { role: "system", content: CLIP_SYSTEM },
+            { role: "user", content: userContent },
+        ],
+        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("score_clip: empty model response");
+    const parsed = parseClipScoreResponse(content);
+    return combineClipScore(parsed, durationSec, opts.weights);
+}
+// ── Helpers ─────────────────────────────────────────────────
+function num(v, fb) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) ? n : fb;
+}
+function clamp01(n) {
+    return Math.max(0, Math.min(1, n));
+}
+//# sourceMappingURL=clip-scoring.js.map

package/dist/core/clip-scoring.js.map

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

package/dist/core/clip-scoring.test.d.ts

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

package/dist/core/clip-scoring.test.d.ts.map

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

package/dist/core/clip-scoring.test.js

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { combineClipScore, parseClipScoreResponse, scoreClipInternal } from "./clip-scoring.js";
+describe("parseClipScoreResponse", () => {
+    it("parses a well-formed response", () => {
+        const r = parseClipScoreResponse(JSON.stringify({ hook: 0.8, flow: 0.7, engagement: 0.9, trend: 0.4, why: "strong open" }));
+        expect(r.hook).toBe(0.8);
+        expect(r.flow).toBe(0.7);
+        expect(r.engagement).toBe(0.9);
+        expect(r.trend).toBe(0.4);
+        expect(r.why).toContain("strong");
+    });
+    it("clamps out-of-range values to [0,1]", () => {
+        const r = parseClipScoreResponse(JSON.stringify({ hook: 99, flow: -5, engagement: 0.5, trend: 1 }));
+        expect(r.hook).toBe(1);
+        expect(r.flow).toBe(0);
+        expect(r.engagement).toBe(0.5);
+        expect(r.trend).toBe(1);
+    });
+    it("falls back to 0 on missing fields", () => {
+        const r = parseClipScoreResponse("{}");
+        expect(r.hook).toBe(0);
+        expect(r.flow).toBe(0);
+        expect(r.engagement).toBe(0);
+        expect(r.trend).toBe(0);
+    });
+    it("survives prose wrapping the JSON", () => {
+        const r = parseClipScoreResponse('pre {"hook":0.5,"flow":0.5,"engagement":0.5,"trend":0.5,"why":"x"} post');
+        expect(r.hook).toBe(0.5);
+    });
+    it("throws on totally absent JSON", () => {
+        expect(() => parseClipScoreResponse("no json here")).toThrow(/no JSON/);
+    });
+});
+describe("combineClipScore", () => {
+    it("produces 100 for max scores with default weights", () => {
+        const r = combineClipScore({ hook: 1, flow: 1, engagement: 1, trend: 1, why: "" }, 30);
+        expect(r.score).toBe(100);
+        expect(r.durationSec).toBe(30);
+    });
+    it("produces 0 for min scores", () => {
+        const r = combineClipScore({ hook: 0, flow: 0, engagement: 0, trend: 0, why: "" }, 30);
+        expect(r.score).toBe(0);
+    });
+    it("respects custom weights", () => {
+        // hook=1, others=0; with weights {hook:100, flow:0, engagement:0, trend:0}
+        // → 100. Default weights would put it at 30.
+        const r = combineClipScore({ hook: 1, flow: 0, engagement: 0, trend: 0, why: "" }, 30, {
+            hook: 100,
+            flow: 0,
+            engagement: 0,
+            trend: 0,
+        });
+        expect(r.score).toBe(100);
+    });
+});
+describe("scoreClipInternal", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        delete process.env.OPENAI_API_KEY;
+    });
+    it("throws when no API key is configured", async () => {
+        delete process.env.OPENAI_API_KEY;
+        await expect(scoreClipInternal("hello world", 0, 10)).rejects.toThrow(/OPENAI_API_KEY/);
+    });
+    it("calls OpenAI chat completions with json_object response format and parses the result", async () => {
+        process.env.OPENAI_API_KEY = "test-key";
+        let captured;
+        vi.stubGlobal("fetch", vi.fn(async (url, init) => {
+            captured = { url, body: JSON.parse(init?.body ?? "{}") };
+            return {
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    choices: [
+                        {
+                            message: {
+                                content: JSON.stringify({
+                                    hook: 0.8,
+                                    flow: 0.6,
+                                    engagement: 0.7,
+                                    trend: 0.5,
+                                    why: "tight open, payoff lands",
+                                }),
+                            },
+                        },
+                    ],
+                }),
+                text: async () => "",
+            };
+        }));
+        const r = await scoreClipInternal("a strong hook line", 5, 25);
+        expect(r.score).toBeGreaterThan(0);
+        expect(r.score).toBeLessThanOrEqual(100);
+        expect(r.hook).toBe(0.8);
+        expect(r.durationSec).toBe(20);
+        expect(captured?.url).toBe("https://api.openai.com/v1/chat/completions");
+        expect(captured?.body.response_format).toEqual({ type: "json_object" });
+        expect(captured?.body.temperature).toBe(0);
+    });
+    it("propagates HTTP errors with the OpenAI status", async () => {
+        process.env.OPENAI_API_KEY = "test-key";
+        vi.stubGlobal("fetch", vi.fn(async () => {
+            return {
+                ok: false,
+                status: 429,
+                text: async () => "rate limited",
+                json: async () => ({}),
+            };
+        }));
+        await expect(scoreClipInternal("hi", 0, 10)).rejects.toThrow(/429/);
+    });
+});
+//# sourceMappingURL=clip-scoring.test.js.map

package/dist/core/clip-scoring.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clip-scoring.test.js","sourceRoot":"","sources":["../../src/core/clip-scoring.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEhG,QAAQ,CAAC,wBAAwB,EAAE,GAAG,EAAE;IACtC,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,sBAAsB,CAC9B,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAC1F,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,GAAG,sBAAsB,CAC9B,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAClE,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,CAAC,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,GAAG,sBAAsB,CAC9B,yEAAyE,CAC1E,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,EAAE,CAAC,sBAAsB,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAChC,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,CAAC,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACvF,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;QACvF,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,2EAA2E;QAC3E,6CAA6C;QAC7C,MAAM,CAAC,GAAG,gBAAgB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;YACrF,IAAI,EAAE,GAAG;YACT,IAAI,EAAE,CAAC;YACP,UAAU,EAAE,CAAC;YACb,KAAK,EAAE,CAAC;SACT,CAAC,CAAC;QACH,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;QACpD,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QAClC,MAAM,MAAM,CAAC,iBAAiB,CAAC,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sFAAsF,EAAE,KAAK,IAAI,EAAE;QACpG,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,UAAU,CAAC;QACxC,IAAI,QAAoE,CAAC;QACzE,EAAE,CAAC,UAAU,CACX,OAAO,EACP,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,IAAwB,EAAE,EAAE;YACpD,QAAQ,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACzD,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;oBACjB,OAAO,EAAE;wBACP;4BACE,OAAO,EAAE;gCACP,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC;oCACtB,IAAI,EAAE,GAAG;oCACT,IAAI,EAAE,GAAG;oCACT,UAAU,EAAE,GAAG;oCACf,KAAK,EAAE,GAAG;oCACV,GAAG,EAAE,0BAA0B;iCAChC,CAAC;6BACH;yBACF;qBACF;iBACF,CAAC;gBACF,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,EAAE;aACE,CAAC;QAC3B,CAAC,CAAC,CACH,CAAC;QAEF,MAAM,CAAC,GAAG,MAAM,iBAAiB,CAAC,oBAAoB,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;QACzE,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;QACxE,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;QAC7D,OAAO,CAAC,GAAG,CAAC,cAAc,GAAG,UAAU,CAAC;QACxC,EAAE,CAAC,UAAU,CACX,OAAO,EACP,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE;YACf,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,cAAc;gBAChC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;aACA,CAAC;QAC3B,CAAC,CAAC,CACH,CAAC;QACF,MAAM,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/core/emoji-captions.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Emoji-injection pass for keyword captions.
+ *
+ * Submagic / CapCut have made the "💯 caption + 🔥 emoji" look the
+ * default vibe of viral short-form. Rather than ship a static emoji
+ * map, we ask the LLM (one call over ALL cues) for the single
+ * most-fitting emoji per cue (or empty when nothing clearly fits).
+ *
+ * Pure-ish: takes the OpenAI-style chat client as a dependency so the
+ * caller can swap in `fetch` directly OR mock it in tests.
+ */
+import type { AssCue } from "./ass.js";
+export type EmojiDensity = "low" | "med" | "high";
+export interface InjectEmojisOptions {
+    density?: EmojiDensity;
+    model?: string;
+    apiKey?: string;
+    signal?: AbortSignal;
+    /** Override fetch — for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface InjectEmojisResult {
+    cues: AssCue[];
+    /** Count of cues that received an emoji (excluding empty strings). */
+    injected: number;
+    /** When set, the LLM call failed and cues were returned unchanged. */
+    error?: string;
+}
+/**
+ * Inject emojis into a list of cues via one LLM call. On failure
+ * (network down, malformed response, length mismatch) we return the
+ * cues UNCHANGED + populate `error` so the caller can surface it.
+ *
+ * For density="high" the emoji is rendered on its own line ABOVE the
+ * caption text (separated by ASS's `\\N` break) for the stacked CapCut
+ * look. For low/med it's appended inline.
+ */
+export declare function injectEmojis(cues: AssCue[], opts?: InjectEmojisOptions): Promise<InjectEmojisResult>;
+/**
+ * Tolerant parser. Accepts either {emojis: [...]} or a bare array, pads
+ * / truncates to `expected` length so length always lines up. Exported
+ * for testing.
+ */
+export declare function parseEmojiResponse(content: string, expected: number): string[];
+//# sourceMappingURL=emoji-captions.d.ts.map

package/dist/core/emoji-captions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emoji-captions.d.ts","sourceRoot":"","sources":["../../src/core/emoji-captions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGvC,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAgBD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAgE7B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAsB9E"}

package/dist/core/emoji-captions.js

@@ -0,0 +1,121 @@
+import { resolveApiKey } from "./auth/api-keys.js";
+const SYSTEM = `You are an emoji selector for short-form video captions. For each caption line, return the SINGLE most-fitting emoji or an empty string when nothing clearly fits.
+
+Rules:
+- Output JSON: {"emojis": [string, ...]} aligned 1-to-1 with the input order. Length MUST equal the input length.
+- Each entry is a single emoji character (e.g. "🔥") or "". No multi-emoji entries, no text.
+- Don't force emojis where they'd feel random — empty string is the right answer ~half the time.
+- Match the density target the user specifies.`;
+const DENSITY_TARGETS = {
+    low: "Roughly 1 in 4 cues should get an emoji. Be very selective — only when an emoji genuinely amplifies the line.",
+    med: "Roughly 1 in 2 cues should get an emoji. Pick the obvious wins; leave neutral lines empty.",
+    high: "Every cue should get an emoji where ANY emoji fits. Empty only for purely connective lines.",
+};
+/**
+ * Inject emojis into a list of cues via one LLM call. On failure
+ * (network down, malformed response, length mismatch) we return the
+ * cues UNCHANGED + populate `error` so the caller can surface it.
+ *
+ * For density="high" the emoji is rendered on its own line ABOVE the
+ * caption text (separated by ASS's `\\N` break) for the stacked CapCut
+ * look. For low/med it's appended inline.
+ */
+export async function injectEmojis(cues, opts = {}) {
+    if (cues.length === 0)
+        return { cues, injected: 0 };
+    const density = opts.density ?? "med";
+    const model = opts.model ?? "gpt-4o-mini";
+    const apiKey = opts.apiKey ?? resolveApiKey("OPENAI_API_KEY", "openai");
+    if (!apiKey) {
+        return { cues, injected: 0, error: "OPENAI_API_KEY not set" };
+    }
+    const numbered = cues.map((c, i) => `${i + 1}. ${c.text}`).join("\n");
+    const userText = `Density target: ${DENSITY_TARGETS[density]}\n\n` +
+        `Return exactly ${cues.length} entries.\n\n` +
+        `CAPTIONS:\n${numbered}`;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let emojis;
+    try {
+        const res = await fetchImpl("https://api.openai.com/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                model,
+                messages: [
+                    { role: "system", content: SYSTEM },
+                    { role: "user", content: userText },
+                ],
+                response_format: { type: "json_object" },
+                temperature: 0,
+            }),
+            signal: opts.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            return {
+                cues,
+                injected: 0,
+                error: `OpenAI HTTP ${res.status}: ${text.slice(0, 160)}`,
+            };
+        }
+        const data = (await res.json());
+        const content = data.choices?.[0]?.message?.content ?? "";
+        emojis = parseEmojiResponse(content, cues.length);
+    }
+    catch (e) {
+        return { cues, injected: 0, error: e.message };
+    }
+    if (emojis.length !== cues.length) {
+        return { cues, injected: 0, error: "emoji count mismatch" };
+    }
+    let injected = 0;
+    const out = cues.map((c, i) => {
+        const e = (emojis[i] ?? "").trim();
+        if (!e)
+            return c;
+        injected++;
+        const text = density === "high" ? `${e}\\N${c.text}` : `${c.text} ${e}`;
+        return { ...c, text };
+    });
+    return { cues: out, injected };
+}
+/**
+ * Tolerant parser. Accepts either {emojis: [...]} or a bare array, pads
+ * / truncates to `expected` length so length always lines up. Exported
+ * for testing.
+ */
+export function parseEmojiResponse(content, expected) {
+    let arr;
+    try {
+        const obj = JSON.parse(content);
+        if (Array.isArray(obj))
+            arr = obj;
+        else if (typeof obj === "object" && obj !== null) {
+            const v = obj.emojis;
+            arr = Array.isArray(v) ? v : [];
+        }
+        else
+            arr = [];
+    }
+    catch {
+        const m = content.match(/\[[\s\S]*\]/);
+        if (m) {
+            try {
+                arr = JSON.parse(m[0]);
+            }
+            catch {
+                arr = [];
+            }
+        }
+        else
+            arr = [];
+    }
+    const list = Array.isArray(arr) ? arr.map((v) => (typeof v === "string" ? v : "")) : [];
+    while (list.length < expected)
+        list.push("");
+    return list.slice(0, expected);
+}
+//# sourceMappingURL=emoji-captions.js.map

package/dist/core/emoji-captions.js.map

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

package/dist/core/face-reframe.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Face-tracked reframe — pure planning + ffmpeg-filter synthesis.
+ *
+ * `analyzeReframe` shells out to the MediaPipe / PySceneDetect sidecar to get
+ * a per-shot smoothed face centre. `buildReframeFilter` is a pure function
+ * that compiles the plan into a single ffmpeg `crop=...` expression that
+ * follows the subject across shots. Splitting the heavy I/O from the
+ * filter math keeps the latter unit-testable without Python installed.
+ */
+export type Aspect = "9:16" | "1:1" | "4:5" | "16:9";
+export interface AspectRatio {
+    /** Width side of the ratio (e.g. 9 for 9:16). */
+    w: number;
+    /** Height side of the ratio (e.g. 16 for 9:16). */
+    h: number;
+}
+export declare function parseAspect(aspect: Aspect): AspectRatio;
+export interface ReframeFrameSample {
+    atSec: number;
+    faceCx: number;
+    faceCy: number;
+    faceW: number;
+    faceH: number;
+}
+export type ShotMode = "face" | "motion" | "static";
+export interface ReframeShot {
+    startSec: number;
+    endSec: number;
+    frames: ReframeFrameSample[];
+    /** Smoothed centre X (normalized 0-1). */
+    smoothedX: number;
+    /** Smoothed centre Y (normalized 0-1). */
+    smoothedY: number;
+    mode: ShotMode;
+}
+export interface ReframePlan {
+    shots: ReframeShot[];
+    totalSec: number;
+    fps: number;
+    sourceWidth: number;
+    sourceHeight: number;
+}
+export interface AnalyzeReframeOptions {
+    signal?: AbortSignal;
+    /** Frames per second to face-detect. Default 5. */
+    sampleFps?: number;
+    /** MediaPipe min_detection_confidence. Default 0.5. */
+    minDetectionConfidence?: number;
+    /** Smoothing window in seconds (informational; sidecar uses median). Default 0.5. */
+    smoothingWindowSec?: number;
+}
+/**
+ * Spawn the face-reframe sidecar; return the parsed shot plan.
+ * Throws on sidecar failure with the structured error embedded.
+ */
+export declare function analyzeReframe(videoPath: string, opts?: AnalyzeReframeOptions): Promise<ReframePlan>;
+export interface BuildReframeFilterResult {
+    /** ffmpeg `-vf` value (already includes both crop + scale). */
+    filter: string;
+    /** Output width (after crop, before scale-back). */
+    outWidth: number;
+    /** Output height (after crop, before scale-back). */
+    outHeight: number;
+    /** Per-shot crop X positions (after clamping into [0, srcW-outW]). */
+    shotXs: number[];
+}
+/**
+ * Compute the crop dimensions for a target aspect when cropping FROM a
+ * source frame. The crop is sized to fit ENTIRELY inside the source — i.e.
+ * we letterbox neither dimension. The returned `outW` × `outH` matches the
+ * target aspect exactly.
+ *
+ * Pure / unit-testable.
+ */
+export declare function reframeCropSize(srcW: number, srcH: number, aspect: Aspect): {
+    outW: number;
+    outH: number;
+};
+/**
+ * Compile a per-shot smoothed-face plan into one ffmpeg `crop` expression
+ * that switches X position by timestamp. Each shot contributes one
+ * `if(between(t, a, b), x_i, ...)` tier; the outermost ELSE is a centre
+ * crop so the filter is a no-op outside any defined shot.
+ *
+ * The crop's Y is left static (we don't currently track vertical motion;
+ * faces tend to dominate the upper third on portrait crops anyway).
+ *
+ * Pure / unit-testable. No ffmpeg execution.
+ */
+export declare function buildReframeFilter(plan: ReframePlan, aspect: Aspect): BuildReframeFilterResult;
+//# sourceMappingURL=face-reframe.d.ts.map

package/dist/core/face-reframe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"face-reframe.d.ts","sourceRoot":"","sources":["../../src/core/face-reframe.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,CAAC,EAAE,MAAM,CAAC;IACV,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAMvD;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qFAAqF;IACrF,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,WAAW,CAAC,CAiCtB;AAED,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6BhC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,wBAAwB,CAsC9F"}