tokwatchr 0.6.5 → 0.7.1

package/dist/cli/index.mjs

@@ -0,0 +1,1464 @@
+#! /usr/bin/env node
+import { cac } from "cac";
+import { basename, dirname, join } from "node:path";
+import pc from "picocolors";
+import { Impit } from "impit";
+import { spawn, spawnSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createWriteStream, existsSync, mkdirSync } from "node:fs";
+//#region package.json
+var version = "0.7.1";
+//#endregion
+//#region src/api/client.ts
+/**
+* Create an `Impit` HTTP client configured for TikTok.
+*
+* Uses browser TLS fingerprint emulation to bypass bot detection.
+*/
+function createClient(options = {}) {
+	const impitOptions = { browser: options.browser ?? "chrome" };
+	if (options.proxyUrl) impitOptions.proxyUrl = options.proxyUrl;
+	if (options.timeout) impitOptions.timeout = options.timeout;
+	if (options.headers && Object.keys(options.headers).length > 0) impitOptions.headers = options.headers;
+	if (options.cookieJar) {
+		const jar = options.cookieJar;
+		impitOptions.cookieJar = {
+			setCookie: (cookie, url) => Promise.resolve(jar.setCookie(cookie, url)),
+			getCookieString: (url) => Promise.resolve(jar.getCookieString(url))
+		};
+	}
+	return new Impit(impitOptions);
+}
+//#endregion
+//#region src/errors.ts
+var TikTokLiveError = class extends Error {
+	name = "TikTokLiveError";
+};
+var UserOfflineError = class extends TikTokLiveError {
+	name = "UserOfflineError";
+	constructor(username) {
+		super(`User "${username}" is not currently live (or does not exist)`);
+	}
+};
+var UserNotFoundError = class extends TikTokLiveError {
+	name = "UserNotFoundError";
+	constructor(username) {
+		super(`User "${username}" does not exist on TikTok`);
+	}
+};
+var RoomResolveError = class extends TikTokLiveError {
+	name = "RoomResolveError";
+	constructor(username, cause) {
+		super(`Failed to resolve room ID for "${username}" — may not exist or be offline${cause ? `: ${cause}` : ""}`);
+	}
+};
+var StreamFetchError = class extends TikTokLiveError {
+	name = "StreamFetchError";
+	constructor(roomId, cause) {
+		super(`Failed to fetch stream URL for room ${roomId}${cause ? `: ${cause}` : ""}`);
+	}
+};
+var DownloadFailedError = class extends TikTokLiveError {
+	name = "DownloadFailedError";
+	constructor(message, cause) {
+		super(`${message}${cause ? `: ${cause}` : ""}`);
+	}
+};
+var FfmpegError = class extends TikTokLiveError {
+	name = "FfmpegError";
+	constructor(message, exitCode) {
+		super(`FFmpeg error: ${message}${exitCode != null ? ` (exit code ${exitCode})` : ""}`);
+	}
+};
+var AbortError = class extends TikTokLiveError {
+	name = "AbortError";
+	constructor() {
+		super("Download was aborted");
+	}
+};
+//#endregion
+//#region src/api/room.ts
+/**
+* TikTok API endpoint patterns for room ID resolution.
+*/
+const TIKTOK_LIVE_URL = "https://www.tiktok.com/@{username}/live";
+const TIKTOK_PROFILE_URL = "https://www.tiktok.com/@{username}";
+const TIKTOK_API_ROOM_URL = "https://www.tiktok.com/api-live/user/room/?aid=1988&uniqueId={username}&sourceType=54";
+/**
+* Check whether a TikTok username exists by hitting the profile page.
+* Throws UserNotFoundError if the account doesn't exist.
+*/
+async function checkUserExists(username, impIt, signal) {
+	const url = TIKTOK_PROFILE_URL.replace("{username}", username);
+	if ((await impIt.fetch(url, {
+		headers: {
+			Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+			"Accept-Language": "en-US,en;q=0.9"
+		},
+		signal
+	})).status === 404) throw new UserNotFoundError(username);
+}
+/**
+* Resolve a TikTok username to a live room ID.
+*
+* Strategy:
+* 0. Verify the user exists (profile page check).
+* 1. Scrape the user's live page HTML for the room ID in SIGI_STATE.
+* 2. Fall back to the TikTok API.
+* 3. Throw if neither works.
+*/
+async function resolveRoomId(username, impIt, options = {}) {
+	const cleanUsername = username.replace(/^@/, "").trim();
+	await checkUserExists(cleanUsername, impIt, options.signal);
+	const roomId = await tryScrapeRoomId(cleanUsername, impIt, options.signal);
+	if (roomId) return roomId;
+	const apiRoomId = await tryApiRoomId(cleanUsername, impIt, options.signal);
+	if (apiRoomId) return apiRoomId;
+	throw new RoomResolveError(cleanUsername);
+}
+/**
+* Try to extract room ID from the TikTok live page HTML.
+*/
+async function tryScrapeRoomId(username, impIt, signal) {
+	try {
+		const url = TIKTOK_LIVE_URL.replace("{username}", username);
+		const response = await impIt.fetch(url, {
+			headers: {
+				Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+				"Accept-Language": "en-US,en;q=0.9"
+			},
+			signal
+		});
+		if (!response.ok) return null;
+		const html = await response.text();
+		const roomId = extractRoomIdFromSigiState(html);
+		if (roomId) return roomId;
+		const roomIdMatch = html.match(/"roomId"\s*:\s*"(\d+)"/);
+		if (roomIdMatch?.[1]) return roomIdMatch[1];
+		const roomIdParamMatch = html.match(/room_id=(\d+)/);
+		if (roomIdParamMatch?.[1]) return roomIdParamMatch[1];
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Try to extract room ID from SIGI_STATE embedded JSON.
+*/
+function extractRoomIdFromSigiState(html) {
+	try {
+		const match = html.match(/<script[^>]*id=["']SIGI_STATE["'][^>]*type=["']application\/json["'][^>]*>([\s\S]*?)<\/script>/i);
+		if (!match) return null;
+		const sigiState = JSON.parse(match[1]);
+		const liveRoom = sigiState?.LiveRoom?.liveRoomInfo;
+		if (liveRoom?.roomId) return String(liveRoom.roomId);
+		const liveRoom2 = sigiState?.LiveRoom?.liveRoomInfo?.user?.roomId;
+		if (liveRoom2) return String(liveRoom2);
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Try to resolve room ID via the TikTok API.
+*/
+async function tryApiRoomId(username, impIt, signal) {
+	try {
+		const url = TIKTOK_API_ROOM_URL.replace("{username}", encodeURIComponent(username));
+		const response = await impIt.fetch(url, {
+			headers: {
+				Accept: "application/json, text/plain, */*",
+				Referer: `https://www.tiktok.com/@${username}`
+			},
+			signal
+		});
+		if (!response.ok) return null;
+		const dataObj = (await response.json()).data;
+		if (!dataObj) return null;
+		if (dataObj.liveRoom?.status !== 2) return null;
+		const user = dataObj.user;
+		if (!user) return null;
+		const roomId = user.roomId;
+		if (roomId) return String(roomId);
+		return null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region src/utils/quality.ts
+/**
+* Quality ladder sorted from highest to lowest.
+*/
+const QUALITY_ORDER = [
+	"fullhd1",
+	"hd1",
+	"sd2",
+	"sd1"
+];
+const QUALITY_LABELS = {
+	fullhd1: "1080p",
+	hd1: "720p",
+	sd2: "540p",
+	sd1: "360p"
+};
+const QUALITY_LEVELS = {
+	fullhd1: 4,
+	hd1: 3,
+	sd2: 2,
+	sd1: 1
+};
+/**
+* Build a QualityOption from a raw url object.
+*/
+function buildQualityOption(key, flv, hls) {
+	return {
+		key,
+		label: QUALITY_LABELS[key],
+		level: QUALITY_LEVELS[key],
+		flv,
+		hls: hls ?? ""
+	};
+}
+/**
+* Select a quality from available options.
+*
+* @param qualities - Available quality options to choose from.
+* @param preference - "best" (highest available), "worst" (lowest), or a specific key.
+* @returns The selected quality option.
+*/
+function selectQuality(qualities, preference) {
+	if (qualities.length === 0) throw new Error("No stream qualities available");
+	if (preference === "best") return qualities[0];
+	if (preference === "worst") return qualities[qualities.length - 1];
+	return qualities.find((q) => q.key === preference) ?? qualities[0];
+}
+/**
+* Parse quality options from the TikTok room/info response.
+*
+* Supports both the legacy `flv_pull_url` format and the newer
+* `live_core_sdk_data` format.
+*/
+function parseQualities(data) {
+	if (!data || typeof data !== "object") return [];
+	const d = data;
+	const sdkQualities = parseSdkQualities(d);
+	if (sdkQualities.length > 0) return sdkQualities;
+	return parseLegacyQualities(d);
+}
+function parseSdkQualities(data) {
+	try {
+		const streamUrl = data.stream_url;
+		if (!streamUrl) return [];
+		const sdkData = streamUrl.live_core_sdk_data;
+		if (!sdkData) return [];
+		const pullData = sdkData.pull_data;
+		if (!pullData) return [];
+		const streamDataStr = pullData.stream_data;
+		if (typeof streamDataStr !== "string") return [];
+		const innerData = JSON.parse(streamDataStr)?.data;
+		if (!innerData) return [];
+		const qualities = [];
+		for (const key of QUALITY_ORDER) {
+			const q = innerData[key];
+			if (!q) continue;
+			const main = q.main;
+			if (!main) continue;
+			const flv = main.flv;
+			if (typeof flv !== "string" || flv.length === 0) continue;
+			const hls = typeof main.hls === "string" ? main.hls : void 0;
+			qualities.push(buildQualityOption(key, flv, hls));
+		}
+		return qualities;
+	} catch {
+		return [];
+	}
+}
+function parseLegacyQualities(data) {
+	try {
+		const streamUrl = data.stream_url;
+		if (!streamUrl) return [];
+		const flvPullUrl = streamUrl.flv_pull_url;
+		if (!flvPullUrl) return [];
+		const qualities = [];
+		const keyMap = {
+			FULL_HD1: "fullhd1",
+			HD1: "hd1",
+			SD2: "sd2",
+			SD1: "sd1"
+		};
+		for (const [tikTokKey, url] of Object.entries(flvPullUrl)) {
+			const key = keyMap[tikTokKey];
+			if (key && typeof url === "string" && url.length > 0) qualities.push(buildQualityOption(key, url));
+		}
+		qualities.sort((a, b) => b.level - a.level);
+		return qualities;
+	} catch {
+		return [];
+	}
+}
+//#endregion
+//#region src/api/stream.ts
+/**
+* Fetch stream info for a given room ID.
+*
+* Calls the TikTok webcast room/info API and parses the response
+* to extract stream URLs and quality options.
+*/
+async function fetchStreamInfo(roomId, username, impIt, options = {}) {
+	const url = `https://webcast.tiktok.com/webcast/room/info/?aid=1988&room_id=${encodeURIComponent(roomId)}`;
+	const response = await impIt.fetch(url, {
+		headers: {
+			Accept: "application/json, text/plain, */*",
+			Referer: `https://www.tiktok.com/@${username}/live`
+		},
+		signal: options.signal
+	});
+	if (!response.ok) throw new StreamFetchError(roomId, `HTTP ${response.status}: ${response.statusText}`);
+	const data = (await response.json()).data;
+	if (!data) throw new StreamFetchError(roomId, "No data in response");
+	const status = data.status;
+	if (status !== 2) throw new StreamFetchError(roomId, `Room is not live (status: ${status})`);
+	const qualities = parseQualities(data);
+	if (qualities.length === 0) throw new StreamFetchError(roomId, "No stream qualities found");
+	const selectedQuality = selectQuality(qualities, options.quality ?? "best");
+	const title = typeof data.title === "string" ? data.title : "";
+	const viewerCount = typeof data.stats?.viewer_count === "number" ? data.stats.viewer_count : 0;
+	return {
+		roomId,
+		username,
+		title,
+		qualities,
+		selectedQuality,
+		streamUrl: selectedQuality.flv,
+		viewerCount,
+		startedAt: /* @__PURE__ */ new Date()
+	};
+}
+//#endregion
+//#region src/download/ffmpeg.ts
+/**
+* Parse ffmpeg stderr for duration and time progress.
+*
+* ffmpeg outputs lines like:
+*   frame=  123 fps= 30 q=28.0 size=    1024kB time=00:01:23.45 ...
+*/
+function parseFfmpegProgress(line) {
+	const result = {};
+	const timeMatch = line.match(/time=(\d+):(\d+):(\d+)\.(\d+)/);
+	if (timeMatch) {
+		const hours = Number(timeMatch[1]);
+		const minutes = Number(timeMatch[2]);
+		const seconds = Number(timeMatch[3]);
+		result.duration = hours * 3600 + minutes * 60 + seconds;
+	}
+	const sizeMatch = line.match(/size=\s*(\d+)(\w+)B/);
+	if (sizeMatch && sizeMatch.length >= 3) {
+		const value = Number(sizeMatch[1]);
+		const unit = sizeMatch[2];
+		if (unit === "k" || unit === "K") result.sizeBytes = value * 1024;
+		else if (unit === "m" || unit === "M") result.sizeBytes = value * 1024 * 1024;
+		else result.sizeBytes = value;
+	}
+	return result.sizeBytes !== void 0 || result.duration !== void 0 ? result : null;
+}
+/**
+* Download a livestream via ffmpeg.
+*
+* Spawns ffmpeg as a subprocess, pipes the stream URL as input,
+* and writes the transcoded/remuxed output to the specified path.
+*
+* Advantages over raw HTTP:
+* - Proper container format (mp4/mkv)
+* - Stream copy (fast) or re-encode
+* - Better handling of stream interruptions
+*/
+async function downloadWithFfmpeg(options) {
+	const { ffmpegPath, url, outputPath, quality, args: extraArgs, bitrate, signal, onProgress, maxDuration, timeout = 30 } = options;
+	const ffmpegArgs = [
+		"-y",
+		"-i",
+		url
+	];
+	if (maxDuration && maxDuration > 0 && maxDuration < Infinity) ffmpegArgs.push("-t", String(maxDuration));
+	if (bitrate) ffmpegArgs.push("-c:v", "libx264", "-b:v", bitrate, "-c:a", "copy");
+	else if (extraArgs && extraArgs.length > 0) ffmpegArgs.push(...extraArgs);
+	else ffmpegArgs.push("-c", "copy");
+	ffmpegArgs.push(outputPath);
+	return new Promise((resolve, reject) => {
+		const proc = spawn(ffmpegPath, ffmpegArgs, {
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			signal
+		});
+		let stderrBuffer = "";
+		let sizeBytes = 0;
+		let duration = 0;
+		let firstDataTimer = setTimeout(() => {
+			firstDataTimer = null;
+			proc.kill("SIGTERM");
+			reject(new FfmpegError(`ffmpeg produced no output within ${timeout}s — check the stream URL`));
+		}, timeout * 1e3);
+		proc.stderr?.on("data", (chunk) => {
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			const text = typeof chunk === "string" ? chunk : chunk.toString("utf-8");
+			stderrBuffer += text;
+			const lines = text.split("\n");
+			for (const line of lines) {
+				const parsed = parseFfmpegProgress(line);
+				if (parsed) {
+					if (parsed.duration !== void 0) duration = parsed.duration;
+					if (parsed.sizeBytes !== void 0) sizeBytes = parsed.sizeBytes;
+					onProgress?.({
+						downloadedBytes: sizeBytes,
+						downloadedMB: sizeBytes / (1024 * 1024),
+						duration,
+						speed: duration > 0 ? sizeBytes / duration : 0,
+						speedMBps: duration > 0 ? sizeBytes / duration / (1024 * 1024) : 0,
+						quality,
+						state: "recording"
+					});
+				}
+			}
+		});
+		proc.on("error", (err) => {
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			if (err.name === "AbortError") {
+				resolve({
+					sizeBytes,
+					duration,
+					format: outputPath.endsWith(".mkv") ? "mkv" : "mp4"
+				});
+				return;
+			}
+			reject(new FfmpegError(err.message));
+		});
+		proc.on("close", (code) => {
+			if (firstDataTimer) {
+				clearTimeout(firstDataTimer);
+				firstDataTimer = null;
+			}
+			if (signal?.aborted) {
+				resolve({
+					sizeBytes,
+					duration,
+					format: outputPath.endsWith(".mkv") ? "mkv" : "mp4"
+				});
+				return;
+			}
+			if (code === 0) if (sizeBytes > 0) resolve({
+				sizeBytes,
+				duration,
+				format: outputPath.endsWith(".mkv") ? "mkv" : "mp4"
+			});
+			else reject(new FfmpegError(extractFfmpegError(stderrBuffer) || "Stream was empty", code));
+			else if (code === null) if (sizeBytes > 0) resolve({
+				sizeBytes,
+				duration,
+				format: outputPath.endsWith(".mkv") ? "mkv" : "mp4"
+			});
+			else reject(new FfmpegError("Process was killed before any data was received", code));
+			else if (code === 1 || code === 255) if (sizeBytes > 0) resolve({
+				sizeBytes,
+				duration,
+				format: outputPath.endsWith(".mkv") ? "mkv" : "mp4"
+			});
+			else reject(new FfmpegError(extractFfmpegError(stderrBuffer) || `FFmpeg exited with code ${code} and no data`, code));
+			else reject(new FfmpegError(extractFfmpegError(stderrBuffer), code));
+		});
+	});
+}
+/**
+* Extract a meaningful error message from ffmpeg stderr output.
+*/
+function extractFfmpegError(stderr) {
+	const lines = stderr.split("\n").filter((l) => l.trim().length > 0);
+	const errorLines = lines.filter((l) => l.toLowerCase().includes("error") || l.toLowerCase().includes("invalid") || l.toLowerCase().includes("cannot"));
+	if (errorLines.length > 0) return errorLines[0].trim();
+	return lines[lines.length - 1]?.trim() ?? "Unknown ffmpeg error";
+}
+//#endregion
+//#region src/download/raw-http.ts
+/**
+* Download a livestream via raw HTTP FLV streaming.
+*
+* Writes the incoming FLV data directly to disk without transcoding.
+* No ffmpeg required.
+*/
+async function downloadRawHttp(options) {
+	const { url, outputPath, quality, signal, onProgress, maxDuration } = options;
+	const response = await new Impit({ browser: "chrome" }).fetch(url, { signal });
+	if (!response.ok) throw new DownloadFailedError(`HTTP ${response.status}: ${response.statusText}`);
+	const bodyReader = response.body?.getReader();
+	if (!bodyReader) throw new DownloadFailedError("No response body stream");
+	const fileStream = createWriteStream(outputPath);
+	const startTime = Date.now();
+	let downloadedBytes = 0;
+	let lastProgressTime = startTime;
+	let lastProgressBytes = 0;
+	let aborted = false;
+	const reader = bodyReader;
+	return new Promise((resolve, reject) => {
+		const abortHandler = () => {
+			aborted = true;
+			reader.cancel().catch(() => {});
+			fileStream.close();
+			reject(new AbortError());
+		};
+		signal?.addEventListener("abort", abortHandler, { once: true });
+		let durationTimer = null;
+		if (maxDuration && maxDuration > 0 && maxDuration < Infinity) durationTimer = setTimeout(() => {
+			aborted = true;
+			reader.cancel().catch(() => {});
+			fileStream.close();
+			resolve({
+				sizeBytes: downloadedBytes,
+				duration: (Date.now() - startTime) / 1e3,
+				format: "flv"
+			});
+		}, maxDuration * 1e3);
+		function pump() {
+			reader.read().then(({ done, value }) => {
+				if (done || aborted) {
+					fileStream.close();
+					if (!aborted) resolve({
+						sizeBytes: downloadedBytes,
+						duration: (Date.now() - startTime) / 1e3,
+						format: "flv"
+					});
+					if (durationTimer) clearTimeout(durationTimer);
+					signal?.removeEventListener("abort", abortHandler);
+					return;
+				}
+				downloadedBytes += value.byteLength;
+				fileStream.write(value);
+				const now = Date.now();
+				const elapsed = now - lastProgressTime;
+				if (elapsed >= 1e3) {
+					const speed = (downloadedBytes - lastProgressBytes) / (elapsed / 1e3);
+					lastProgressTime = now;
+					lastProgressBytes = downloadedBytes;
+					onProgress?.({
+						downloadedBytes,
+						downloadedMB: downloadedBytes / (1024 * 1024),
+						duration: (now - startTime) / 1e3,
+						speed,
+						speedMBps: speed / (1024 * 1024),
+						quality,
+						state: "recording"
+					});
+				}
+				pump();
+			}).catch((err) => {
+				if (aborted) return;
+				fileStream.close();
+				if (durationTimer) clearTimeout(durationTimer);
+				signal?.removeEventListener("abort", abortHandler);
+				reject(err instanceof Error ? new DownloadFailedError("Stream read error", err) : new DownloadFailedError("Stream read error"));
+			});
+		}
+		fileStream.on("error", (err) => {
+			if (aborted) return;
+			if (durationTimer) clearTimeout(durationTimer);
+			signal?.removeEventListener("abort", abortHandler);
+			reject(new DownloadFailedError("File write error", err));
+		});
+		pump();
+	});
+}
+//#endregion
+//#region src/utils/template.ts
+/**
+* Render a filename template with runtime values.
+*
+* Available variables:
+* - {username} - TikTok username
+* - {date}     - Current date in YYYYMMDD format
+* - {time}     - Current time in HHmmss format
+* - {title}    - Stream title (sanitized)
+*
+* Default template: "{username}={date}_{time}"
+*/
+function renderFilename(template, values) {
+	const now = /* @__PURE__ */ new Date();
+	const date = values.date ?? formatDate(now);
+	const time = values.time ?? formatTime(now);
+	let result = template;
+	result = result.replaceAll("{username}", values.username);
+	result = result.replaceAll("{date}", date);
+	result = result.replaceAll("{time}", time);
+	if (values.title) result = result.replaceAll("{title}", sanitize(values.title));
+	if (values.part !== void 0) result = result.replaceAll("{part}", String(values.part));
+	return result;
+}
+function formatDate(date) {
+	return `${date.getFullYear()}${String(date.getMonth() + 1).padStart(2, "0")}${String(date.getDate()).padStart(2, "0")}`;
+}
+function formatTime(date) {
+	return `${String(date.getHours()).padStart(2, "0")}${String(date.getMinutes()).padStart(2, "0")}${String(date.getSeconds()).padStart(2, "0")}`;
+}
+/**
+* Sanitize a string for use in filenames.
+* Replaces characters that are problematic across OSes.
+*/
+function sanitize(input) {
+	return input.replaceAll(/[/\\?%*:|"<>]/g, "_").replaceAll(/\s+/g, "_").replaceAll(/_+/g, "_").replace(/^_+|_+$/g, "").slice(0, 64);
+}
+//#endregion
+//#region src/TikTokLiveDownloader.ts
+const DEFAULT_OPTIONS = {
+	output: ".",
+	filename: "{username}={date}_{time}",
+	quality: "best",
+	format: "mp4",
+	useFfmpeg: false,
+	ffmpegPath: null,
+	ffmpegArgs: [],
+	bitrate: null,
+	maxDuration: Infinity,
+	maxSegmentDuration: Infinity,
+	checkInterval: 180,
+	proxyUrl: null,
+	cookieJar: null,
+	browser: "chrome",
+	timeout: 30,
+	headers: {},
+	onProgress: null,
+	onStart: null,
+	onError: null,
+	signal: null
+};
+/**
+* Main class for downloading TikTok livestreams.
+*
+* Usage:
+* ```ts
+* const d = new TikTokLiveDownloader('username')
+* d.on('progress', s => console.log(`${s.downloadedMB}MB`))
+* const result = await d.start()
+* ```
+*/
+var TikTokLiveDownloader = class {
+	username;
+	options;
+	emitter;
+	impIt;
+	_state = "idle";
+	abortController;
+	_stats = null;
+	_result = null;
+	constructor(username, opts = {}) {
+		this.username = username.replace(/^@/, "").trim();
+		this.emitter = new EventEmitter();
+		this.abortController = new AbortController();
+		this.options = this.resolveOptions(opts);
+		this.impIt = createClient({
+			browser: this.options.browser,
+			proxyUrl: this.options.proxyUrl,
+			timeout: this.options.timeout * 1e3,
+			headers: this.options.headers,
+			cookieJar: this.options.cookieJar
+		});
+		if (this.options.signal) this.options.signal.addEventListener("abort", () => this.abortController.abort(), { once: true });
+	}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return this;
+	}
+	once(event, listener) {
+		this.emitter.once(event, listener);
+		return this;
+	}
+	off(event, listener) {
+		this.emitter.off(event, listener);
+		return this;
+	}
+	emit(event, ...args) {
+		this.emitter.emit(event, ...args);
+	}
+	get state() {
+		return this._state;
+	}
+	get stats() {
+		return this._stats;
+	}
+	get result() {
+		return this._result;
+	}
+	/**
+	* Start recording. If the user is not currently live, polls
+	* until they go live and then starts recording.
+	*
+	* Resolves when the stream ends or maxDuration is reached.
+	*/
+	async start() {
+		return this._run(true);
+	}
+	/**
+	* Start recording immediately. Throws if the user is not live.
+	*/
+	async startRecording() {
+		return this._run(false);
+	}
+	/**
+	* Wait until the user goes live (does not record).
+	*/
+	async waitForLive() {
+		this.setState("waiting");
+		const roomId = await this.resolveRoomIdWithRetry();
+		const info = await this.fetchStreamInfo(roomId);
+		this.setState("idle");
+		return info;
+	}
+	/**
+	* Gracefully stop the recording.
+	*/
+	async stop() {
+		if (this._state !== "recording" && this._state !== "waiting") return;
+		this.setState("stopping");
+		this.abortController.abort();
+		await new Promise((resolve) => {
+			const check = () => {
+				if (this._state === "done") resolve();
+				else setTimeout(check, 100);
+			};
+			check();
+		});
+	}
+	/**
+	* Immediately abort the recording.
+	*/
+	abort() {
+		this.abortController.abort();
+	}
+	setState(state) {
+		this._state = state;
+	}
+	resolveOptions(opts) {
+		const resolved = {
+			...DEFAULT_OPTIONS,
+			...Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== void 0))
+		};
+		if (opts.useFfmpeg === void 0 && opts.ffmpegPath === void 0) {
+			const systemPath = detectSystemFfmpeg();
+			if (systemPath) {
+				resolved.useFfmpeg = true;
+				resolved.ffmpegPath = systemPath;
+			} else resolved.useFfmpeg = false;
+		} else if (opts.useFfmpeg !== false) {
+			resolved.useFfmpeg = true;
+			resolved.ffmpegPath = opts.ffmpegPath ?? "ffmpeg";
+		}
+		if (resolved.format === "mp4" || resolved.format === "mkv") {
+			if (!resolved.useFfmpeg) resolved.format = "flv";
+		}
+		return resolved;
+	}
+	async _run(waitForLive) {
+		this.abortController = new AbortController();
+		if (this.options.signal) this.options.signal.addEventListener("abort", () => this.abortController.abort(), { once: true });
+		const pendingRemuxes = [];
+		try {
+			this.setState("waiting");
+			let roomId = await this.resolveRoomIdOnce();
+			if (!roomId && waitForLive) roomId = await this.resolveRoomIdWithRetry();
+			if (!roomId) throw new UserOfflineError(this.username);
+			this.setState("waiting");
+			const firstInfo = waitForLive ? await this.pollStreamInfo(roomId) : await this.fetchStreamInfo(roomId);
+			if (!(this.options.maxSegmentDuration > 0 && this.options.maxSegmentDuration < Infinity)) {
+				const tsResult = await this.downloadSegment(firstInfo, 1);
+				const finalResult = await this.remuxSegment(tsResult);
+				this._result = finalResult;
+				this.setState("done");
+				this.emit("complete", [finalResult]);
+				return finalResult;
+			}
+			let info = firstInfo;
+			let partNum = 1;
+			while (true) {
+				this.abortController.signal?.throwIfAborted();
+				this._state = "waiting";
+				const tsResult = await this.downloadSegment(info, partNum);
+				const remuxPromise = this.remuxSegment(tsResult);
+				pendingRemuxes.push(remuxPromise);
+				this._result = tsResult;
+				this.emit("segment", tsResult, partNum);
+				partNum++;
+				await sleep(1e3);
+				try {
+					const freshRoomId = await this.resolveRoomIdOnce();
+					if (!freshRoomId) break;
+					info = await this.fetchStreamInfo(freshRoomId);
+				} catch {
+					break;
+				}
+			}
+			const finalResults = await Promise.all(pendingRemuxes);
+			this._result = finalResults[finalResults.length - 1] ?? null;
+			this.setState("done");
+			this.emit("complete", finalResults);
+			return finalResults[finalResults.length - 1];
+		} catch (err) {
+			if (err instanceof StreamFetchError) this.emit("waiting", {
+				username: this.username,
+				phase: "stream",
+				elapsed: 0
+			});
+			if (pendingRemuxes.length > 0) await Promise.allSettled(pendingRemuxes);
+			this.setState("done");
+			const error = err instanceof Error ? err : new Error(String(err));
+			this.emit("error", error);
+			this.options.onError?.(error);
+			throw error;
+		}
+	}
+	async resolveRoomIdOnce() {
+		try {
+			return await resolveRoomId(this.username, this.impIt, { signal: this.abortController.signal });
+		} catch (error) {
+			if (error instanceof UserNotFoundError) throw error;
+			try {
+				const url = `https://www.tiktok.com/api-live/user/room/?aid=1988&uniqueId=${encodeURIComponent(this.username)}&sourceType=54`;
+				const resp = await this.impIt.fetch(url, { signal: this.abortController.signal });
+				if (resp.ok) {
+					const roomId = ((await resp.json()).data?.user)?.roomId;
+					if (roomId) return String(roomId);
+				}
+			} catch {}
+			return null;
+		}
+	}
+	async resolveRoomIdWithRetry() {
+		const interval = this.options.checkInterval;
+		const maxInterval = Math.max(interval, 180);
+		const waitStart = Date.now();
+		while (true) {
+			this.abortController.signal?.throwIfAborted();
+			const roomId = await this.resolveRoomIdOnce();
+			if (roomId) return roomId;
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1e3
+			});
+			await sleep(maxInterval * 1e3);
+		}
+	}
+	async fetchStreamInfo(roomId) {
+		const info = await fetchStreamInfo(roomId, this.username, this.impIt, {
+			quality: this.options.quality,
+			signal: this.abortController.signal
+		});
+		this.emit("start", info);
+		this.options.onStart?.(info);
+		return info;
+	}
+	/**
+	* Poll for stream info until the stream becomes active.
+	* Used in waitForLive mode when the room exists but the stream
+	* has not yet started broadcasting.
+	*/
+	async pollStreamInfo(roomId) {
+		const interval = this.options.checkInterval;
+		const maxInterval = Math.max(interval, 180);
+		const waitStart = Date.now();
+		while (true) {
+			this.abortController.signal?.throwIfAborted();
+			try {
+				return await this.fetchStreamInfo(roomId);
+			} catch (err) {
+				if (err instanceof StreamFetchError) {
+					this.emit("waiting", {
+						username: this.username,
+						phase: "stream",
+						elapsed: (Date.now() - waitStart) / 1e3
+					});
+					await sleep(maxInterval * 1e3);
+					continue;
+				}
+				throw err;
+			}
+		}
+	}
+	/**
+	* Download a single segment. Always downloads to .ts (crash-safe).
+	* Does NOT remux — that is handled by remuxSegment() running in the background.
+	*/
+	async downloadSegment(info, partNumber) {
+		const startTime = /* @__PURE__ */ new Date();
+		const quality = info.selectedQuality;
+		const segmentMaxDuration = this.options.maxSegmentDuration > 0 && this.options.maxSegmentDuration < Infinity ? this.options.maxSegmentDuration : this.options.maxDuration;
+		const outputDir = this.options.output;
+		if (!existsSync(outputDir)) mkdirSync(outputDir, { recursive: true });
+		const fileBase = renderFilename(this.options.filename, {
+			username: this.username,
+			title: info.title,
+			part: partNumber
+		});
+		const fileName = partNumber && !this.options.filename.includes("{part}") ? `${fileBase}_part${partNumber}` : fileBase;
+		this.emit("progress", {
+			downloadedBytes: 0,
+			downloadedMB: 0,
+			duration: 0,
+			speed: 0,
+			speedMBps: 0,
+			quality: quality.key,
+			state: "recording"
+		});
+		this.setState("recording");
+		const onProgress = (stats) => {
+			this._stats = stats;
+			this.emit("progress", stats);
+			this.options.onProgress?.(stats);
+		};
+		if (this.options.useFfmpeg && this.options.ffmpegPath) {
+			const tsPath = join(outputDir, `${fileName}.ts`);
+			const result = await downloadWithFfmpeg({
+				ffmpegPath: this.options.ffmpegPath,
+				url: info.streamUrl,
+				outputPath: tsPath,
+				quality: quality.key,
+				signal: this.abortController.signal,
+				onProgress,
+				maxDuration: segmentMaxDuration < Infinity ? segmentMaxDuration : void 0,
+				timeout: this.options.timeout * 1e3
+			});
+			return {
+				filePath: tsPath,
+				sizeBytes: result.sizeBytes,
+				sizeMB: result.sizeBytes / (1024 * 1024),
+				duration: result.duration,
+				username: this.username,
+				roomId: info.roomId,
+				quality: quality.key,
+				format: "ts",
+				startedAt: startTime,
+				endedAt: /* @__PURE__ */ new Date()
+			};
+		}
+		const outputPath = join(outputDir, `${fileName}.flv`);
+		const result = await downloadRawHttp({
+			url: info.streamUrl,
+			outputPath,
+			quality: quality.key,
+			signal: this.abortController.signal,
+			onProgress,
+			maxDuration: segmentMaxDuration < Infinity ? segmentMaxDuration : void 0
+		});
+		return {
+			filePath: outputPath,
+			sizeBytes: result.sizeBytes,
+			sizeMB: result.sizeBytes / (1024 * 1024),
+			duration: result.duration,
+			username: this.username,
+			roomId: info.roomId,
+			quality: quality.key,
+			format: "flv",
+			startedAt: startTime,
+			endedAt: /* @__PURE__ */ new Date()
+		};
+	}
+	/**
+	* Remux a downloaded .ts segment to the target format with audio normalization.
+	* Runs in background, does not block the download loop.
+	*
+	* If remux fails, keeps the .ts as a playable fallback.
+	*/
+	async remuxSegment(tsResult) {
+		if (!this.options.useFfmpeg || !this.options.ffmpegPath || tsResult.format !== "ts") return tsResult;
+		const targetFormat = this.options.format;
+		const inputPath = tsResult.filePath;
+		if (targetFormat === "ts") return tsResult;
+		const finalExt = targetFormat === "mkv" ? "mkv" : "mp4";
+		const finalPath = inputPath.replace(/\.ts$/, `.${finalExt}`);
+		if (finalPath === inputPath) return tsResult;
+		this.emit("remux", {
+			filePath: inputPath,
+			inputSizeMB: tsResult.sizeMB,
+			status: "started"
+		});
+		try {
+			await this.remuxAndNormalize(this.options.ffmpegPath, inputPath, finalPath);
+			let realSizeBytes = tsResult.sizeBytes;
+			try {
+				const { statSync } = await import("node:fs");
+				realSizeBytes = statSync(finalPath).size;
+			} catch {}
+			try {
+				const { unlinkSync } = await import("node:fs");
+				unlinkSync(inputPath);
+			} catch {}
+			this.emit("remux", {
+				filePath: inputPath,
+				outputPath: finalPath,
+				inputSizeMB: tsResult.sizeMB,
+				outputSizeMB: realSizeBytes / (1024 * 1024),
+				status: "completed"
+			});
+			return {
+				...tsResult,
+				filePath: finalPath,
+				sizeBytes: realSizeBytes,
+				sizeMB: realSizeBytes / (1024 * 1024),
+				format: finalExt
+			};
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			console.warn(`tokwatchr: remux failed for ${inputPath}, keeping .ts as fallback: ${msg}`);
+			this.emit("remux", {
+				filePath: inputPath,
+				inputSizeMB: tsResult.sizeMB,
+				status: "failed"
+			});
+			return tsResult;
+		}
+	}
+	/**
+	* Remux a .ts file to the target container with EBU R128 audio normalization.
+	*
+	* Two-pass loudnorm (equivalent to `ffmpeg-normalize --preset streaming-video -c:a aac`):
+	*   1. Measure integrated loudness, LRA, true peak
+	*   2. Apply linear normalization + encode AAC + copy video
+	*
+	* If the measurement pass fails (short file, edge case), falls back to
+	* plain AAC encode without loudnorm.
+	*/
+	async remuxAndNormalize(ffmpegPath, inputPath, outputPath) {
+		const measured = await this.measureLoudness(ffmpegPath, inputPath);
+		const args = [
+			"-hide_banner",
+			"-y",
+			"-i",
+			inputPath,
+			"-c:v",
+			"copy"
+		];
+		if (measured) args.push("-af", [
+			"loudnorm=I=-14",
+			"LRA=7",
+			"TP=-2",
+			"linear=true",
+			`measured_I=${measured.inputI}`,
+			`measured_LRA=${measured.inputLra}`,
+			`measured_TP=${measured.inputTp}`,
+			`measured_thresh=${measured.inputThresh}`,
+			`offset=${measured.offset}`
+		].join(":"));
+		args.push("-c:a", "aac", "-b:a", "128k");
+		args.push(outputPath);
+		return new Promise((resolve, reject) => {
+			const stderrChunks = [];
+			const proc = spawn(ffmpegPath, args, {
+				stdio: [
+					"ignore",
+					"ignore",
+					"pipe"
+				],
+				timeout: 6e5
+			});
+			proc.stderr?.on("data", (chunk) => {
+				stderrChunks.push(chunk);
+			});
+			proc.on("error", (err) => reject(err));
+			proc.on("close", (code) => {
+				if (code === 0) resolve();
+				else {
+					const stderrOutput = Buffer.concat(stderrChunks).toString("utf-8");
+					const tail = stderrOutput.length > 1500 ? `...${stderrOutput.slice(-1500)}` : stderrOutput;
+					const msg = tail ? `Remux exited with code ${code}: ${tail}` : `Remux exited with code ${code}`;
+					reject(new Error(msg));
+				}
+			});
+		});
+	}
+	/**
+	* Measure loudness of a .ts file using ffmpeg's loudnorm filter.
+	*
+	* Runs `loudnorm` with `print_format=json` and parses the JSON
+	* output from stderr. Returns the measured values for use in
+	* the second pass, or null if measurement failed.
+	*/
+	async measureLoudness(ffmpegPath, inputPath) {
+		return new Promise((resolve, reject) => {
+			const proc = spawn(ffmpegPath, [
+				"-hide_banner",
+				"-y",
+				"-i",
+				inputPath,
+				"-af",
+				"loudnorm=I=-14:LRA=7:TP=-2:print_format=json",
+				"-f",
+				"null",
+				"-"
+			], {
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe"
+				],
+				timeout: 3e5
+			});
+			let stderr = "";
+			proc.stderr?.on("data", (chunk) => {
+				stderr += chunk.toString("utf-8");
+			});
+			proc.on("error", (err) => reject(err));
+			proc.on("close", (code) => {
+				if (code !== 0) {
+					resolve(null);
+					return;
+				}
+				try {
+					resolve(parseLoudnormJson(stderr));
+				} catch {
+					resolve(null);
+				}
+			});
+		});
+	}
+};
+/**
+* Parse the JSON output from ffmpeg's loudnorm print_format=json.
+*
+* Handles two output styles:
+*   Multi-line:
+*     [Parsed_loudnorm_0 @ 0x...]
+*     { "input_i": "-23.5", ... }
+*   Single-line:
+*     [Parsed_loudnorm_0 @ 0x...] { "input_i": "-23.5", ... }
+*/
+function parseLoudnormJson(stderr) {
+	try {
+		let start = -1;
+		let depth = 0;
+		for (let i = 0; i < stderr.length; i++) {
+			const ch = stderr[i];
+			if (ch === "{") {
+				if (start === -1) start = i;
+				depth++;
+			} else if (ch === "}") {
+				depth--;
+				if (depth === 0 && start !== -1) {
+					const jsonStr = stderr.slice(start, i + 1);
+					const data = JSON.parse(jsonStr);
+					if (typeof data.input_i === "string" && typeof data.input_lra === "string" && typeof data.input_tp === "string" && typeof data.input_thresh === "string" && typeof data.target_offset === "string") return {
+						inputI: data.input_i,
+						inputLra: data.input_lra,
+						inputTp: data.input_tp,
+						inputThresh: data.input_thresh,
+						offset: data.target_offset
+					};
+					return null;
+				}
+			}
+		}
+	} catch {}
+	return null;
+}
+/**
+* Detect whether `ffmpeg` is available on the system PATH.
+*
+* Returns "ffmpeg" (or the resolved path) if found, or null if not.
+*/
+function detectSystemFfmpeg() {
+	try {
+		return spawnSync("ffmpeg", ["-version"], {
+			stdio: "pipe",
+			timeout: 5e3
+		}).status === 0 ? "ffmpeg" : null;
+	} catch {
+		return null;
+	}
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//#endregion
+//#region src/cli/utils/format.ts
+/**
+* Format a byte count into a human-readable string.
+*
+* @example formatBytes(1_234_567) // "1.2 MB"
+*/
+function formatBytes(bytes) {
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB"
+	];
+	let value = bytes;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+/**
+* Format a duration in seconds to a concise string.
+*
+* @example formatDuration(3661) // "1h 1m 1s"
+*/
+function formatDuration(seconds) {
+	const h = Math.floor(seconds / 3600);
+	const m = Math.floor(seconds % 3600 / 60);
+	const s = Math.floor(seconds % 60);
+	const parts = [];
+	if (h > 0) parts.push(`${h}h`);
+	if (m > 0) parts.push(`${m}m`);
+	parts.push(`${s}s`);
+	return parts.join(" ");
+}
+/**
+* Format a speed in bytes/sec to a human-readable string.
+*
+* @example formatSpeed(3_200_000) // "3.1 MB/s"
+*/
+function formatSpeed(bytesPerSec) {
+	const units = [
+		"B/s",
+		"KB/s",
+		"MB/s",
+		"GB/s"
+	];
+	let value = bytesPerSec;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+//#endregion
+//#region src/cli/commands/download.ts
+/**
+* Execute the `download` command.
+*
+* Uses plain console output (no spinner) so terminal stays in cooked
+* mode and SIGINT flows normally through process.on().
+*/
+async function executeDownload(username, options) {
+	let downloader;
+	const onSignal = async () => {
+		await downloader.stop();
+	};
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+	downloader = new TikTokLiveDownloader(username, {
+		output: options.output,
+		quality: options.quality,
+		format: options.format,
+		proxyUrl: options.proxy,
+		useFfmpeg: options.ffmpeg
+	});
+	console.log(`${pc.dim("Resolving room...")}`);
+	downloader.on("error", () => {});
+	downloader.on("start", (info) => {
+		console.log(`\n${pc.blue(`@${info.username}`)}`);
+		console.log(`  ${pc.green("Recording...")}`);
+	});
+	downloader.on("progress", (stats) => {
+		const line = `${formatBytes(stats.downloadedBytes)} @ ${formatSpeed(stats.speed)}  [${formatDuration(stats.duration)}]`;
+		process.stderr.write(`\r  ${line}  `);
+	});
+	downloader.on("remux", (info) => {
+		switch (info.status) {
+			case "started":
+				process.stderr.write(`\n  ${pc.dim("Remuxing...")}`);
+				break;
+			case "completed":
+				process.stderr.write(`\r  ${pc.green("Remuxed:")} ${basename(info.outputPath ?? "")}\n`);
+				break;
+			case "failed":
+				process.stderr.write(`\n  ${pc.yellow("Remux failed, keeping .ts as fallback")}\n`);
+				break;
+		}
+	});
+	downloader.on("complete", (results) => {
+		process.stderr.write("\n");
+		for (const r of results) console.log(`  ${pc.green("Saved:")} ${basename(r.filePath)}  ${pc.dim(`(${formatBytes(r.sizeBytes)}, ${formatDuration(r.duration)})`)}`);
+		const totalMB = results.reduce((sum, r) => sum + r.sizeMB, 0);
+		console.log(`  Done — ${results.length} segment(s), ${totalMB.toFixed(1)}MB total`);
+		if (results.length > 0) console.log(`  ${pc.dim(`Output: ${dirname(results[0]?.filePath ?? "")}/`)}`);
+	});
+	try {
+		await downloader.startRecording();
+	} catch (error) {
+		if (error instanceof UserNotFoundError) {
+			console.error(pc.red("[error]"), "User not found. Check the username and try again.");
+			process.exit(1);
+		}
+		if (error instanceof UserOfflineError) {
+			console.error(pc.red("[error]"), error.message);
+			process.exit(1);
+		}
+		console.error(pc.red("[error]"), String(error));
+		throw error;
+	}
+}
+//#endregion
+//#region src/cli/commands/watch.ts
+/**
+* Execute the `watch` command.
+*
+* Uses plain console output (no spinner) so terminal stays in cooked
+* mode and SIGINT flows normally through process.on().
+*/
+async function executeWatch(username, options) {
+	let downloader;
+	let stopped = false;
+	const onSignal = async () => {
+		stopped = true;
+		await downloader.stop();
+	};
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+	downloader = new TikTokLiveDownloader(username, {
+		output: options.output,
+		quality: options.quality,
+		format: options.format,
+		proxyUrl: options.proxy,
+		useFfmpeg: options.ffmpeg,
+		maxDuration: options.maxDuration ? options.maxDuration * 60 : void 0,
+		maxSegmentDuration: (options.segmentDuration ?? 20) * 60,
+		checkInterval: (options.interval ?? 3) * 60
+	});
+	downloader.on("error", () => {});
+	downloader.on("start", (info) => {
+		console.log(`\n${pc.blue(`@${info.username}`)}`);
+		console.log(`  ${pc.green("Recording...")}`);
+	});
+	downloader.on("waiting", (info) => {
+		process.stderr.write(`\r  ${pc.dim(`Waiting... ${formatDuration(info.elapsed)}`)}  `);
+	});
+	downloader.on("progress", (stats) => {
+		const line = `${formatBytes(stats.downloadedBytes)} @ ${formatSpeed(stats.speed)}  [${formatDuration(stats.duration)}]`;
+		process.stderr.write(`\r  ${line}  `);
+	});
+	downloader.on("remux", (info) => {
+		switch (info.status) {
+			case "started":
+				process.stderr.write(`\n  ${pc.dim("Remuxing...")}`);
+				break;
+			case "completed":
+				process.stderr.write(`\r  ${pc.green("Remuxed:")} ${basename(info.outputPath ?? "")}\n`);
+				break;
+			case "failed":
+				process.stderr.write(`\n  ${pc.yellow("Remux failed, keeping .ts as fallback")}\n`);
+				break;
+		}
+	});
+	downloader.on("segment", (result, partNum) => {
+		process.stderr.write("\n");
+		console.log(`  ${pc.green("Segment")} ${partNum}: ${basename(result.filePath)}  ${pc.dim(`(${formatBytes(result.sizeBytes)}, ${formatDuration(result.duration)})`)}`);
+	});
+	downloader.on("complete", (results) => {
+		process.stderr.write("\n");
+		for (const r of results) console.log(`  ${pc.green("Saved:")} ${basename(r.filePath)}  ${pc.dim(`(${formatBytes(r.sizeBytes)}, ${formatDuration(r.duration)})`)}`);
+		const totalMB = results.reduce((sum, r) => sum + r.sizeMB, 0);
+		console.log(`  Done — ${results.length} segment(s), ${totalMB.toFixed(1)}MB total`);
+		if (results.length > 0) console.log(`  ${pc.dim(`Output: ${dirname(results[0]?.filePath ?? "")}/`)}`);
+	});
+	console.log(`${pc.dim("Waiting for ")}${pc.blue(username)}${pc.dim(" to go live...")}`);
+	while (true) {
+		if (stopped) break;
+		try {
+			await downloader.start();
+			if (stopped) break;
+			console.log(`\n  ${pc.dim("Stream ended, watching for next...")}`);
+		} catch (error) {
+			if (stopped) break;
+			if (error instanceof UserNotFoundError) {
+				console.error(pc.red("[error]"), "User not found. Check the username and try again.");
+				process.exit(1);
+			}
+			console.error(`\n  ${pc.yellow(`[warning] ${error}`)}`);
+			await new Promise((r) => setTimeout(r, 1e4));
+			console.log(`  ${pc.dim("Retrying...")}`);
+		}
+	}
+}
+//#endregion
+//#region src/cli/utils/errors.ts
+/**
+* Base error for all CLI-level failures.
+* Separate from tokwatchr's own error classes.
+*/
+var CliError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "CliError";
+	}
+};
+/**
+* Render a caught error to stderr and exit with a non-zero code.
+* Tokwatchr errors are rendered with their own messages; unexpected
+* errors include the stack trace in debug mode.
+*/
+function handleFatalError(error) {
+	if (error instanceof CliError) {
+		console.error(pc.red("[error]"), error.message);
+		process.exit(1);
+	}
+	if (error instanceof Error) switch (error.name) {
+		case "UserNotFoundError":
+			console.error(pc.red("[error]"), "User not found. Check the username and try again.");
+			break;
+		case "UserOfflineError":
+			console.error(pc.red("[error]"), error.message);
+			break;
+		case "RoomResolveError":
+			console.error(pc.red("[error]"), "Could not find the user's livestream room.");
+			break;
+		case "StreamFetchError":
+			console.error(pc.red("[error]"), "Could not fetch stream info. Check the username and try again.");
+			break;
+		case "DownloadFailedError":
+			console.error(pc.red("[error]"), `Download failed: ${error.message}`);
+			break;
+		case "FfmpegError":
+			console.error(pc.red("[error]"), error.message);
+			break;
+		case "AbortError":
+			console.error(pc.blue("[info]"), "Aborted.");
+			break;
+		default:
+			console.error(pc.red("[error]"), `Unexpected error: ${error.message}`);
+			if (process.env.DEBUG) console.error(error.stack);
+			break;
+	}
+	else console.error(pc.red("[error]"), String(error));
+	process.exit(1);
+}
+//#endregion
+//#region src/cli/index.ts
+const cli = cac("tokwatchr");
+cli.command("download <username>", "Download a TikTok livestream (user must be live)").option("-o, --output <dir>", "Output directory [cwd]").option("-q, --quality <quality>", "Quality: best|worst|fullhd1|hd1|sd2|sd1 [best]").option("-f, --format <format>", "Format: mp4|mkv|ts|flv [mp4]").option("--proxy <url>", "HTTP/SOCKS proxy URL").option("--no-ffmpeg", "Skip ffmpeg processing (output .flv)").example("tokwatchr download officialgeilegisela").example("tokwatchr download tv_asahi_news -o ./vods -q hd1").example("tokwatchr download username --proxy socks5://localhost:1080").action(async (username, options) => {
+	try {
+		await executeDownload(username, options);
+	} catch (error) {
+		handleFatalError(error);
+	}
+});
+cli.command("watch <username>", "Wait for a user to go live, then start recording").option("-o, --output <dir>", "Output directory [cwd]").option("-q, --quality <quality>", "Quality: best|worst|fullhd1|hd1|sd2|sd1 [best]").option("-f, --format <format>", "Format: mp4|mkv|ts|flv [mp4]").option("-d, --max-duration <minutes>", "Max recording duration in minutes [no limit]").option("-s, --segment-duration <minutes>", "Split into N-minute segments [20]").option("-i, --interval <minutes>", "Poll interval in minutes [3]").option("--proxy <url>", "HTTP/SOCKS proxy URL").option("--no-ffmpeg", "Skip ffmpeg processing (output .flv)").example("tokwatchr watch username").example("tokwatchr watch username -s 10 -d 120").example("tokwatchr watch username -i 1").action(async (username, options) => {
+	try {
+		await executeWatch(username, options);
+	} catch (error) {
+		handleFatalError(error);
+	}
+});
+cli.help();
+cli.version(version);
+cli.parse();
+//#endregion
+export {};