youtube-knowledge-mcp 2.2.0 → 3.0.1

package/dist/utils/video-store.d.ts

@@ -0,0 +1,69 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { z } from 'zod';
+/**
+ * Reading the catalogued videos back.
+ *
+ * `upload_date` is NULL, never '', for a video only ever seen in a flat
+ * listing — flat entries carry no publication date. A date filter therefore
+ * excludes those rows rather than silently treating them as ancient.
+ */
+declare const videoRowSchema: z.ZodObject<{
+    video_id: z.ZodString;
+    channel_id: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    duration_s: z.ZodNullable<z.ZodNumber>;
+    upload_date: z.ZodNullable<z.ZodString>;
+    view_count: z.ZodNullable<z.ZodNumber>;
+    comment_count: z.ZodNullable<z.ZodNumber>;
+    live_status: z.ZodNullable<z.ZodString>;
+    thumbnail_url: z.ZodNullable<z.ZodString>;
+    tab: z.ZodNullable<z.ZodString>;
+    also_in_tabs: z.ZodString;
+    detail_at: z.ZodNullable<z.ZodNumber>;
+    stored_comments: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    upload_date: string | null;
+    view_count: number | null;
+    comment_count: number | null;
+    live_status: string | null;
+    channel_id: string | null;
+    tab: string | null;
+    video_id: string;
+    duration_s: number | null;
+    thumbnail_url: string | null;
+    also_in_tabs: string;
+    detail_at: number | null;
+    stored_comments: number;
+}, {
+    title: string;
+    upload_date: string | null;
+    view_count: number | null;
+    comment_count: number | null;
+    live_status: string | null;
+    channel_id: string | null;
+    tab: string | null;
+    video_id: string;
+    duration_s: number | null;
+    thumbnail_url: string | null;
+    also_in_tabs: string;
+    detail_at: number | null;
+    stored_comments: number;
+}>;
+export type StoredVideo = z.infer<typeof videoRowSchema>;
+export interface VideoQuery {
+    channelId?: string;
+    match?: string;
+    since?: string;
+    until?: string;
+    minDurationSeconds?: number;
+    detailedOnly?: boolean;
+    withComments?: boolean;
+    order?: 'newest' | 'oldest' | 'views' | 'comments' | 'catalog';
+    limit?: number;
+    offset?: number;
+}
+export declare function queryVideos(database: DatabaseSync, query: VideoQuery): StoredVideo[];
+export declare function countVideos(database: DatabaseSync, query: VideoQuery): number;
+export {};
+//# sourceMappingURL=video-store.d.ts.map

package/dist/utils/video-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-store.d.ts","sourceRoot":"","sources":["../../src/utils/video-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AAEH,QAAA,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAclB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEzD,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiDD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,CAYpF;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,UAAU,GAAG,MAAM,CAQ7E"}

package/dist/utils/video-store.js

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { queryRows } from './store-rows.js';
+/**
+ * Reading the catalogued videos back.
+ *
+ * `upload_date` is NULL, never '', for a video only ever seen in a flat
+ * listing — flat entries carry no publication date. A date filter therefore
+ * excludes those rows rather than silently treating them as ancient.
+ */
+const videoRowSchema = z.object({
+    video_id: z.string(),
+    channel_id: z.string().nullable(),
+    title: z.string(),
+    duration_s: z.number().nullable(),
+    upload_date: z.string().nullable(),
+    view_count: z.number().nullable(),
+    comment_count: z.number().nullable(),
+    live_status: z.string().nullable(),
+    thumbnail_url: z.string().nullable(),
+    tab: z.string().nullable(),
+    also_in_tabs: z.string(),
+    detail_at: z.number().nullable(),
+    stored_comments: z.number(),
+});
+function buildWhere(query) {
+    const clauses = [];
+    const params = [];
+    if (query.channelId !== undefined) {
+        clauses.push('v.channel_id = ?');
+        params.push(query.channelId);
+    }
+    if (query.match !== undefined && query.match !== '') {
+        clauses.push('lower(v.title) LIKE ?');
+        params.push(`%${query.match.toLowerCase()}%`);
+    }
+    if (query.since !== undefined) {
+        clauses.push('v.upload_date IS NOT NULL AND v.upload_date >= ?');
+        params.push(query.since.replace(/-/g, ''));
+    }
+    if (query.until !== undefined) {
+        clauses.push('v.upload_date IS NOT NULL AND v.upload_date <= ?');
+        params.push(query.until.replace(/-/g, ''));
+    }
+    if (query.minDurationSeconds !== undefined && query.minDurationSeconds > 0) {
+        clauses.push('v.duration_s >= ?');
+        params.push(query.minDurationSeconds);
+    }
+    if (query.detailedOnly === true)
+        clauses.push('v.detail_at IS NOT NULL');
+    if (query.withComments === true) {
+        clauses.push('EXISTS (SELECT 1 FROM comment c WHERE c.video_id = v.video_id)');
+    }
+    return { sql: clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`, params };
+}
+const ORDER = {
+    // NULLS LAST so an un-dated video sorts as unknown rather than oldest.
+    newest: 'v.upload_date DESC NULLS LAST, v.video_id',
+    oldest: 'v.upload_date ASC NULLS LAST, v.video_id',
+    views: 'v.view_count DESC NULLS LAST, v.video_id',
+    comments: 'stored_comments DESC, v.video_id',
+    catalog: 'v.catalog_rank ASC NULLS LAST, v.video_id',
+};
+const SELECT = `
+SELECT v.video_id, v.channel_id, v.title, v.duration_s, v.upload_date, v.view_count,
+       v.comment_count, v.live_status, v.thumbnail_url, v.tab, v.also_in_tabs, v.detail_at,
+       (SELECT COUNT(*) FROM comment c WHERE c.video_id = v.video_id) AS stored_comments
+FROM video v`;
+export function queryVideos(database, query) {
+    const where = buildWhere(query);
+    return queryRows(database.prepare(`${SELECT}${where.sql} ORDER BY ${ORDER[query.order ?? 'newest']} LIMIT ? OFFSET ?`), videoRowSchema, ...where.params, query.limit ?? 25, query.offset ?? 0);
+}
+export function countVideos(database, query) {
+    const where = buildWhere(query);
+    const rows = queryRows(database.prepare(`SELECT COUNT(*) AS n FROM video v${where.sql}`), z.object({ n: z.number() }), ...where.params);
+    return rows[0]?.n ?? 0;
+}
+//# sourceMappingURL=video-store.js.map

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

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

package/dist/utils/video-stream.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Handing a video's stream to ffmpeg without downloading the file.
+ *
+ * Every tool that looks at pixels (a still, a contact sheet, scene cuts) needs the
+ * same two guarantees, so they live in one place: the media URL really is an https
+ * URL, and ffmpeg is told it may open nothing else.
+ */
+/** Up to 1080p: enough to read small text in a still. */
+export declare const DETAIL_STREAM_SELECTOR = "bestvideo[height<=1080]/best";
+/** Up to 720p: plenty for frames shrunk to fit a model's context. */
+export declare const PREVIEW_STREAM_SELECTOR = "bestvideo[height<=720]/best[height<=720]/best";
+/** The lightest stream that still shows a cut: scene detection reads every frame. */
+export declare const SCAN_STREAM_SELECTOR = "bestvideo[height<=360]/worst";
+/**
+ * ffmpeg accepts file:, pipe:, concat: and more as inputs. The only thing yt-dlp
+ * should have resolved is an https media URL, and this allowlist makes ffmpeg refuse
+ * anything else even if it had. A per-input option, so it must precede `-i`.
+ */
+export declare const FFMPEG_NETWORK_INPUT_ARGS: string[];
+export declare function resolveStreamUrl(videoId: string, selector: string, label: string): Promise<string>;
+//# sourceMappingURL=video-stream.d.ts.map

package/dist/utils/video-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stream.d.ts","sourceRoot":"","sources":["../../src/utils/video-stream.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AAEH,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,iCAAiC,CAAC;AACrE,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,kDAAkD,CAAC;AACvF,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,iCAAiC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,UAAkD,CAAC;AAEzF,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAiBjB"}

package/dist/utils/video-stream.js

@@ -0,0 +1,36 @@
+import { YouTubeError } from './errors.js';
+import { runYtDlp } from './ytdlp.js';
+/**
+ * Handing a video's stream to ffmpeg without downloading the file.
+ *
+ * Every tool that looks at pixels (a still, a contact sheet, scene cuts) needs the
+ * same two guarantees, so they live in one place: the media URL really is an https
+ * URL, and ffmpeg is told it may open nothing else.
+ */
+/** Up to 1080p: enough to read small text in a still. */
+export const DETAIL_STREAM_SELECTOR = 'bestvideo[height<=1080]/best';
+/** Up to 720p: plenty for frames shrunk to fit a model's context. */
+export const PREVIEW_STREAM_SELECTOR = 'bestvideo[height<=720]/best[height<=720]/best';
+/** The lightest stream that still shows a cut: scene detection reads every frame. */
+export const SCAN_STREAM_SELECTOR = 'bestvideo[height<=360]/worst';
+/**
+ * ffmpeg accepts file:, pipe:, concat: and more as inputs. The only thing yt-dlp
+ * should have resolved is an https media URL, and this allowlist makes ffmpeg refuse
+ * anything else even if it had. A per-input option, so it must precede `-i`.
+ */
+export const FFMPEG_NETWORK_INPUT_ARGS = ['-protocol_whitelist', 'https,tls,tcp,crypto'];
+export async function resolveStreamUrl(videoId, selector, label) {
+    const mediaUrl = (await runYtDlp(['-f', selector, '--get-url', '--no-playlist'], {
+        label: `${label} (resolve)`,
+        target: `https://www.youtube.com/watch?v=${videoId}`,
+    }))
+        .trim()
+        .split('\n')[0];
+    if (!mediaUrl?.startsWith('https://')) {
+        throw new YouTubeError('YTDLP_FAILED', 'Could not resolve a video stream for this video.', {
+            nextStep: 'Check the video is playable, or call check_health.',
+        });
+    }
+    return mediaUrl;
+}
+//# sourceMappingURL=video-stream.js.map

package/dist/utils/video-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-stream.js","sourceRoot":"","sources":["../../src/utils/video-stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;GAMG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AACrE,qEAAqE;AACrE,MAAM,CAAC,MAAM,uBAAuB,GAAG,+CAA+C,CAAC;AACvF,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,8BAA8B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,qBAAqB,EAAE,sBAAsB,CAAC,CAAC;AAEzF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAe,EACf,QAAgB,EAChB,KAAa;IAEb,MAAM,QAAQ,GAAG,CACf,MAAM,QAAQ,CAAC,CAAC,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,CAAC,EAAE;QAC7D,KAAK,EAAE,GAAG,KAAK,YAAY;QAC3B,MAAM,EAAE,mCAAmC,OAAO,EAAE;KACrD,CAAC,CACH;SACE,IAAI,EAAE;SACN,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAElB,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,YAAY,CAAC,cAAc,EAAE,kDAAkD,EAAE;YACzF,QAAQ,EAAE,oDAAoD;SAC/D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/utils/whisper.d.ts

@@ -0,0 +1,39 @@
+import type { TranscriptSegment } from './transcript.js';
+/**
+ * Transcribing audio on this machine, with whisper.cpp.
+ *
+ * For a video with no captions this is the only way to get words out of it. It is
+ * strictly optional, like ffmpeg: nothing here runs unless a person asks for a local
+ * transcription, and no model is downloaded for them. The model is a file they point
+ * `YOUTUBE_MCP_WHISPER_MODEL` at, because which one to run is a trade between speed,
+ * disk and accuracy that this server cannot make for them.
+ */
+/** The executable's name since whisper.cpp 1.7; earlier releases called it `main`. */
+export declare const WHISPER_BINARY = "whisper-cli";
+export interface WhisperStatus {
+    installed: boolean;
+    version?: string;
+    /** The path the person configured, whether or not a file is there. */
+    modelPath?: string;
+    modelFound: boolean;
+}
+export declare function probeWhisper(): Promise<WhisperStatus>;
+/** The model to run, or the typed reason there is nothing to run. */
+export declare function requireWhisper(operation: string): Promise<string>;
+/** whisper.cpp's JSON as segments in seconds; the silence marker is dropped. */
+export declare function parseWhisperJson(raw: string): TranscriptSegment[];
+/**
+ * The language as whisper.cpp names it: the primary subtag, lower-case.
+ *
+ * Callers pass BCP-47 tags such as `pt-BR` or `zh-Hans`, and whisper.cpp knows only `pt`
+ * and `zh` and exits on anything else (measured against whisper.cpp 1.9.5).
+ */
+export declare function whisperLanguage(tag: string): string;
+/**
+ * Transcribe one audio file.
+ *
+ * The language is always explicit: left to auto-detect, a small model took English
+ * speech for French, and a transcript in the wrong language is worse than none.
+ */
+export declare function runWhisper(audioPath: string, language: string, modelPath: string, outputBase: string): Promise<TranscriptSegment[]>;
+//# sourceMappingURL=whisper.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"whisper.d.ts","sourceRoot":"","sources":["../../src/utils/whisper.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;GAQG;AAEH,sFAAsF;AACtF,eAAO,MAAM,cAAc,gBAAgB,CAAC;AAM5C,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;CACrB;AAuBD,wBAAsB,YAAY,IAAI,OAAO,CAAC,aAAa,CAAC,CAY3D;AAED,qEAAqE;AACrE,wBAAsB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkCvE;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,EAAE,CA0BjE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA8B9B"}

package/dist/utils/whisper.js

@@ -0,0 +1,137 @@
+import { execa } from 'execa';
+import { readFile, rm, stat } from 'node:fs/promises';
+import { z } from 'zod';
+import { currentContext } from './context.js';
+import { envString } from './env.js';
+import { YouTubeError } from './errors.js';
+import { MILLISECONDS_PER_SECOND } from './seconds.js';
+/**
+ * Transcribing audio on this machine, with whisper.cpp.
+ *
+ * For a video with no captions this is the only way to get words out of it. It is
+ * strictly optional, like ffmpeg: nothing here runs unless a person asks for a local
+ * transcription, and no model is downloaded for them. The model is a file they point
+ * `YOUTUBE_MCP_WHISPER_MODEL` at, because which one to run is a trade between speed,
+ * disk and accuracy that this server cannot make for them.
+ */
+/** The executable's name since whisper.cpp 1.7; earlier releases called it `main`. */
+export const WHISPER_BINARY = 'whisper-cli';
+const PROBE_TIMEOUT_MS = 5_000;
+/** whisper.cpp writes this for a stretch with no speech; it is not part of what was said. */
+const SILENCE_MARKER = '[BLANK_AUDIO]';
+const whisperOutputSchema = z.object({
+    transcription: z.array(z.object({
+        offsets: z.object({ from: z.number(), to: z.number() }),
+        text: z.string(),
+    })),
+});
+function configuredModel() {
+    return envString('YOUTUBE_MCP_WHISPER_MODEL');
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function probeWhisper() {
+    const modelPath = configuredModel();
+    const modelFound = modelPath !== undefined && (await isFile(modelPath));
+    const model = modelPath === undefined ? {} : { modelPath };
+    try {
+        const { stdout } = await execa(WHISPER_BINARY, ['--version'], { timeout: PROBE_TIMEOUT_MS });
+        const version = /version:\s*(\S+)/.exec(stdout)?.[1] ?? 'unknown';
+        return { installed: true, version, ...model, modelFound };
+    }
+    catch {
+        return { installed: false, ...model, modelFound };
+    }
+}
+/** The model to run, or the typed reason there is nothing to run. */
+export async function requireWhisper(operation) {
+    const status = await probeWhisper();
+    if (!status.installed) {
+        throw new YouTubeError('WHISPER_MISSING', `${operation} requires whisper.cpp, which is not installed.`, {
+            nextStep: 'Install whisper.cpp (macOS: `brew install whisper.cpp`; elsewhere build it from https://github.com/ggml-org/whisper.cpp) so that `whisper-cli` is on PATH, then call check_health.',
+        });
+    }
+    if (status.modelPath === undefined) {
+        throw new YouTubeError('WHISPER_MISSING', `${operation} needs a whisper model, and none is configured.`, {
+            nextStep: 'Download a ggml model file (for example ggml-base.bin from https://huggingface.co/ggerganov/whisper.cpp) and set YOUTUBE_MCP_WHISPER_MODEL to its path.',
+        });
+    }
+    if (!status.modelFound) {
+        throw new YouTubeError('WHISPER_MISSING', `The whisper model at ${status.modelPath} is not a readable file.`, { nextStep: 'Fix the path in YOUTUBE_MCP_WHISPER_MODEL, then call check_health.' });
+    }
+    return status.modelPath;
+}
+/** whisper.cpp's JSON as segments in seconds; the silence marker is dropped. */
+export function parseWhisperJson(raw) {
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new YouTubeError('MALFORMED_RESPONSE', 'whisper.cpp wrote output that is not JSON.', {
+            cause: error,
+        });
+    }
+    const parsed = whisperOutputSchema.safeParse(json);
+    if (!parsed.success) {
+        throw new YouTubeError('MALFORMED_RESPONSE', 'whisper.cpp wrote JSON without a transcription.', { cause: parsed.error });
+    }
+    return parsed.data.transcription
+        .map(({ offsets, text }) => ({
+        start: offsets.from / MILLISECONDS_PER_SECOND,
+        end: offsets.to / MILLISECONDS_PER_SECOND,
+        text: text.trim(),
+    }))
+        .filter((segment) => segment.text !== '' && segment.text !== SILENCE_MARKER);
+}
+/**
+ * The language as whisper.cpp names it: the primary subtag, lower-case.
+ *
+ * Callers pass BCP-47 tags such as `pt-BR` or `zh-Hans`, and whisper.cpp knows only `pt`
+ * and `zh` and exits on anything else (measured against whisper.cpp 1.9.5).
+ */
+export function whisperLanguage(tag) {
+    return (tag.split('-')[0] ?? tag).toLowerCase();
+}
+/**
+ * Transcribe one audio file.
+ *
+ * The language is always explicit: left to auto-detect, a small model took English
+ * speech for French, and a transcript in the wrong language is worse than none.
+ */
+export async function runWhisper(audioPath, language, modelPath, outputBase) {
+    const outputPath = `${outputBase}.json`;
+    try {
+        await execa(WHISPER_BINARY, [
+            '-m',
+            modelPath,
+            '-f',
+            audioPath,
+            '-l',
+            whisperLanguage(language),
+            '-oj',
+            '-of',
+            outputBase,
+            '-np',
+        ], { cancelSignal: currentContext().signal });
+        return parseWhisperJson(await readFile(outputPath, 'utf-8'));
+    }
+    catch (error) {
+        if (error instanceof YouTubeError)
+            throw error;
+        throw new YouTubeError('YTDLP_FAILED', 'whisper.cpp could not transcribe this audio.', {
+            nextStep: 'Check that the model file is a valid ggml model, or call check_health.',
+            cause: error,
+        });
+    }
+    finally {
+        await rm(outputPath, { force: true });
+    }
+}
+//# sourceMappingURL=whisper.js.map

package/dist/utils/whisper.js.map

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

package/dist/utils/youtube-channel.d.ts

@@ -1,5 +1,4 @@
 import { type ListedImage } from './flat-listing.js';
-/** Listings and metadata for channels and playlists. */
 export interface VideoListItem {
     id: string;
     title: string;
@@ -26,6 +25,10 @@ export interface ChannelInfo {
     avatarUrl?: string;
     /** The channel's uncropped banner, when yt-dlp listed one. */
     bannerUrl?: string;
+    /** Present only when the channel page says so. */
+    isVerified?: boolean;
+    /** The keywords the channel lists for itself; absent when it lists none. */
+    tags?: string[];
 }
 export interface PlaylistInfo {
     id: string;
@@ -38,7 +41,15 @@ export interface PlaylistInfo {
     url: string;
     description: string;
 }
-export declare function listVideos(urlOrChannel: string, limit?: number): Promise<VideoListItem[]>;
+export declare function listVideos(urlOrChannel: string, limit?: number, start?: number): Promise<VideoListItem[]>;
+/**
+ * How many videos a listing says it has, when it says anything.
+ *
+ * `playlist_count` is populated for playlists and routinely null for channel
+ * tabs, so this returns undefined rather than a guess. One extra cheap call —
+ * the same `--playlist-items 0` metadata read getPlaylistInfo already does.
+ */
+export declare function playlistTotal(urlOrChannel: string): Promise<number | undefined>;
 export declare function getPlaylistInfo(playlistUrl: string): Promise<PlaylistInfo>;
 export declare function getChannelInfo(channel: string): Promise<ChannelInfo>;
 //# sourceMappingURL=youtube-channel.d.ts.map

package/dist/utils/youtube-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"youtube-channel.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-channel.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAK3B,wDAAwD;AAExD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB3F;AAED,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAwBhF;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwB1E"}
+{"version":3,"file":"youtube-channel.d.ts","sourceRoot":"","sources":["../../src/utils/youtube-channel.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAS3B,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,UAAU,CAAC,EAAE,WAAW,EAAE,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,UAAU,CAC9B,YAAY,EAAE,MAAM,EACpB,KAAK,SAAK,EACV,KAAK,SAAI,GACR,OAAO,CAAC,aAAa,EAAE,CAAC,CAsB1B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiBrF;AAED,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAwBhF;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8B1E"}

package/dist/utils/youtube-channel.js

@@ -1,17 +1,24 @@
+import { z } from 'zod';
 import { formatYouTubeDate } from './format.js';
 import { TIMEOUTS, parseYtDlpJson, parseYtDlpJsonLines, runYtDlp } from './ytdlp.js';
 import { FLAT_PRINT_TEMPLATE, flatEntrySchema, toVideoListItem, } from './flat-listing.js';
 import { selectChannelImages } from './channel-images.js';
 import { channelMetaSchema, playlistMetaSchema } from './youtube-schemas.js';
 import { channelUrlFor, resolveListTarget } from './youtube-url.js';
-export async function listVideos(urlOrChannel, limit = 20) {
+/** Listings and metadata for channels and playlists. */
+const playlistCountSchema = z.object({ playlist_count: z.number().nullish() });
+export async function listVideos(urlOrChannel, limit = 20, start = 1) {
     const stdout = await runYtDlp([
         '--skip-download',
         '--flat-playlist',
+        '--lazy-playlist',
         '--print',
         FLAT_PRINT_TEMPLATE,
-        '--playlist-end',
-        limit.toString(),
+        // `-I start:end` rather than --playlist-end so a later page can begin
+        // where the previous one stopped. YouTube still walks from the top to
+        // reach `start`, which is why the caller caches instead of paging deep.
+        '--playlist-items',
+        `${String(start)}:${String(start + limit - 1)}`,
     ], {
         label: 'fetch_videos',
         timeoutMs: TIMEOUTS.transcript,
@@ -19,6 +26,29 @@ export async function listVideos(urlOrChannel, limit = 20) {
     });
     return parseYtDlpJsonLines(stdout, flatEntrySchema).map(toVideoListItem);
 }
+/**
+ * How many videos a listing says it has, when it says anything.
+ *
+ * `playlist_count` is populated for playlists and routinely null for channel
+ * tabs, so this returns undefined rather than a guess. One extra cheap call —
+ * the same `--playlist-items 0` metadata read getPlaylistInfo already does.
+ */
+export async function playlistTotal(urlOrChannel) {
+    try {
+        const stdout = await runYtDlp(['--dump-single-json', '--flat-playlist', '--playlist-items', '0'], {
+            label: 'fetch_videos:count',
+            timeoutMs: TIMEOUTS.metadata,
+            target: resolveListTarget(urlOrChannel),
+        });
+        const parsed = parseYtDlpJson(stdout, playlistCountSchema, 'a playlist count');
+        return parsed.playlist_count ?? undefined;
+    }
+    catch {
+        // A total is a nicety; failing to get one must not fail the page. Its
+        // absence is already meaningful — "unknown", which is the truth here.
+        return undefined;
+    }
+}
 export async function getPlaylistInfo(playlistUrl) {
     const target = resolveListTarget(playlistUrl);
     const stdout = await runYtDlp(['--dump-single-json', '--flat-playlist', '--playlist-items', '0'], {
@@ -53,6 +83,12 @@ export async function getChannelInfo(channel) {
         subscriberCount: data.channel_follower_count ?? 0,
         channelUrl: data.channel_url ?? channelUrl,
         description: data.description ?? '',
+        ...(data.channel_is_verified === null || data.channel_is_verified === undefined
+            ? {}
+            : { isVerified: data.channel_is_verified }),
+        ...(data.tags === null || data.tags === undefined || data.tags.length === 0
+            ? {}
+            : { tags: data.tags }),
         // The same listing carries the avatar and banner; they were discarded here
         // for two releases.
         ...selectChannelImages(data.thumbnails),

package/dist/utils/youtube-channel.js.map

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