@kenkaiiii/gg-editor 0.7.0 → 0.7.2

package/dist/core/srt.js

@@ -14,15 +14,35 @@
  * CRLF line endings are NOT required by the spec — most parsers accept LF
  * (we emit LF for simplicity and cross-platform sanity).
  *
- * Input is a list of cues with seconds-precision start/end. Empty `text`
- * cues are skipped (an empty cue is invalid SRT).
+ * ── Precision policy ─────────────────────────────────────────
+ * SRT's wire precision is exactly 1ms. We canonicalise every timestamp to a
+ * non-negative INTEGER millisecond at the boundary of this module:
+ *
+ *   secondsToMs(s) = Math.max(0, Math.round(s * 1000))
+ *
+ * All downstream math (cue ordering, gap extension, end>start validation,
+ * grouping) runs on those ms-ints. This eliminates two whole classes of
+ * float-arithmetic bugs:
+ *
+ *   1. Cues whose float `end > start` but whose ms-rounded values collide
+ *      (e.g. start=0.1001, end=0.1004 → both round to 100). The float check
+ *      would pass, then we'd emit `00:00:00,100 --> 00:00:00,100` — invalid.
+ *   2. Drift when extending a cue's end up to the next cue's start: float
+ *      assignment can carry a 1e-15 epsilon that flips a Math.round at the
+ *      ms boundary. Integer assignment is exact.
+ *
+ * Callers pass seconds (the natural unit for whisper / OpenAI output); the
+ * conversion happens exactly once per timestamp, here. If you already have
+ * ms-ints upstream, use `formatSrtTimeMs` directly to skip the round trip.
  */
 /**
  * Word-level SRT — one cue per word. Useful for vertical-format burned-in
  * captions where each word pops as it's spoken.
  *
  * Behaviour:
- *   - Skips empty / zero-duration words.
+ *   - Skips empty / zero-duration words (post-rounding, so 0.1001s/0.1004s
+ *     pairs that collapse to the same ms are dropped instead of producing
+ *     invalid same-stamp cues).
  *   - Optional `groupSize` clusters N consecutive words into one cue (e.g. 2-3
  *     words at a time for a more readable rhythm). Default 1.
  *   - Optional `gapSec` extends a cue's end up to the next cue's start so the
@@ -30,61 +50,110 @@
  */
 export function buildWordLevelSrt(words, opts = {}) {
     const groupSize = Math.max(1, Math.floor(opts.groupSize ?? 1));
-    const filled = words.filter((w) => (w.text ?? "").trim() && w.end > w.start);
+    const filled = [];
+    for (const w of words) {
+        const text = (w.text ?? "").trim();
+        if (!text)
+            continue;
+        const startMs = secondsToMs(w.start);
+        const endMs = secondsToMs(w.end);
+        if (endMs <= startMs)
+            continue;
+        filled.push({ startMs, endMs, text });
+    }
     const cues = [];
     for (let i = 0; i < filled.length; i += groupSize) {
         const group = filled.slice(i, i + groupSize);
         cues.push({
-            start: group[0].start,
-            end: group[group.length - 1].end,
-            text: group.map((g) => g.text.trim()).join(" "),
+            startMs: group[0].startMs,
+            endMs: group[group.length - 1].endMs,
+            text: group.map((g) => g.text).join(" "),
         });
     }
     if (opts.gapSec !== undefined && opts.gapSec >= 0) {
+        const gapMs = secondsToMs(opts.gapSec);
         for (let i = 0; i < cues.length - 1; i += 1) {
-            const gap = cues[i + 1].start - cues[i].end;
-            if (gap > 0 && gap <= opts.gapSec) {
-                cues[i].end = cues[i + 1].start;
+            const gap = cues[i + 1].startMs - cues[i].endMs;
+            if (gap > 0 && gap <= gapMs) {
+                // Integer assignment — no float epsilon to lose.
+                cues[i].endMs = cues[i + 1].startMs;
             }
         }
     }
-    return buildSrt(cues);
+    return buildFromIntCues(cues);
 }
-/** Build an SRT string from cues. Cues are emitted in input order. */
+/**
+ * Build an SRT string from cues. Cues are emitted in input order. Throws on
+ * cues that collapse to zero or negative duration AFTER ms-rounding —
+ * upstream code is expected to handle that ahead of time.
+ */
 export function buildSrt(cues) {
+    const intCues = cues.map((c) => ({
+        startMs: secondsToMs(c.start),
+        endMs: secondsToMs(c.end),
+        text: (c.text ?? "").trim(),
+    }));
+    // Validate each non-empty cue; matches the previous public contract of
+    // throwing when end <= start, but now in ms-int space so the error message
+    // reflects what would actually have been emitted.
+    let ordinal = 0;
+    for (const c of intCues) {
+        if (!c.text)
+            continue;
+        ordinal += 1;
+        if (c.endMs <= c.startMs) {
+            throw new Error(`cue ${ordinal}: end (${msToSrtTime(c.endMs)}) must be > start (${msToSrtTime(c.startMs)})`);
+        }
+    }
+    return buildFromIntCues(intCues);
+}
+/** Internal: skip empty-text cues, format the rest. */
+function buildFromIntCues(cues) {
     const out = [];
     let n = 0;
     for (const cue of cues) {
-        const text = (cue.text ?? "").trim();
-        if (!text)
+        if (!cue.text)
             continue;
-        if (cue.end <= cue.start) {
-            throw new Error(`cue ${n + 1}: end (${cue.end}) must be > start (${cue.start})`);
-        }
+        if (cue.endMs <= cue.startMs)
+            continue; // Defensive — public callers also validate.
         n += 1;
         out.push(String(n));
-        out.push(`${formatSrtTime(cue.start)} --> ${formatSrtTime(cue.end)}`);
-        out.push(text);
+        out.push(`${msToSrtTime(cue.startMs)} --> ${msToSrtTime(cue.endMs)}`);
+        out.push(cue.text);
         out.push("");
     }
     return out.join("\n");
 }
-/** Format seconds → "HH:MM:SS,mmm" (SRT timestamp). */
+/** Format seconds → "HH:MM:SS,mmm" (SRT timestamp). Single rounding step. */
 export function formatSrtTime(seconds) {
-    if (!Number.isFinite(seconds) || seconds < 0)
-        seconds = 0;
-    const totalMs = Math.round(seconds * 1000);
-    const ms = totalMs % 1000;
-    const totalSec = Math.floor(totalMs / 1000);
+    return msToSrtTime(secondsToMs(seconds));
+}
+/**
+ * Format ms-int → "HH:MM:SS,mmm". Use this when you already have ms-int
+ * timing (e.g. straight off whisper.cpp's `offsets.from`) to avoid an
+ * unnecessary round-trip through float seconds.
+ */
+export function msToSrtTime(ms) {
+    if (!Number.isFinite(ms) || ms < 0)
+        ms = 0;
+    ms = Math.round(ms); // Defensive — callers should pass integers.
+    const milli = ms % 1000;
+    const totalSec = Math.floor(ms / 1000);
     const ss = totalSec % 60;
     const mm = Math.floor(totalSec / 60) % 60;
     const hh = Math.floor(totalSec / 3600);
-    return (String(hh).padStart(2, "0") +
-        ":" +
-        String(mm).padStart(2, "0") +
-        ":" +
-        String(ss).padStart(2, "0") +
-        "," +
-        String(ms).padStart(3, "0"));
+    return pad2(hh) + ":" + pad2(mm) + ":" + pad2(ss) + "," + String(milli).padStart(3, "0");
+}
+/**
+ * Convert float seconds → integer milliseconds with the same rounding rule
+ * used everywhere in this module. Negative inputs and NaN clamp to 0.
+ */
+export function secondsToMs(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return 0;
+    return Math.round(seconds * 1000);
+}
+function pad2(n) {
+    return n < 10 ? "0" + n : String(n);
 }
 //# sourceMappingURL=srt.js.map

package/dist/core/srt.js.map

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

package/dist/core/srt.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { buildSrt, buildWordLevelSrt, formatSrtTime } from "./srt.js";
+import { buildSrt, buildWordLevelSrt, formatSrtTime, msToSrtTime, secondsToMs } from "./srt.js";
 describe("formatSrtTime", () => {
     it("formats zero", () => {
         expect(formatSrtTime(0)).toBe("00:00:00,000");
@@ -13,6 +13,36 @@ describe("formatSrtTime", () => {
     it("clamps negatives to zero", () => {
         expect(formatSrtTime(-3)).toBe("00:00:00,000");
     });
+    it("clamps NaN / Infinity to zero", () => {
+        expect(formatSrtTime(Number.NaN)).toBe("00:00:00,000");
+        expect(formatSrtTime(Number.POSITIVE_INFINITY)).toBe("00:00:00,000");
+    });
+    it("rounds half away from zero at the ms boundary", () => {
+        // 1.2345s → 1234.5ms → round to 1235 (Math.round rule).
+        expect(formatSrtTime(1.2345)).toBe("00:00:01,235");
+    });
+    it("survives float multiplication artifacts", () => {
+        // 0.1 + 0.2 = 0.30000000000000004 in IEEE-754; must still emit 300ms.
+        expect(formatSrtTime(0.1 + 0.2)).toBe("00:00:00,300");
+    });
+});
+describe("secondsToMs / msToSrtTime", () => {
+    it("secondsToMs rounds half-away-from-zero", () => {
+        expect(secondsToMs(0)).toBe(0);
+        expect(secondsToMs(0.0005)).toBe(1);
+        expect(secondsToMs(0.0014)).toBe(1);
+        expect(secondsToMs(35.123)).toBe(35123);
+    });
+    it("secondsToMs clamps negatives, NaN, Infinity to 0", () => {
+        expect(secondsToMs(-1)).toBe(0);
+        expect(secondsToMs(Number.NaN)).toBe(0);
+        expect(secondsToMs(Number.POSITIVE_INFINITY)).toBe(0);
+    });
+    it("msToSrtTime accepts pre-converted integer ms (no float round-trip)", () => {
+        expect(msToSrtTime(0)).toBe("00:00:00,000");
+        expect(msToSrtTime(35123)).toBe("00:00:35,123");
+        expect(msToSrtTime(3661234)).toBe("01:01:01,234");
+    });
 });
 describe("buildWordLevelSrt", () => {
     it("emits one cue per word by default", () => {
@@ -61,6 +91,22 @@ describe("buildWordLevelSrt", () => {
         expect(out).toContain("2\n00:00:00,300 --> 00:00:00,600\nb");
         expect(out).not.toContain("3\n");
     });
+    it("drops words whose ms-rounded duration collapses to zero", () => {
+        const out = buildWordLevelSrt([
+            { start: 0, end: 0.3, text: "keep" },
+            // start=0.3001, end=0.3004 — both round to 300ms. Drop silently rather
+            // than emit invalid `00:00:00,300 --> 00:00:00,300`.
+            { start: 0.3001, end: 0.3004, text: "drop" },
+            { start: 0.4, end: 0.6, text: "keep2" },
+        ]);
+        expect(out).toContain("keep");
+        expect(out).toContain("keep2");
+        expect(out).not.toContain("drop");
+        // Numbering must be contiguous (1, 2 — not 1, 3).
+        expect(out).toContain("1\n");
+        expect(out).toContain("2\n");
+        expect(out).not.toContain("3\n");
+    });
 });
 describe("buildSrt", () => {
     it("emits 1-indexed cues with HH:MM:SS,mmm timestamps", () => {
@@ -99,6 +145,13 @@ describe("buildSrt", () => {
         expect(() => buildSrt([{ start: 5, end: 5, text: "x" }])).toThrow(/end/);
         expect(() => buildSrt([{ start: 5, end: 4, text: "x" }])).toThrow(/end/);
     });
+    it("rejects cues whose float end>start collapses to the same ms-int", () => {
+        // start=0.1001, end=0.1004 — both round to 100ms. Float check would
+        // pass, but the SRT line `00:00:00,100 --> 00:00:00,100` is invalid
+        // (zero displayed duration). Must throw, matching the post-rounding
+        // wire reality.
+        expect(() => buildSrt([{ start: 0.1001, end: 0.1004, text: "x" }])).toThrow(/end/);
+    });
     it("returns empty string for no usable cues", () => {
         expect(buildSrt([])).toBe("");
         expect(buildSrt([{ start: 0, end: 1, text: "" }])).toBe("");

package/dist/core/srt.test.js.map

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

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

@@ -0,0 +1,58 @@
+/**
+ * Pure helper for composing a single thumbnail frame: pull a frame at
+ * `atSec` and burn a headline on top with ffmpeg drawtext.
+ *
+ * Extracted from compose-thumbnail.ts so `compose_thumbnail_variants`
+ * can call the same logic three times without duplicating the drawtext
+ * filter construction.
+ */
+export interface ComposeThumbnailOpts {
+    /** Source video path (already absolute or pre-resolved). */
+    input: string;
+    /** Output .jpg/.png absolute path. */
+    output: string;
+    /** Frame timestamp. */
+    atSec: number;
+    /** Headline text overlay (raw — escaping is handled internally). */
+    text: string;
+    /** Path to a TTF font; falls back to common system locations. */
+    fontFile?: string;
+    fontSize?: number;
+    fontColor?: string;
+    /** Empty string disables outline. Default 'black'. */
+    outlineColor?: string;
+    position?: "top" | "center" | "bottom";
+    /** Optional output width (height auto). */
+    width?: number;
+    signal?: AbortSignal;
+}
+export interface ComposeThumbnailResult {
+    ok: true;
+    path: string;
+    fontFile: string;
+}
+/**
+ * Burn a headline onto a single frame from the source video and write
+ * it to disk. Returns the resolved font path so callers can surface it
+ * in their output.
+ *
+ * Throws on:
+ *   - no system font found (and none provided)
+ *   - ffmpeg drawtext exit ≠ 0
+ */
+export declare function composeThumbnailFrame(opts: ComposeThumbnailOpts, cwd?: string): Promise<ComposeThumbnailResult>;
+export declare function pickFont(): string | undefined;
+/**
+ * Escape a string for ffmpeg drawtext's `text='...'` parameter.
+ *
+ * Rules (verified against real-world implementations):
+ *   1. `\\` first  → `\\\\`
+ *   2. `:`         → `\\:`
+ *   3. `'`         → `\\'`
+ *   4. `%`         → `\\%`  (because `%{...}` is used for runtime expansions)
+ *   5. newlines    → literal `\\n` (drawtext renders as a line break)
+ *
+ * Backslash MUST come first so subsequent escapes don't double-escape.
+ */
+export declare function escapeDrawtextValue(text: string): string;
+//# sourceMappingURL=thumbnail-compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-compose.d.ts","sourceRoot":"","sources":["../../src/core/thumbnail-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACvC,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAUD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,oBAAoB,EAC1B,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,sBAAsB,CAAC,CA8CjC;AAED,wBAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAS7C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD"}

package/dist/core/thumbnail-compose.js

@@ -0,0 +1,101 @@
+/**
+ * Pure helper for composing a single thumbnail frame: pull a frame at
+ * `atSec` and burn a headline on top with ffmpeg drawtext.
+ *
+ * Extracted from compose-thumbnail.ts so `compose_thumbnail_variants`
+ * can call the same logic three times without duplicating the drawtext
+ * filter construction.
+ */
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { runFfmpeg } from "./media/ffmpeg.js";
+const SYSTEM_FONT_GUESSES = [
+    "/System/Library/Fonts/Helvetica.ttc",
+    "/System/Library/Fonts/Supplemental/Arial.ttf",
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+    "/usr/share/fonts/TTF/DejaVuSans-Bold.ttf",
+    "C:\\Windows\\Fonts\\Arial.ttf",
+];
+/**
+ * Burn a headline onto a single frame from the source video and write
+ * it to disk. Returns the resolved font path so callers can surface it
+ * in their output.
+ *
+ * Throws on:
+ *   - no system font found (and none provided)
+ *   - ffmpeg drawtext exit ≠ 0
+ */
+export async function composeThumbnailFrame(opts, cwd = process.cwd()) {
+    const fontFile = opts.fontFile ? resolvePath(cwd, opts.fontFile) : pickFont();
+    if (!fontFile) {
+        throw new Error("no system font found — pass fontFile=<path-to-.ttf> (~/Library/Fonts on macOS, /usr/share/fonts on Linux)");
+    }
+    const fontSize = opts.fontSize ?? 96;
+    const fontColor = opts.fontColor ?? "white";
+    const outlineColor = opts.outlineColor === "" ? "" : (opts.outlineColor ?? "black");
+    const pos = opts.position ?? "bottom";
+    const yExpr = pos === "top" ? "h*0.08" : pos === "center" ? "(h-text_h)/2" : "h-text_h-h*0.08";
+    const safeText = escapeDrawtextValue(opts.text);
+    const drawText = `drawtext=fontfile=${escapeFilterPath(fontFile)}:` +
+        `text='${safeText}':` +
+        `fontsize=${fontSize}:` +
+        `fontcolor=${fontColor}:` +
+        `x=(w-text_w)/2:` +
+        `y=${yExpr}` +
+        (outlineColor ? `:bordercolor=${outlineColor}:borderw=4` : "");
+    const vf = opts.width ? `scale=${opts.width}:-1,${drawText}` : drawText;
+    mkdirSync(dirname(opts.output), { recursive: true });
+    const r = await runFfmpeg([
+        "-ss",
+        String(opts.atSec),
+        "-i",
+        opts.input,
+        "-frames:v",
+        "1",
+        "-vf",
+        vf,
+        "-q:v",
+        "2",
+        opts.output,
+    ], { signal: opts.signal });
+    if (r.code !== 0) {
+        throw new Error(`ffmpeg drawtext exited ${r.code} — verify atSec is in range and ffmpeg has --enable-libfreetype`);
+    }
+    return { ok: true, path: opts.output, fontFile };
+}
+export function pickFont() {
+    for (const p of SYSTEM_FONT_GUESSES) {
+        try {
+            if (existsSync(p))
+                return p;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return undefined;
+}
+function escapeFilterPath(p) {
+    return p.replace(/\\/g, "\\\\").replace(/:/g, "\\:").replace(/'/g, "\\'");
+}
+/**
+ * Escape a string for ffmpeg drawtext's `text='...'` parameter.
+ *
+ * Rules (verified against real-world implementations):
+ *   1. `\\` first  → `\\\\`
+ *   2. `:`         → `\\:`
+ *   3. `'`         → `\\'`
+ *   4. `%`         → `\\%`  (because `%{...}` is used for runtime expansions)
+ *   5. newlines    → literal `\\n` (drawtext renders as a line break)
+ *
+ * Backslash MUST come first so subsequent escapes don't double-escape.
+ */
+export function escapeDrawtextValue(text) {
+    return text
+        .replace(/\\/g, "\\\\")
+        .replace(/:/g, "\\:")
+        .replace(/'/g, "\\'")
+        .replace(/%/g, "\\%")
+        .replace(/\r\n?|\n/g, "\\n");
+}
+//# sourceMappingURL=thumbnail-compose.js.map

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

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

package/dist/core/thumbnail-promise.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Thumbnail-promise verifier.
+ *
+ * The thumbnail makes a visual promise (a man underwater, a huge pile
+ * of money, a broken phone). Per the MrBeast manual: "match the
+ * clickbait expectations and front-load." If the promised element
+ * doesn't show up until minute 8, retention craters before the payoff.
+ *
+ * This module asks the vision model to:
+ *   1. Look at the thumbnail FIRST and identify the visual promise.
+ *   2. Look at N sampled frames from the opening window.
+ *   3. Score how well those frames deliver on (or build up to) the
+ *      promise.
+ *
+ * One LLM call, structured JSON out. Pure parser exported for tests.
+ */
+export interface ThumbnailPromiseResult {
+    /** 0..1 — how well the opening delivers on the thumbnail's visual promise. */
+    matches: number;
+    /** ≤200 char description of what the thumbnail is promising. */
+    thumbnailPromise: string;
+    /** ≤200 char description of what the opening frames actually show. */
+    openingShows: string;
+    /** Up to 4 specific elements promised by the thumbnail but missing from the opening. */
+    missing: string[];
+    /** ≤200 char actionable suggestion. */
+    suggestion: string;
+}
+export interface VerifyOptions {
+    apiKey?: string;
+    model?: string;
+    detail?: "low" | "high";
+    /** Window length used to sample frames; surfaced in the prompt for context. */
+    windowSec: number;
+    signal?: AbortSignal;
+}
+/**
+ * Run ONE vision call against the thumbnail + N opening frames.
+ */
+export declare function runThumbnailPromise(thumbnailPath: string, framePaths: string[], opts: VerifyOptions): Promise<ThumbnailPromiseResult>;
+/**
+ * Parse the model's JSON. Robust to missing keys; clamps `matches` to
+ * [0, 1] and caps strings. Pure — exported for testing.
+ */
+export declare function parsePromiseResponse(content: string): ThumbnailPromiseResult;
+//# sourceMappingURL=thumbnail-promise.d.ts.map

package/dist/core/thumbnail-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-promise.d.ts","sourceRoot":"","sources":["../../src/core/thumbnail-promise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;CACpB;AA0BD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAAE,EACpB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,sBAAsB,CAAC,CA+DjC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,sBAAsB,CAoB5E"}