Loading repository data…
zerodytrash / repository
Node.js library to receive live stream events (comments, gifts, etc.) in realtime from TikTok LIVE.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
The #1 TikTok LIVE API Client for Node.JS (Unofficial, Unaffiliated with ByteDance Ltd.)
A Node.js library to receive live stream events such as comments and gifts in realtime
from TikTok LIVE by connecting to TikTok's internal Webcast push service.
This package includes a wrapper that connects to the Webcast service using just the username (@uniqueId).
This allows you to connect to your own live chat as well as the live chat of other streamers. No credentials are
required. Besides Chat Comments, other events such
as Members Joining, Gifts, Subscriptions, Viewers, Follows, Shares, Questions, Likes
and Battles can be tracked.
[!NOTE] This is not a production-ready API. It is a reverse engineering project. Use the WebSocket API for production.
[!TIP] An example project is available at https://tiktok-chat-reader.zerody.one/ - View Source
npm i tiktok-live-connector
// Username of someone who is currently live
import { TikTokLiveConnection, WebcastEvent } from 'tiktok-live-connector';
const tiktokUsername = 'officialgeilegisela';
// Create a new wrapper object and pass the username
const connection = new TikTokLiveConnection(tiktokUsername);
// Connect to the chat (await can be used as well)
connection.connect().then(state => {
console.info(`Connected to roomId ${state.roomId}`);
}).catch(err => {
console.error('Failed to connect', err);
});
// Define the events that you want to handle
// In this case we listen to chat messages (comments)
connection.on(WebcastEvent.CHAT, data => {
console.log(`${data.user.uniqueId} (userId:${data.user.uniqueId}) writes: ${data.comment}`);
});
// And here we receive gifts sent to the streamer
connection.on(WebcastEvent.GIFT, data => {
console.log(`${data.user.uniqueId} (userId:${data.user.userId}) sends ${data.giftId}`);
});
// ...and more events described in the documentation below
To create a new TikTokLiveConnection object the following parameters can be specified.
TikTokLiveConnection(uniqueId, [options])
| Param Name | Required | Description |
|---|---|---|
uniqueId | Yes | The unique username of the broadcaster. You can find this name in the URL.Example: https://www.tiktok.com/@officialgeilegisela/live becomes officialgeilegisela. The leading @ and the full URL form are also accepted. |
options | No | Optional connection properties. Defaults are applied when a value is not specified.signApiKey (default: undefined)Euler Stream API key. When provided, it is written to the global SignConfig.apiKey before the underlying Euler client is created. Ignored when eulerApiInstance is passed.eulerApiInstance (default: undefined)Pre-built EulerStreamApiClient to use for all sign-server traffic. Takes precedence over signApiKey.session (default: undefined)Authenticated session bundle. Pass session.cookie to seed the cookie jar with sessionid and tt-target-idc, and/or session.oAuthToken to send an OAuth token to the sign server. Required when authenticateWs or useMobile is true. See Authenticated Connection.authenticateWs (default: false)Forward the session cookies or OAuth token to the sign server so the WebSocket is authenticated. Disabled by default since signing is done by a third-party service; enabling it sends your session credentials to that service.useMobile (default: false)Use the mobile WebSocket flow. Implies authenticateWs: true and requires session.cookie.processInitialData (default: true)Decode and emit the message batch returned in the initial sign response (recent chat history etc.).fetchRoomInfoOnConnect (default: true)Fetch room info during connect. If the streamer is not currently live the connect rejects with UserOfflineError. The fetched info is stored on connection.roomInfo and is also accessible via fetchRoomInfo().enableExtendedGiftInfo (default: false)Fetch the room gift list during connect so events carry an field with name, cost, and image data. (default: randomized)Pre-built presets. Defaults to a freshly randomized set from . (default: )Extra options forwarded to the underlying HTTP client (proxy agent, timeout, etc.). Headers and search params from this object are merged with the defaults; transport-only fields are passed through. See . (default: )Extra options forwarded to the underlying WebSocket client. See . (default: )Partial overrides for the resolved used by the HTTP client. Use this to customize , , etc. (default: )Partial overrides for the resolved used by the WebSocket client. Use this to customize or . |
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
}
});
| Method Name | Description |
|---|---|
connect([roomId]) | Connects to the live stream chat. Returns a Promise<TikTokLiveConnectionState> that resolves when the WebSocket is open and the room has been entered. Pass an explicit roomId to skip room-id resolution. |
disconnect() | Closes the WebSocket and waits for the close event before resolving. Safe to call even when not connected. |
sendMessage(content, [roomId]) | Sends a chat message to the connected room (or to roomId if provided). Requires signApiKey and an authenticated session. See Send Messages. |
fetchRoomId([uniqueId]) | Resolves the room id for the configured username (or for uniqueId if provided). Tries HTML scrape, then the TikTok API, then Euler Stream as a fallback. |
fetchIsLive([uniqueId]) | Resolves whether the user is currently live. Same fallback chain as fetchRoomId. |
waitUntilLive([seconds], [abortSignal]) | Polls fetchIsLive every seconds seconds (minimum 30) until the streamer goes live. Reject via abortSignal to cancel. |
fetchRoomInfo([roomId]) | Fetches room info from TikTok's webcast API. Caches the result on connection.roomInfo. Callable without an active connection. See Retrieve Room Info. |
fetchAvailableGifts() | Fetches the room gift list. Caches on connection.availableGifts. Callable without an active connection. See Retrieve Available Gifts. |
| Property Name | Description |
|---|---|
webClient: WebcastHttpClient | The HTTP client used to talk to TikTok's web and webcast APIs. Holds the cookie jar, the merged client params, and the merged client headers. |
apiClient: EulerStreamApiClient | The Euler Stream API client used for sign-server traffic and other premium endpoints. Equivalent to webClient.apiClient. |
wsClient: WebcastWebSocketClient | null | The active WebSocket client. null until the connection is established and after disconnect. |
options: TikTokLiveConnectionMutableOptions | The subset of options retained on the instance (processInitialData, fetchRoomInfoOnConnect, enableExtendedGiftInfo, authenticateWs, useMobile). |
roomInfo: RoomInfo | null | The room info object cached from the most recent fetchRoomInfo() call (or from connect, when fetchRoomInfoOnConnect is true). |
availableGifts: RoomGiftInfo | null | The cached gift list. Populated when enableExtendedGiftInfo is true or after manually calling fetchAvailableGifts(). |
isConnecting: boolean | True while connect() is in flight. |
isConnected: boolean | True after a successful connect, until the WebSocket closes. |
clientParams: Record<string, string> | Live URI parameters sent with every webClient request. Mutating this changes outgoing query strings. |
roomId: string | The currently bound room id. Empty string until connect resolves or fetchRoomId() is called. |
state: TikTokLiveConnectionState | Snapshot containing isConnected, isConnecting, roomId, roomInfo, and availableGifts. |
WebSocket URL signing is delegated to the Euler Stream sign server via the
@eulerstream/euler-api-sdk package. Configuration is held on the
mutable SignConfig singleton.
For most users, passing signApiKey to the TikTokLiveConnection constructor is enough. It writes the key to
SignConfig.apiKey before the underlying Euler client is built.
For advanced cases (custom sign-server URL, extra headers, JWT auth), mutate SignConfig directly before
constructing your first connection:
Selected from shared topics, language and repository description—not editorial ratings.
moegirlwiki /
The library provides the out of box accessing to MediaWiki API in both browsers & Node.js, and the syntax is very similar to vanilla `new mw.Api()`. TypeScript definition included~
63/100 healthWebcastGiftMessageextendedGiftInfoclientPresets{ device, screen, location }getRandomPresets()webClientOptions{}wsClientOptions{}webConfigOverrides{}WebcastWebConfigDefaultsDEFAULT_HTTP_CLIENT_PARAMSDEFAULT_HTTP_CLIENT_HEADERSwsConfigOverrides{}WebcastWebSocketConfigDefaultsDEFAULT_WS_CLIENT_PARAMSDEFAULT_WS_CLIENT_HEADERS