TikTok Live Connector

https://github.com/zerodytrash/tiktok-live-connector
Admin
TikTok Live Connector is a Node.js library for connecting to TikTok LIVE streams to receive...
Tokens:56,544
Snippets:416
Trust Score:9.2
License:AGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic GET request example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-http-client.md

Shows a basic call to the request method with merged query parameters and JSON responseType. The host, path, and a searchParam are provided. Use this for straightforward requests that do not require signing.

```typescript
// Basic GET with merged params
const res = await client.request({
    host: 'webcast.tiktok.com',
    path: 'webcast/room/info/',
    searchParams: { room_id: '12345' },
    signRequest: false,
    responseType: 'json'
});
```

--------------------------------

### Basic Connect Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Example of connecting to a live stream and logging the room ID upon success.

```ts
connection.connect().then(state => {
    console.log(`Connected to roomId ${state.roomId}`);
});
```

--------------------------------

### Usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-websocket-client.md

Example of creating a WebSocket provider and using it to connect to a TikTok live room.

```ts
import { createWebSocketProvider, getWebSocketConfigDefaults, getRandomPresets } from 'tiktok-live-connector';

const provider = createWebSocketProvider(getWebSocketConfigDefaults(getRandomPresets()), {
    handshakeTimeout: 10000
});

const ws = provider({
    roomId: 'room123',
    baseUrl: 'wss://webcast.blisscdn.com/',
    wsParams: { room_id: 'room123', compress: 'gzip' },
    wsHeaders: { Cookie: 'tt-target-idc=useast1a' }
});
```

--------------------------------

### Example 2: Using JWT Authentication - Client-Side

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Client-side example showing how to set the JWT header and create a connection.

```ts
import { SignConfig, TikTokLiveConnection } from 'tiktok-live-connector';

SignConfig.baseOptions = SignConfig.baseOptions || {};
SignConfig.baseOptions.headers = {
    ...(SignConfig.baseOptions.headers || {}),
    'x-jwt-key': 'generated-jwt-key'
};

const connection = new TikTokLiveConnection('tv_asahi_news');
```

--------------------------------

### Environment Variables Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/configuration.md

Example environment variables in .env style

```ts
// .env style
SIGN_API_KEY=your_key
SIGN_API_URL=https://api.eulerstream.com
TIKTOK_CLIENT_TIMEOUT=15000
RANDOMIZE_TIKTOK_DEVICE=true
```

--------------------------------

### Install tiktok-live-connector via npm

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Install the tiktok-live-connector package via npm.

```bash
npm i tiktok-live-connector
```

--------------------------------

### Proto-utils code examples

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/proto-utils.md

Code examples for the proto-utils module, including configuration, deserialization, and error handling.

```ts
export const WebcastDeserializeConfig: IWebcastDeserializeConfig = {
    skipMessageTypes: [],
    includeMessageTypes: null,
    showBase64OnDecodeError: true
};
```

```ts
import { WebcastDeserializeConfig } from 'tiktok-live-connector';

// Skip heavy, rarely-needed messages to save CPU/memory
WebcastDeserializeConfig.skipMessageTypes = ['WebcastMemberMessage'];
```

```ts
export function deserializeMessage<T extends keyof WebcastMessage>(
    protoName: T,
    binaryMessage: Buffer
): WebcastMessage[T]
```

```ts
import { deserializeMessage } from 'tiktok-live-connector';

const fetched = deserializeMessage('ProtoMessageFetchResult', buffer);
for (const msg of fetched.messages) {
    console.log(msg.method, msg.decodedData?.data);
}
```

```ts
// Error handling for a bad buffer
try {
    deserializeMessage('WebcastChatMessage', badBuffer);
} catch (err) {
    if (err instanceof SchemaDecodeError) {
        console.error('Undecodable payload:', err.message);
    }
}
```

--------------------------------

### Example Options

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of creating a TikTokLiveConnection with various options including API key, data processing, gift info, web/WS config overrides, and client options.

```typescript
const tikTokLiveConnection = new TikTokLiveConnection(tiktokUsername, {
    signApiKey: 'your-api-key',
    processInitialData: false,
    enableExtendedGiftInfo: true,
    webConfigOverrides: {
        DEFAULT_HTTP_CLIENT_PARAMS: {
            app_language: 'en-US',
            device_platform: 'web_pc'
        },
        DEFAULT_HTTP_CLIENT_HEADERS: {
            'X-Custom-Header': 'value'
        }
    },
    wsConfigOverrides: {
        DEFAULT_WS_CLIENT_PARAMS: {
            app_language: 'en-US'
        },
        DEFAULT_WS_CLIENT_HEADERS: {
            'X-Custom-Header': 'value'
        }
    },
    webClientOptions: {
        timeout: { request: 10000 }
    },
    wsClientOptions: {
        handshakeTimeout: 10000
    }
});
```

--------------------------------

### waitUntilLive and Property Getters Examples

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Code examples for the waitUntilLive method and property getters.

```ts
public async waitUntilLive(
    seconds: number = 60,
    abortSignal?: AbortSignal
): Promise<void>
```

```ts
// Resolve once the streamer goes live
await connection.waitUntilLive(30);

// Cancellable
const controller = new AbortController();
setTimeout(() => controller.abort(new Error('Giving up')), 5 * 60 * 1000);
try {
    await connection.waitUntilLive(60, controller.signal);
} catch (err) {
    console.log('Cancelled', err);
}
```

```ts
console.log(connection.state); // current snapshot
connection.webClient.clientParams['region'] = 'US';
```

--------------------------------

### Usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/legacy.md

Example usage of the data-converter helper functions.

```ts
import { mapBadges, getPreferredPictureFormat } from 'tiktok-live-connector/legacy';

const url = getPreferredPictureFormat(avatarUrlList);
const badges = mapBadges(user.badgeList);
```

--------------------------------

### getSessionBundle usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-cookie-jar.md

Example of retrieving the session bundle and checking if it exists.

```typescript
const bundle = await cookieJar.getSessionBundle();
if (bundle) console.log('session present');
```

--------------------------------

### Example 2: Using JWT Authentication - Server-Side

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Server-side example showing how to mint a short-lived JWT using the Euler API client.

```ts
import { SignConfig, createEulerClient } from 'tiktok-live-connector';

SignConfig.apiKey = 'your_server_side_api_key';
const apiClient = createEulerClient();

const res = await apiClient.authentication.createJWT(
    122, // Your account ID
    {
        limits: { minute: 5, hour: 5, day: 5 },
        expireAfter: 60 * 60 * 2 // 2 hours, the maximum accepted value
    }
);

console.log('Generated JWT:', res.data.token);
```

--------------------------------

### TikTokLiveConnection Constructor Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/configuration.md

Example of constructing a TikTokLiveConnection with various configuration options.

```typescript
import { TikTokLiveConnection } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection('@user', {
    signApiKey: process.env.EULER_API_KEY,
    processInitialData: true,
    enableExtendedGiftInfo: true,
    webConfigOverrides: {
        DEFAULT_HTTP_CLIENT_PARAMS: { app_language: 'en-US' },
        DEFAULT_HTTP_CLIENT_HEADERS: { 'X-Custom-Header': 'value' }
    },
    wsConfigOverrides: {
        DEFAULT_WS_CLIENT_PARAMS: { app_language: 'en-US' }
    },
    webClientOptions: { timeout: { request: 10000 } },
    wsClientOptions: { handshakeTimeout: 10000 }
});
```

--------------------------------

### Usage Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Example usage of the composite routes with configuration to skip the Euler fallback.

```ts
import { RouteConfig } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection('@user');

// Skip the Euler fallback entirely
RoomIdRouteConfig.skipFetchRoomIdFromEulerRoute = true;

const isLive = await RouteConfig.fetchIsLiveComposite({
    webClient: connection.webClient,
    apiClient: connection.apiClient,
    uniqueId: 'user'
});
```

--------------------------------

### fetchRoomInfo

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Method signature and usage example for fetchRoomInfo.

```ts
@HandleError('Failed to fetch room info.')
public async fetchRoomInfo(roomId: string = this.roomId): Promise<RoomInfoResponse>
```

```ts
const info = await connection.fetchRoomInfo();
console.log(info.stream_url.hls_pull_url);
```

--------------------------------

### Error Handling and Reconnect Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Example of handling connection errors and implementing a reconnect pattern.

```ts
// Error handling + reconnect pattern
connection.connect().catch(err => {
    if (err instanceof UserOfflineError) {
        console.log('Streamer is currently offline');
    } else if (err instanceof SignatureRateLimitError) {
        console.log(`Rate limited, retry after ${err.retryAfter / 1000}s`);
    } else {
        console.error(err);
    }
});
```

--------------------------------

### Device Preset Usage Example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/web-config.md

Demonstrates importing and using the device preset utilities from the tiktok-live-connector package.

```ts
import { userAgentToDevicePreset, generateDeviceId, WebcastWebConfigDefaults } from 'tiktok-live-connector';

const preset = userAgentToDevicePreset('Mozilla/5.0 … Chrome/129.0.0.0');
const deviceId = generateDeviceId(); // '1234567890123456789'
```

--------------------------------

### Advanced Construction with Auth

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Advanced example with authentication, provider override, and error handling.

```ts
// Construction with auth + provider override + error handling
import { TikTokLiveConnection } from 'tiktok-live-connector';

try {
    const connection = new TikTokLiveConnection('tv_asahi_news', {
        signApiKey: process.env.EULER_API_KEY,
        authenticateWs: true,
        session: {
            cookie: {
                type: 'cookie',
                value: { sessionId: '<id>', ttTargetIdc: 'useast1a' }
            }
        }
    });
    await connection.connect();
    console.log('Connected to room', connection.roomId);
} catch (err) {
    console.error('Connect failed', err);
}
```

--------------------------------

### GET webcast/gift/list/

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Documentation for the fetchRoomGiftsRoute, which retrieves the gift list for a live room.

```APIDOC
## GET webcast/gift/list/

### Description
Fetches the list of gifts available for a live room. This route requires a signature from TikTok.

### Method
GET

### Endpoint
`webcast/gift/list/`

### Parameters
#### Query Parameters
- **room_id** (string) - Required - The ID of the room to fetch gifts for. If not provided, the `roomId` from the web client is used.

### Request Example
```
GET /webcast/gift/list/?room_id=1234567890
```

### Response
#### Success Response (200)
- **response.data.gifts** (array) - The list of gifts.

#### Response Example
```json
{
  "data": {
    "gifts": [
      {
        "id": 1,
        "name": "Rose"
      }
    ]
  }
}
```

### Error Handling
- Throws `InvalidRequestError` when no `roomId` is available.
```

--------------------------------

### Example 1: Fetching Rate Limits

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Demonstrates how to fetch rate limits using the Euler Stream API client exposed as connection.apiClient.

```ts
import { TikTokLiveConnection } from 'tiktok-live-connector';

const connection = new TikTokLiveConnection('officialgeilegisela', {
    signApiKey: 'your-api-key'
});

const response = await connection.apiClient.webcast.getRateLimits();
console.log('Rate Limits:', response.data);
```

--------------------------------

### Basic Construction

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Basic example of creating a TikTokLiveConnection instance with a username and empty options.

```ts
// Basic construction
const connection = new TikTokLiveConnection('officialgeilegisela', {});
```

--------------------------------

### serializeCookieSessionBundle usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-cookie-jar.md

Example of serializing a cookie session bundle into a header string.

```typescript
const cookieHeader = WebcastCookieJar.serializeCookieSessionBundle(
    WebcastWebConfigDefaults,
    { type: 'cookie', value: { sessionId: 'x', ttTargetIdc: 'useast1a' } }
);
```

--------------------------------

### GET webcast/room/info/

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Documentation for the fetchRoomInfoRoute, which retrieves room information from TikTok's webcast API.

```APIDOC
## GET webcast/room/info/

### Description
Fetches room information from TikTok's webcast API. This route is used to retrieve details about a live room, such as status and metadata.

### Method
GET

### Endpoint
`webcast/room/info/`

### Parameters
#### Query Parameters
- **room_id** (string) - Required - The ID of the room to fetch information for. If not provided, the `roomId` from the web client is used.

### Request Example
```
GET /webcast/room/info/?room_id=1234567890
```

### Response
#### Success Response (200)
- **response** (any) - The raw response from TikTok's API.

#### Response Example
```json
{
  "data": {
    "roomId": "1234567890",
    "status": 2
  }
}
```

### Error Handling
- Throws `InvalidRequestError` when no `roomId` is available.
```

--------------------------------

### fetchAvailableGifts

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Method signature and usage example for fetchAvailableGifts.

```ts
@HandleError('Failed to fetch room gifts.')
public async fetchAvailableGifts(): Promise<RoomGiftInfo>
```

```ts
const gifts = await connection.fetchAvailableGifts();
console.log(gifts[0].name, gifts[0].diamond_count);
```

--------------------------------

### setSessionBundle usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-cookie-jar.md

Example of calling setSessionBundle with a cookie session bundle, setting the session ID and target IDC.

```typescript
await connection.webClient.cookieJar.setSessionBundle({
    type: 'cookie',
    value: { sessionId: '<id>', ttTargetIdc: 'useast1a' }
});
```

--------------------------------

### Like Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the LIKE event, triggered when a viewer sends likes.

```ts
connection.on(WebcastEvent.LIKE, data => {
    const uniqueId = data.user?.uniqueId;
    const nickname = data.user?.nickname;
    if (uniqueId) {
        console.log(`User uniqueId: ${uniqueId}`);
    }
    if (nickname) {
        console.log(`User nickname: ${nickname}`);
    }
    console.log(`Likes: ${data.likeCount}, total likes: ${data.totalLikeCount}`);
});
```

--------------------------------

### sendMessage

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Method signature, basic usage, and error handling example for sendMessage.

```ts
@HandleError('Failed to send message.')
public async sendMessage(content: string, roomId = this.roomId): Promise<WebcastRoomChatRouteResponse>
```

```ts
await connection.sendMessage('Hello world!');
```

```ts
// Error handling: premium endpoint rejection
try {
    await connection.sendMessage('Hello!', roomId);
} catch (err) {
    if (err instanceof PremiumFeatureError) {
        console.error('Sending chat requires a paid Euler plan:', err.message);
    }
}
```

--------------------------------

### fetchIsLive(uniqueId?)

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Method signature and usage example for checking if the streamer is live.

```ts
@HandleError('Failed to retrieve live status from all sources.')
public async fetchIsLive(uniqueId: string = this.uniqueId): Promise<boolean>
```

```ts
if (await connection.fetchIsLive()) {
    console.log('Live!');
}
```

--------------------------------

### GET api-live/user/room/

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Documentation for the fetchRoomInfoFromApiLiveRoute, which retrieves room information from TikTok's API Live endpoint.

```APIDOC
## GET api-live/user/room/

### Description
Fetches room information from TikTok's API Live endpoint. This route is used to retrieve room details based on a user's unique ID.

### Method
GET

### Endpoint
`api-live/user/room/`

### Parameters
#### Query Parameters
- **uniqueId** (string) - Required - The unique identifier of the user.
- **sourceType** (string) - Required - The source type, always set to `'54'`.

### Request Example
```
GET /api-live/user/room/?uniqueId=user123&sourceType=54
```

### Response
#### Success Response (200)
- **statusCode** (number) - The HTTP status code.
- **message** (string) - Optional - A message from the API.
- **data** (object) - Optional - Contains user and liveRoom information.
  - **user** (object) - Optional - User details, including `roomId`.
  - **liveRoom** (object) - Optional - Live room details, including `status` and `roomId`.

#### Response Example
```json
{
  "statusCode": 0,
  "data": {
    "user": {
      "roomId": "1234567890"
    },
    "liveRoom": {
      "status": 2,
      "roomId": "1234567890"
    }
  }
}
```

### Error Handling
- Throws `InvalidResponseError` if `roomData.statusCode` is truthy or if `data.user.roomId` is missing.
```

--------------------------------

### fetchRoomId(uniqueId?)

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/tiktok-live-connection.md

Method signature and usage example for fetching the room ID.

```ts
@HandleError('Failed to retrieve Room ID from all sources.')
public async fetchRoomId(uniqueId: string = this.uniqueId): Promise<string>
```

```ts
const roomId = await connection.fetchRoomId();
```

--------------------------------

### Member Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the MEMBER event, triggered when a new viewer joins the live stream.

```ts
connection.on(WebcastEvent.MEMBER, (data: WebcastMemberMessage) => {
    const uniqueId = data.user?.uniqueId;
    const nickname = data.user?.nickname;
    if (uniqueId) {
        console.log(`User uniqueId: ${uniqueId}`);
    }
    if (nickname) {
        console.log(`User nickname: ${nickname}`);
    }
    console.log(`Viewers: ${data.memberCount}`);
});
```

--------------------------------

### linkMicBattle

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Triggered every time a battle starts.

```ts
connection.on(WebcastEvent.LINK_MIC_BATTLE, (data) => {
    const participants = Object.values(data.anchorInfo)
        .map(info => info.user?.displayId || info.user?.nickName)
        .filter(Boolean);
    console.log(`New Battle ${data.battleId}`);
    if (participants.length) {
        console.log(`Participants: ${participants.join(' VS ')}`);
    }
});
```

--------------------------------

### Control Event Handlers

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Examples of handling various TikTok Live connection control events using the connection.on() method.

```ts
connection.on(
    ControlEvent.CONNECTED,
    (state: TikTokLiveConnectionState) => {
        console.log(`Hurray! Connected to roomId ${state.roomId}`);
        console.log(`Room info loaded: ${Boolean(state.roomInfo)}`);
    }
);
```

```ts
connection.on(ControlEvent.DISCONNECTED, ({ code, reason }) => {
    console.log(`Disconnected :(${code})`);
    if (reason) {
        console.log(`Reason: ${reason}`);
    }
});
```

```ts
connection.on(ControlEvent.RAW_DATA, (messageTypeName, binary) => {
    console.log(messageTypeName, binary);
});
```

```ts
connection.on(ControlEvent.DECODED_DATA, (event: string, decodedData: any, binary: Uint8Array) => {
    console.log(event, decodedData);
});
```

```ts
connection.on(ControlEvent.WEBSOCKET_CONNECTED, (client: TikTokWsClient) => {
    console.log('WebSocket open:', client.open);
});
```

```ts
connection.on(ControlEvent.WEBSOCKET_DATA, (data: Uint8Array) => {
    console.log(`WebSocket bytes: ${data.length}`);
});
```

```ts
connection.on(ControlEvent.ERROR, ({ info, exception }) => {
    console.error('Error!', info, exception);
});
```

--------------------------------

### Chat Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the CHAT event, triggered when a new chat comment arrives.

```ts
connection.on(WebcastEvent.CHAT, (data: WebcastChatMessage) => {
    const uniqueId = data.user?.uniqueId;
    const nickname = data.user?.nickname;
    if (uniqueId) {
        console.log(`User uniqueId: ${uniqueId}`);
    }
    if (nickname) {
        console.log(`User nickname: ${nickname}`);
    }
    console.log(`Comment: ${data.comment}`);
});
```

--------------------------------

### Room User Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the ROOM_USER event, which provides viewer count and top gifter information.

```ts
connection.on(WebcastEvent.ROOM_USER, data => {
    console.log(`Viewer Count: ${data.viewerCount}`);
    const topGifter = data.ranksList[0];
    if (topGifter?.user) {
        const uniqueId = topGifter.user.uniqueId;
        const nickname = topGifter.user.nickname;
        if (uniqueId) {
            console.log(`Top gifter uniqueId: ${uniqueId} (${topGifter.coinCount})`);
        }
        if (nickname) {
            console.log(`Top gifter nickname: ${nickname} (${topGifter.coinCount})`);
        }
    }
});
```

--------------------------------

### Legacy WebcastPushConnection usage example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/legacy.md

Shows how to use the legacy WebcastPushConnection. Import from 'tiktok-live-connector/legacy', create a connection with a username, and listen for legacy events like CHAT and STREAM_END. The CHAT data is flattened with user fields at top level and Longs as strings. connect() returns a promise that should be caught.

```ts
import { WebcastPushConnection, WebcastEvent, ControlEvent } from 'tiktok-live-connector/legacy';

const connection = new WebcastPushConnection('@user');

connection.on(WebcastEvent.CHAT, (data) => {
    // `data` is the FLATTENED shape: user fields at top level, Longs as strings
    console.log(`${data.uniqueId}: ${data.comment}`);
});

connection.on(ControlEvent.STREAM_END, ({ action }) => {
    console.log('Legacy stream end', action);
});

connection.connect().catch(err => console.error(err));
```

--------------------------------

### Proto Utils API Reference

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/proto-utils.md

This page documents several utility functions from the tiktok-live-connector project, including deserializeWebSocketMessage, validateAndNormalizeUniqueId, and createBaseWebcastPushFrame. Each function is described with its source location, purpose, and usage. The code snippets include the function signatures and an example of using validateAndNormalizeUniqueId.

```ts
export async function deserializeWebSocketMessage(binaryMessage: Uint8Array): Promise<DecodedWebcastPushFrame>
```

```ts
export function validateAndNormalizeUniqueId(uniqueId: unknown): string
```

```ts
import { validateAndNormalizeUniqueId } from 'tiktok-live-connector';

validateAndNormalizeUniqueId('https://www.tiktok.com/@user/live'); // => 'user'
validateAndNormalizeUniqueId('@user'); // => 'user'
```

```ts
export function createBaseWebcastPushFrame(overrides: Partial<WebcastPushFrame>): BinaryWriter
```

--------------------------------

### GET @{uniqueId}/live

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Documentation for the fetchRoomInfoFromHtmlRoute, which retrieves room information by scraping the HTML of a user's live page.

```APIDOC
## GET @{uniqueId}/live

### Description
Fetches room information by scraping the HTML of a user's live page. This route extracts the `SIGI_STATE` JSON blob from the page.

### Method
GET

### Endpoint
`@{uniqueId}/live`

### Parameters
#### Path Parameters
- **uniqueId** (string) - Required - The unique identifier of the user.

### Request Example
```
GET /@user123/live
```

### Response
#### Success Response (200)
- **liveRoomUserInfo** (object) - Optional - The live room user information extracted from the `SIGI_STATE` JSON.

#### Response Example
```json
{
  "liveRoomUserInfo": {
    "user": {
      "roomId": "1234567890"
    },
    "liveRoom": {
      "status": 2,
      "roomId": "1234567890"
    }
  }
}
```

### Error Handling
- Throws `InvalidResponseError` when the pattern doesn't match (possibly blocked by TikTok), when the JSON fails to parse (possibly captcha-blocked), or when `LiveRoom` is absent.
```

--------------------------------

### Signed request example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-http-client.md

Shows a signed request with error handling for SignAPIError. The try/catch logs the error reason and message when signing fails. Use for routes that require a signature.

```typescript
// Signed request with error handling
try {
    await client.request({
        host: 'webcast.tiktok.com',
        path: 'webcast/gift/list/',
        signRequest: true,
        responseType: 'json'
    });
} catch (err) {
    if (err instanceof SignAPIError) {
        console.error('Signing failed:', err.reason, err.message);
    }
}
```

--------------------------------

### Gift Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the GIFT event, including streak logic for giftType 1.

```ts
connection.on(WebcastEvent.GIFT, (data: WebcastGiftMessage) => {
    const giftType = data.giftDetails?.giftType;
    const repeatEnd = data.repeatEnd;
    if (giftType === 1 && !repeatEnd) {
        // Streak in progress => show only temporary
        console.log('Gift streak in progress');
    } else {
        // Streak ended or non-streakable gift => process the gift with final repeat_count
        console.log('Gift streak ended or non-streakable gift');
    }
    const uniqueId = data.user?.uniqueId;
    const giftName = data.giftDetails?.giftName;
    if (uniqueId) {
        console.log(`User uniqueId: ${uniqueId}`);
    }
    if (giftName) {
        console.log(`Gift name: ${giftName}`);
    }
    console.log(`Gift ID: ${data.giftId}, repeatCount: ${data.repeatCount}`);
});
```

--------------------------------

### fetchRoomInfoRoute

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Defines the route parameters and response type for fetching room info, and creates a route that GETs webcast/room/info/ with clientParams and room_id. Throws InvalidRequestError when no roomId is available.

```ts
export type RoomInfoRouteParams = WebcastHttpRouteArgs<{ roomId?: string }>;
export type RoomInfoResponse = any;

export const fetchRoomInfoRoute = createRoute<RoomInfoRouteParams, RoomInfoResponse>(
    BaseFetchRoute.FETCH_ROOM_INFO,
    async ({ routeId, webClient, roomId = webClient.roomId }) => { ... }
);
```

--------------------------------

### Override RouteConfig handler example

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Shows how to override a handler in RouteConfig. It saves the original fetchSignedWebSocketFromProvider, replaces it with a wrapper that logs the roomId, and calls the original.

```typescript
import { RouteConfig } from 'tiktok-live-connector';

const original = RouteConfig.fetchSignedWebSocketFromProvider;
RouteConfig.fetchSignedWebSocketFromProvider = async (args) => {
    console.log('signing for room', args.roomId);
    return original(args);
};

```

--------------------------------

### fetchRoomInfoFromHtmlRoute + RoomInfoFromHtmlRouteConfig

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/routes.md

Defines the extraction pattern for the SIGI_STATE JSON blob and the route parameters and response type for fetching room info from HTML. The route GETs @{uniqueId}/live HTML and extracts the SIGI_STATE JSON, returning liveRoomUserInfo. Throws InvalidResponseError when the pattern doesn't match, JSON fails to parse, or LiveRoom is absent.

```ts
export const RoomInfoFromHtmlRouteConfig = {
    extractionPattern: /<script id="SIGI_STATE" type="application\/json">(.*?)<\/script>/
};

export type FetchRoomInfoFromHtmlRouteParams = WebcastHttpRouteArgs<{ uniqueId: string }>;
export type FetchRoomInfoFromHtmlRouteResponse = Record<string, any> & {
    liveRoomUserInfo?: FetchRoomInfoFromApiRouteResponse['data']
};
```

--------------------------------

### Social Event

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Example of handling the SOCIAL event, triggered when someone shares the stream or follows the host.

```ts
connection.on(WebcastEvent.SOCIAL, data => {
    if (data.action) {
        console.log(`Social action: ${data.action}`);
    }
    const uniqueId = data.user?.uniqueId;
    const nickname = data.user?.nickname;
    if (uniqueId) {
        console.log(`User uniqueId: ${uniqueId}`);
    }
    if (nickname) {
        console.log(`User nickname: ${nickname}`);
    }
    if (data.shareType || data.shareTarget) {
        console.log(`Share type: ${data.shareType}, share target: ${data.shareTarget}`);
    }
});
```

--------------------------------

### getJsonObjectFromWebcastApi method signature and usage

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-http-client.md

Performs a GET request to the webcast API. Includes an example of fetching room information.

```ts
public async getJsonObjectFromWebcastApi<T extends Record<string, any>>(
    path: string,
    params: Record<string, string>,
    signRequest: boolean = false,
    options: Partial<WebcastHttpClientRequestParams> = {}
): Promise<T>
```

```ts
// Protobuf path (used internally by fetchRoomInfoRoute)
const roomInfo = await client.getJsonObjectFromWebcastApi(
    'room/info/',
    { ...client.clientParams, room_id: 'room123' },
    false
);
console.log(roomInfo.data.status);
```

--------------------------------

### streamEnd

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/README.md

Triggered when the live stream gets terminated by the host. Will also trigger the disconnected event.

```ts
connection.on(WebcastEvent.STREAM_END, ({ action }: { action: ControlAction }) => {
    if (action === ControlAction.CONTROL_ACTION_STREAM_ENDED) {
        console.log('Stream ended by user');
    }
    if (action === ControlAction.CONTROL_ACTION_STREAM_SUSPENDED) {
        console.log('Stream ended by platform moderator (ban)');
    }
});
```

--------------------------------

### Basic GET request

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/webcast-http-client.md

Basic GET with merged params.

```APIDOC
const res = await client.request({
    host: 'webcast.tiktok.com',
    path: 'webcast/room/info/',
    searchParams: { room_id: '12345' },
    signRequest: false,
    responseType: 'json'
});
```

--------------------------------

### Create a sign-server client and fetch a JWT

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/web-config.md

Demonstrates setting the Euler Stream API key and custom base URL, then instantiating a cached Euler client and creating a JWT.

```ts
import { SignConfig, createEulerClient } from 'tiktok-live-connector';

SignConfig.apiKey = process.env.EULER_API_KEY!;
SignConfig.basePath = 'https://your-custom-sign-server.com';

const apiClient = createEulerClient(); // singleton, cached after first call
const res = await apiClient.authentication.createJWT(122, {
    limits: { minute: 5, hour: 5, day: 5 },
    expireAfter: 60 * 60 * 2
});

```

--------------------------------

### Route Instantiation: Old vs New

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/BREAKING.md

Comparison of old class-based route instantiation and new function-based route usage.

```ts
const route = new FetchRoomInfoFromEulerRoute(webClient);
const info = await route({ roomId });
```

```ts
import { fetchRoomInfoFromEulerRoute } from 'tiktok-live-connector';
const info = await fetchRoomInfoFromEulerRoute({ webClient, apiClient, roomId });
```

--------------------------------

### Events System TypeScript Examples

Source: https://github.com/zerodytrash/tiktok-live-connector/blob/ts-rewrite/_autodocs/api-reference/events.md

TypeScript code examples for the events system: enums for connection state and control events, plus usage of the connection event handlers.

```ts
export enum ConnectState {
    DISCONNECTED = 'DISCONNECTED',
    CONNECTING = 'CONNECTING',
    CONNECTED = 'CONNECTED'
}
```

```ts
export enum ControlEvent {
    CONNECTED = 'connected',
    DISCONNECTED = 'disconnected',
    ERROR = 'error',
    RAW_DATA = 'rawData',
    DECODED_DATA = 'decodedData',
    WEBSOCKET_CONNECTED = 'websocketConnected',
    WEBSOCKET_DATA = 'websocketData',
    ENTER_ROOM = 'enterRoom',
}
```

```ts
connection.on(ControlEvent.CONNECTED, (state) => {
    console.log('Connected to room', state.roomId);
});

connection.on(ControlEvent.ERROR, ({ info, exception }) => {
    console.error(info, exception);
});

connection.on(ControlEvent.DISCONNECTED, ({ code, reason }) => {
    console.log(`Disconnected (${code})${reason ? ': ' + reason : ''}`);
});
```
Tokens:
Raw