youtube-knowledge-mcp 2.2.0 → 3.0.1

package/dist/utils/comment-store.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { queryRows, sqliteBoolean } from './store-rows.js';
+/**
+ * Comments on disk.
+ *
+ * Upserted on the comment id, never INSERT OR REPLACE: replace deletes and
+ * reinserts, which changes the rowid the external-content FTS index is keyed
+ * on. Upsert keeps it and fires the update trigger, so a re-harvest costs
+ * network and never data.
+ */
+export const COMMENT_COMMIT_BATCH = 2_000;
+const UPSERT = `
+INSERT INTO comment (
+  comment_id, video_id, parent_id, text, like_count, author, author_id, author_url,
+  author_thumbnail, author_is_uploader, author_is_verified, is_pinned, is_favorited,
+  time_text, published_at, harvested_at
+) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)
+ON CONFLICT(comment_id) DO UPDATE SET
+  text = excluded.text,
+  like_count = excluded.like_count,
+  is_pinned = excluded.is_pinned,
+  is_favorited = excluded.is_favorited,
+  harvested_at = excluded.harvested_at`;
+const commentRowSchema = z.object({
+    comment_id: z.string(),
+    video_id: z.string(),
+    parent_id: z.string().nullable(),
+    text: z.string(),
+    like_count: z.number(),
+    author: z.string(),
+    author_id: z.string().nullable(),
+    author_is_uploader: sqliteBoolean,
+    author_is_verified: sqliteBoolean,
+    is_pinned: sqliteBoolean,
+    is_favorited: sqliteBoolean,
+    published_at: z.number().nullable(),
+});
+function bind(comment, videoId, now) {
+    return [
+        comment.id,
+        videoId,
+        comment.parentId,
+        comment.text,
+        comment.likeCount,
+        comment.author,
+        comment.authorId ?? null,
+        comment.authorUrl ?? null,
+        comment.authorThumbnailUrl ?? null,
+        Number(comment.authorIsUploader),
+        Number(comment.authorIsVerified),
+        Number(comment.isPinned),
+        Number(comment.isFavorited),
+        comment.timeText ?? null,
+        comment.timestamp ?? null,
+        now,
+    ];
+}
+/** Writes threads and their replies. The caller owns the transaction. */
+export function saveThreads(database, videoId, threads, now = Date.now()) {
+    const statement = database.prepare(UPSERT);
+    let written = 0;
+    for (const thread of threads) {
+        statement.run(...bind(thread.comment, videoId, now));
+        written += 1;
+        for (const reply of thread.replies) {
+            statement.run(...bind(reply, videoId, now));
+            written += 1;
+        }
+    }
+    return written;
+}
+function buildWhere(query) {
+    const clauses = [];
+    const params = [];
+    if (query.videoId !== undefined) {
+        clauses.push('c.video_id = ?');
+        params.push(query.videoId);
+    }
+    if (query.channelId !== undefined) {
+        clauses.push('c.video_id IN (SELECT video_id FROM video WHERE channel_id = ?)');
+        params.push(query.channelId);
+    }
+    if (query.authorId !== undefined) {
+        clauses.push('(c.author_id = ? OR c.author = ?)');
+        params.push(query.authorId, query.authorId);
+    }
+    if (query.threadOf !== undefined) {
+        clauses.push('(c.comment_id = ? OR c.parent_id = ?)');
+        params.push(query.threadOf, query.threadOf);
+    }
+    if (query.topLevelOnly === true)
+        clauses.push('c.parent_id IS NULL');
+    if (query.minLikes !== undefined && query.minLikes > 0) {
+        clauses.push('c.like_count >= ?');
+        params.push(query.minLikes);
+    }
+    if (query.match !== undefined && query.match !== '') {
+        // Bound, never concatenated: `match` is caller text and FTS5 has its own
+        // expression syntax that must not reach the SQL parser.
+        clauses.push('c.rowid IN (SELECT rowid FROM comment_fts WHERE comment_fts MATCH ?)');
+        params.push(query.match);
+    }
+    return { sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`, params };
+}
+const ORDER = {
+    likes: 'c.like_count DESC, c.comment_id',
+    newest: 'c.published_at DESC, c.comment_id',
+    oldest: 'c.published_at ASC, c.comment_id',
+    // Threads read in reply order; relevance needs the FTS rank, which only
+    // exists when a match was given, so it falls back to likes.
+    relevance: 'c.like_count DESC, c.comment_id',
+};
+export function queryComments(database, query) {
+    const where = buildWhere(query);
+    const order = query.threadOf === undefined
+        ? ORDER[query.order ?? 'likes']
+        : 'c.parent_id NULLS FIRST, c.published_at';
+    return queryRows(database.prepare(`SELECT c.comment_id, c.video_id, c.parent_id, c.text, c.like_count, c.author,
+              c.author_id, c.author_is_uploader, c.author_is_verified, c.is_pinned,
+              c.is_favorited, c.published_at
+       FROM comment c${where.sql}
+       ORDER BY ${order} LIMIT ? OFFSET ?`), commentRowSchema, ...where.params, query.limit ?? 25, query.offset ?? 0);
+}
+export function countComments(database, query) {
+    const where = buildWhere(query);
+    const rows = queryRows(database.prepare(`SELECT COUNT(*) AS n FROM comment c${where.sql}`), z.object({ n: z.number() }), ...where.params);
+    return rows[0]?.n ?? 0;
+}
+//# sourceMappingURL=comment-store.js.map

package/dist/utils/comment-store.js.map

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

package/dist/utils/comment-threads.d.ts

@@ -0,0 +1,51 @@
+import type { z } from 'zod';
+import type { commentRowSchema } from './youtube-schemas.js';
+/**
+ * Rebuilding threads from yt-dlp's flat comment array.
+ *
+ * yt-dlp returns replies alongside their parents and marks each with a
+ * `parent` of `root` or the parent's id. The previous implementation filtered
+ * the replies away *after* paying to fetch them, which is the most expensive
+ * possible way to have no replies.
+ */
+export type CommentRow = z.infer<typeof commentRowSchema>;
+export interface ThreadedComment {
+    id: string;
+    parentId: string | null;
+    author: string;
+    authorId?: string;
+    authorUrl?: string;
+    authorThumbnailUrl?: string;
+    authorIsUploader: boolean;
+    authorIsVerified: boolean;
+    text: string;
+    likeCount: number;
+    isPinned: boolean;
+    isFavorited: boolean;
+    timestamp?: number;
+    publishedAt?: string;
+    timeText?: string;
+}
+export interface CommentThread {
+    comment: ThreadedComment;
+    replies: ThreadedComment[];
+    /** Replies present in THIS extraction, not YouTube's own figure. */
+    replyCount: number;
+}
+export interface ThreadedComments {
+    threads: CommentThread[];
+    rootCount: number;
+    replyCount: number;
+    /** Replies whose parent was cut by a cap. Kept, and counted, never dropped. */
+    orphanCount: number;
+}
+/**
+ * Groups rows into threads, in yt-dlp's own order.
+ *
+ * A reply whose parent is missing — because `max_parents` truncated the set —
+ * is promoted to a root rather than discarded, keeping its `parentId` so the
+ * gap stays visible. Silently dropping data is the bug this whole release is
+ * about.
+ */
+export declare function toThreads(rows: CommentRow[]): ThreadedComments;
+//# sourceMappingURL=comment-threads.d.ts.map

package/dist/utils/comment-threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-threads.d.ts","sourceRoot":"","sources":["../../src/utils/comment-threads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;GAOG;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;CACrB;AAiCD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,gBAAgB,CA0C9D"}

package/dist/utils/comment-threads.js

@@ -0,0 +1,76 @@
+function toComment(row, index) {
+    const parent = row.parent ?? 'root';
+    const timestamp = row.timestamp ?? undefined;
+    // yt-dlp writes null for an absent field; normalised to undefined once here
+    // so every spread below is a plain `=== undefined` check.
+    const authorId = row.author_id ?? undefined;
+    const authorUrl = row.author_url ?? undefined;
+    const authorThumbnail = row.author_thumbnail ?? undefined;
+    const timeText = row._time_text ?? undefined;
+    return {
+        // yt-dlp always supplies an id; the fallback keeps a malformed row
+        // addressable rather than silently merging it with another.
+        id: row.id ?? `unknown-${String(index)}`,
+        parentId: parent === 'root' ? null : parent,
+        author: row.author ?? 'Unknown',
+        ...(authorId === undefined ? {} : { authorId }),
+        ...(authorUrl === undefined ? {} : { authorUrl }),
+        ...(authorThumbnail === undefined ? {} : { authorThumbnailUrl: authorThumbnail }),
+        authorIsUploader: row.author_is_uploader ?? false,
+        authorIsVerified: row.author_is_verified ?? false,
+        text: row.text ?? '',
+        likeCount: row.like_count ?? 0,
+        isPinned: row.is_pinned ?? false,
+        isFavorited: row.is_favorited ?? false,
+        ...(timestamp === undefined ? {} : { timestamp }),
+        ...(timestamp === undefined ? {} : { publishedAt: new Date(timestamp * 1000).toISOString() }),
+        ...(timeText === undefined ? {} : { timeText }),
+    };
+}
+/**
+ * Groups rows into threads, in yt-dlp's own order.
+ *
+ * A reply whose parent is missing — because `max_parents` truncated the set —
+ * is promoted to a root rather than discarded, keeping its `parentId` so the
+ * gap stays visible. Silently dropping data is the bug this whole release is
+ * about.
+ */
+export function toThreads(rows) {
+    const comments = rows.map(toComment);
+    const threads = [];
+    const threadById = new Map();
+    let replyCount = 0;
+    let orphanCount = 0;
+    for (const comment of comments) {
+        if (comment.parentId === null) {
+            const thread = { comment, replies: [], replyCount: 0 };
+            threads.push(thread);
+            threadById.set(comment.id, thread);
+        }
+    }
+    for (const comment of comments) {
+        if (comment.parentId === null)
+            continue;
+        const thread = threadById.get(comment.parentId);
+        if (thread === undefined) {
+            // The parent was cut by a cap. Keep the reply as its own thread so the
+            // text survives, and count it so the caller knows threads are partial.
+            orphanCount += 1;
+            threads.push({ comment, replies: [], replyCount: 0 });
+            continue;
+        }
+        thread.replies.push(comment);
+        thread.replyCount += 1;
+        replyCount += 1;
+    }
+    for (const thread of threads) {
+        thread.replies.sort((left, right) => (left.timestamp ?? 0) - (right.timestamp ?? 0));
+    }
+    return {
+        threads,
+        rootCount: threads.length - orphanCount,
+        replyCount,
+        orphanCount,
+    };
+}
+//# sourceMappingURL=comment-threads.js.map

package/dist/utils/comment-threads.js.map

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

package/dist/utils/concat.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Joining clips into one video, in the order given.
+ *
+ * The inputs are files already on this machine, typically what extract_clip wrote.
+ * They are re-encoded rather than copied, because clips cut at different moments or
+ * from different sources rarely share the exact stream parameters a copy needs.
+ */
+export declare const MIN_CONCAT_FILES = 2;
+export declare const MAX_CONCAT_FILES = 20;
+export interface ConcatResult {
+    filePath: string;
+    clips: number;
+    bytes: number;
+}
+export declare function concatClips(inputs: string[], options: {
+    name?: string;
+    outputDir?: string;
+}): Promise<ConcatResult>;
+//# sourceMappingURL=concat.d.ts.map

package/dist/utils/concat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat.d.ts","sourceRoot":"","sources":["../../src/utils/concat.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAKnC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AA8DD,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C,OAAO,CAAC,YAAY,CAAC,CAwEvB"}

package/dist/utils/concat.js

@@ -0,0 +1,135 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { safeStem } from './clips.js';
+import { YouTubeError } from './errors.js';
+import { runFfmpeg } from './ffmpeg.js';
+import { dataDir } from './paths.js';
+import { requireFfmpeg } from './preflight.js';
+import { assertInsideHome, resolveOutputDir } from './validate.js';
+import { TIMEOUTS } from './ytdlp.js';
+/**
+ * Joining clips into one video, in the order given.
+ *
+ * The inputs are files already on this machine, typically what extract_clip wrote.
+ * They are re-encoded rather than copied, because clips cut at different moments or
+ * from different sources rarely share the exact stream parameters a copy needs.
+ */
+export const MIN_CONCAT_FILES = 2;
+export const MAX_CONCAT_FILES = 20;
+const MONTAGES_DIR = dataDir('montages');
+const NAME_HASH_LENGTH = 8;
+/** A path as one entry of ffmpeg's concat list: single-quoted, with any quote escaped. */
+function listEntry(path) {
+    return `file '${path.replace(/'/g, `'\\''`)}'`;
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where the result may go.
+ *
+ * Never onto one of the clips being joined: ffmpeg would read and write the same file
+ * and destroy it. And never over a file the caller did not make: a name the caller
+ * chose can collide with anything in the folder, so an existing file is refused. A name
+ * this server derived from the inputs is its own, so repeating the call rewrites it.
+ */
+async function assertSafeOutput(filePath, inputs, chosenName) {
+    if (inputs.includes(filePath)) {
+        throw new YouTubeError('INVALID_INPUT', `The result would overwrite ${filePath}, a clip being joined.`, {
+            nextStep: 'Choose a different name, or another outputDir.',
+        });
+    }
+    if (chosenName && (await exists(filePath))) {
+        throw new YouTubeError('INVALID_INPUT', `${filePath} already exists.`, {
+            nextStep: 'Choose a different name, or remove the existing file first.',
+        });
+    }
+}
+async function assertReadableFile(path) {
+    let isFile;
+    try {
+        isFile = (await stat(path)).isFile();
+    }
+    catch (error) {
+        throw new YouTubeError('NOT_FOUND', `There is no file at ${path}.`, {
+            nextStep: 'Pass the paths extract_clip returned, in the order you want them.',
+            cause: error,
+        });
+    }
+    if (!isFile) {
+        throw new YouTubeError('INVALID_INPUT', `${path} is not a file.`, {
+            nextStep: 'Pass paths to video files, not folders.',
+        });
+    }
+}
+export async function concatClips(inputs, options) {
+    if (inputs.length < MIN_CONCAT_FILES || inputs.length > MAX_CONCAT_FILES) {
+        throw new YouTubeError('INVALID_INPUT', `Join between ${String(MIN_CONCAT_FILES)} and ${String(MAX_CONCAT_FILES)} clips at a time.`, { nextStep: 'Join in stages: concatenate groups, then concatenate the results.' });
+    }
+    await requireFfmpeg('Joining clips');
+    const targetDir = resolveOutputDir(options.outputDir, MONTAGES_DIR);
+    const paths = inputs.map((input) => assertInsideHome(input, 'clip'));
+    for (const path of paths)
+        await assertReadableFile(path);
+    const hash = createHash('sha256')
+        .update(paths.join('\n'))
+        .digest('hex')
+        .slice(0, NAME_HASH_LENGTH);
+    const stem = options.name === undefined ? `montage-${hash}` : safeStem(options.name, `montage-${hash}`);
+    const filePath = join(targetDir, `${stem}.mp4`);
+    await assertSafeOutput(filePath, paths, options.name !== undefined);
+    const resultExisted = await exists(filePath);
+    await mkdir(targetDir, { recursive: true });
+    // One folder per call: two calls joining the same clips must not share, and then
+    // delete, each other's list.
+    const workDir = await mkdtemp(join(targetDir, '.concat-'));
+    const listPath = join(workDir, 'list.txt');
+    await writeFile(listPath, `${paths.map(listEntry).join('\n')}\n`, 'utf-8');
+    try {
+        await runFfmpeg([
+            // The list is the only thing ffmpeg reads, and it names files only.
+            '-protocol_whitelist',
+            'file',
+            '-f',
+            'concat',
+            // Paths in the list are absolute and already checked above.
+            '-safe',
+            '0',
+            '-i',
+            listPath,
+            '-c:v',
+            'libx264',
+            '-c:a',
+            'aac',
+            '-movflags',
+            '+faststart',
+            '-y',
+            filePath,
+        ], {
+            failure: 'ffmpeg could not join those clips.',
+            nextStep: 'Check that every file is a playable video, or call check_health.',
+            // Joining re-encodes, so it takes as long as the clips do; the client's
+            // cancellation is the lever, as for a download.
+            timeoutMs: TIMEOUTS.download,
+        });
+    }
+    catch (error) {
+        // Only a file this call began is removed: before it, nothing existed at that path
+        // unless the name was derived, and a derived name is this server's own.
+        if (!resultExisted)
+            await rm(filePath, { force: true });
+        throw error;
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true });
+    }
+    return { filePath, clips: paths.length, bytes: (await stat(filePath)).size };
+}
+//# sourceMappingURL=concat.js.map

package/dist/utils/concat.js.map

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

package/dist/utils/contact-sheet.d.ts

@@ -0,0 +1,28 @@
+import type { FramePlanRequest } from './frame-plan.js';
+/**
+ * A whole video's worth of looking in one picture.
+ *
+ * A model reading a video does not need every frame; it needs to see the shape of
+ * it. Tiling a couple of dozen small stills into one image is a single inline
+ * block instead of two dozen, and the order of the cells is the order of the
+ * timestamps returned beside it, so no text has to be burned into the pixels.
+ */
+/** Each cell's width; four columns come to about 1300px, sharp but still a single block. */
+export declare const SHEET_TILE_WIDTH = 320;
+export declare const MAX_SHEET_FRAMES = 24;
+export declare const DEFAULT_SHEET_COLUMNS = 4;
+export interface ContactSheet {
+    bytes: Buffer;
+    columns: number;
+    rows: number;
+}
+export interface VideoContactSheet extends ContactSheet {
+    videoId: string;
+    title: string;
+    duration: number;
+    /** One per cell, left to right then top to bottom. */
+    timestamps: number[];
+}
+export declare function buildContactSheet(frames: Buffer[], columns: number): Promise<ContactSheet>;
+export declare function captureContactSheet(video: string, request: FramePlanRequest, columns: number): Promise<VideoContactSheet>;
+//# sourceMappingURL=contact-sheet.d.ts.map

package/dist/utils/contact-sheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-sheet.d.ts","sourceRoot":"","sources":["../../src/utils/contact-sheet.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAIxD;;;;;;;GAOG;AAEH,4FAA4F;AAC5F,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAIvC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAqChG;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,iBAAiB,CAAC,CAkB5B"}

package/dist/utils/contact-sheet.js

@@ -0,0 +1,65 @@
+import { YouTubeError } from './errors.js';
+import { FFMPEG_JPEG_QUALITY, runFfmpeg } from './ffmpeg.js';
+import { captureFrames } from './frames.js';
+import { TIMEOUTS } from './ytdlp.js';
+/**
+ * A whole video's worth of looking in one picture.
+ *
+ * A model reading a video does not need every frame; it needs to see the shape of
+ * it. Tiling a couple of dozen small stills into one image is a single inline
+ * block instead of two dozen, and the order of the cells is the order of the
+ * timestamps returned beside it, so no text has to be burned into the pixels.
+ */
+/** Each cell's width; four columns come to about 1300px, sharp but still a single block. */
+export const SHEET_TILE_WIDTH = 320;
+export const MAX_SHEET_FRAMES = 24;
+export const DEFAULT_SHEET_COLUMNS = 4;
+const TILE_GAP = 4;
+export async function buildContactSheet(frames, columns) {
+    if (frames.length === 0) {
+        throw new YouTubeError('INVALID_INPUT', 'A contact sheet needs at least one frame.');
+    }
+    // A grid wider than the frames it holds is only empty margin.
+    const width = Math.max(1, Math.min(columns, frames.length));
+    const rows = Math.ceil(frames.length / width);
+    const failure = 'ffmpeg could not assemble the contact sheet.';
+    const nextStep = 'Try fewer frames, or check that ffmpeg is working.';
+    const { stdout } = await runFfmpeg([
+        '-f',
+        'image2pipe',
+        '-c:v',
+        'mjpeg',
+        '-i',
+        'pipe:0',
+        '-vf',
+        `tile=${String(width)}x${String(rows)}:margin=${String(TILE_GAP)}:padding=${String(TILE_GAP)}:color=black`,
+        '-frames:v',
+        '1',
+        '-q:v',
+        FFMPEG_JPEG_QUALITY,
+        '-f',
+        'image2pipe',
+        '-c:v',
+        'mjpeg',
+        'pipe:1',
+    ], { failure, nextStep, timeoutMs: TIMEOUTS.transcript, input: Buffer.concat(frames) });
+    if (stdout.byteLength === 0)
+        throw new YouTubeError('YTDLP_FAILED', failure, { nextStep });
+    return { bytes: stdout, columns: width, rows };
+}
+export async function captureContactSheet(video, request, columns) {
+    const batch = await captureFrames(video, request, {
+        width: SHEET_TILE_WIDTH,
+        maxFrames: MAX_SHEET_FRAMES,
+        label: 'Contact sheet',
+    });
+    const sheet = await buildContactSheet(batch.frames.map((frame) => frame.bytes), columns);
+    return {
+        ...sheet,
+        videoId: batch.videoId,
+        title: batch.title,
+        duration: batch.duration,
+        timestamps: batch.frames.map((frame) => frame.timestamp),
+    };
+}
+//# sourceMappingURL=contact-sheet.js.map

package/dist/utils/contact-sheet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contact-sheet.js","sourceRoot":"","sources":["../../src/utils/contact-sheet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;GAOG;AAEH,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AACnC,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,MAAM,QAAQ,GAAG,CAAC,CAAC;AAgBnB,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAgB,EAAE,OAAe;IACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,YAAY,CAAC,eAAe,EAAE,2CAA2C,CAAC,CAAC;IACvF,CAAC;IAED,8DAA8D;IAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;IAE9C,MAAM,OAAO,GAAG,8CAA8C,CAAC;IAC/D,MAAM,QAAQ,GAAG,oDAAoD,CAAC;IAEtE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAChC;QACE,IAAI;QACJ,YAAY;QACZ,MAAM;QACN,OAAO;QACP,IAAI;QACJ,QAAQ;QACR,KAAK;QACL,QAAQ,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,QAAQ,CAAC,YAAY,MAAM,CAAC,QAAQ,CAAC,cAAc;QAC1G,WAAW;QACX,GAAG;QACH,MAAM;QACN,mBAAmB;QACnB,IAAI;QACJ,YAAY;QACZ,MAAM;QACN,OAAO;QACP,QAAQ;KACT,EACD,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CACpF,CAAC;IAEF,IAAI,MAAM,CAAC,UAAU,KAAK,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3F,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAa,EACb,OAAyB,EACzB,OAAe;IAEf,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE;QAChD,KAAK,EAAE,gBAAgB;QACvB,SAAS,EAAE,gBAAgB;QAC3B,KAAK,EAAE,eAAe;KACvB,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,MAAM,iBAAiB,CACnC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EACxC,OAAO,CACR,CAAC;IAEF,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/utils/coverage-text.d.ts

@@ -0,0 +1,3 @@
+import type { Coverage } from '../harvest-schemas.js';
+export declare function renderCoverage(coverage: Coverage): string;
+//# sourceMappingURL=coverage-text.d.ts.map

package/dist/utils/coverage-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-text.d.ts","sourceRoot":"","sources":["../../src/utils/coverage-text.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AA8CtD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CA6BzD"}

package/dist/utils/coverage-text.js

@@ -0,0 +1,62 @@
+/**
+ * The human- and model-readable form of a receipt.
+ *
+ * `structuredContent` carries the machine-readable truth, but a model reads
+ * the text block, and that is where an overclaim actually happens. So every
+ * extraction tool prepends this, from one function, rather than each writing
+ * its own wording and drifting.
+ *
+ * The incomplete form says three things on purpose: the numbers, why it
+ * stopped, and an explicit instruction not to describe it as everything. The
+ * last one reads as belt-and-braces next to the `complete: false` field, and
+ * it is: the field is for programs, the sentence is for the reader.
+ */
+const UNITS = {
+    'channel-catalog': 'videos',
+    'video-details': 'videos',
+    'video-comments': 'comments',
+};
+const WHY = {
+    COMPLETE: 'complete',
+    CAP_REACHED: 'stopped by the requested cap',
+    BUDGET_SPENT: 'stopped when the time budget ran out',
+    RATE_LIMITED: 'stopped because YouTube throttled this client',
+    CANCELLED: 'cancelled by the client',
+    TIMEOUT: 'timed out',
+    SOURCE_REFUSED: 'YouTube refused this content to the current session',
+    COMMENTS_DISABLED: 'comments are turned off for this video',
+    SOURCE_SILENT: 'YouTube states no total, so exhaustion cannot be proven',
+    PARTIAL_ERROR: 'some items failed',
+    NOT_ATTEMPTED: 'not attempted yet',
+};
+function count(value) {
+    return value.toLocaleString('en-US');
+}
+function ratio(coverage) {
+    if (coverage.expected === undefined || coverage.expected === 0)
+        return '';
+    const percent = (coverage.have / coverage.expected) * 100;
+    return ` (${percent < 0.1 && percent > 0 ? '<0.1' : percent.toFixed(1)}%)`;
+}
+export function renderCoverage(coverage) {
+    const unit = UNITS[coverage.scope];
+    const of = coverage.expected === undefined
+        ? `${count(coverage.have)} ${unit}`
+        : `${count(coverage.have)} of ${coverage.expectedSource === 'youtube:comment_count' ? 'about ' : ''}${count(coverage.expected)} ${unit}${ratio(coverage)}`;
+    const lines = [`Coverage: ${of} for ${coverage.targetId}.`];
+    if (coverage.complete) {
+        lines.push(`COMPLETE — ${WHY[coverage.reason]}, harvested ${coverage.harvestedAt}.`);
+        if (coverage.staleAfter !== undefined) {
+            lines.push(`Re-check after ${coverage.staleAfter} (this can change upstream).`);
+        }
+        return lines.join('\n');
+    }
+    const bias = coverage.sortApplied === 'top' && coverage.limitApplied !== undefined
+        ? ', sorted by "top" (a biased prefix, not a random sample)'
+        : '';
+    lines.push(`INCOMPLETE — ${WHY[coverage.reason]}${bias}.`, `Do not describe this as the full ${unit === 'comments' ? 'comment history' : 'video list'}.`);
+    if (coverage.note !== undefined)
+        lines.push(coverage.note);
+    return lines.join('\n');
+}
+//# sourceMappingURL=coverage-text.js.map

package/dist/utils/coverage-text.js.map

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