tokwatchr 0.4.3 → 0.5.0

package/dist/index.d.mts

@@ -88,7 +88,17 @@ 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 TikTokLiveDownloaderEvents {
+  /** Emitted periodically while waiting for a room or stream to become active. */
+  waiting: [info: WaitingInfo];
   /** 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. */
@@ -237,6 +247,12 @@ declare class TikTokLiveDownloader {
   private resolveRoomIdOnce;
   private resolveRoomIdWithRetry;
   private fetchStreamInfo;
+  /**
+   * 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.
+   */
+  private pollStreamInfo;
   /**
    * Download a single segment. Always downloads to .ts (crash-safe).
    * Does NOT remux — that is handled by remuxSegment() running in the background.
@@ -324,4 +340,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, 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

@@ -620,7 +620,7 @@ const DEFAULT_OPTIONS = {
 	bitrate: null,
 	maxDuration: Infinity,
 	maxSegmentDuration: Infinity,
-	checkInterval: 3e4,
+	checkInterval: 18e4,
 	proxyUrl: null,
 	cookieJar: null,
 	browser: "chrome",
@@ -773,7 +773,7 @@ var TikTokLiveDownloader = class {
 			if (!roomId && waitForLive) roomId = await this.resolveRoomIdWithRetry();
 			if (!roomId) throw new UserOfflineError(this.username);
 			this.setState("waiting");
-			const firstInfo = await this.fetchStreamInfo(roomId);
+			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);
@@ -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,11 +839,17 @@ var TikTokLiveDownloader = class {
 	}
 	async resolveRoomIdWithRetry() {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 3e4);
+		const maxInterval = Math.max(interval, 18e4);
+		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);
 		}
 	}
@@ -852,6 +863,33 @@ var TikTokLiveDownloader = class {
 		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, 18e4);
+		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);
+					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.
 	*/

package/package.json

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

package/src/TikTokLiveDownloader.ts

@@ -9,7 +9,11 @@ import { resolveRoomId } from "./api/room.js";
 import { fetchStreamInfo } from "./api/stream.js";
 import { downloadWithFfmpeg } from "./download/ffmpeg.js";
 import { downloadRawHttp } from "./download/raw-http.js";
-import { UserNotFoundError, UserOfflineError } from "./errors.js";
+import {
+	StreamFetchError,
+	UserNotFoundError,
+	UserOfflineError,
+} from "./errors.js";
 import type {
 	DownloaderState,
 	DownloadResult,
@@ -32,7 +36,7 @@ const DEFAULT_OPTIONS: ResolvedOptions = {
 	bitrate: null,
 	maxDuration: Infinity,
 	maxSegmentDuration: Infinity,
-	checkInterval: 30_000,
+	checkInterval: 180_000,
 	proxyUrl: null,
 	cookieJar: null,
 	browser: "chrome",
@@ -259,7 +263,9 @@ export class TikTokLiveDownloader {
 
 			// Phase 2: Get stream info (refreshed per segment to avoid stale URLs)
 			this.setState("waiting");
-			const firstInfo = await this.fetchStreamInfo(roomId);
+			const firstInfo = waitForLive
+				? await this.pollStreamInfo(roomId)
+				: await this.fetchStreamInfo(roomId);
 
 			const segmentEnabled =
 				this.options.maxSegmentDuration > 0 &&
@@ -314,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) {
@@ -361,7 +377,8 @@ export class TikTokLiveDownloader {
 
 	private async resolveRoomIdWithRetry(): Promise<string> {
 		const interval = this.options.checkInterval;
-		const maxInterval = Math.max(interval, 30_000);
+		const maxInterval = Math.max(interval, 180_000);
+		const waitStart = Date.now();
 
 		while (true) {
 			this.abortController.signal?.throwIfAborted();
@@ -371,6 +388,11 @@ export class TikTokLiveDownloader {
 				return roomId;
 			}
 
+			this.emit("waiting", {
+				username: this.username,
+				phase: "room",
+				elapsed: (Date.now() - waitStart) / 1_000,
+			});
 			await sleep(maxInterval);
 		}
 	}
@@ -387,6 +409,36 @@ export class TikTokLiveDownloader {
 		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.
+	 */
+	private async pollStreamInfo(roomId: string): Promise<StreamInfo> {
+		const interval = this.options.checkInterval;
+		const maxInterval = Math.max(interval, 180_000);
+		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) / 1_000,
+					});
+					await sleep(maxInterval);
+					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.

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
 	StreamQualityKey,
 	TikTokLiveDownloaderEvents,
 	TikTokLiveDownloaderOptions,
+	WaitingInfo,
 } from "./types.js";
 
 // ─── Quality utilities ────────────────────────────────────

package/src/types.ts

@@ -114,7 +114,18 @@ 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 TikTokLiveDownloaderEvents {
+	/** Emitted periodically while waiting for a room or stream to become active. */
+	waiting: [info: WaitingInfo];
 	/** 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. */