@tiktool/captions

TikTok Live Captions — Real-Time Speech-to-Text Transcription & Translation

Turn any TikTok livestream into real-time text. Transcription + translation + speaker identification. Works with any language. Zero config.

This package re-exports the captions module from @tiktool/live. If you also need chat, gifts, viewers, or battle events, install @tiktool/live instead — it includes everything.

Install

npm install @tiktool/captions

Usage

import { TikTokCaptions } from '@tiktool/captions';

const captions = new TikTokCaptions({
  uniqueId: 'username',
  apiKey: 'tk_your_api_key',
  translate: 'en',
});

captions.on('caption', (data) => {
  console.log(`[${data.language}] ${data.text}`);
});

captions.on('translation', (data) => {
  console.log(`[${data.language}] ${data.text}`);
});

captions.on('credits', (credits) => {
  console.log(`${credits.remaining}/${credits.total} credits left`);
});

captions.on('error', (err) => {
  console.error(err.code, err.message);
});

await captions.start();

That's it. Captions start flowing.

Options

All options are passed to the constructor as a single object.

| Option | Type | Default | Required | Description | |---|---|---|---|---| | uniqueId | string | — | ✅ | TikTok username (with or without @) | | apiKey | string | — | ✅ | API key from tik.tools | | language | string | auto-detect | | Source language hint ('en', 'ko', 'ja', etc.) | | translate | string | — | | Target language for translation ('en', 'es', 'fr', etc.) | | diarization | boolean | true | | Identify individual speakers | | maxDurationMinutes | number | 60 | | Auto-disconnect after N minutes (max 300) | | signServerUrl | string | wss://api.tik.tools | | Custom server URL | | autoReconnect | boolean | true | | Reconnect on disconnect | | maxReconnectAttempts | number | 5 | | Retry limit before giving up | | debug | boolean | false | | Log raw WebSocket messages |

Events

| Event | Payload | When | |---|---|---| | caption | CaptionData | New transcription segment | | translation | TranslationData | Translated segment | | status | CaptionStatus | Connection state changes | | credits | CaptionCredits | Credit balance update | | credits_low | { remaining, total, percent } | Credits below threshold | | error | CaptionError | Something went wrong | | connected | — | WebSocket connected | | disconnected | (code, reason) | WebSocket closed |

Methods

| Method | Returns | Description | |---|---|---| | start() | Promise<void> | Connect and begin transcription | | stop() | void | Disconnect and stop |

Types

interface CaptionData {
  text: string;
  language: string;
  isFinal: boolean;
  confidence: number;
  speaker?: string;
  startMs?: number;
  endMs?: number;
}

interface TranslationData {
  text: string;
  language: string;
  isFinal: boolean;
  confidence: number;
  speaker?: string;
}

interface CaptionCredits {
  remaining: number;
  total: number;
  used: number;
  warning: boolean;
}

interface CaptionStatus {
  status: 'connecting' | 'waiting' | 'live' | 'transcribing' |
          'ended' | 'switching_language' | 'language_switched' | 'stream_ended';
  uniqueId?: string;
  roomId?: string;
  language?: string;
  message?: string;
}

interface CaptionError {
  code: string;
  message: string;
}

Languages

Auto-detection works out of the box. No config needed.

Supported: Chinese, English, Korean, Japanese, Spanish, French, German, Portuguese, Russian, Arabic, Hindi, Thai, Vietnamese, Indonesian, Turkish, Italian, Dutch, Polish, Swedish, Greek, Czech, Romanian, Hungarian, Finnish, Danish, Norwegian, Hebrew, Malay, Filipino, Ukrainian, Bengali, Tamil, Telugu, Marathi, Gujarati, Kannada, Malayalam, Punjabi, Urdu, Persian, and more.

Translation works between any supported pair.

Credits

1 credit = 1 minute of audio in 1 language.

| Scenario | Credits used | |---|---| | 10 min transcription only | 10 | | 10 min + translation to 1 language | 20 | | 10 min + translation to 2 languages | 30 |

| Plan | Credits | Billing | |---|---|---| | Free | 60 | One-time trial | | Pro | 500/week or 2,000/month | Recurring | | Ultra | 2,500/week or 10,000/month | Recurring |

Get an API key →

Related

• @tiktool/live — Full TikTok LIVE API (chat, gifts, viewers, battles, captions, and more)

License

MIT