youtube-knowledge-mcp 2.1.0 → 2.2.0

package/dist/utils/thumbnail-paths.d.ts

@@ -0,0 +1,20 @@
+import type { ImageFormat } from './image-dimensions.js';
+import type { ThumbnailTab } from '../thumbnail-schemas.js';
+/**
+ * Every file a channel's thumbnails are made of.
+ *
+ * A sibling of the brains rather than inside them: deleting a brain removes
+ * its whole directory, and a channel's images should outlive its corpus. Keyed
+ * on the channel id, validated once here; a filename is the video id, also
+ * validated here; and the tab and format are closed enums. Nothing a caller or
+ * a hand-edited manifest supplies reaches a path unchecked.
+ */
+export declare function thumbnailsDir(): string;
+export declare function thumbnailDir(channelId: string): string;
+export declare function thumbnailManifestPath(channelId: string): string;
+export declare function thumbnailLockPath(channelId: string): string;
+export declare function channelImagePath(channelId: string, kind: 'avatar' | 'banner', format: ImageFormat): string;
+export declare function videoThumbnailPath(channelId: string, tab: ThumbnailTab, videoId: string, format: ImageFormat): string;
+/** The informational `file` field: where a file sits inside the channel directory. */
+export declare function relativeFile(channelId: string, absolute: string): string;
+//# sourceMappingURL=thumbnail-paths.d.ts.map

package/dist/utils/thumbnail-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-paths.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-paths.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;;;;;;;GAQG;AAEH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,MAAM,EAAE,WAAW,GAClB,MAAM,CAER;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,WAAW,GAClB,MAAM,CAER;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAExE"}

package/dist/utils/thumbnail-paths.js

@@ -0,0 +1,35 @@
+import { join, relative } from 'node:path';
+import { dataDir } from './paths.js';
+import { assertChannelId, assertVideoId } from './validate.js';
+/**
+ * Every file a channel's thumbnails are made of.
+ *
+ * A sibling of the brains rather than inside them: deleting a brain removes
+ * its whole directory, and a channel's images should outlive its corpus. Keyed
+ * on the channel id, validated once here; a filename is the video id, also
+ * validated here; and the tab and format are closed enums. Nothing a caller or
+ * a hand-edited manifest supplies reaches a path unchecked.
+ */
+export function thumbnailsDir() {
+    return dataDir('thumbnails');
+}
+export function thumbnailDir(channelId) {
+    return join(thumbnailsDir(), assertChannelId(channelId));
+}
+export function thumbnailManifestPath(channelId) {
+    return join(thumbnailDir(channelId), 'manifest.json');
+}
+export function thumbnailLockPath(channelId) {
+    return join(thumbnailDir(channelId), 'fetch.lock');
+}
+export function channelImagePath(channelId, kind, format) {
+    return join(thumbnailDir(channelId), 'channel', `${kind}.${format}`);
+}
+export function videoThumbnailPath(channelId, tab, videoId, format) {
+    return join(thumbnailDir(channelId), tab, `${assertVideoId(videoId)}.${format}`);
+}
+/** The informational `file` field: where a file sits inside the channel directory. */
+export function relativeFile(channelId, absolute) {
+    return relative(thumbnailDir(channelId), absolute);
+}
+//# sourceMappingURL=thumbnail-paths.js.map

package/dist/utils/thumbnail-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-paths.js","sourceRoot":"","sources":["../../src/utils/thumbnail-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE3C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG/D;;;;;;;;GAQG;AAEH,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,IAAI,CAAC,aAAa,EAAE,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,SAAiB;IACrD,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IACjD,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,IAAyB,EACzB,MAAmB;IAEnB,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,GAAG,IAAI,IAAI,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,GAAiB,EACjB,OAAe,EACf,MAAmB;IAEnB,OAAO,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;AACnF,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,QAAgB;IAC9D,OAAO,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC"}

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

@@ -0,0 +1,19 @@
+import { type ChannelImage, type ThumbnailEntry, type ThumbnailManifest, type ThumbnailStats, type ThumbnailTab } from '../thumbnail-schemas.js';
+/** The manifest of a channel's thumbnails: reading, writing, finding and forgetting it. */
+export declare const THUMBNAIL_MANIFEST_VERSION = 1;
+export declare function ensureThumbnailDirs(channelId: string, tabs: ThumbnailTab[]): Promise<string>;
+export declare function readThumbnailManifest(channelId: string): Promise<ThumbnailManifest | undefined>;
+export declare function requireThumbnailManifest(channelId: string): Promise<ThumbnailManifest>;
+export declare function writeThumbnailManifest(manifest: ThumbnailManifest): Promise<void>;
+/** Every thumbnail set on disk, newest first. Unreadable directories are skipped. */
+export declare function listThumbnailManifests(): Promise<ThumbnailManifest[]>;
+/** The thumbnail set for a channel named any way the caller likes, from disk alone. */
+export declare function resolveThumbnails(channel: string): Promise<ThumbnailManifest>;
+export declare function deleteThumbnails(channelId: string): Promise<boolean>;
+/** Where a saved entry's file is, recomputed from validated parts; never read from the manifest. */
+export declare function entryPath(channelId: string, entry: ThumbnailEntry): string | undefined;
+export declare function channelImageFile(channelId: string, image: ChannelImage): string | undefined;
+/** True when the file a saved record describes is on disk at the recorded size. */
+export declare function isIntact(path: string | undefined, bytes: number | undefined): Promise<boolean>;
+export declare function computeThumbnailStats(entries: ThumbnailEntry[]): ThumbnailStats;
+//# sourceMappingURL=thumbnail-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"thumbnail-store.d.ts","sourceRoot":"","sources":["../../src/utils/thumbnail-store.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,yBAAyB,CAAC;AAajC,2FAA2F;AAE3F,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,EAAE,GACnB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAExC;AAED,wBAAsB,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAY5F;AAED,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvF;AAED,qFAAqF;AACrF,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAa3E;AAED,uFAAuF;AACvF,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBnF;AAED,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAK1E;AAED,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAGtF;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,mFAAmF;AACnF,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,CA2B/E"}

package/dist/utils/thumbnail-store.js

@@ -0,0 +1,125 @@
+import { existsSync } from 'node:fs';
+import { readdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { thumbnailManifestSchema, } from '../thumbnail-schemas.js';
+import { findByChannel } from './channel-lookup.js';
+import { YouTubeError } from './errors.js';
+import { readJsonFile, writeJsonAtomic } from './json-file.js';
+import { ensurePrivateDir } from './paths.js';
+import { channelImagePath, thumbnailDir, thumbnailManifestPath, thumbnailsDir, videoThumbnailPath, } from './thumbnail-paths.js';
+/** The manifest of a channel's thumbnails: reading, writing, finding and forgetting it. */
+export const THUMBNAIL_MANIFEST_VERSION = 1;
+export async function ensureThumbnailDirs(channelId, tabs) {
+    const directory = await ensurePrivateDir(thumbnailDir(channelId));
+    await ensurePrivateDir(join(directory, 'channel'));
+    for (const tab of tabs)
+        await ensurePrivateDir(join(directory, tab));
+    return directory;
+}
+export async function readThumbnailManifest(channelId) {
+    return readJsonFile(thumbnailManifestPath(channelId), thumbnailManifestSchema);
+}
+export async function requireThumbnailManifest(channelId) {
+    const manifest = await readThumbnailManifest(channelId);
+    if (manifest === undefined) {
+        throw new YouTubeError('NOT_FOUND', `No thumbnails have been fetched for channel ${channelId}.`, {
+            nextStep: 'Call fetch_channel_thumbnails with the channel URL or handle.',
+        });
+    }
+    return manifest;
+}
+export async function writeThumbnailManifest(manifest) {
+    await ensurePrivateDir(thumbnailDir(manifest.channel.channelId));
+    await writeJsonAtomic(thumbnailManifestPath(manifest.channel.channelId), manifest);
+}
+/** Every thumbnail set on disk, newest first. Unreadable directories are skipped. */
+export async function listThumbnailManifests() {
+    if (!existsSync(thumbnailsDir()))
+        return [];
+    const manifests = [];
+    for (const entry of await readdir(thumbnailsDir(), { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const manifest = await readJsonFile(join(thumbnailsDir(), entry.name, 'manifest.json'), thumbnailManifestSchema);
+        if (manifest !== undefined)
+            manifests.push(manifest);
+    }
+    return manifests.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+/** The thumbnail set for a channel named any way the caller likes, from disk alone. */
+export async function resolveThumbnails(channel) {
+    const manifests = await listThumbnailManifests();
+    const [first, second] = findByChannel(manifests, channel);
+    if (first === undefined) {
+        const fetched = manifests.map((m) => m.channel.handle || m.channel.name);
+        throw new YouTubeError('NOT_FOUND', `No thumbnails have been fetched for "${channel}".`, {
+            nextStep: fetched.length === 0
+                ? 'Call fetch_channel_thumbnails with the channel URL or handle.'
+                : `Call fetch_channel_thumbnails to fetch them. Channels with thumbnails: ${fetched.join(', ')}.`,
+        });
+    }
+    if (second !== undefined) {
+        throw new YouTubeError('INVALID_INPUT', `"${channel}" matches more than one channel.`, {
+            nextStep: `Use the channel id instead: ${[first, second].map((m) => m.channel.channelId).join(', ')}.`,
+        });
+    }
+    return first;
+}
+export async function deleteThumbnails(channelId) {
+    const directory = thumbnailDir(channelId);
+    const existed = existsSync(directory);
+    await rm(directory, { recursive: true, force: true });
+    return existed;
+}
+/** Where a saved entry's file is, recomputed from validated parts; never read from the manifest. */
+export function entryPath(channelId, entry) {
+    if (entry.state !== 'saved' || entry.format === undefined)
+        return undefined;
+    return videoThumbnailPath(channelId, entry.tab, entry.videoId, entry.format);
+}
+export function channelImageFile(channelId, image) {
+    if (image.state !== 'saved' || image.format === undefined)
+        return undefined;
+    return channelImagePath(channelId, image.kind, image.format);
+}
+/** True when the file a saved record describes is on disk at the recorded size. */
+export async function isIntact(path, bytes) {
+    if (path === undefined)
+        return false;
+    try {
+        return (await stat(path)).size === bytes;
+    }
+    catch {
+        return false;
+    }
+}
+export function computeThumbnailStats(entries) {
+    const tabs = new Map();
+    let saved = 0;
+    let failed = 0;
+    let pending = 0;
+    let totalBytes = 0;
+    for (const entry of entries) {
+        const tab = tabs.get(entry.tab) ?? { videoCount: 0, savedCount: 0 };
+        tab.videoCount++;
+        if (entry.state === 'saved') {
+            saved++;
+            tab.savedCount++;
+            totalBytes += entry.bytes ?? 0;
+        }
+        else if (entry.state === 'failed')
+            failed++;
+        else
+            pending++;
+        tabs.set(entry.tab, tab);
+    }
+    return {
+        videoCount: entries.length,
+        savedCount: saved,
+        failedCount: failed,
+        pendingCount: pending,
+        totalBytes,
+        tabs: [...tabs.entries()].map(([tab, counts]) => ({ tab, ...counts })),
+    };
+}
+//# sourceMappingURL=thumbnail-store.js.map

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

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

package/dist/utils/transcript-cache.d.ts

@@ -0,0 +1,20 @@
+import { type TranscriptSegment } from './transcript.js';
+export interface TranscriptResult {
+    /** The whole transcript as plain text, unchanged from previous releases. */
+    transcript: string;
+    /** The same content with cue timings preserved. */
+    segments: TranscriptSegment[];
+    language: string;
+    videoId: string;
+    /** True when served from the local cache rather than refetched. */
+    cached: boolean;
+}
+export interface GetTranscriptOptions {
+    language?: string;
+    /** Ignore any cached copy and refetch from YouTube. */
+    refresh?: boolean;
+}
+/** True when a usable transcript is already on disk, in any language. */
+export declare function hasCachedTranscript(videoId: string): boolean;
+export declare function getTranscript(urlOrId: string, options?: GetTranscriptOptions): Promise<TranscriptResult>;
+//# sourceMappingURL=transcript-cache.d.ts.map

package/dist/utils/transcript-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-cache.d.ts","sourceRoot":"","sources":["../../src/utils/transcript-cache.ts"],"names":[],"mappings":"AAUA,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAqCD,yEAAyE;AACzE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,gBAAgB,CAAC,CAqF3B"}

package/dist/utils/transcript-cache.js

@@ -0,0 +1,127 @@
+import { join } from 'path';
+import { readFile, unlink } from 'fs/promises';
+import { existsSync, readdirSync } from 'fs';
+import { YouTubeError } from './errors.js';
+import { TIMEOUTS, runYtDlp } from './ytdlp.js';
+import { noCaptionsError } from './caption-probe.js';
+import { assertLanguageTag } from './validate.js';
+import { envInt } from './env.js';
+import { dataDir, ensurePrivateDir } from './paths.js';
+import { writeJsonAtomic } from './json-file.js';
+import { TRANSCRIPT_CACHE_VERSION, cachedTranscriptSchema, parseVtt, segmentsToText, } from './transcript.js';
+import { extractVideoId, watchUrl } from './youtube-url.js';
+/** Fetching a transcript from YouTube and keeping it on disk. */
+const CACHE_DIR = dataDir('transcripts');
+/** Captions rarely change, but a cache with no expiry is a cache that goes wrong. */
+const TRANSCRIPT_TTL_MS = envInt('YOUTUBE_MCP_TRANSCRIPT_TTL_MS', 30 * 86_400_000, { min: 0 });
+function cachePath(videoId, language) {
+    return join(CACHE_DIR, `${videoId}.${language}.json`);
+}
+async function readCachedTranscript(videoId, language) {
+    const path = cachePath(videoId, language);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = cachedTranscriptSchema.safeParse(JSON.parse(await readFile(path, 'utf-8')));
+        // Anything unreadable — an older layout, a truncated write, a hand-edit —
+        // is treated as absent and refetched, rather than half-trusted.
+        if (!parsed.success)
+            return undefined;
+        const cached = parsed.data;
+        // A cache written by an older version holds untimed text; regenerate it
+        // rather than reading it back as if it had timings.
+        if (cached.version !== TRANSCRIPT_CACHE_VERSION)
+            return undefined;
+        const fetchedAt = Date.parse(cached.fetchedAt);
+        if (Number.isFinite(fetchedAt) && Date.now() - fetchedAt > TRANSCRIPT_TTL_MS)
+            return undefined;
+        return cached;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when a usable transcript is already on disk, in any language. */
+export function hasCachedTranscript(videoId) {
+    if (!existsSync(CACHE_DIR))
+        return false;
+    return readdirSync(CACHE_DIR).some((name) => name.startsWith(`${videoId}.`) && name.endsWith('.json'));
+}
+export async function getTranscript(urlOrId, options = {}) {
+    const preferredLang = options.language ?? 'en';
+    const videoId = extractVideoId(urlOrId);
+    assertLanguageTag(preferredLang);
+    const url = watchUrl(videoId);
+    await ensurePrivateDir(CACHE_DIR);
+    if (!options.refresh) {
+        const cached = await readCachedTranscript(videoId, preferredLang);
+        if (cached) {
+            return {
+                transcript: segmentsToText(cached.segments),
+                segments: cached.segments,
+                language: cached.language,
+                videoId,
+                cached: true,
+            };
+        }
+    }
+    const tempDir = join(CACHE_DIR, 'temp');
+    await ensurePrivateDir(tempDir);
+    const outputTemplate = join(tempDir, videoId);
+    try {
+        await runYtDlp([
+            '--skip-download',
+            '--write-auto-sub',
+            '--write-sub',
+            '--sub-lang',
+            `${preferredLang},${preferredLang}-orig`,
+            '--sub-format',
+            'vtt',
+            '--convert-subs',
+            'vtt',
+            '-o',
+            outputTemplate,
+        ], { label: 'get_transcript', timeoutMs: TIMEOUTS.transcript, target: url });
+        const candidates = [
+            { file: `${outputTemplate}.${preferredLang}.vtt`, language: preferredLang },
+            {
+                file: `${outputTemplate}.${preferredLang}-orig.vtt`,
+                language: `${preferredLang} (auto-generated)`,
+            },
+            { file: `${outputTemplate}.en.vtt`, language: 'en' },
+        ];
+        const found = candidates.find((candidate) => existsSync(candidate.file));
+        if (!found)
+            throw await noCaptionsError(url, preferredLang);
+        const segments = parseVtt(await readFile(found.file, 'utf-8'));
+        if (segments.length === 0)
+            throw await noCaptionsError(url, preferredLang);
+        const entry = {
+            version: TRANSCRIPT_CACHE_VERSION,
+            videoId,
+            language: found.language,
+            fetchedAt: new Date().toISOString(),
+            segments,
+        };
+        await writeJsonAtomic(cachePath(videoId, preferredLang), entry, { pretty: false });
+        await unlink(found.file).catch(() => undefined);
+        return {
+            transcript: segmentsToText(segments),
+            segments,
+            language: found.language,
+            videoId,
+            cached: false,
+        };
+    }
+    catch (error) {
+        // Already typed and actionable — pass it through rather than flattening it
+        // into a generic string, which is what the old wrapper did to every failure.
+        if (error instanceof YouTubeError)
+            throw error;
+        throw new YouTubeError('YTDLP_FAILED', `Could not read the transcript for ${videoId}.`, {
+            nextStep: 'Verify the video exists and has captions, or call check_health.',
+            cause: error,
+        });
+    }
+}
+//# sourceMappingURL=transcript-cache.js.map

package/dist/utils/transcript-cache.js.map

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

package/dist/utils/transcript-search.d.ts

@@ -0,0 +1,20 @@
+import type { TranscriptSegment } from './transcript.js';
+/** Finding a phrase in a transcript. */
+export interface TranscriptMatch {
+    segment: TranscriptSegment;
+    /** The matched text, for highlighting. */
+    match: string;
+    url: string;
+}
+/**
+ * Find a compiled pattern in a transcript.
+ *
+ * Matching runs over the joined text of a small window of segments, not each
+ * segment alone, so a phrase split across a caption boundary is still found —
+ * which is most phrases, since caption breaks fall mid-sentence.
+ *
+ * The pattern arrives compiled (see `compilePattern`), so it was validated
+ * exactly once, with the flags in force here.
+ */
+export declare function searchSegments(segments: TranscriptSegment[], pattern: RegExp, limit?: number): TranscriptMatch[];
+//# sourceMappingURL=transcript-search.d.ts.map

package/dist/utils/transcript-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-search.d.ts","sourceRoot":"","sources":["../../src/utils/transcript-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,wCAAwC;AAExC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,OAAO,EAAE,MAAM,EACf,KAAK,SAAK,GACT,eAAe,EAAE,CA0BnB"}

package/dist/utils/transcript-search.js

@@ -0,0 +1,35 @@
+/**
+ * Find a compiled pattern in a transcript.
+ *
+ * Matching runs over the joined text of a small window of segments, not each
+ * segment alone, so a phrase split across a caption boundary is still found —
+ * which is most phrases, since caption breaks fall mid-sentence.
+ *
+ * The pattern arrives compiled (see `compilePattern`), so it was validated
+ * exactly once, with the flags in force here.
+ */
+export function searchSegments(segments, pattern, limit = 20) {
+    const matches = [];
+    for (let index = 0; index < segments.length && matches.length < limit; index++) {
+        const current = segments[index];
+        if (!current)
+            continue;
+        // Two segments of lookahead covers phrases spanning a caption break.
+        const haystack = segments
+            .slice(index, index + 3)
+            .map((segment) => segment.text)
+            .join(' ');
+        pattern.lastIndex = 0;
+        const found = pattern.exec(haystack);
+        if (!found)
+            continue;
+        // The lookahead window means a hit can start in a *later* segment. Only
+        // accept it here if it begins inside this one; otherwise the same hit is
+        // reported once per preceding segment, and attributed to the wrong time.
+        if (found.index > current.text.length)
+            continue;
+        matches.push({ segment: current, match: found[0], url: '' });
+    }
+    return matches;
+}
+//# sourceMappingURL=transcript-search.js.map

package/dist/utils/transcript-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-search.js","sourceRoot":"","sources":["../../src/utils/transcript-search.ts"],"names":[],"mappings":"AAWA;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,QAA6B,EAC7B,OAAe,EACf,KAAK,GAAG,EAAE;IAEV,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO;YAAE,SAAS;QAEvB,qEAAqE;QACrE,MAAM,QAAQ,GAAG,QAAQ;aACtB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC;aACvB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;aAC9B,IAAI,CAAC,GAAG,CAAC,CAAC;QAEb,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK;YAAE,SAAS;QAErB,wEAAwE;QACxE,yEAAyE;QACzE,yEAAyE;QACzE,IAAI,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM;YAAE,SAAS;QAEhD,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/transcript.d.ts

@@ -15,15 +15,14 @@ export declare const transcriptSegmentSchema: z.ZodObject<{
     text: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     text: string;
-    start: number;
     end: number;
+    start: number;
 }, {
     text: string;
-    start: number;
     end: number;
+    start: number;
 }>;
 export type TranscriptSegment = z.infer<typeof transcriptSegmentSchema>;
-export type TranscriptFormat = 'text' | 'timestamped' | 'segments';
 /** Bumped whenever the cache representation changes, so old files are refetched. */
 export declare const TRANSCRIPT_CACHE_VERSION = 2;
 /**
@@ -47,39 +46,37 @@ export declare const cachedTranscriptSchema: z.ZodObject<{
         text: z.ZodString;
     }, "strip", z.ZodTypeAny, {
         text: string;
-        start: number;
         end: number;
+        start: number;
     }, {
         text: string;
-        start: number;
         end: number;
+        start: number;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     videoId: string;
     version: number;
     language: string;
+    fetchedAt: string;
     segments: {
         text: string;
-        start: number;
         end: number;
+        start: number;
     }[];
-    fetchedAt: string;
 }, {
     videoId: string;
     version: number;
     language: string;
+    fetchedAt: string;
     segments: {
         text: string;
-        start: number;
         end: number;
+        start: number;
     }[];
-    fetchedAt: string;
 }>;
 export type CachedTranscript = z.infer<typeof cachedTranscriptSchema>;
 /** 3723.5 -> "1:02:03", 62 -> "1:02" */
 export declare function formatTimestamp(totalSeconds: number): string;
-/** 3723.5 -> "01:02:03,500" — the SRT wire format. */
-export declare function formatSrtTimestamp(totalSeconds: number): string;
 /**
  * Parse WebVTT into segments.
  *
@@ -105,24 +102,6 @@ export declare function sliceSegments(segments: TranscriptSegment[], range: {
     startTime?: number;
     endTime?: number;
 }): TranscriptSegment[];
-export interface TranscriptMatch {
-    segment: TranscriptSegment;
-    /** The matched text, for highlighting. */
-    match: string;
-    url: string;
-}
-/**
- * Find a phrase or pattern in a transcript.
- *
- * Matching runs over the joined text of a small window of segments, not each
- * segment alone, so a phrase split across a caption boundary is still found —
- * which is most phrases, since caption breaks fall mid-sentence.
- */
-export declare function searchSegments(segments: TranscriptSegment[], query: string, options?: {
-    regex?: boolean;
-    caseSensitive?: boolean;
-    limit?: number;
-}): TranscriptMatch[];
 export interface TruncationResult {
     text: string;
     truncated: boolean;
@@ -138,6 +117,6 @@ export interface TruncationResult {
  * continue from.
  */
 export declare function windowText(text: string, offset?: number, maxChars?: number): TruncationResult;
-export declare function toSrt(segments: TranscriptSegment[]): string;
-export declare function toVtt(segments: TranscriptSegment[]): string;
+export * from './subtitles.js';
+export * from './transcript-search.js';
 //# sourceMappingURL=transcript.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/utils/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB;IAClC,2CAA2C;;;;;;;;;;;;EAI3C,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,aAAa,GAAG,UAAU,CAAC;AAEnE,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;QAtBjC,2CAA2C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B3C,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS5D;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS/D;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CA4BhE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAMpE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAI3E;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,iBAAiB,EAAE,CAOrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACzE,eAAe,EAAE,CAiCnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAcxF;AAED,wBAAgB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAY3D;AAED,wBAAgB,KAAK,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAW3D"}
+{"version":3,"file":"transcript.d.ts","sourceRoot":"","sources":["../../src/utils/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AAEH,eAAO,MAAM,uBAAuB;IAClC,2CAA2C;;;;;;;;;;;;EAI3C,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;QApBjC,2CAA2C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B3C,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAS5D;AA0BD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,EAAE,CA4BhE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAMpE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAI3E;AAED,iDAAiD;AACjD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAAE,EAC7B,KAAK,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,iBAAiB,EAAE,CAOrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAcxF;AAED,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC"}

package/dist/utils/transcript.js

@@ -44,16 +44,6 @@ export function formatTimestamp(totalSeconds) {
         return `${hours}:${minutes.toString().padStart(2, '0')}:${paddedSeconds}`;
     return `${minutes}:${paddedSeconds}`;
 }
-/** 3723.5 -> "01:02:03,500" — the SRT wire format. */
-export function formatSrtTimestamp(totalSeconds) {
-    const clamped = Math.max(0, totalSeconds);
-    const hours = Math.floor(clamped / 3600);
-    const minutes = Math.floor((clamped % 3600) / 60);
-    const seconds = Math.floor(clamped % 60);
-    const millis = Math.round((clamped - Math.floor(clamped)) * 1000);
-    const pad = (value, width = 2) => value.toString().padStart(width, '0');
-    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)},${pad(millis, 3)}`;
-}
 /**
  * WebVTT cue text is a small markup language: inline timestamps and <c> spans
  * for karaoke-style highlighting. The parser hands back the spec's parsed tree,
@@ -143,42 +133,6 @@ export function sliceSegments(segments, range) {
     // relevant to the range the caller asked about.
     return segments.filter((segment) => segment.end > from && segment.start < to);
 }
-/**
- * Find a phrase or pattern in a transcript.
- *
- * Matching runs over the joined text of a small window of segments, not each
- * segment alone, so a phrase split across a caption boundary is still found —
- * which is most phrases, since caption breaks fall mid-sentence.
- */
-export function searchSegments(segments, query, options = {}) {
-    const { regex = false, caseSensitive = false, limit = 20 } = options;
-    const flags = caseSensitive ? 'g' : 'gi';
-    const pattern = regex
-        ? new RegExp(query, flags)
-        : new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), flags);
-    const matches = [];
-    for (let index = 0; index < segments.length && matches.length < limit; index++) {
-        const current = segments[index];
-        if (!current)
-            continue;
-        // Two segments of lookahead covers phrases spanning a caption break.
-        const haystack = segments
-            .slice(index, index + 3)
-            .map((segment) => segment.text)
-            .join(' ');
-        pattern.lastIndex = 0;
-        const found = pattern.exec(haystack);
-        if (!found)
-            continue;
-        // The lookahead window means a hit can start in a *later* segment. Only
-        // accept it here if it begins inside this one; otherwise the same hit is
-        // reported once per preceding segment, and attributed to the wrong time.
-        if (found.index > current.text.length)
-            continue;
-        matches.push({ segment: current, match: found[0], url: '' });
-    }
-    return matches;
-}
 /**
  * Window a long string.
  *
@@ -198,22 +152,6 @@ export function windowText(text, offset = 0, maxChars) {
     const end = softEnd > from ? softEnd : hardEnd;
     return { text: text.slice(from, end), truncated: true, nextOffset: end, totalChars };
 }
-export function toSrt(segments) {
-    return (segments
-        .map((segment, index) => [
-        index + 1,
-        `${formatSrtTimestamp(segment.start)} --> ${formatSrtTimestamp(segment.end)}`,
-        segment.text,
-    ].join('\n'))
-        .join('\n\n') + '\n');
-}
-export function toVtt(segments) {
-    const body = segments
-        .map((segment) => [
-        `${formatSrtTimestamp(segment.start).replace(',', '.')} --> ${formatSrtTimestamp(segment.end).replace(',', '.')}`,
-        segment.text,
-    ].join('\n'))
-        .join('\n\n');
-    return `WEBVTT\n\n${body}\n`;
-}
+export * from './subtitles.js';
+export * from './transcript-search.js';
 //# sourceMappingURL=transcript.js.map