tokwatchr 0.4.0

package/src/download/raw-http.ts

@@ -0,0 +1,150 @@
+import type { PathLike } from "node:fs";
+import { createWriteStream } from "node:fs";
+import { Impit } from "impit";
+import { AbortError, DownloadFailedError } from "../errors.js";
+import type { DownloadStats, StreamQualityKey } from "../types.js";
+
+export interface RawHttpDownloadOptions {
+	url: string;
+	outputPath: PathLike;
+	quality: StreamQualityKey;
+	signal?: AbortSignal;
+	onProgress?: (stats: DownloadStats) => void;
+	maxDuration?: number;
+}
+
+/**
+ * Download a livestream via raw HTTP FLV streaming.
+ *
+ * Writes the incoming FLV data directly to disk without transcoding.
+ * No ffmpeg required.
+ */
+export async function downloadRawHttp(
+	options: RawHttpDownloadOptions,
+): Promise<{
+	sizeBytes: number;
+	duration: number;
+	format: "flv";
+}> {
+	const { url, outputPath, quality, signal, onProgress, maxDuration } = options;
+
+	const impIt = new Impit({
+		browser: "chrome",
+	});
+
+	const response = await impIt.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;
+
+	// Narrowed const for use in closures
+	const reader: ReadableStreamDefaultReader<Uint8Array> = bodyReader;
+
+	return new Promise((resolve, reject) => {
+		const abortHandler = () => {
+			aborted = true;
+			reader.cancel().catch(() => {});
+			fileStream.close();
+			reject(new AbortError());
+		};
+
+		signal?.addEventListener("abort", abortHandler, { once: true });
+
+		// Duration limit timer
+		let durationTimer: ReturnType<typeof setTimeout> | null = null;
+		if (maxDuration && maxDuration > 0 && maxDuration < Infinity) {
+			durationTimer = setTimeout(() => {
+				aborted = true;
+				reader.cancel().catch(() => {});
+				fileStream.close();
+				resolve({
+					sizeBytes: downloadedBytes,
+					duration: (Date.now() - startTime) / 1000,
+					format: "flv",
+				});
+			}, maxDuration * 1000);
+		}
+
+		function pump(): void {
+			reader
+				.read()
+				.then(({ done, value }) => {
+					if (done || aborted) {
+						fileStream.close();
+						if (!aborted) {
+							resolve({
+								sizeBytes: downloadedBytes,
+								duration: (Date.now() - startTime) / 1000,
+								format: "flv",
+							});
+						}
+						if (durationTimer) clearTimeout(durationTimer);
+						signal?.removeEventListener("abort", abortHandler);
+						return;
+					}
+
+					downloadedBytes += value.byteLength;
+					fileStream.write(value);
+
+					// Emit progress every ~second
+					const now = Date.now();
+					const elapsed = now - lastProgressTime;
+					if (elapsed >= 1000) {
+						const bytesSinceLast = downloadedBytes - lastProgressBytes;
+						const speed = bytesSinceLast / (elapsed / 1000);
+						lastProgressTime = now;
+						lastProgressBytes = downloadedBytes;
+
+						onProgress?.({
+							downloadedBytes,
+							downloadedMB: downloadedBytes / (1024 * 1024),
+							duration: (now - startTime) / 1000,
+							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();
+	});
+}

package/src/errors.ts

@@ -0,0 +1,58 @@
+export class TikTokLiveError extends Error {
+	override name = "TikTokLiveError";
+}
+
+export class UserOfflineError extends TikTokLiveError {
+	override name = "UserOfflineError";
+	constructor(username: string) {
+		super(`User "${username}" is not currently live`);
+	}
+}
+
+export class UserNotFoundError extends TikTokLiveError {
+	override name = "UserNotFoundError";
+	constructor(username: string) {
+		super(`User "${username}" does not exist on TikTok`);
+	}
+}
+
+export class RoomResolveError extends TikTokLiveError {
+	override name = "RoomResolveError";
+	constructor(username: string, cause?: unknown) {
+		super(
+			`Failed to resolve room ID for "${username}"${cause ? `: ${cause}` : ""}`,
+		);
+	}
+}
+
+export class StreamFetchError extends TikTokLiveError {
+	override name = "StreamFetchError";
+	constructor(roomId: string, cause?: unknown) {
+		super(
+			`Failed to fetch stream URL for room ${roomId}${cause ? `: ${cause}` : ""}`,
+		);
+	}
+}
+
+export class DownloadFailedError extends TikTokLiveError {
+	override name = "DownloadFailedError";
+	constructor(message: string, cause?: unknown) {
+		super(`${message}${cause ? `: ${cause}` : ""}`);
+	}
+}
+
+export class FfmpegError extends TikTokLiveError {
+	override name = "FfmpegError";
+	constructor(message: string, exitCode?: number | null) {
+		super(
+			`FFmpeg error: ${message}${exitCode != null ? ` (exit code ${exitCode})` : ""}`,
+		);
+	}
+}
+
+export class AbortError extends TikTokLiveError {
+	override name = "AbortError";
+	constructor() {
+		super("Download was aborted");
+	}
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+// ─── Main class & functional API ──────────────────────────
+
+export type { CreateClientOptions } from "./api/client.js";
+export { createClient } from "./api/client.js";
+export type { RoomResolveOptions } from "./api/room.js";
+// ─── API utilities (mid-level) ────────────────────────────
+export { resolveRoomId } from "./api/room.js";
+export type { StreamInfoOptions } from "./api/stream.js";
+export { fetchStreamInfo } from "./api/stream.js";
+// ─── Error classes ────────────────────────────────────────
+export {
+	AbortError,
+	DownloadFailedError,
+	FfmpegError,
+	RoomResolveError,
+	StreamFetchError,
+	TikTokLiveError,
+	UserNotFoundError,
+	UserOfflineError,
+} from "./errors.js";
+export type { DownloadFunctionOptions } from "./TikTokLiveDownloader.js";
+export { download, TikTokLiveDownloader } from "./TikTokLiveDownloader.js";
+// ─── Types ────────────────────────────────────────────────
+export type {
+	CookieJarLike,
+	DownloaderState,
+	DownloadResult,
+	DownloadStats,
+	OutputFormat,
+	QualityOption,
+	StreamInfo,
+	StreamQualityKey,
+	TikTokLiveDownloaderEvents,
+	TikTokLiveDownloaderOptions,
+} from "./types.js";
+
+// ─── Quality utilities ────────────────────────────────────
+export {
+	buildQualityOption,
+	parseQualities,
+	selectQuality,
+} from "./utils/quality.js";
+
+// ─── Template ─────────────────────────────────────────────
+export { renderFilename } from "./utils/template.js";

package/src/types.ts

@@ -0,0 +1,155 @@
+import type { Browser } from "impit";
+
+// ─── Quality ──────────────────────────────────────────────
+
+export type StreamQualityKey = "fullhd1" | "hd1" | "sd2" | "sd1";
+
+export interface QualityOption {
+	key: StreamQualityKey;
+	label: string;
+	level: number;
+	flv: string;
+	hls: string;
+}
+
+// ─── Stream info ──────────────────────────────────────────
+
+export interface StreamInfo {
+	roomId: string;
+	username: string;
+	title: string;
+	qualities: QualityOption[];
+	selectedQuality: QualityOption;
+	streamUrl: string;
+	viewerCount: number;
+	startedAt: Date;
+}
+
+// ─── Download stats (live) ────────────────────────────────
+
+export interface DownloadStats {
+	downloadedBytes: number;
+	downloadedMB: number;
+	duration: number; // seconds elapsed
+	speed: number; // bytes/sec
+	speedMBps: number;
+	quality: StreamQualityKey;
+	state: DownloaderState;
+}
+
+// ─── Download result ──────────────────────────────────────
+
+export interface DownloadResult {
+	filePath: string;
+	sizeBytes: number;
+	sizeMB: number;
+	duration: number; // seconds of content
+	username: string;
+	roomId: string;
+	quality: StreamQualityKey;
+	format: OutputFormat;
+	startedAt: Date;
+	endedAt: Date;
+}
+
+// ─── States ───────────────────────────────────────────────
+
+export type DownloaderState =
+	| "idle"
+	| "waiting"
+	| "recording"
+	| "stopping"
+	| "done";
+export type OutputFormat = "mp4" | "mkv" | "ts" | "flv";
+
+// ─── Options ──────────────────────────────────────────────
+
+export interface TikTokLiveDownloaderOptions {
+	/** Output directory (default: process.cwd()) */
+	output?: string;
+	/** Filename template. Variables: {username}, {date}, {time}, {title} (default: "{username}={date}_{time}") */
+	filename?: string;
+	/** Quality preference (default: "best") */
+	quality?: "best" | "worst" | StreamQualityKey;
+	/** Output container format (default: "mp4" when ffmpeg available, "flv" otherwise) */
+	format?: OutputFormat;
+	/** Use ffmpeg for download + remux. Auto-detects system ffmpeg on PATH. */
+	useFfmpeg?: boolean;
+	/** Custom ffmpeg binary path. Overrides auto-detected system ffmpeg. */
+	ffmpegPath?: string;
+	/** Extra ffmpeg output arguments (default: ["-c", "copy"]). Set to override. */
+	ffmpegArgs?: string[];
+	/** Re-encode bitrate (e.g. "1M", "1000k"). Default: copy streams (no re-encode). */
+	bitrate?: string;
+	/** Max recording duration in seconds (default: Infinity). */
+	maxDuration?: number;
+	/** Split recording into segments of this many seconds (default: Infinity = single file). */
+	maxSegmentDuration?: number;
+	/** Polling interval in ms when waiting for live (default: 30_000). */
+	checkInterval?: number;
+	/** HTTP proxy URL (supports http, https, socks4, socks5). */
+	proxyUrl?: string;
+	/** Tough-cookie compatible cookie jar for authenticated sessions. */
+	cookieJar?: CookieJarLike;
+	/** Browser to emulate (default: "chrome"). */
+	browser?: Browser;
+	/** Request timeout in ms (default: 30_000). */
+	timeout?: number;
+	/** Extra headers to send with every request. */
+	headers?: Record<string, string>;
+	/** Progress callback (functional shorthand). */
+	onProgress?: (stats: DownloadStats) => void;
+	/** Start callback (functional shorthand). */
+	onStart?: (info: StreamInfo) => void;
+	/** Error callback (functional shorthand). */
+	onError?: (err: Error) => void;
+	/** AbortSignal for cancellation. */
+	signal?: AbortSignal;
+}
+
+export interface CookieJarLike {
+	setCookie(raw: string, url: string): Promise<void>;
+	getCookieString(url: string): Promise<string>;
+}
+
+// ─── Events ───────────────────────────────────────────────
+
+export interface TikTokLiveDownloaderEvents {
+	/** Emitted when a live stream is detected and we're about to start recording. */
+	start: [info: StreamInfo];
+	/** Emitted periodically (every ~1s) during recording with current stats. */
+	progress: [stats: DownloadStats];
+	/** Emitted when each segment completes. Only fires when maxSegmentDuration is set. */
+	segment: [result: DownloadResult, partNumber: number];
+	/** Emitted when all segments are done and the stream has ended. */
+	complete: [results: DownloadResult[]];
+	/** Emitted on any error. The downloader will also throw. */
+	error: [err: Error];
+	/** Emitted when stop() is called and cleanup is done. */
+	stop: [];
+}
+
+// ─── Internal resolved options ────────────────────────────
+
+export interface ResolvedOptions {
+	output: string;
+	filename: string;
+	quality: "best" | "worst" | StreamQualityKey;
+	format: OutputFormat;
+	useFfmpeg: boolean;
+	ffmpegPath: string | null;
+	ffmpegArgs: string[];
+	bitrate: string | null;
+	maxDuration: number;
+	maxSegmentDuration: number;
+	checkInterval: number;
+	proxyUrl: string | null;
+	cookieJar: CookieJarLike | null;
+	browser: Browser;
+	timeout: number;
+	headers: Record<string, string>;
+	onProgress: ((stats: DownloadStats) => void) | null;
+	onStart: ((info: StreamInfo) => void) | null;
+	onError: ((err: Error) => void) | null;
+	signal: AbortSignal | null;
+}

package/src/utils/quality.ts

@@ -0,0 +1,171 @@
+import type { QualityOption, StreamQualityKey } from "../types.js";
+
+/**
+ * Quality ladder sorted from highest to lowest.
+ */
+const QUALITY_ORDER: StreamQualityKey[] = ["fullhd1", "hd1", "sd2", "sd1"];
+
+const QUALITY_LABELS: Record<StreamQualityKey, string> = {
+	fullhd1: "1080p",
+	hd1: "720p",
+	sd2: "540p",
+	sd1: "360p",
+};
+
+const QUALITY_LEVELS: Record<StreamQualityKey, number> = {
+	fullhd1: 4,
+	hd1: 3,
+	sd2: 2,
+	sd1: 1,
+};
+
+/**
+ * Build a QualityOption from a raw url object.
+ */
+export function buildQualityOption(
+	key: StreamQualityKey,
+	flv: string,
+	hls?: string,
+): QualityOption {
+	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.
+ */
+export function selectQuality(
+	qualities: QualityOption[],
+	preference: "best" | "worst" | StreamQualityKey,
+): QualityOption {
+	if (qualities.length === 0) {
+		throw new Error("No stream qualities available");
+	}
+
+	if (preference === "best") {
+		// biome-ignore lint/style/noNonNullAssertion: length checked above
+		return qualities[0]!;
+	}
+
+	if (preference === "worst") {
+		// biome-ignore lint/style/noNonNullAssertion: length checked above
+		return qualities[qualities.length - 1]!;
+	}
+
+	// Specific key requested - find it or fall back to best
+	const found = qualities.find((q) => q.key === preference);
+	// biome-ignore lint/style/noNonNullAssertion: length checked above
+	return found ?? 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.
+ */
+export function parseQualities(data: unknown): QualityOption[] {
+	if (!data || typeof data !== "object") {
+		return [];
+	}
+
+	const d = data as Record<string, unknown>;
+
+	// Try new SDK format first
+	const sdkQualities = parseSdkQualities(d);
+	if (sdkQualities.length > 0) {
+		return sdkQualities;
+	}
+
+	// Fall back to legacy flv_pull_url format
+	return parseLegacyQualities(d);
+}
+
+function parseSdkQualities(data: Record<string, unknown>): QualityOption[] {
+	try {
+		const streamUrl = data.stream_url as Record<string, unknown> | undefined;
+		if (!streamUrl) return [];
+
+		const sdkData = streamUrl.live_core_sdk_data as
+			| Record<string, unknown>
+			| undefined;
+		if (!sdkData) return [];
+
+		const pullData = sdkData.pull_data as Record<string, unknown> | undefined;
+		if (!pullData) return [];
+
+		const streamDataStr = pullData.stream_data;
+		if (typeof streamDataStr !== "string") return [];
+
+		const streamData = JSON.parse(streamDataStr);
+		const innerData = (streamData as Record<string, unknown>)?.data as
+			| Record<string, unknown>
+			| undefined;
+		if (!innerData) return [];
+
+		const qualities: QualityOption[] = [];
+
+		for (const key of QUALITY_ORDER) {
+			const q = innerData[key] as Record<string, unknown> | undefined;
+			if (!q) continue;
+
+			const main = q.main as Record<string, unknown> | undefined;
+			if (!main) continue;
+
+			const flv = main.flv;
+			if (typeof flv !== "string" || flv.length === 0) continue;
+
+			const hls = typeof main.hls === "string" ? main.hls : undefined;
+			qualities.push(buildQualityOption(key, flv, hls));
+		}
+
+		return qualities;
+	} catch {
+		return [];
+	}
+}
+
+function parseLegacyQualities(data: Record<string, unknown>): QualityOption[] {
+	try {
+		const streamUrl = data.stream_url as Record<string, unknown> | undefined;
+		if (!streamUrl) return [];
+
+		const flvPullUrl = streamUrl.flv_pull_url as
+			| Record<string, unknown>
+			| undefined;
+		if (!flvPullUrl) return [];
+
+		const qualities: QualityOption[] = [];
+
+		// Map TikTok keys to our normalized keys
+		const keyMap: Record<string, StreamQualityKey> = {
+			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));
+			}
+		}
+
+		// Sort by level descending
+		qualities.sort((a, b) => b.level - a.level);
+
+		return qualities;
+	} catch {
+		return [];
+	}
+}

package/src/utils/template.ts

@@ -0,0 +1,67 @@
+/**
+ * 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}"
+ */
+export function renderFilename(
+	template: string,
+	values: {
+		username: string;
+		title?: string;
+		date?: string;
+		time?: string;
+		part?: number;
+	},
+): string {
+	const now = 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 !== undefined) {
+		result = result.replaceAll("{part}", String(values.part));
+	}
+
+	return result;
+}
+
+function formatDate(date: Date): string {
+	const y = date.getFullYear();
+	const m = String(date.getMonth() + 1).padStart(2, "0");
+	const d = String(date.getDate()).padStart(2, "0");
+	return `${y}${m}${d}`;
+}
+
+function formatTime(date: Date): string {
+	const h = String(date.getHours()).padStart(2, "0");
+	const m = String(date.getMinutes()).padStart(2, "0");
+	const s = String(date.getSeconds()).padStart(2, "0");
+	return `${h}${m}${s}`;
+}
+
+/**
+ * Sanitize a string for use in filenames.
+ * Replaces characters that are problematic across OSes.
+ */
+function sanitize(input: string): string {
+	return input
+		.replaceAll(/[/\\?%*:|"<>]/g, "_")
+		.replaceAll(/\s+/g, "_")
+		.replaceAll(/_+/g, "_")
+		.replace(/^_+|_+$/g, "")
+		.slice(0, 64);
+}