@tiktool/live 2.6.0 → 2.6.2
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.
- package/README.md +124 -19
- package/dist/index.d.mts +178 -1
- package/dist/index.d.ts +178 -1
- package/dist/index.js +205 -1
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +204 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +13 -3
package/README.md
CHANGED
|
@@ -9,7 +9,9 @@
|
|
|
9
9
|
|
|
10
10
|
Real-time chat, gifts, viewers, battles, follows & 18+ event types from any TikTok livestream.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
**NEW:** 🎤 [Real-Time Live Captions](#-real-time-live-captions) — AI-powered speech-to-text transcription & translation with speaker diarization and sub-second latency.
|
|
13
|
+
|
|
14
|
+
[Quick Start](#-quick-start) · [Events](#-events) · [Live Captions](#-real-time-live-captions) · [API](#-api-reference) · [Rate Limits](#-rate-limits) · [Get API Key](https://tik.tools)
|
|
13
15
|
|
|
14
16
|
---
|
|
15
17
|
|
|
@@ -44,7 +46,7 @@ await live.connect();
|
|
|
44
46
|
```
|
|
45
47
|
Your App tik.tools TikTok
|
|
46
48
|
+-----------+ +--------------+ +--------------+
|
|
47
|
-
| -+-- sign_url -->
|
|
49
|
+
| -+-- sign_url --> Signs URL | | |
|
|
48
50
|
| Your <-+-- X-Bogus --| with params | | TikTok |
|
|
49
51
|
| Code | | | | WebSocket |
|
|
50
52
|
| -+------------ Connect directly ---------->| Server |
|
|
@@ -110,6 +112,119 @@ live.on('event', (event) => {
|
|
|
110
112
|
|
|
111
113
|
---
|
|
112
114
|
|
|
115
|
+
## 🎤 Real-Time Live Captions
|
|
116
|
+
|
|
117
|
+
AI-powered speech-to-text transcription and translation for TikTok LIVE streams. Features include:
|
|
118
|
+
|
|
119
|
+
- **Auto-detect language** — Automatically identifies the spoken language
|
|
120
|
+
- **Speaker diarization** — Identifies individual speakers in multi-person streams
|
|
121
|
+
- **Real-time translation** — Translate to any supported language with sub-second latency
|
|
122
|
+
- **Partial + final results** — Get streaming partial transcripts and confirmed final text
|
|
123
|
+
- **Credit-based billing** — 1 credit = 1 minute of transcription/translation
|
|
124
|
+
|
|
125
|
+
### Quick Start
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
import { TikTokCaptions } from '@tiktool/live';
|
|
129
|
+
|
|
130
|
+
const captions = new TikTokCaptions({
|
|
131
|
+
uniqueId: 'streamer_name',
|
|
132
|
+
apiKey: 'YOUR_API_KEY',
|
|
133
|
+
translate: 'en',
|
|
134
|
+
diarization: true,
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
captions.on('caption', (event) => {
|
|
138
|
+
const prefix = event.speaker ? `[${event.speaker}] ` : '';
|
|
139
|
+
console.log(`${prefix}${event.text}${event.isFinal ? ' ✓' : '...'}`);
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
captions.on('translation', (event) => {
|
|
143
|
+
console.log(` → ${event.text}`);
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
captions.on('credits', (event) => {
|
|
147
|
+
console.log(`${event.remaining}/${event.total} min remaining`);
|
|
148
|
+
});
|
|
149
|
+
|
|
150
|
+
captions.on('credits_low', (event) => {
|
|
151
|
+
console.warn(`Low credits! ${event.remaining} min left`);
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
await captions.start();
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### `new TikTokCaptions(options)`
|
|
158
|
+
|
|
159
|
+
| Option | Type | Default | Description |
|
|
160
|
+
|--------|------|---------|-------------|
|
|
161
|
+
| `uniqueId` | `string` | — | TikTok username (without @) |
|
|
162
|
+
| `apiKey` | `string` | — | **Required.** API key from [tik.tools](https://tik.tools) |
|
|
163
|
+
| `language` | `string` | `''` | Source language hint (empty = auto-detect) |
|
|
164
|
+
| `translate` | `string` | `''` | Target translation language (e.g. `'en'`, `'es'`, `'fr'`) |
|
|
165
|
+
| `diarization` | `boolean` | `true` | Enable speaker identification |
|
|
166
|
+
| `maxDurationMinutes` | `number` | `60` | Auto-disconnect after N minutes (max: 300) |
|
|
167
|
+
| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
|
|
168
|
+
| `maxReconnectAttempts` | `number` | `5` | Max reconnect attempts |
|
|
169
|
+
| `debug` | `boolean` | `false` | Debug logging |
|
|
170
|
+
|
|
171
|
+
### Caption Events
|
|
172
|
+
|
|
173
|
+
| Event | Callback | Description |
|
|
174
|
+
|-------|----------|-------------|
|
|
175
|
+
| `caption` | `(data: CaptionData) => void` | Real-time transcription (partial + final) |
|
|
176
|
+
| `translation` | `(data: TranslationData) => void` | Translated text |
|
|
177
|
+
| `status` | `(data: CaptionStatus) => void` | Session status changes |
|
|
178
|
+
| `credits` | `(data: CaptionCredits) => void` | Credit balance updates |
|
|
179
|
+
| `credits_low` | `(data) => void` | Low credit warning (≤20%) |
|
|
180
|
+
| `connected` | `() => void` | WebSocket connected |
|
|
181
|
+
| `disconnected` | `(code, reason) => void` | Disconnected |
|
|
182
|
+
| `error` | `(data: CaptionError) => void` | Error |
|
|
183
|
+
|
|
184
|
+
### Methods
|
|
185
|
+
|
|
186
|
+
| Method | Returns | Description |
|
|
187
|
+
|--------|---------|-------------|
|
|
188
|
+
| `start()` | `Promise<void>` | Connect and start transcription |
|
|
189
|
+
| `stop()` | `void` | Stop and disconnect |
|
|
190
|
+
| `setLanguage(lang)` | `void` | Switch translation language on-the-fly |
|
|
191
|
+
| `getCredits()` | `void` | Request credit balance update |
|
|
192
|
+
| `connected` | `boolean` | Connection status |
|
|
193
|
+
| `language` | `string` | Current target language |
|
|
194
|
+
|
|
195
|
+
### Raw WebSocket
|
|
196
|
+
|
|
197
|
+
You can also connect directly via WebSocket without the SDK:
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
wss://api.tik.tools/captions?uniqueId=USERNAME&apiKey=YOUR_KEY&translate=en&diarization=true&max_duration_minutes=120
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Caption Credits
|
|
204
|
+
|
|
205
|
+
Every API key includes a **60-minute free trial** for live captions (speech-to-text with auto-detect to any language).
|
|
206
|
+
|
|
207
|
+
| Tier | Included Credits | Additional Top-Ups |
|
|
208
|
+
|------|-----------------|-------------------|
|
|
209
|
+
| **Free** | 60 min free trial | — |
|
|
210
|
+
| **Pro** | 2,000 min/month | Available |
|
|
211
|
+
| **Ultra** | 10,000 min/month | Available |
|
|
212
|
+
|
|
213
|
+
**Top-Up Packages:**
|
|
214
|
+
|
|
215
|
+
| Package | Credits | Price | Per Credit |
|
|
216
|
+
|---------|---------|-------|------------|
|
|
217
|
+
| Starter | 150 min | $4.99 | $0.033/min |
|
|
218
|
+
| Growth | 600 min | $14.99 | $0.025/min |
|
|
219
|
+
| Scale | 2,000 min | $39.99 | $0.020/min |
|
|
220
|
+
| Whale | 10,000 min | $149.99 | $0.015/min |
|
|
221
|
+
|
|
222
|
+
> **1 credit = 1 minute** of audio transcribed/translated into one language.
|
|
223
|
+
|
|
224
|
+
Try the live demo at [tik.tools/captions](https://tik.tools/captions) — see real-time transcription and translation on actual TikTok LIVE streams.
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
113
228
|
## API Reference
|
|
114
229
|
|
|
115
230
|
### `new TikTokLive(options)`
|
|
@@ -141,11 +256,11 @@ live.on('event', (event) => {
|
|
|
141
256
|
|
|
142
257
|
All API requests require an API key. Get yours at [tik.tools](https://tik.tools).
|
|
143
258
|
|
|
144
|
-
| Tier | Rate Limit | WS Connections | Bulk Check |
|
|
145
|
-
|
|
146
|
-
| **Free** | 30/min | 3 | 5 |
|
|
147
|
-
| **Pro** | 120/min | 50 | 50 |
|
|
148
|
-
| **Ultra** | Unlimited | 10,000 | 500 |
|
|
259
|
+
| Tier | Rate Limit | WS Connections | Bulk Check | Caption Credits | Price |
|
|
260
|
+
|------|-----------|----------------|------------|-----------------|-------|
|
|
261
|
+
| **Free** | 30/min | 3 | 5 | 60 min trial | Free |
|
|
262
|
+
| **Pro** | 120/min | 50 | 50 | 2,000/month | Paid |
|
|
263
|
+
| **Ultra** | Unlimited | 10,000 | 500 | 10,000/month | Paid |
|
|
149
264
|
|
|
150
265
|
The SDK calls the sign server **once per connection**, then stays connected via WebSocket. A free key is sufficient for most use cases.
|
|
151
266
|
|
|
@@ -163,15 +278,13 @@ This endpoint uses a **two-step sign-and-return pattern** because TikTok session
|
|
|
163
278
|
```typescript
|
|
164
279
|
import { getRegionalRanklist } from '@tiktool/live';
|
|
165
280
|
|
|
166
|
-
// Step 1: Get signed URL from the API
|
|
167
281
|
const signed = await getRegionalRanklist({
|
|
168
282
|
apiKey: 'YOUR_PRO_KEY',
|
|
169
283
|
roomId: '7607695933891218198',
|
|
170
284
|
anchorId: '7444599004337652758',
|
|
171
|
-
rankType: '8',
|
|
285
|
+
rankType: '8',
|
|
172
286
|
});
|
|
173
287
|
|
|
174
|
-
// Step 2: Fetch from YOUR IP with YOUR session cookie
|
|
175
288
|
const resp = await fetch(signed.signed_url, {
|
|
176
289
|
method: signed.method,
|
|
177
290
|
headers: { ...signed.headers, Cookie: `sessionid=YOUR_SID; ${signed.cookies}` },
|
|
@@ -193,14 +306,6 @@ data.rank_view.ranks.forEach((r: any, i: number) =>
|
|
|
193
306
|
| `"15"` | Popular LIVE |
|
|
194
307
|
| `"16"` | League |
|
|
195
308
|
|
|
196
|
-
### Response Shape
|
|
197
|
-
|
|
198
|
-
The TikTok response contains `data.rank_view` with:
|
|
199
|
-
- **`ranks`** — Array of ranked users with `user.nickname`, `user.display_id`, `score`
|
|
200
|
-
- **`owner_rank`** — The streamer's own position and gap info
|
|
201
|
-
- **`countdown`** — Seconds until the ranking period ends
|
|
202
|
-
- **`cut_off_line`** — Minimum score to appear on the leaderboard
|
|
203
|
-
|
|
204
309
|
---
|
|
205
310
|
|
|
206
311
|
## Examples
|
|
@@ -270,7 +375,7 @@ const live = new TikTokLive({
|
|
|
270
375
|
agent,
|
|
271
376
|
});
|
|
272
377
|
|
|
273
|
-
await live.connect();
|
|
378
|
+
await live.connect();
|
|
274
379
|
```
|
|
275
380
|
|
|
276
381
|
Both the initial page request and the WebSocket connection are routed through the proxy. This is useful for:
|
package/dist/index.d.mts
CHANGED
|
@@ -423,6 +423,183 @@ declare class TikTokLive extends EventEmitter {
|
|
|
423
423
|
private stopHeartbeat;
|
|
424
424
|
}
|
|
425
425
|
|
|
426
|
+
/**
|
|
427
|
+
* TikTokCaptions — Real-time speech-to-text transcription and translation for TikTok LIVE streams.
|
|
428
|
+
*
|
|
429
|
+
* AI-powered audio transcription with speaker diarization, multi-language auto-detection,
|
|
430
|
+
* real-time translation, and sub-second latency. Connects via WebSocket to the TikTool
|
|
431
|
+
* captions relay for continuous streaming transcription.
|
|
432
|
+
*
|
|
433
|
+
* @example
|
|
434
|
+
* ```ts
|
|
435
|
+
* import { TikTokCaptions } from '@tiktool/live';
|
|
436
|
+
*
|
|
437
|
+
* const captions = new TikTokCaptions({
|
|
438
|
+
* uniqueId: 'username',
|
|
439
|
+
* apiKey: 'your-api-key',
|
|
440
|
+
* language: 'en', // translate to English
|
|
441
|
+
* });
|
|
442
|
+
*
|
|
443
|
+
* captions.on('caption', (data) => {
|
|
444
|
+
* console.log(`[${data.language}] ${data.text}`);
|
|
445
|
+
* });
|
|
446
|
+
*
|
|
447
|
+
* captions.on('translation', (data) => {
|
|
448
|
+
* console.log(`[translated] ${data.text}`);
|
|
449
|
+
* });
|
|
450
|
+
*
|
|
451
|
+
* await captions.start();
|
|
452
|
+
* ```
|
|
453
|
+
*/
|
|
454
|
+
|
|
455
|
+
interface TikTokCaptionsOptions {
|
|
456
|
+
/** TikTok username to transcribe (without @) */
|
|
457
|
+
uniqueId: string;
|
|
458
|
+
/** API key for authentication */
|
|
459
|
+
apiKey: string;
|
|
460
|
+
/** Source language hint (e.g. 'en', 'ja'). Leave empty for auto-detection. */
|
|
461
|
+
language?: string;
|
|
462
|
+
/** Target language for real-time translation (e.g. 'en', 'es', 'fr'). One language per session. */
|
|
463
|
+
translate?: string;
|
|
464
|
+
/** Enable speaker diarization to identify individual speakers (default: true) */
|
|
465
|
+
diarization?: boolean;
|
|
466
|
+
/** Max session duration in minutes before auto-disconnect (default: 60, max: 300) */
|
|
467
|
+
maxDurationMinutes?: number;
|
|
468
|
+
/** Custom server URL (default: wss://api.tik.tools) */
|
|
469
|
+
signServerUrl?: string;
|
|
470
|
+
/** Enable debug logging */
|
|
471
|
+
debug?: boolean;
|
|
472
|
+
/** Auto-reconnect on disconnect */
|
|
473
|
+
autoReconnect?: boolean;
|
|
474
|
+
/** Max reconnect attempts (default: 5) */
|
|
475
|
+
maxReconnectAttempts?: number;
|
|
476
|
+
}
|
|
477
|
+
interface CaptionData {
|
|
478
|
+
/** Transcribed text */
|
|
479
|
+
text: string;
|
|
480
|
+
/** Detected source language */
|
|
481
|
+
language: string;
|
|
482
|
+
/** Whether this is the final version of this segment */
|
|
483
|
+
isFinal: boolean;
|
|
484
|
+
/** Confidence score (0-1) */
|
|
485
|
+
confidence: number;
|
|
486
|
+
/** Speaker identifier (if available) */
|
|
487
|
+
speaker?: string;
|
|
488
|
+
/** Start time in milliseconds */
|
|
489
|
+
startMs?: number;
|
|
490
|
+
/** End time in milliseconds */
|
|
491
|
+
endMs?: number;
|
|
492
|
+
}
|
|
493
|
+
interface TranslationData {
|
|
494
|
+
/** Translated text */
|
|
495
|
+
text: string;
|
|
496
|
+
/** Target language */
|
|
497
|
+
language: string;
|
|
498
|
+
/** Whether this is the final version */
|
|
499
|
+
isFinal: boolean;
|
|
500
|
+
/** Confidence score (0-1) */
|
|
501
|
+
confidence: number;
|
|
502
|
+
/** Speaker identifier (if available) */
|
|
503
|
+
speaker?: string;
|
|
504
|
+
}
|
|
505
|
+
interface CaptionCredits {
|
|
506
|
+
/** Credits remaining */
|
|
507
|
+
remaining: number;
|
|
508
|
+
/** Total credits purchased */
|
|
509
|
+
total: number;
|
|
510
|
+
/** Credits used in this session */
|
|
511
|
+
used: number;
|
|
512
|
+
/** Whether credits are low */
|
|
513
|
+
warning: boolean;
|
|
514
|
+
}
|
|
515
|
+
interface CaptionStatus {
|
|
516
|
+
/** Current status */
|
|
517
|
+
status: 'connecting' | 'waiting' | 'live' | 'transcribing' | 'ended' | 'switching_language' | 'language_switched' | 'stream_ended';
|
|
518
|
+
/** TikTok username */
|
|
519
|
+
uniqueId?: string;
|
|
520
|
+
/** Room ID (once resolved) */
|
|
521
|
+
roomId?: string;
|
|
522
|
+
/** Language (for language switch events) */
|
|
523
|
+
language?: string;
|
|
524
|
+
/** Status message */
|
|
525
|
+
message?: string;
|
|
526
|
+
}
|
|
527
|
+
interface CaptionError {
|
|
528
|
+
/** Error code */
|
|
529
|
+
code: string;
|
|
530
|
+
/** Human-readable error message */
|
|
531
|
+
message: string;
|
|
532
|
+
}
|
|
533
|
+
interface TikTokCaptionsEvents {
|
|
534
|
+
/** Fired for each transcription token */
|
|
535
|
+
caption: (data: CaptionData) => void;
|
|
536
|
+
/** Fired for each translated token */
|
|
537
|
+
translation: (data: TranslationData) => void;
|
|
538
|
+
/** Status changes (connecting, live, transcribing, etc.) */
|
|
539
|
+
status: (data: CaptionStatus) => void;
|
|
540
|
+
/** Credit balance updates */
|
|
541
|
+
credits: (data: CaptionCredits) => void;
|
|
542
|
+
/** Low credit warning */
|
|
543
|
+
credits_low: (data: {
|
|
544
|
+
remaining: number;
|
|
545
|
+
total: number;
|
|
546
|
+
percent: number;
|
|
547
|
+
}) => void;
|
|
548
|
+
/** Error events */
|
|
549
|
+
error: (data: CaptionError) => void;
|
|
550
|
+
/** WebSocket connected */
|
|
551
|
+
connected: () => void;
|
|
552
|
+
/** WebSocket disconnected */
|
|
553
|
+
disconnected: (code: number, reason: string) => void;
|
|
554
|
+
}
|
|
555
|
+
declare class TikTokCaptions extends EventEmitter {
|
|
556
|
+
private ws;
|
|
557
|
+
private _connected;
|
|
558
|
+
private intentionalClose;
|
|
559
|
+
private reconnectAttempts;
|
|
560
|
+
private readonly uniqueId;
|
|
561
|
+
private readonly apiKey;
|
|
562
|
+
private readonly serverUrl;
|
|
563
|
+
private readonly autoReconnect;
|
|
564
|
+
private readonly maxReconnectAttempts;
|
|
565
|
+
private readonly debug;
|
|
566
|
+
private readonly _translate;
|
|
567
|
+
private readonly _diarization;
|
|
568
|
+
private readonly _maxDurationMinutes;
|
|
569
|
+
private _language;
|
|
570
|
+
constructor(options: TikTokCaptionsOptions);
|
|
571
|
+
/**
|
|
572
|
+
* Start real-time captions for the configured TikTok user.
|
|
573
|
+
* Connects to the captions WebSocket relay and begins transcription
|
|
574
|
+
* once the user goes live (or immediately if already live).
|
|
575
|
+
*/
|
|
576
|
+
start(): Promise<void>;
|
|
577
|
+
/**
|
|
578
|
+
* Stop captions and disconnect.
|
|
579
|
+
*/
|
|
580
|
+
stop(): void;
|
|
581
|
+
/**
|
|
582
|
+
* Switch the translation target language on-the-fly.
|
|
583
|
+
* Causes a brief interruption while the transcription engine reconfigures.
|
|
584
|
+
*/
|
|
585
|
+
setLanguage(language: string): void;
|
|
586
|
+
/**
|
|
587
|
+
* Request a credit balance update from the server.
|
|
588
|
+
*/
|
|
589
|
+
getCredits(): void;
|
|
590
|
+
/** Whether the WebSocket is currently connected */
|
|
591
|
+
get connected(): boolean;
|
|
592
|
+
/** The current target language */
|
|
593
|
+
get language(): string;
|
|
594
|
+
on<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
595
|
+
once<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
596
|
+
off<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
597
|
+
emit<K extends keyof TikTokCaptionsEvents>(event: K, ...args: Parameters<TikTokCaptionsEvents[K]>): boolean;
|
|
598
|
+
private buildWsUrl;
|
|
599
|
+
private send;
|
|
600
|
+
private handleMessage;
|
|
601
|
+
}
|
|
602
|
+
|
|
426
603
|
interface GetRanklistOptions {
|
|
427
604
|
/** API server URL (default: https://api.tik.tools) */
|
|
428
605
|
serverUrl?: string;
|
|
@@ -578,4 +755,4 @@ interface RegionalRanklistSignedResponse {
|
|
|
578
755
|
*/
|
|
579
756
|
declare function getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
|
|
580
757
|
|
|
581
|
-
export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, 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, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, getRanklist, getRegionalRanklist };
|
|
758
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -423,6 +423,183 @@ declare class TikTokLive extends EventEmitter {
|
|
|
423
423
|
private stopHeartbeat;
|
|
424
424
|
}
|
|
425
425
|
|
|
426
|
+
/**
|
|
427
|
+
* TikTokCaptions — Real-time speech-to-text transcription and translation for TikTok LIVE streams.
|
|
428
|
+
*
|
|
429
|
+
* AI-powered audio transcription with speaker diarization, multi-language auto-detection,
|
|
430
|
+
* real-time translation, and sub-second latency. Connects via WebSocket to the TikTool
|
|
431
|
+
* captions relay for continuous streaming transcription.
|
|
432
|
+
*
|
|
433
|
+
* @example
|
|
434
|
+
* ```ts
|
|
435
|
+
* import { TikTokCaptions } from '@tiktool/live';
|
|
436
|
+
*
|
|
437
|
+
* const captions = new TikTokCaptions({
|
|
438
|
+
* uniqueId: 'username',
|
|
439
|
+
* apiKey: 'your-api-key',
|
|
440
|
+
* language: 'en', // translate to English
|
|
441
|
+
* });
|
|
442
|
+
*
|
|
443
|
+
* captions.on('caption', (data) => {
|
|
444
|
+
* console.log(`[${data.language}] ${data.text}`);
|
|
445
|
+
* });
|
|
446
|
+
*
|
|
447
|
+
* captions.on('translation', (data) => {
|
|
448
|
+
* console.log(`[translated] ${data.text}`);
|
|
449
|
+
* });
|
|
450
|
+
*
|
|
451
|
+
* await captions.start();
|
|
452
|
+
* ```
|
|
453
|
+
*/
|
|
454
|
+
|
|
455
|
+
interface TikTokCaptionsOptions {
|
|
456
|
+
/** TikTok username to transcribe (without @) */
|
|
457
|
+
uniqueId: string;
|
|
458
|
+
/** API key for authentication */
|
|
459
|
+
apiKey: string;
|
|
460
|
+
/** Source language hint (e.g. 'en', 'ja'). Leave empty for auto-detection. */
|
|
461
|
+
language?: string;
|
|
462
|
+
/** Target language for real-time translation (e.g. 'en', 'es', 'fr'). One language per session. */
|
|
463
|
+
translate?: string;
|
|
464
|
+
/** Enable speaker diarization to identify individual speakers (default: true) */
|
|
465
|
+
diarization?: boolean;
|
|
466
|
+
/** Max session duration in minutes before auto-disconnect (default: 60, max: 300) */
|
|
467
|
+
maxDurationMinutes?: number;
|
|
468
|
+
/** Custom server URL (default: wss://api.tik.tools) */
|
|
469
|
+
signServerUrl?: string;
|
|
470
|
+
/** Enable debug logging */
|
|
471
|
+
debug?: boolean;
|
|
472
|
+
/** Auto-reconnect on disconnect */
|
|
473
|
+
autoReconnect?: boolean;
|
|
474
|
+
/** Max reconnect attempts (default: 5) */
|
|
475
|
+
maxReconnectAttempts?: number;
|
|
476
|
+
}
|
|
477
|
+
interface CaptionData {
|
|
478
|
+
/** Transcribed text */
|
|
479
|
+
text: string;
|
|
480
|
+
/** Detected source language */
|
|
481
|
+
language: string;
|
|
482
|
+
/** Whether this is the final version of this segment */
|
|
483
|
+
isFinal: boolean;
|
|
484
|
+
/** Confidence score (0-1) */
|
|
485
|
+
confidence: number;
|
|
486
|
+
/** Speaker identifier (if available) */
|
|
487
|
+
speaker?: string;
|
|
488
|
+
/** Start time in milliseconds */
|
|
489
|
+
startMs?: number;
|
|
490
|
+
/** End time in milliseconds */
|
|
491
|
+
endMs?: number;
|
|
492
|
+
}
|
|
493
|
+
interface TranslationData {
|
|
494
|
+
/** Translated text */
|
|
495
|
+
text: string;
|
|
496
|
+
/** Target language */
|
|
497
|
+
language: string;
|
|
498
|
+
/** Whether this is the final version */
|
|
499
|
+
isFinal: boolean;
|
|
500
|
+
/** Confidence score (0-1) */
|
|
501
|
+
confidence: number;
|
|
502
|
+
/** Speaker identifier (if available) */
|
|
503
|
+
speaker?: string;
|
|
504
|
+
}
|
|
505
|
+
interface CaptionCredits {
|
|
506
|
+
/** Credits remaining */
|
|
507
|
+
remaining: number;
|
|
508
|
+
/** Total credits purchased */
|
|
509
|
+
total: number;
|
|
510
|
+
/** Credits used in this session */
|
|
511
|
+
used: number;
|
|
512
|
+
/** Whether credits are low */
|
|
513
|
+
warning: boolean;
|
|
514
|
+
}
|
|
515
|
+
interface CaptionStatus {
|
|
516
|
+
/** Current status */
|
|
517
|
+
status: 'connecting' | 'waiting' | 'live' | 'transcribing' | 'ended' | 'switching_language' | 'language_switched' | 'stream_ended';
|
|
518
|
+
/** TikTok username */
|
|
519
|
+
uniqueId?: string;
|
|
520
|
+
/** Room ID (once resolved) */
|
|
521
|
+
roomId?: string;
|
|
522
|
+
/** Language (for language switch events) */
|
|
523
|
+
language?: string;
|
|
524
|
+
/** Status message */
|
|
525
|
+
message?: string;
|
|
526
|
+
}
|
|
527
|
+
interface CaptionError {
|
|
528
|
+
/** Error code */
|
|
529
|
+
code: string;
|
|
530
|
+
/** Human-readable error message */
|
|
531
|
+
message: string;
|
|
532
|
+
}
|
|
533
|
+
interface TikTokCaptionsEvents {
|
|
534
|
+
/** Fired for each transcription token */
|
|
535
|
+
caption: (data: CaptionData) => void;
|
|
536
|
+
/** Fired for each translated token */
|
|
537
|
+
translation: (data: TranslationData) => void;
|
|
538
|
+
/** Status changes (connecting, live, transcribing, etc.) */
|
|
539
|
+
status: (data: CaptionStatus) => void;
|
|
540
|
+
/** Credit balance updates */
|
|
541
|
+
credits: (data: CaptionCredits) => void;
|
|
542
|
+
/** Low credit warning */
|
|
543
|
+
credits_low: (data: {
|
|
544
|
+
remaining: number;
|
|
545
|
+
total: number;
|
|
546
|
+
percent: number;
|
|
547
|
+
}) => void;
|
|
548
|
+
/** Error events */
|
|
549
|
+
error: (data: CaptionError) => void;
|
|
550
|
+
/** WebSocket connected */
|
|
551
|
+
connected: () => void;
|
|
552
|
+
/** WebSocket disconnected */
|
|
553
|
+
disconnected: (code: number, reason: string) => void;
|
|
554
|
+
}
|
|
555
|
+
declare class TikTokCaptions extends EventEmitter {
|
|
556
|
+
private ws;
|
|
557
|
+
private _connected;
|
|
558
|
+
private intentionalClose;
|
|
559
|
+
private reconnectAttempts;
|
|
560
|
+
private readonly uniqueId;
|
|
561
|
+
private readonly apiKey;
|
|
562
|
+
private readonly serverUrl;
|
|
563
|
+
private readonly autoReconnect;
|
|
564
|
+
private readonly maxReconnectAttempts;
|
|
565
|
+
private readonly debug;
|
|
566
|
+
private readonly _translate;
|
|
567
|
+
private readonly _diarization;
|
|
568
|
+
private readonly _maxDurationMinutes;
|
|
569
|
+
private _language;
|
|
570
|
+
constructor(options: TikTokCaptionsOptions);
|
|
571
|
+
/**
|
|
572
|
+
* Start real-time captions for the configured TikTok user.
|
|
573
|
+
* Connects to the captions WebSocket relay and begins transcription
|
|
574
|
+
* once the user goes live (or immediately if already live).
|
|
575
|
+
*/
|
|
576
|
+
start(): Promise<void>;
|
|
577
|
+
/**
|
|
578
|
+
* Stop captions and disconnect.
|
|
579
|
+
*/
|
|
580
|
+
stop(): void;
|
|
581
|
+
/**
|
|
582
|
+
* Switch the translation target language on-the-fly.
|
|
583
|
+
* Causes a brief interruption while the transcription engine reconfigures.
|
|
584
|
+
*/
|
|
585
|
+
setLanguage(language: string): void;
|
|
586
|
+
/**
|
|
587
|
+
* Request a credit balance update from the server.
|
|
588
|
+
*/
|
|
589
|
+
getCredits(): void;
|
|
590
|
+
/** Whether the WebSocket is currently connected */
|
|
591
|
+
get connected(): boolean;
|
|
592
|
+
/** The current target language */
|
|
593
|
+
get language(): string;
|
|
594
|
+
on<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
595
|
+
once<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
596
|
+
off<K extends keyof TikTokCaptionsEvents>(event: K, listener: TikTokCaptionsEvents[K]): this;
|
|
597
|
+
emit<K extends keyof TikTokCaptionsEvents>(event: K, ...args: Parameters<TikTokCaptionsEvents[K]>): boolean;
|
|
598
|
+
private buildWsUrl;
|
|
599
|
+
private send;
|
|
600
|
+
private handleMessage;
|
|
601
|
+
}
|
|
602
|
+
|
|
426
603
|
interface GetRanklistOptions {
|
|
427
604
|
/** API server URL (default: https://api.tik.tools) */
|
|
428
605
|
serverUrl?: string;
|
|
@@ -578,4 +755,4 @@ interface RegionalRanklistSignedResponse {
|
|
|
578
755
|
*/
|
|
579
756
|
declare function getRegionalRanklist(opts: GetRegionalRanklistOptions): Promise<RegionalRanklistSignedResponse>;
|
|
580
757
|
|
|
581
|
-
export { type AnchorRankListEntry, type AnchorRankListResponse, type BarrageEvent, type BaseEvent, type BattleArmiesEvent, type BattleEvent, type BattleTaskEvent, type BattleTeam, type BattleTeamUser, 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, TikTokLive, type TikTokLiveEvents, type TikTokLiveOptions, type TikTokUser, type UnknownEvent, getRanklist, getRegionalRanklist };
|
|
758
|
+
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 };
|