Package Exports
- @tiktool/live
Readme
@tiktool/live
Connect to any TikTok LIVE stream in 4 lines of code.
Real-time chat, gifts, viewers, battles, follows & 18+ event types from any TikTok livestream.
Quick Start · Events · API · Rate Limits · Get API Key
⚡ Quick Start
npm install @tiktool/liveGet your free API key at tik.tools
import { TikTokLive } from '@tiktool/live';
const live = new TikTokLive({
uniqueId: 'tv_asahi_news',
apiKey: 'YOUR_API_KEY',
});
live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`));
live.on('member', e => console.log(`${e.user.uniqueId} joined`));
live.on('roomUserSeq', e => console.log(`Viewers: ${e.viewerCount}`));
await live.connect();How It Works
Your App tik.tools TikTok
+-----------+ +--------------+ +--------------+
| -+-- sign_url --> Signs URL | | |
| Your <-+-- X-Bogus --| with params | | TikTok |
| Code | | | | WebSocket |
| -+------------ Connect directly ---------->| Server |
| <-+------------ Live events (protobuf) <---| |
+-----------+ +--------------+ +--------------+
^ Only interaction ^ Direct from
with our server YOUR IP- Your app connects directly to TikTok from your IP address
- The sign server only generates cryptographic signatures (requires API key)
- TikTok never sees the sign server
- Built-in protobuf parser, no external dependencies
Events
Listening
live.on('chat', (event) => {
event.user.uniqueId // string
event.comment // string
});
live.on('event', (event) => {
console.log(event.type, event);
});Reference
| Event | Type | Description | Fields |
|---|---|---|---|
chat |
ChatEvent |
Chat message | user, comment |
member |
MemberEvent |
User joined | user, action |
like |
LikeEvent |
User liked | user, likeCount, totalLikes |
gift |
GiftEvent |
Gift sent | user, giftName, diamondCount, repeatCount, combo |
social |
SocialEvent |
Follow / Share | user, action |
roomUserSeq |
RoomUserSeqEvent |
Viewer count | viewerCount, totalViewers |
battle |
BattleEvent |
Link Mic battle | status |
battleArmies |
BattleArmiesEvent |
Battle teams | — |
subscribe |
SubscribeEvent |
New subscriber | user, subMonth |
emoteChat |
EmoteChatEvent |
Emote in chat | user, emoteId |
envelope |
EnvelopeEvent |
Treasure chest | diamondCount |
question |
QuestionEvent |
Q&A question | user, questionText |
control |
ControlEvent |
Stream control | action (3 = ended) |
room |
RoomEvent |
Room status | status |
liveIntro |
LiveIntroEvent |
Stream intro | title |
rankUpdate |
RankUpdateEvent |
Rank update | rankType |
linkMic |
LinkMicEvent |
Link Mic | action |
unknown |
UnknownEvent |
Unrecognized | method |
Connection Events
| Event | Callback | Description |
|---|---|---|
connected |
() => void |
Connected to stream |
disconnected |
(code, reason) => void |
Disconnected |
roomInfo |
(info: RoomInfo) => void |
Room info |
error |
(error: Error) => void |
Error |
API Reference
new TikTokLive(options)
| Option | Type | Default | Description |
|---|---|---|---|
uniqueId |
string |
— | TikTok username (without @) |
apiKey |
string |
— | Required. API key from tik.tools |
signServerUrl |
string |
https://api.tik.tools |
Sign server URL |
autoReconnect |
boolean |
true |
Auto-reconnect on disconnect |
maxReconnectAttempts |
number |
5 |
Max reconnect attempts |
heartbeatInterval |
number |
10000 |
Heartbeat interval (ms) |
debug |
boolean |
false |
Debug logging |
Methods
| Method | Returns | Description |
|---|---|---|
connect() |
Promise<void> |
Connect to livestream |
disconnect() |
void |
Disconnect |
connected |
boolean |
Connection status |
eventCount |
number |
Total events received |
roomId |
string |
Current room ID |
Rate Limits
All API requests require an API key. Get yours at tik.tools.
| Tier | Rate Limit | Endpoints | Price |
|---|---|---|---|
| Free | 5/min | sign_url, check_alive |
Free |
| Basic | 30/min | + fetch, room_info, bulk_live_check, WS relay |
Free (with key) |
| Pro | 120/min | + room_video, all endpoints |
Coming soon |
The SDK calls the sign server once per connection, then stays connected via WebSocket. A free key is sufficient for most use cases.
Examples
Chat Bot
import { TikTokLive } from '@tiktool/live';
const live = new TikTokLive({
uniqueId: 'streamer_name',
apiKey: 'YOUR_API_KEY',
});
live.on('chat', (e) => {
if (e.comment.toLowerCase() === '!hello') {
console.log(`Hello, ${e.user.nickname}!`);
}
});
live.on('gift', (e) => {
if (e.repeatEnd) {
console.log(`${e.user.uniqueId} sent ${e.repeatCount}x ${e.giftName} (${e.diamondCount * e.repeatCount} diamonds)`);
}
});
await live.connect();OBS Overlay
import { TikTokLive } from '@tiktool/live';
import { WebSocketServer } from 'ws';
const wss = new WebSocketServer({ port: 8080 });
const live = new TikTokLive({
uniqueId: 'streamer_name',
apiKey: 'YOUR_API_KEY',
});
live.on('event', (event) => {
for (const client of wss.clients) {
client.send(JSON.stringify(event));
}
});
await live.connect();
console.log('Forwarding events to ws://localhost:8080');TypeScript
Full TypeScript support with type inference:
import { TikTokLive, ChatEvent, GiftEvent } from '@tiktool/live';
const live = new TikTokLive({
uniqueId: 'username',
apiKey: 'YOUR_API_KEY',
});
live.on('chat', (event: ChatEvent) => {
const username: string = event.user.uniqueId;
const message: string = event.comment;
});
live.on('gift', (event: GiftEvent) => {
const diamonds: number = event.diamondCount;
const isCombo: boolean = event.combo;
});License
MIT © tiktool