tokwatchr 0.4.4 → 0.6.0

package/dist/index.d.mts

@@ -63,7 +63,7 @@ interface TikTokLiveDownloaderOptions {
   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). */
+  /** Polling interval in seconds when waiting for live (default: 180). */
   checkInterval?: number;
   /** HTTP proxy URL (supports http, https, socks4, socks5). */
   proxyUrl?: string;
@@ -71,7 +71,7 @@ interface TikTokLiveDownloaderOptions {
   cookieJar?: CookieJarLike;
   /** Browser to emulate (default: "chrome"). */
   browser?: Browser;
-  /** Request timeout in ms (default: 30_000). */
+  /** Request timeout in seconds (default: 30). */
   timeout?: number;
   /** Extra headers to send with every request. */
   headers?: Record<string, string>;
@@ -88,7 +88,29 @@ interface CookieJarLike {
   setCookie(raw: string, url: string): Promise<void>;
   getCookieString(url: string): Promise<string>;
 }
+interface WaitingInfo {
+  /** The username being waited on. */
+  username: string;
+  /** Which phase we're waiting in: "room" = looking for a room, "stream" = stream not active. */
+  phase: "room" | "stream";
+  /** Seconds elapsed since this phase started. */
+  elapsed: number;
+}
+interface RemuxInfo {
+  /** Input .ts file path. */
+  filePath: string;
+  /** Input file size in MB. */
+  inputSizeMB: number;
+  /** Remux status: started → completed (with outputPath) or failed (keeping .ts). */
+  status: "started" | "completed" | "failed";
+  /** Output file path. Only set when status is "completed". */
+  outputPath?: string;
+}
 interface TikTokLiveDownloaderEvents {
+  /** Emitted periodically while waiting for a room or stream to become active. */
+  waiting: [info: WaitingInfo];
+  /** Emitted when a remux operation starts, completes, or fails. */
+  remux: [info: RemuxInfo];
   /** 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. */
@@ -330,4 +352,4 @@ declare function renderFilename(template: string, values: {
   part?: number;
 }): string;
 //#endregion
-export { AbortError, type CookieJarLike, type CreateClientOptions, DownloadFailedError, type DownloadFunctionOptions, type DownloadResult, type DownloadStats, type DownloaderState, FfmpegError, type OutputFormat, type QualityOption, RoomResolveError, type RoomResolveOptions, StreamFetchError, type StreamInfo, type StreamInfoOptions, type StreamQualityKey, TikTokLiveDownloader, type TikTokLiveDownloaderEvents, type TikTokLiveDownloaderOptions, TikTokLiveError, UserNotFoundError, UserOfflineError, buildQualityOption, createClient, download, fetchStreamInfo, parseQualities, renderFilename, resolveRoomId, selectQuality };
+export { AbortError, type CookieJarLike, type CreateClientOptions, DownloadFailedError, type DownloadFunctionOptions, type DownloadResult, type DownloadStats, type DownloaderState, FfmpegError, type OutputFormat, type QualityOption, type RemuxInfo, RoomResolveError, type RoomResolveOptions, StreamFetchError, type StreamInfo, type StreamInfoOptions, type StreamQualityKey, TikTokLiveDownloader, type TikTokLiveDownloaderEvents, type TikTokLiveDownloaderOptions, TikTokLiveError, UserNotFoundError, UserOfflineError, type WaitingInfo, buildQualityOption, createClient, download, fetchStreamInfo, parseQualities, renderFilename, resolveRoomId, selectQuality };

package/dist/index.mjs

@@ -368,7 +368,7 @@ function parseFfmpegProgress(line) {
 * - Better handling of stream interruptions
 */
 async function downloadWithFfmpeg(options) {
-	const { ffmpegPath, url, outputPath, quality, args: extraArgs, bitrate, signal, onProgress, maxDuration, timeout = 3e4 } = options;
+	const { ffmpegPath, url, outputPath, quality, args: extraArgs, bitrate, signal, onProgress, maxDuration, timeout = 30 } = options;
 	const ffmpegArgs = [
 		"-y",
 		"-i",
@@ -394,8 +394,8 @@ async function downloadWithFfmpeg(options) {
 		let firstDataTimer = setTimeout(() => {
 			firstDataTimer = null;
 			proc.kill("SIGTERM");
-			reject(new FfmpegError(`ffmpeg produced no output within ${timeout}ms — check the stream URL`));
-		}, timeout);
+			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);
@@ -620,11 +620,11 @@ const DEFAULT_OPTIONS = {
 	bitrate: null,
 	maxDuration: Infinity,
 	maxSegmentDuration: Infinity,
-	checkInterval: 18e4,
+	checkInterval: 180,
 	proxyUrl: null,
 	cookieJar: null,
 	browser: "chrome",
-	timeout: 3e4,
+	timeout: 30,
 	headers: {},
 	onProgress: null,
 	onStart: null,
@@ -808,6 +808,11 @@ var TikTokLiveDownloader = class {
 			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));
@@ -834,12 +839,18 @@ var TikTokLiveDownloader = class {
 	}
 	async resolveRoomIdWithRetry() {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 18e4);
+		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;
-			await sleep(maxInterval);
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1e3
+			});
+			await sleep(maxInterval * 1e3);
 		}
 	}
 	async fetchStreamInfo(roomId) {
@@ -858,14 +869,20 @@ var TikTokLiveDownloader = class {
 	*/
 	async pollStreamInfo(roomId) {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 18e4);
+		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) {
-					await sleep(maxInterval);
+					this.emit("waiting", {
+						username: this.username,
+						phase: "stream",
+						elapsed: (Date.now() - waitStart) / 1e3
+					});
+					await sleep(maxInterval * 1e3);
 					continue;
 				}
 				throw err;
@@ -964,12 +981,23 @@ var TikTokLiveDownloader = class {
 		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);
 			try {
 				const { unlinkSync } = await import("node:fs");
 				unlinkSync(inputPath);
 			} catch {}
+			this.emit("remux", {
+				filePath: inputPath,
+				outputPath: finalPath,
+				inputSizeMB: tsResult.sizeMB,
+				status: "completed"
+			});
 			return {
 				...tsResult,
 				filePath: finalPath,
@@ -978,6 +1006,11 @@ var TikTokLiveDownloader = class {
 		} 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;
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "tokwatchr",
-	"version": "0.4.4",
+	"version": "0.6.0",
 	"description": "Download TikTok livestreams. Given a username, download the livestream.",
 	"type": "module",
 	"main": "./dist/index.mjs",

package/src/TikTokLiveDownloader.ts

@@ -36,11 +36,11 @@ const DEFAULT_OPTIONS: ResolvedOptions = {
 	bitrate: null,
 	maxDuration: Infinity,
 	maxSegmentDuration: Infinity,
-	checkInterval: 180_000,
+	checkInterval: 180,
 	proxyUrl: null,
 	cookieJar: null,
 	browser: "chrome",
-	timeout: 30_000,
+	timeout: 30,
 	headers: {},
 	onProgress: null,
 	onStart: null,
@@ -320,6 +320,16 @@ export class TikTokLiveDownloader {
 			// biome-ignore lint/style/noNonNullAssertion: at least one result
 			return finalResults[finalResults.length - 1]!;
 		} catch (err) {
+			// One-shot waiting feedback for startRecording() users
+			// when the stream isn't active yet.
+			if (err instanceof StreamFetchError) {
+				this.emit("waiting", {
+					username: this.username,
+					phase: "stream",
+					elapsed: 0,
+				});
+			}
+
 			// Await any background remuxes before shutting down,
 			// so they can finish producing .mp4 and delete temp .ts files.
 			if (pendingRemuxes.length > 0) {
@@ -367,7 +377,8 @@ export class TikTokLiveDownloader {
 
 	private async resolveRoomIdWithRetry(): Promise<string> {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 180_000);
+		const maxInterval = Math.max(interval, 180);
+		const waitStart = Date.now();
 
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
@@ -377,7 +388,12 @@ export class TikTokLiveDownloader {
 				return roomId;
 			}
 
-			await sleep(maxInterval);
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1_000,
+			});
+			await sleep(maxInterval * 1_000);
 		}
 	}
 
@@ -400,7 +416,8 @@ export class TikTokLiveDownloader {
 	 */
 	private async pollStreamInfo(roomId: string): Promise<StreamInfo> {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 180_000);
+		const maxInterval = Math.max(interval, 180);
+		const waitStart = Date.now();
 
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
@@ -409,7 +426,12 @@ export class TikTokLiveDownloader {
 				return await this.fetchStreamInfo(roomId);
 			} catch (err) {
 				if (err instanceof StreamFetchError) {
-					await sleep(maxInterval);
+					this.emit("waiting", {
+						username: this.username,
+						phase: "stream",
+						elapsed: (Date.now() - waitStart) / 1_000,
+					});
+					await sleep(maxInterval * 1_000);
 					continue;
 				}
 				throw err;
@@ -550,6 +572,12 @@ export class TikTokLiveDownloader {
 
 		if (finalPath === inputPath) return tsResult;
 
+		this.emit("remux", {
+			filePath: inputPath,
+			inputSizeMB: tsResult.sizeMB,
+			status: "started",
+		});
+
 		try {
 			await this.remuxAndNormalize(
 				this.options.ffmpegPath,
@@ -563,6 +591,14 @@ export class TikTokLiveDownloader {
 			} catch {
 				// ignore cleanup failure
 			}
+
+			this.emit("remux", {
+				filePath: inputPath,
+				outputPath: finalPath,
+				inputSizeMB: tsResult.sizeMB,
+				status: "completed",
+			});
+
 			return {
 				...tsResult,
 				filePath: finalPath,
@@ -573,6 +609,13 @@ export class TikTokLiveDownloader {
 			console.warn(
 				`tokwatchr: remux failed for ${inputPath}, keeping .ts as fallback: ${msg}`,
 			);
+
+			this.emit("remux", {
+				filePath: inputPath,
+				inputSizeMB: tsResult.sizeMB,
+				status: "failed",
+			});
+
 			return tsResult;
 		}
 	}

package/src/download/ffmpeg.ts

@@ -13,10 +13,10 @@ export interface FfmpegDownloadOptions {
 	onProgress?: (stats: DownloadStats) => void;
 	maxDuration?: number;
 	/**
-	 * Startup timeout in ms. If ffmpeg produces no stderr output within
+	 * Startup timeout in seconds. If ffmpeg produces no stderr output within
 	 * this window, it is killed and the promise rejects. Prevents
 	 * indefinite hangs on bad/ stalled stream URLs.
-	 * @default 30_000
+	 * @default 30
 	 */
 	timeout?: number;
 }
@@ -89,7 +89,7 @@ export async function downloadWithFfmpeg(
 		signal,
 		onProgress,
 		maxDuration,
-		timeout = 30_000,
+		timeout = 30,
 	} = options;
 
 	const ffmpegArgs: string[] = [
@@ -123,7 +123,7 @@ export async function downloadWithFfmpeg(
 		let duration = 0;
 
 		// Startup timeout — if ffmpeg produces no stderr output within
-		// `timeout` ms, it likely stalled on a bad URL. Kill it so the
+		// `timeout` seconds, it likely stalled on a bad URL. Kill it so the
 		// caller doesn't hang indefinitely.
 		let firstDataTimer: ReturnType<typeof setTimeout> | null = setTimeout(
 			() => {
@@ -131,11 +131,11 @@ export async function downloadWithFfmpeg(
 				proc.kill("SIGTERM");
 				reject(
 					new FfmpegError(
-						`ffmpeg produced no output within ${timeout}ms — check the stream URL`,
+						`ffmpeg produced no output within ${timeout}s — check the stream URL`,
 					),
 				);
 			},
-			timeout,
+			timeout * 1_000,
 		);
 
 		// Parse stderr for progress

package/src/index.ts

@@ -28,10 +28,12 @@ export type {
 	DownloadStats,
 	OutputFormat,
 	QualityOption,
+	RemuxInfo,
 	StreamInfo,
 	StreamQualityKey,
 	TikTokLiveDownloaderEvents,
 	TikTokLiveDownloaderOptions,
+	WaitingInfo,
 } from "./types.js";
 
 // ─── Quality utilities ────────────────────────────────────

package/src/types.ts

@@ -85,7 +85,7 @@ export interface TikTokLiveDownloaderOptions {
 	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). */
+	/** Polling interval in seconds when waiting for live (default: 180). */
 	checkInterval?: number;
 	/** HTTP proxy URL (supports http, https, socks4, socks5). */
 	proxyUrl?: string;
@@ -93,7 +93,7 @@ export interface TikTokLiveDownloaderOptions {
 	cookieJar?: CookieJarLike;
 	/** Browser to emulate (default: "chrome"). */
 	browser?: Browser;
-	/** Request timeout in ms (default: 30_000). */
+	/** Request timeout in seconds (default: 30). */
 	timeout?: number;
 	/** Extra headers to send with every request. */
 	headers?: Record<string, string>;
@@ -114,7 +114,31 @@ export interface CookieJarLike {
 
 // ─── Events ───────────────────────────────────────────────
 
+export interface WaitingInfo {
+	/** The username being waited on. */
+	username: string;
+	/** Which phase we're waiting in: "room" = looking for a room, "stream" = stream not active. */
+	phase: "room" | "stream";
+	/** Seconds elapsed since this phase started. */
+	elapsed: number;
+}
+
+export interface RemuxInfo {
+	/** Input .ts file path. */
+	filePath: string;
+	/** Input file size in MB. */
+	inputSizeMB: number;
+	/** Remux status: started → completed (with outputPath) or failed (keeping .ts). */
+	status: "started" | "completed" | "failed";
+	/** Output file path. Only set when status is "completed". */
+	outputPath?: string;
+}
+
 export interface TikTokLiveDownloaderEvents {
+	/** Emitted periodically while waiting for a room or stream to become active. */
+	waiting: [info: WaitingInfo];
+	/** Emitted when a remux operation starts, completes, or fails. */
+	remux: [info: RemuxInfo];
 	/** 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. */