@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