Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
import { spawn } from "child_process";
import { z } from "zod";
import { absentWhenNull } from "../utils/zod-helpers.js";
import { paths, pythonEnv } from "../config/paths.js";
import { ClipsHistory } from "../services/clips-history.js";
import {
buildChannelListArgs,
buildVideoInfoArgs,
extractYouTubeVideoId,
isCookieBrowser,
normalizeChannelUrl,
} from "../utils/ytdlp-args.js";
import { selectBestCaptionTrack, parseVtt, parseJson3, cuesToWords } from "../utils/captions.js";
import type { WordTimestamp } from "../models/index.js";
const history = new ClipsHistory();
export const mineChannelToolDef = {
name: "mine_channel",
description:
"Mine a YouTube channel's back catalog for clip-worthy moments without downloading any video. " +
"action='list' lists a channel's uploads (title, duration, upload date), flagging ones already mined " +
"into clip_history so you don't re-suggest from them. action='mine' fetches one video's existing " +
"captions (never the video itself), preferring the original-language track over an auto-translated one, " +
"and converts them to podcli's word-level transcript format. Feed the result straight into the " +
"suggest_clips flow the same way import_transcript's output is used. Never downloads a full video; " +
"that only happens if you separately choose to render a clip from one.",
};
export interface MineChannelInput {
action: "list" | "mine";
channel_url?: string;
video_url?: string;
limit?: number;
cookies_from_browser?: string;
}
interface RunResult {
stdout: string;
stderr: string;
code: number;
}
async function runYtDlp(args: string[]): Promise<RunResult> {
return new Promise((resolve, reject) => {
const proc = spawn(paths.pythonPath, args, { env: pythonEnv() });
let stdout = "";
let stderr = "";
proc.stdout.on("data", (d) => (stdout += d.toString()));
proc.stderr.on("data", (d) => (stderr += d.toString()));
proc.on("error", reject);
proc.on("close", (code) => resolve({ stdout, stderr, code: code ?? 1 }));
});
}
async function fetchText(url: string): Promise<string> {
const res = await fetch(url);
if (!res.ok) throw new Error(`HTTP ${res.status} fetching caption track`);
return res.text();
}
const uploadEntrySchema = z.looseObject({
id: absentWhenNull(z.string()),
title: z.string().catch(""),
duration: absentWhenNull(z.number()),
upload_date: absentWhenNull(z.string()),
url: absentWhenNull(z.string()),
});
const captionTracksSchema = z.record(z.string(), z.array(z.object({ ext: z.string(), url: z.string() })));
const videoInfoSchema = z.looseObject({
id: z.string(),
title: z.string(),
duration: absentWhenNull(z.number()),
subtitles: absentWhenNull(captionTracksSchema),
automatic_captions: absentWhenNull(captionTracksSchema),
});
export interface ChannelUpload {
video_id: string;
title: string;
duration?: number;
upload_date?: string;
url: string;
already_mined: boolean;
}
export interface MinedVideoResult {
video_id: string;
title: string;
duration?: number;
url: string;
already_mined: boolean;
track: { lang: string; kind: "manual" | "auto" } | null;
transcript: {
words: WordTimestamp[];
segments: Array<{ text: string; start: number; end: number }>;
duration?: number;
language: string;
text: string;
} | null;
message: string;
}
// Injectable I/O so the orchestration (parsing, track selection, dedup) is
// testable against fixture data with zero network or subprocess calls.
export interface MineChannelDeps {
runYtDlp: (args: string[]) => Promise<RunResult>;
fetchText: (url: string) => Promise<string>;
minedVideoIds: () => Promise<Set<string>>;
}
export async function listChannelUploads(
deps: MineChannelDeps,
input: { channel_url: string; limit?: number; cookies_from_browser?: string },
): Promise<ChannelUpload[]> {
const args = buildChannelListArgs({
channelUrl: normalizeChannelUrl(input.channel_url),
limit: input.limit,
cookiesFromBrowser: isCookieBrowser(input.cookies_from_browser) ? input.cookies_from_browser : undefined,
});
const { stdout, stderr, code } = await deps.runYtDlp(args);
if (code !== 0) {
throw new Error(stderr.trim() || "yt-dlp failed to list the channel's uploads");
}
const minedIds = await deps.minedVideoIds();
return stdout
.trim()
.split("\n")
.filter(Boolean)
.flatMap((line) => {
const u = uploadEntrySchema.parse(JSON.parse(line));
// A tab or sub-playlist entry (e.g. "Shorts", "Live") has no video id of
// its own: only real uploads do.
if (!u.id) return [];
return [
{
video_id: u.id,
title: u.title,
duration: u.duration,
upload_date: u.upload_date,
url: u.url ?? `https://www.youtube.com/watch?v=${u.id}`,
already_mined: minedIds.has(u.id),
},
];
});
}
export async function mineVideoCaptions(
deps: MineChannelDeps,
input: { video_url: string; cookies_from_browser?: string },
): Promise<MinedVideoResult> {
const args = buildVideoInfoArgs({
videoUrl: input.video_url,
cookiesFromBrowser: isCookieBrowser(input.cookies_from_browser) ? input.cookies_from_browser : undefined,
});
const { stdout, stderr, code } = await deps.runYtDlp(args);
if (code !== 0) {
throw new Error(stderr.trim() || "yt-dlp failed to fetch video info");
}
// --dump-json prints exactly one JSON object; take the last non-empty line
// defensively in case a warning slipped through on an earlier line.
const jsonLine = stdout.trim().split("\n").filter(Boolean).at(-1);
if (!jsonLine) throw new Error("yt-dlp returned no video info");
const info = videoInfoSchema.parse(JSON.parse(jsonLine));
// --no-playlist stops a playlist/mix url from resolving to its first entry,
// but a url that already names one video (e.g. a stale redirect) can still
// resolve to a different id than the one asked for. Catch that here rather
// than silently returning the wrong video's captions.
const requestedId = extractYouTubeVideoId(input.video_url);
if (requestedId && requestedId !== info.id) {
throw new Error(
`yt-dlp resolved ${input.video_url} to video ${info.id}, not the requested ${requestedId}`,
);
}
const minedIds = await deps.minedVideoIds();
const alreadyMined = minedIds.has(info.id);
const track = selectBestCaptionTrack(info.subtitles, info.automatic_captions);
if (!track) {
return {
video_id: info.id,
title: info.title,
duration: info.duration,
url: input.video_url,
already_mined: alreadyMined,
track: null,
transcript: null,
message: "No captions available for this video, nothing to mine.",
};
}
const captionText = await deps.fetchText(track.url);
const { words, segments } =
track.ext === "json3"
? parseJson3(captionText)
: (() => {
const cues = parseVtt(captionText);
return { words: cuesToWords(cues), segments: cues.map((c) => ({ text: c.text, start: c.start, end: c.end })) };
})();
const language = track.lang.replace(/-orig$/, "");
return {
video_id: info.id,
title: info.title,
duration: info.duration,
url: input.video_url,
already_mined: alreadyMined,
track: { lang: track.lang, kind: track.kind },
transcript: {
words,
segments,
duration: info.duration,
language,
text: words.map((w) => w.word).join(" "),
},
message: alreadyMined
? "This video already has clips in history. Review before re-mining to avoid duplicates."
: `Mined ${words.length} words from the ${track.kind} ${track.lang} track. ` +
"Use this transcript the same way import_transcript's output is used, then suggest_clips.",
};
}
const defaultDeps: MineChannelDeps = {
runYtDlp,
fetchText,
minedVideoIds: () => history.minedYouTubeVideoIds(),
};
export async function handleMineChannel(input: MineChannelInput): Promise<string> {
if (input.action === "list") {
if (!input.channel_url) throw new Error("channel_url is required for action=list");
const uploads = await listChannelUploads(defaultDeps, {
channel_url: input.channel_url,
limit: input.limit,
cookies_from_browser: input.cookies_from_browser,
});
return JSON.stringify({ uploads, count: uploads.length });
}
if (!input.video_url) throw new Error("video_url is required for action=mine");
const result = await mineVideoCaptions(defaultDeps, {
video_url: input.video_url,
cookies_from_browser: input.cookies_from_browser,
});
return JSON.stringify(result);
}