@tiktool/live 2.6.7 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +25 -323
  2. package/dist/index.d.mts +81 -707
  3. package/dist/index.d.ts +81 -707
  4. package/dist/index.js +335 -978
  5. package/dist/index.js.map +1 -1
  6. package/dist/index.mjs +334 -972
  7. package/dist/index.mjs.map +1 -1
  8. package/package.json +10 -17
package/README.md CHANGED
@@ -1,18 +1,19 @@
1
- # TikTok LIVE API — Node.js & TypeScript
1
+ <div align="center">
2
2
 
3
- ### The managed TikTok Live Connector — receive chat, gifts, viewers, battles & 18+ events from any TikTok LIVE stream via WebSocket.
3
+ # @tiktool/live
4
+
5
+ ### Connect to any TikTok LIVE stream in 4 lines of code.
4
6
 
5
7
  [![npm version](https://img.shields.io/npm/v/@tiktool/live?color=%23ff0050&label=npm&logo=npm)](https://www.npmjs.com/package/@tiktool/live)
6
- [![npm downloads](https://img.shields.io/npm/dm/@tiktool/live)](https://www.npmjs.com/package/@tiktool/live)
7
8
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
9
  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?logo=node.js)](https://nodejs.org)
9
10
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?logo=typescript)](https://www.typescriptlang.org)
10
11
 
11
- > **99.9% uptime** — Never breaks when TikTok updates. No protobuf, no reverse engineering, no maintenance. Also available for [Python](https://pypi.org/project/tiktok-live-api/), [Java, Go, C#, and any language via WebSocket](https://tik.tools/docs).
12
+ Real-time chat, gifts, viewers, battles, follows & 18+ event types from any TikTok livestream.
12
13
 
13
- **🎤 NEW:** [Real-Time Live Captions](#-real-time-live-captions) — AI-powered speech-to-text transcription & translation with speaker diarization. **No other TikTok library offers this.**
14
+ [Quick Start](#-quick-start) · [Events](#-events) · [API](#-api-reference) · [Rate Limits](#-rate-limits) · [Get API Key](https://tik.tools)
14
15
 
15
- [Try It Now](#-try-it-now--5-minute-live-demo) · [Events](#-events) · [Live Captions](#-real-time-live-captions) · [API](#-api-reference) · [Rate Limits](#-rate-limits) · [Get API Key](https://tik.tools)
16
+ </div>
16
17
 
17
18
  ---
18
19
 
@@ -22,81 +23,24 @@
22
23
  npm install @tiktool/live
23
24
  ```
24
25
 
25
- Get your free API key at [tik.tools](https://tik.tools) — then run the demo below.
26
-
27
- ## 🚀 Try It Now — 5-Minute Live Demo
28
-
29
- Copy-paste this into a file and run it. Connects to a live TikTok stream, prints every event for 5 minutes, then exits. Works on the free Sandbox tier.
30
-
31
- **Save as `demo.mjs` and run with `node demo.mjs`:**
26
+ Get your free API key at [tik.tools](https://tik.tools)
32
27
 
33
- ```javascript
34
- // demo.mjs — TikTok LIVE in 5 minutes
35
- // npm install @tiktool/live
28
+ ```typescript
36
29
  import { TikTokLive } from '@tiktool/live';
37
30
 
38
- const API_KEY = 'YOUR_API_KEY'; // Get free key → https://tik.tools
39
- const LIVE_USERNAME = 'tv_asahi_news'; // Any live TikTok username
40
-
41
- const live = new TikTokLive({ uniqueId: LIVE_USERNAME, apiKey: API_KEY });
42
- let events = 0;
43
-
44
- live.on('chat', e => { events++; console.log(`💬 ${e.user.uniqueId}: ${e.comment}`); });
45
- live.on('gift', e => { events++; console.log(`🎁 ${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount}💎)`); });
46
- live.on('like', e => { events++; console.log(`❤️ ${e.user.uniqueId} liked × ${e.likeCount}`); });
47
- live.on('member', e => { events++; console.log(`👋 ${e.user.uniqueId} joined`); });
48
- live.on('follow', e => { events++; console.log(`➕ ${e.user.uniqueId} followed`); });
49
- live.on('share', e => { events++; console.log(`🔗 ${e.user.uniqueId} shared`); });
50
- live.on('roomUserSeq', e => { events++; console.log(`👀 Viewers: ${e.viewerCount}`); });
51
- live.on('subscribe', e => { events++; console.log(`⭐ ${e.user.uniqueId} subscribed`); });
52
- live.on('battle', e => { events++; console.log(`⚔️ Battle update`); });
31
+ const live = new TikTokLive({
32
+ uniqueId: 'tv_asahi_news',
33
+ apiKey: 'YOUR_API_KEY',
34
+ });
53
35
 
54
- live.on('connected', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
55
- live.on('disconnected', () => console.log(`\n📊 Done! Received ${events} events.\n`));
36
+ live.on('chat', e => console.log(`${e.user.uniqueId}: ${e.comment}`));
37
+ live.on('gift', e => console.log(`${e.user.uniqueId} sent ${e.giftName} (${e.diamondCount} diamonds)`));
38
+ live.on('member', e => console.log(`${e.user.uniqueId} joined`));
39
+ live.on('roomUserSeq', e => console.log(`Viewers: ${e.viewerCount}`));
56
40
 
57
41
  await live.connect();
58
- setTimeout(() => { live.disconnect(); }, 300_000);
59
- ```
60
-
61
- <details>
62
- <summary><strong>🔌 Pure WebSocket version (no SDK, any language)</strong></summary>
63
-
64
- Works with any WebSocket client. No dependencies except `ws` (Node.js) or your language's WebSocket library.
65
-
66
- ```javascript
67
- // ws-demo.mjs — Pure WebSocket, zero SDK
68
- // npm install ws
69
- import WebSocket from 'ws';
70
-
71
- const API_KEY = 'YOUR_API_KEY';
72
- const LIVE_USERNAME = 'tv_asahi_news';
73
-
74
- const ws = new WebSocket(`wss://api.tik.tools?uniqueId=${LIVE_USERNAME}&apiKey=${API_KEY}`);
75
- let events = 0;
76
-
77
- ws.on('open', () => console.log(`\n✅ Connected to @${LIVE_USERNAME} — listening for 5 min...\n`));
78
- ws.on('message', (raw) => {
79
- const msg = JSON.parse(raw);
80
- events++;
81
- const d = msg.data || {};
82
- const user = d.user?.uniqueId || d.uniqueId || '';
83
- switch (msg.event) {
84
- case 'chat': console.log(`💬 ${user}: ${d.comment}`); break;
85
- case 'gift': console.log(`🎁 ${user} sent ${d.giftName} (${d.diamondCount}💎)`); break;
86
- case 'like': console.log(`❤️ ${user} liked × ${d.likeCount}`); break;
87
- case 'member': console.log(`👋 ${user} joined`); break;
88
- case 'roomUserSeq': console.log(`👀 Viewers: ${d.viewerCount}`); break;
89
- case 'roomInfo': console.log(`📡 Room: ${msg.roomId}`); break;
90
- default: console.log(`📦 ${msg.event}`); break;
91
- }
92
- });
93
- ws.on('close', () => console.log(`\n📊 Done! Received ${events} events.\n`));
94
-
95
- setTimeout(() => ws.close(), 300_000);
96
42
  ```
97
43
 
98
- </details>
99
-
100
44
  ---
101
45
 
102
46
  ## How It Works
@@ -104,7 +48,7 @@ setTimeout(() => ws.close(), 300_000);
104
48
  ```
105
49
  Your App tik.tools TikTok
106
50
  +-----------+ +--------------+ +--------------+
107
- | -+-- sign_url --> Signs URL | | |
51
+ | -+-- sign_url --> Signs URL | | |
108
52
  | Your <-+-- X-Bogus --| with params | | TikTok |
109
53
  | Code | | | | WebSocket |
110
54
  | -+------------ Connect directly ---------->| Server |
@@ -114,7 +58,7 @@ setTimeout(() => ws.close(), 300_000);
114
58
  with our server YOUR IP
115
59
  ```
116
60
 
117
- - Your app connects directly to TikTok — from your IP or through a proxy
61
+ - Your app connects directly to TikTok from your IP address
118
62
  - The sign server only generates cryptographic signatures (requires API key)
119
63
  - TikTok never sees the sign server
120
64
  - Built-in protobuf parser, no external dependencies
@@ -170,110 +114,6 @@ live.on('event', (event) => {
170
114
 
171
115
  ---
172
116
 
173
- ## 🎤 Real-Time Live Captions
174
-
175
- AI-powered speech-to-text transcription and translation for TikTok LIVE streams. Features include:
176
-
177
- - **Auto-detect language** — Automatically identifies the spoken language
178
- - **Speaker diarization** — Identifies individual speakers in multi-person streams
179
- - **Real-time translation** — Translate to any supported language with sub-second latency
180
- - **Partial + final results** — Get streaming partial transcripts and confirmed final text
181
- - **Credit-based billing** — 1 credit = 1 minute of transcription/translation
182
-
183
- ### Quick Start
184
-
185
- ```typescript
186
- import { TikTokCaptions } from '@tiktool/live';
187
-
188
- const captions = new TikTokCaptions({
189
- uniqueId: 'streamer_name',
190
- apiKey: 'YOUR_API_KEY',
191
- translate: 'en',
192
- diarization: true,
193
- });
194
-
195
- captions.on('caption', (event) => {
196
- const prefix = event.speaker ? `[${event.speaker}] ` : '';
197
- console.log(`${prefix}${event.text}${event.isFinal ? ' ✓' : '...'}`);
198
- });
199
-
200
- captions.on('translation', (event) => {
201
- console.log(` → ${event.text}`);
202
- });
203
-
204
- captions.on('credits', (event) => {
205
- console.log(`${event.remaining}/${event.total} min remaining`);
206
- });
207
-
208
- captions.on('credits_low', (event) => {
209
- console.warn(`Low credits! ${event.remaining} min left`);
210
- });
211
-
212
- await captions.start();
213
- ```
214
-
215
- ### `new TikTokCaptions(options)`
216
-
217
- | Option | Type | Default | Description |
218
- |--------|------|---------|-------------|
219
- | `uniqueId` | `string` | — | TikTok username (without @) |
220
- | `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
221
- | `language` | `string` | `''` | Source language hint (empty = auto-detect) |
222
- | `translate` | `string` | `''` | Target translation language (e.g. `'en'`, `'es'`, `'fr'`) |
223
- | `diarization` | `boolean` | `true` | Enable speaker identification |
224
- | `maxDurationMinutes` | `number` | `60` | Auto-disconnect after N minutes (max: 300) |
225
- | `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
226
- | `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
227
- | `debug` | `boolean` | `false` | Debug logging |
228
-
229
- ### Caption Events
230
-
231
- | Event | Callback | Description |
232
- |-------|----------|-------------|
233
- | `caption` | `(data: CaptionData) => void` | Real-time transcription (partial + final) |
234
- | `translation` | `(data: TranslationData) => void` | Translated text |
235
- | `status` | `(data: CaptionStatus) => void` | Session status changes |
236
- | `credits` | `(data: CaptionCredits) => void` | Credit balance updates |
237
- | `credits_low` | `(data) => void` | Low credit warning (≤20%) |
238
- | `connected` | `() => void` | WebSocket connected |
239
- | `disconnected` | `(code, reason) => void` | Disconnected |
240
- | `error` | `(data: CaptionError) => void` | Error |
241
-
242
- ### Methods
243
-
244
- | Method | Returns | Description |
245
- |--------|---------|-------------|
246
- | `start()` | `Promise<void>` | Connect and start transcription |
247
- | `stop()` | `void` | Stop and disconnect |
248
- | `setLanguage(lang)` | `void` | Switch translation language on-the-fly |
249
- | `getCredits()` | `void` | Request credit balance update |
250
- | `connected` | `boolean` | Connection status |
251
- | `language` | `string` | Current target language |
252
-
253
- ### Raw WebSocket
254
-
255
- You can also connect directly via WebSocket without the SDK:
256
-
257
- ```
258
- wss://api.tik.tools/captions?uniqueId=USERNAME&apiKey=YOUR_KEY&translate=en&diarization=true&max_duration_minutes=120
259
- ```
260
-
261
- ### Caption Credits
262
-
263
- Caption credits are **pay-as-you-go add-ons** — no credits are included in the base subscription. Requires Basic tier or higher.
264
-
265
- | Package | Credits | Price | Per Credit |
266
- |---------|---------|-------|------------|
267
- | **Starter** | 1,000 min | $10 | $0.010/min |
268
- | **Creator** | 5,000 min | $35 | $0.007/min |
269
- | **Agency** | 20,000 min | $100 | $0.005/min |
270
-
271
- > **1 credit = 1 minute** of audio transcribed/translated into one language. If translating to 2 languages simultaneously, it burns 2 credits per minute.
272
-
273
- Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see real-time transcription and translation on actual TikTok LIVE streams.
274
-
275
- ---
276
-
277
117
  ## API Reference
278
118
 
279
119
  ### `new TikTokLive(options)`
@@ -283,15 +123,10 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
283
123
  | `uniqueId` | `string` | — | TikTok username (without @) |
284
124
  | `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
285
125
  | `signServerUrl` | `string` | `https://api.tik.tools` | Sign server URL |
286
- | `agent` | `http.Agent` | — | HTTP agent for proxying connections |
287
126
  | `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
288
127
  | `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
289
128
  | `heartbeatInterval` | `number` | `10000` | Heartbeat interval (ms) |
290
129
  | `debug` | `boolean` | `false` | Debug logging |
291
- | `sessionId` | `string` | — | TikTok `sessionid` cookie for authenticated features (ranklist, chat) |
292
- | `ttTargetIdc` | `string` | — | TikTok target IDC region (e.g. `useast5`). Required with `sessionId` |
293
- | `roomId` | `string` | — | Pre-known room ID — skips HTML page scrape |
294
- | `ttwid` | `string` | — | Pre-fetched `ttwid` cookie. With `roomId`, skips all HTTP requests |
295
130
 
296
131
  ### Methods
297
132
 
@@ -299,12 +134,9 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
299
134
  |--------|---------|-------------|
300
135
  | `connect()` | `Promise<void>` | Connect to livestream |
301
136
  | `disconnect()` | `void` | Disconnect |
302
- | `setSession(sessionId, ttTargetIdc?)` | `void` | Update session at runtime |
303
- | `buildSessionCookieHeader()` | `string \| undefined` | Build cookie header for auth API requests |
304
137
  | `connected` | `boolean` | Connection status |
305
138
  | `eventCount` | `number` | Total events received |
306
139
  | `roomId` | `string` | Current room ID |
307
- | `sessionId` | `string \| undefined` | Current session ID |
308
140
 
309
141
  ---
310
142
 
@@ -312,117 +144,13 @@ Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see re
312
144
 
313
145
  All API requests require an API key. Get yours at [tik.tools](https://tik.tools).
314
146
 
315
- | Tier | Requests/Day | Rate Limit | WS Connections | WS Duration | WS Connects | Bulk Check | CAPTCHA | Feed Discovery | Price |
316
- |------|-------------|-----------|----------------|-------------|-------------|------------|---------|----------------|-------|
317
- | **Sandbox** | 50 | 5/min | 1 | 5 min | 10/hr · 30/day | 1 | ✕ | ✕ | Free |
318
- | **Basic** | 10,000 | 60/min | 3 | 8 hours | 60/hr · 200/day | 10 | ✕ | ✕ | From $7/wk |
319
- | **Pro** | 75,000 | Unlimited | 50 | 8 hours | Unlimited | 50 | 50/day | 100/day | From $15/wk |
320
- | **Ultra** | 300,000 | Unlimited | 500 | 8 hours | Unlimited | 500 | 500/day | 2,000/day | From $45/wk |
147
+ | Tier | Rate Limit | Endpoints | Price |
148
+ |------|-----------|-----------|-------|
149
+ | **Free** | 5/min | `sign_url`, `check_alive` | Free |
150
+ | **Basic** | 30/min | + `fetch`, `room_info`, `bulk_live_check`, WS relay | Free (with key) |
151
+ | **Pro** | 120/min | + `room_video`, all endpoints | Coming soon |
321
152
 
322
- **Caption Credits** are available as pay-as-you-go add-ons (1 credit = 1 min of audio in 1 language):
323
- - **Starter**: 1,000 credits — $10
324
- - **Creator**: 5,000 credits — $35
325
- - **Agency**: 20,000 credits — $100
326
-
327
- The SDK calls the sign server **once per connection**, then stays connected via WebSocket. Sandbox is for API verification only — use Basic or higher for production.
328
-
329
- ---
330
-
331
- ## 🔍 Feed Discovery
332
-
333
- Discover recommended TikTok LIVE streams. **Requires Pro or Ultra tier.**
334
-
335
- ```typescript
336
- import { getLiveFeed, fetchFeed } from '@tiktool/live';
337
-
338
- // Option 1: Two-step (sign-and-return)
339
- const signed = await getLiveFeed({
340
- apiKey: 'YOUR_PRO_KEY',
341
- sessionId: 'YOUR_TIKTOK_SESSIONID',
342
- region: 'US',
343
- count: 10,
344
- });
345
-
346
- const resp = await fetch(signed.signed_url, {
347
- headers: { ...signed.headers, Cookie: signed.cookies || '' },
348
- });
349
- const data = await resp.json();
350
-
351
- // Option 2: One-step convenience
352
- const feed = await fetchFeed({
353
- apiKey: 'YOUR_PRO_KEY',
354
- sessionId: 'YOUR_TIKTOK_SESSIONID',
355
- count: 10,
356
- });
357
-
358
- for (const entry of feed.data || []) {
359
- const room = entry.data;
360
- console.log(`🔴 @${room.owner.display_id}: "${room.title}" — ${room.user_count} viewers`);
361
- }
362
- ```
363
-
364
- ### Channel Types
365
-
366
- | Value | Channel |
367
- |-------|--------|
368
- | `"87"` | Recommended (default) |
369
- | `"86"` | Suggested |
370
- | `"42"` | Following |
371
- | `"1111006"` | Gaming |
372
-
373
- ### Pagination
374
-
375
- Use `maxTime` from the previous response to load more:
376
-
377
- ```typescript
378
- const page2 = await getLiveFeed({
379
- apiKey: 'YOUR_PRO_KEY',
380
- sessionId: 'YOUR_TIKTOK_SESSIONID',
381
- maxTime: data.extra?.max_time, // cursor from previous response
382
- });
383
- ```
384
-
385
- ---
386
-
387
- ## 🏆 Regional Leaderboard
388
-
389
- Get daily, hourly, popular, or league LIVE rankings for any streamer. **Requires Pro or Ultra tier.**
390
-
391
- This endpoint uses a **two-step sign-and-return pattern** because TikTok sessions are IP-bound:
392
-
393
- 1. Call `getRegionalRanklist()` to get a signed URL from the server
394
- 2. POST the signed URL from **your own IP** with your TikTok session cookie
395
-
396
- ```typescript
397
- import { getRegionalRanklist } from '@tiktool/live';
398
-
399
- const signed = await getRegionalRanklist({
400
- apiKey: 'YOUR_PRO_KEY',
401
- roomId: '7607695933891218198',
402
- anchorId: '7444599004337652758',
403
- rankType: '8',
404
- });
405
-
406
- const resp = await fetch(signed.signed_url, {
407
- method: signed.method,
408
- headers: { ...signed.headers, Cookie: `sessionid=YOUR_SID; ${signed.cookies}` },
409
- body: signed.body,
410
- });
411
-
412
- const { data } = await resp.json();
413
- data.rank_view.ranks.forEach((r: any, i: number) =>
414
- console.log(`${i+1}. ${r.user.nickname} — ${r.score} pts`)
415
- );
416
- ```
417
-
418
- ### Rank Types
419
-
420
- | Value | Period |
421
- |-------|--------|
422
- | `"1"` | Hourly |
423
- | `"8"` | Daily (default) |
424
- | `"15"` | Popular LIVE |
425
- | `"16"` | League |
153
+ The SDK calls the sign server **once per connection**, then stays connected via WebSocket. A free key is sufficient for most use cases.
426
154
 
427
155
  ---
428
156
 
@@ -477,32 +205,6 @@ console.log('Forwarding events to ws://localhost:8080');
477
205
 
478
206
  ---
479
207
 
480
- ## 🌐 Proxy Support
481
-
482
- Route all connections through an HTTP proxy. Works with any HTTPS proxy provider (residential, datacenter, etc.).
483
-
484
- ```typescript
485
- import { TikTokLive } from '@tiktool/live';
486
- import { HttpsProxyAgent } from 'https-proxy-agent';
487
-
488
- const agent = new HttpsProxyAgent('http://user:pass@proxy.example.com:1234');
489
-
490
- const live = new TikTokLive({
491
- uniqueId: 'streamer_name',
492
- apiKey: 'YOUR_API_KEY',
493
- agent,
494
- });
495
-
496
- await live.connect();
497
- ```
498
-
499
- Both the initial page request and the WebSocket connection are routed through the proxy. This is useful for:
500
- - Running multiple concurrent connections from different IPs
501
- - Avoiding rate limits
502
- - Geo-targeting specific regions
503
-
504
- ---
505
-
506
208
  ## TypeScript
507
209
 
508
210
  Full TypeScript support with type inference: