@tiktool/live 2.6.2 → 2.6.4

package/README.md

@@ -239,6 +239,10 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
 | `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
 | `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
 | `debug` | `boolean` | `false` | Debug logging |
+| `sessionId` | `string` | — | TikTok `sessionid` cookie for authenticated features (ranklist, chat) |
+| `ttTargetIdc` | `string` | — | TikTok target IDC region (e.g. `useast5`). Required with `sessionId` |
+| `roomId` | `string` | — | Pre-known room ID — skips HTML page scrape |
+| `ttwid` | `string` | — | Pre-fetched `ttwid` cookie. With `roomId`, skips all HTTP requests |
 
 ### Methods
 
@@ -246,9 +250,12 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
 |--------|---------|-------------|
 | `connect()` | `Promise<void>` | Connect to livestream |
 | `disconnect()` | `void` | Disconnect |
+| `setSession(sessionId, ttTargetIdc?)` | `void` | Update session at runtime |
+| `buildSessionCookieHeader()` | `string \| undefined` | Build cookie header for auth API requests |
 | `connected` | `boolean` | Connection status |
 | `eventCount` | `number` | Total events received |
 | `roomId` | `string` | Current room ID |
+| `sessionId` | `string \| undefined` | Current session ID |
 
 ---
 
@@ -256,16 +263,72 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
 
 All API requests require an API key. Get yours at [tik.tools](https://tik.tools).
 
-| Tier | Rate Limit | WS Connections | Bulk Check | Caption Credits | Price |
-|------|-----------|----------------|------------|-----------------|-------|
-| **Free** | 30/min | 3 | 5 | 60 min trial | Free |
-| **Pro** | 120/min | 50 | 50 | 2,000/month | Paid |
-| **Ultra** | Unlimited | 10,000 | 500 | 10,000/month | Paid |
+| Tier | Rate Limit | WS Connections | Bulk Check | Feed Discovery | Caption Credits | Price |
+|------|-----------|----------------|------------|----------------|-----------------|-------|
+| **Free** | 30/min | 3 | 5 | ✕ | 60 min trial | Free |
+| **Pro** | 120/min | 50 | 50 | 100/day | 2,000/month | Paid |
+| **Ultra** | Unlimited | 10,000 | 500 | 2,000/day | 10,000/month | Paid |
 
 The SDK calls the sign server **once per connection**, then stays connected via WebSocket. A free key is sufficient for most use cases.
 
 ---
 
+## 🔍 Feed Discovery
+
+Discover recommended TikTok LIVE streams. **Requires Pro or Ultra tier.**
+
+```typescript
+import { getLiveFeed, fetchFeed } from '@tiktool/live';
+
+// Option 1: Two-step (sign-and-return)
+const signed = await getLiveFeed({
+    apiKey: 'YOUR_PRO_KEY',
+    sessionId: 'YOUR_TIKTOK_SESSIONID',
+    region: 'US',
+    count: 10,
+});
+
+const resp = await fetch(signed.signed_url, {
+    headers: { ...signed.headers, Cookie: signed.cookies || '' },
+});
+const data = await resp.json();
+
+// Option 2: One-step convenience
+const feed = await fetchFeed({
+    apiKey: 'YOUR_PRO_KEY',
+    sessionId: 'YOUR_TIKTOK_SESSIONID',
+    count: 10,
+});
+
+for (const entry of feed.data || []) {
+    const room = entry.data;
+    console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
+}
+```
+
+### Channel Types
+
+| Value | Channel |
+|-------|--------|
+| `"87"` | Recommended (default) |
+| `"86"` | Suggested |
+| `"42"` | Following |
+| `"1111006"` | Gaming |
+
+### Pagination
+
+Use `maxTime` from the previous response to load more:
+
+```typescript
+const page2 = await getLiveFeed({
+    apiKey: 'YOUR_PRO_KEY',
+    sessionId: 'YOUR_TIKTOK_SESSIONID',
+    maxTime: data.extra?.max_time, // cursor from previous response
+});
+```
+
+---
+
 ## 🏆 Regional Leaderboard
 
 Get daily, hourly, popular, or league LIVE rankings for any streamer. **Requires Pro or Ultra tier.**

package/dist/index.d.mts

@@ -377,6 +377,67 @@ interface EntranceResponse {
     }>;
 }
 type RanklistResponse = OnlineAudienceResponse | AnchorRankListResponse | EntranceResponse;
+/** Streamer info in a feed room entry */
+interface FeedRoomOwner {
+    /** TikTok user ID */
+    id_str: string;
+    /** Username (@handle) */
+    display_id: string;
+    /** Display name */
+    nickname: string;
+    /** Avatar thumbnail URLs */
+    avatar_thumb?: {
+        url_list: string[];
+    };
+    /** Avatar large URLs */
+    avatar_large?: {
+        url_list: string[];
+    };
+}
+/** A single live room entry from the feed */
+interface FeedRoom {
+    /** Room ID */
+    id_str: string;
+    /** Stream title */
+    title: string;
+    /** Current viewer count */
+    user_count: number;
+    /** Stream cover image URL */
+    cover?: {
+        url_list: string[];
+    };
+    /** Streamer info */
+    owner: FeedRoomOwner;
+    /** Stream status (2 = live) */
+    status: number;
+    /** Stream start time (unix seconds) */
+    create_time?: number;
+    /** Like count */
+    like_count?: number;
+    /** Hashtag IDs */
+    hashtag_ids?: string[];
+}
+/** Signed-URL response from GET/POST /webcast/feed */
+interface FeedSignedResponse {
+    /** Always 0 on success */
+    status_code: number;
+    /** The signed TikTok URL to fetch */
+    signed_url: string;
+    /** Required headers */
+    headers: Record<string, string>;
+    /** Cookies to include (ttwid, sessionid, etc.) */
+    cookies?: string;
+    /** Region used */
+    region: string;
+    /** Channel ID used */
+    channel_id: string;
+    /** Remaining daily feed calls */
+    feed_remaining: number;
+    /** Daily feed call limit */
+    feed_limit: number;
+    /** Human-readable instructions */
+    note: string;
+}
 
 declare class TikTokLive extends EventEmitter {
     private ws;
@@ -567,6 +628,9 @@ declare class TikTokCaptions extends EventEmitter {
     private readonly _diarization;
     private readonly _maxDurationMinutes;
     private _language;
+    private streamAbortController;
+    private flvExtractor;
+    private streamUrl;
     constructor(options: TikTokCaptionsOptions);
     /**
      * Start real-time captions for the configured TikTok user.
@@ -598,6 +662,11 @@ declare class TikTokCaptions extends EventEmitter {
     private buildWsUrl;
     private send;
     private handleMessage;
+    /**
+     * Connect to the TikTok FLV stream and extract audio.
+     * Sends binary audio buffers to the server via WebSocket.
+     */
+    private connectToStream;
 }
 
 interface GetRanklistOptions {
@@ -755,4 +824,84 @@ interface RegionalRanklistSignedResponse {
  */
 declare function getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
 
-export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type CaptionCredits, type CaptionData, type CaptionError, type CaptionStatus, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type GetRanklistOptions, type GetRegionalRanklistOptions, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type OnlineAudienceEntry, type OnlineAudienceResponse, type QuestionEvent, type RankUpdateEvent, type RanklistResponse, type RanklistSelfInfo, type RanklistUser, type RegionalRanklistSignedResponse, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type SubscribeEvent, TikTokCaptions, type TikTokCaptionsEvents, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type TranslationData, type UnknownEvent, getRanklist, getRegionalRanklist };
+interface GetLiveFeedOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication (Pro or Ultra tier required) */
+    apiKey: string;
+    /** Region code (default: 'US') */
+    region?: string;
+    /**
+     * Feed channel:
+     * - '87' = Recommended (default)
+     * - '86' = Suggested
+     * - '42' = Following
+     * - '1111006' = Gaming
+     */
+    channelId?: string;
+    /** Number of rooms to return (max 50, default 20) */
+    count?: number;
+    /** Pagination cursor from previous response (default: '0') */
+    maxTime?: string;
+    /** TikTok sessionid cookie — required for populated results */
+    sessionId?: string;
+    /** TikTok ttwid cookie */
+    ttwid?: string;
+    /** TikTok msToken cookie */
+    msToken?: string;
+}
+/**
+ * Get a signed URL for fetching the TikTok LIVE feed.
+ *
+ * **Two-step pattern**: Returns a signed URL with headers and cookies.
+ * Fetch the signed URL from your own IP to get the feed data.
+ *
+ * Requires **Pro** or **Ultra** API key tier.
+ *
+ * @example
+ * ```ts
+ * // Step 1: Get signed URL
+ * const signed = await getLiveFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     region: 'US',
+ *     count: 10,
+ * });
+ *
+ * // Step 2: Fetch from YOUR IP
+ * const resp = await fetch(signed.signed_url, {
+ *     headers: { ...signed.headers, Cookie: signed.cookies || '' },
+ * });
+ * const data = await resp.json();
+ * console.log(`Found ${data.data?.length || 0} live rooms`);
+ *
+ * // Step 3: Load more (pagination)
+ * const nextSigned = await getLiveFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     maxTime: data.extra?.max_time || '0',
+ * });
+ * ```
+ */
+declare function getLiveFeed(opts: GetLiveFeedOptions): Promise<FeedSignedResponse>;
+/**
+ * Convenience: Get the feed AND fetch the signed URL in one step.
+ * Returns the parsed JSON feed data from TikTok.
+ *
+ * @example
+ * ```ts
+ * const feed = await fetchFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     region: 'GR',
+ *     count: 10,
+ * });
+ * for (const entry of feed.data || []) {
+ *     const room = entry.data;
+ *     console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
+ * }
+ * ```
+ */
+declare function fetchFeed(opts: GetLiveFeedOptions): Promise<any>;
+
+export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type CaptionCredits, type CaptionData, type CaptionError, type CaptionStatus, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type FeedRoom, type FeedRoomOwner, type FeedSignedResponse, type GetLiveFeedOptions, type GetRanklistOptions, type GetRegionalRanklistOptions, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type OnlineAudienceEntry, type OnlineAudienceResponse, type QuestionEvent, type RankUpdateEvent, type RanklistResponse, type RanklistSelfInfo, type RanklistUser, type RegionalRanklistSignedResponse, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type SubscribeEvent, TikTokCaptions, type TikTokCaptionsEvents, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type TranslationData, type UnknownEvent, fetchFeed, getLiveFeed, getRanklist, getRegionalRanklist };

package/dist/index.d.ts

@@ -377,6 +377,67 @@ interface EntranceResponse {
     }>;
 }
 type RanklistResponse = OnlineAudienceResponse | AnchorRankListResponse | EntranceResponse;
+/** Streamer info in a feed room entry */
+interface FeedRoomOwner {
+    /** TikTok user ID */
+    id_str: string;
+    /** Username (@handle) */
+    display_id: string;
+    /** Display name */
+    nickname: string;
+    /** Avatar thumbnail URLs */
+    avatar_thumb?: {
+        url_list: string[];
+    };
+    /** Avatar large URLs */
+    avatar_large?: {
+        url_list: string[];
+    };
+}
+/** A single live room entry from the feed */
+interface FeedRoom {
+    /** Room ID */
+    id_str: string;
+    /** Stream title */
+    title: string;
+    /** Current viewer count */
+    user_count: number;
+    /** Stream cover image URL */
+    cover?: {
+        url_list: string[];
+    };
+    /** Streamer info */
+    owner: FeedRoomOwner;
+    /** Stream status (2 = live) */
+    status: number;
+    /** Stream start time (unix seconds) */
+    create_time?: number;
+    /** Like count */
+    like_count?: number;
+    /** Hashtag IDs */
+    hashtag_ids?: string[];
+}
+/** Signed-URL response from GET/POST /webcast/feed */
+interface FeedSignedResponse {
+    /** Always 0 on success */
+    status_code: number;
+    /** The signed TikTok URL to fetch */
+    signed_url: string;
+    /** Required headers */
+    headers: Record<string, string>;
+    /** Cookies to include (ttwid, sessionid, etc.) */
+    cookies?: string;
+    /** Region used */
+    region: string;
+    /** Channel ID used */
+    channel_id: string;
+    /** Remaining daily feed calls */
+    feed_remaining: number;
+    /** Daily feed call limit */
+    feed_limit: number;
+    /** Human-readable instructions */
+    note: string;
+}
 
 declare class TikTokLive extends EventEmitter {
     private ws;
@@ -567,6 +628,9 @@ declare class TikTokCaptions extends EventEmitter {
     private readonly _diarization;
     private readonly _maxDurationMinutes;
     private _language;
+    private streamAbortController;
+    private flvExtractor;
+    private streamUrl;
     constructor(options: TikTokCaptionsOptions);
     /**
      * Start real-time captions for the configured TikTok user.
@@ -598,6 +662,11 @@ declare class TikTokCaptions extends EventEmitter {
     private buildWsUrl;
     private send;
     private handleMessage;
+    /**
+     * Connect to the TikTok FLV stream and extract audio.
+     * Sends binary audio buffers to the server via WebSocket.
+     */
+    private connectToStream;
 }
 
 interface GetRanklistOptions {
@@ -755,4 +824,84 @@ interface RegionalRanklistSignedResponse {
  */
 declare function getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
 
-export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type CaptionCredits, type CaptionData, type CaptionError, type CaptionStatus, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type GetRanklistOptions, type GetRegionalRanklistOptions, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type OnlineAudienceEntry, type OnlineAudienceResponse, type QuestionEvent, type RankUpdateEvent, type RanklistResponse, type RanklistSelfInfo, type RanklistUser, type RegionalRanklistSignedResponse, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type SubscribeEvent, TikTokCaptions, type TikTokCaptionsEvents, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type TranslationData, type UnknownEvent, getRanklist, getRegionalRanklist };
+interface GetLiveFeedOptions {
+    /** API server URL (default: https://api.tik.tools) */
+    serverUrl?: string;
+    /** API key for authentication (Pro or Ultra tier required) */
+    apiKey: string;
+    /** Region code (default: 'US') */
+    region?: string;
+    /**
+     * Feed channel:
+     * - '87' = Recommended (default)
+     * - '86' = Suggested
+     * - '42' = Following
+     * - '1111006' = Gaming
+     */
+    channelId?: string;
+    /** Number of rooms to return (max 50, default 20) */
+    count?: number;
+    /** Pagination cursor from previous response (default: '0') */
+    maxTime?: string;
+    /** TikTok sessionid cookie — required for populated results */
+    sessionId?: string;
+    /** TikTok ttwid cookie */
+    ttwid?: string;
+    /** TikTok msToken cookie */
+    msToken?: string;
+}
+/**
+ * Get a signed URL for fetching the TikTok LIVE feed.
+ *
+ * **Two-step pattern**: Returns a signed URL with headers and cookies.
+ * Fetch the signed URL from your own IP to get the feed data.
+ *
+ * Requires **Pro** or **Ultra** API key tier.
+ *
+ * @example
+ * ```ts
+ * // Step 1: Get signed URL
+ * const signed = await getLiveFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     region: 'US',
+ *     count: 10,
+ * });
+ *
+ * // Step 2: Fetch from YOUR IP
+ * const resp = await fetch(signed.signed_url, {
+ *     headers: { ...signed.headers, Cookie: signed.cookies || '' },
+ * });
+ * const data = await resp.json();
+ * console.log(`Found ${data.data?.length || 0} live rooms`);
+ *
+ * // Step 3: Load more (pagination)
+ * const nextSigned = await getLiveFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     maxTime: data.extra?.max_time || '0',
+ * });
+ * ```
+ */
+declare function getLiveFeed(opts: GetLiveFeedOptions): Promise<FeedSignedResponse>;
+/**
+ * Convenience: Get the feed AND fetch the signed URL in one step.
+ * Returns the parsed JSON feed data from TikTok.
+ *
+ * @example
+ * ```ts
+ * const feed = await fetchFeed({
+ *     apiKey: 'your-pro-key',
+ *     sessionId: 'your-tiktok-sessionid',
+ *     region: 'GR',
+ *     count: 10,
+ * });
+ * for (const entry of feed.data || []) {
+ *     const room = entry.data;
+ *     console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
+ * }
+ * ```
+ */
+declare function fetchFeed(opts: GetLiveFeedOptions): Promise<any>;
+
+export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, type CaptionCredits, type CaptionData, type CaptionError, type CaptionStatus, type ChatEvent, type ControlEvent, type EmoteChatEvent, type EntranceInfo, type EntranceResponse, type EntranceTab, type EnvelopeEvent, type FeedRoom, type FeedRoomOwner, type FeedSignedResponse, type GetLiveFeedOptions, type GetRanklistOptions, type GetRegionalRanklistOptions, type GiftEvent, type LikeEvent, type LinkMicEvent, type LiveEvent, type LiveIntroEvent, type MemberEvent, type OnlineAudienceEntry, type OnlineAudienceResponse, type QuestionEvent, type RankUpdateEvent, type RanklistResponse, type RanklistSelfInfo, type RanklistUser, type RegionalRanklistSignedResponse, type RoomEvent, type RoomInfo, type RoomUserSeqEvent, type SocialEvent, type SubscribeEvent, TikTokCaptions, type TikTokCaptionsEvents, type TikTokCaptionsOptions, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type TranslationData, type UnknownEvent, fetchFeed, getLiveFeed, getRanklist, getRegionalRanklist };