0
# Dubbing
1

2
## Dubbing Methods
3

4
### dubbing.create()
5

6
```typescript { .api }
7
create(
8
  request: {
9
    file?: File | Blob;  // Use file or sourceUrl, not both
10
    sourceUrl?: string;  // Use file or sourceUrl, not both
11
    sourceLang?: string;  // Auto-detect if omitted
12
    targetLang: string;
13
    name?: string;
14
    numSpeakers?: number;  // Number of speakers (1-20)
15
    watermark?: boolean;  // Default: false
16
    startTime?: number;  // Seconds, for partial dubbing
17
    endTime?: number;  // Seconds, for partial dubbing
18
    highestResolution?: boolean;  // Default: false
19
    dubbingStudioActors?: Record<string, string>;  // speaker_id: voice_id
20
    excludedTranscriptSegmentIndexes?: number[];
21
    useProfilingState?: boolean;
22
    dropBackgroundAudio?: boolean;  // Default: false
23
    useAudioIsolation?: boolean;
24
    mode?: "automatic" | "manual";
25
  },
26
  options?: RequestOptions
27
): Promise<DoDubbingResponse>
28

29
interface DoDubbingResponse {
30
  dubbingId: string;
31
  expectedDurationSec?: number;
32
}
33
```
34

35
### dubbing.get()
36

37
```typescript { .api }
38
get(
39
  dubbingId: string,
40
  options?: RequestOptions
41
): Promise<DubbingMetadataResponse>
42

43
interface DubbingMetadataResponse {
44
  dubbingId: string;
45
  name: string;
46
  status: string;  // "dubbing" | "dubbed" | "failed"
47
  targetLanguages: string[];
48
  sourceLanguage?: string;
49
  error?: string;
50
  // Additional metadata...
51
}
52
```
53

54
### dubbing.delete()
55

56
```typescript { .api }
57
delete(
58
  dubbingId: string,
59
  options?: RequestOptions
60
): Promise<void>
61
```
62

63
### dubbing.getAudio()
64

65
```typescript { .api }
66
getAudio(
67
  dubbingId: string,
68
  languageCode: string,
69
  options?: RequestOptions
70
): Promise<ReadableStream<Uint8Array>>
71
```
72

73
### dubbing.getTranscript()
74

75
```typescript { .api }
76
getTranscript(
77
  dubbingId: string,
78
  languageCode: string,
79
  request?: { formatType?: "srt" | "webvtt" | "json" },
80
  options?: RequestOptions
81
): Promise<TranscriptResponse>
82
```
83

84
## Usage Examples
85

86
### Basic Dubbing from File
87

88
```typescript
89
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
90
import fs from "fs";
91

92
const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });
93

94
const videoFile = fs.readFileSync("/path/video.mp4");
95

96
const dub = await client.dubbing.create({
97
  file: videoFile,
98
  targetLang: "es",  // Spanish
99
  sourceLang: "en",  // English (optional, auto-detect if omitted)
100
  name: "My Video Dubbing",
101
  numSpeakers: 2,
102
  watermark: false
103
});
104

105
console.log(`Dubbing ID: ${dub.dubbingId}`);
106
console.log(`Expected duration: ${dub.expectedDurationSec}s`);
107
```
108

109
### Dubbing from URL
110

111
```typescript
112
const dub = await client.dubbing.create({
113
  sourceUrl: "https://example.com/video.mp4",
114
  targetLang: "fr",  // French
115
  name: "French Dubbing"
116
});
117
```
118

119
### Poll for Completion
120

121
```typescript
122
async function waitForDubbing(dubbingId: string) {
123
  while (true) {
124
    const status = await client.dubbing.get(dubbingId);
125

126
    console.log(`Status: ${status.status}`);
127

128
    if (status.status === "dubbed") {
129
      return status;
130
    } else if (status.status === "failed") {
131
      throw new Error(`Dubbing failed: ${status.error}`);
132
    }
133

134
    await new Promise(resolve => setTimeout(resolve, 5000));  // Wait 5s
135
  }
136
}
137

138
const completed = await waitForDubbing(dub.dubbingId);
139
console.log(`Dubbed to: ${completed.targetLanguages.join(", ")}`);
140
```
141

142
### Download Dubbed Audio
143

144
```typescript
145
const audio = await client.dubbing.getAudio(dub.dubbingId, "es");
146

147
const output = fs.createWriteStream("dubbed_spanish.mp4");
148
for await (const chunk of audio) {
149
  output.write(chunk);
150
}
151
output.end();
152
```
153

154
### Get Transcript
155

156
```typescript
157
// SRT format
158
const srt = await client.dubbing.getTranscript(dub.dubbingId, "es", {
159
  formatType: "srt"
160
});
161

162
// WebVTT format
163
const webvtt = await client.dubbing.getTranscript(dub.dubbingId, "es", {
164
  formatType: "webvtt"
165
});
166

167
// JSON format
168
const json = await client.dubbing.getTranscript(dub.dubbingId, "es", {
169
  formatType: "json"
170
});
171
```
172

173
### Partial Dubbing
174

175
```typescript
176
// Dub only a portion of the video (60s to 120s)
177
const partial = await client.dubbing.create({
178
  file: videoFile,
179
  targetLang: "de",
180
  startTime: 60,
181
  endTime: 120
182
});
183
```
184

185
### Custom Voice Mapping
186

187
```typescript
188
// Map specific speakers to custom voices
189
const customDub = await client.dubbing.create({
190
  file: videoFile,
191
  targetLang: "it",
192
  numSpeakers: 3,
193
  dubbingStudioActors: {
194
    "speaker_1": "21m00Tcm4TlvDq8ikWAM",  // Voice ID for speaker 1
195
    "speaker_2": "AZnzlk1XvdvUeBnXmlld",  // Voice ID for speaker 2
196
    "speaker_3": "EXAVITQu4vr4xnSDxMaL"   // Voice ID for speaker 3
197
  }
198
});
199
```
200

201
### Audio Isolation
202

203
```typescript
204
// Use audio isolation to remove background noise
205
const isolated = await client.dubbing.create({
206
  file: videoFile,
207
  targetLang: "ja",
208
  useAudioIsolation: true,
209
  dropBackgroundAudio: true
210
});
211
```
212

213
### High Resolution
214

215
```typescript
216
// Request highest resolution output
217
const highRes = await client.dubbing.create({
218
  file: videoFile,
219
  targetLang: "pt",
220
  highestResolution: true
221
});
222
```
223

224
### Delete Dubbing
225

226
```typescript
227
await client.dubbing.delete(dub.dubbingId);
228
console.log("Dubbing deleted");
229
```
230

231
## Complete Workflow
232

233
```typescript
234
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
235
import fs from "fs";
236

237
const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });
238

239
// 1. Start dubbing
240
const videoFile = fs.readFileSync("original.mp4");
241
const dub = await client.dubbing.create({
242
  file: videoFile,
243
  sourceLang: "en",
244
  targetLang: "es",
245
  name: "Spanish Dub",
246
  numSpeakers: 2,
247
  highestResolution: true
248
});
249

250
console.log(`Started dubbing: ${dub.dubbingId}`);
251

252
// 2. Poll for completion
253
let status;
254
while (true) {
255
  status = await client.dubbing.get(dub.dubbingId);
256
  console.log(`Status: ${status.status}`);
257

258
  if (status.status === "dubbed") break;
259
  if (status.status === "failed") throw new Error(status.error);
260

261
  await new Promise(r => setTimeout(r, 5000));
262
}
263

264
// 3. Download dubbed audio
265
const audio = await client.dubbing.getAudio(dub.dubbingId, "es");
266
const audioFile = fs.createWriteStream("dubbed_spanish.mp4");
267
for await (const chunk of audio) audioFile.write(chunk);
268
audioFile.end();
269

270
// 4. Download transcript
271
const transcript = await client.dubbing.getTranscript(dub.dubbingId, "es", {
272
  formatType: "srt"
273
});
274
fs.writeFileSync("transcript_spanish.srt", transcript);
275

276
console.log("Dubbing complete!");
277
```
278

279
## Important Notes
280

281
- **Source**: Use `file` OR `sourceUrl`, not both
282
- **Language codes**: ISO 639-1 (e.g., "en", "es", "fr")
283
- **Speakers**: 1-20 speakers supported
284
- **Status values**: "dubbing", "dubbed", "failed"
285
- **Partial dubbing**: Use `startTime` and `endTime` (seconds)
286
- **Audio isolation**: Removes background noise when enabled
287
- **Transcript formats**: "srt", "webvtt", "json"
288
- **Polling**: Dubbing is async, poll `get()` for status
289
- **Resolution**: `highestResolution` may increase processing time
290