0
# Transcription Vocabularies
1

2
Transcription vocabulary management for improving automated speech recognition accuracy. Transcription vocabularies contain custom phrases, words, and proper names that boost recognition probability for live stream subtitles.
3

4
## Capabilities
5

6
### Transcription Vocabulary Creation
7

8
Create custom vocabulary lists to improve transcription accuracy for domain-specific terminology.
9

10
```typescript { .api }
11
/**
12
 * Create a new Transcription Vocabulary
13
 * @param body - Vocabulary creation parameters
14
 * @returns Promise resolving to the created vocabulary
15
 */
16
create(
17
  body: TranscriptionVocabularyCreateParams,
18
  options?: Core.RequestOptions
19
): Core.APIPromise<TranscriptionVocabulary>;
20

21
interface TranscriptionVocabularyCreateParams {
22
  /** Phrases, words, or proper names to boost recognition probability */
23
  phrases: Array<string>;
24
  /** Optional user-supplied name for the vocabulary */
25
  name?: string;
26
  /** Optional metadata (max 255 characters) */
27
  passthrough?: string;
28
}
29
```
30

31
**Usage Example:**
32

33
```typescript
34
import Mux from "@mux/mux-node";
35

36
const mux = new Mux({
37
  tokenId: process.env.MUX_TOKEN_ID,
38
  tokenSecret: process.env.MUX_TOKEN_SECRET,
39
});
40

41
// Create vocabulary for technical terms
42
const vocabulary = await mux.video.transcriptionVocabularies.create({
43
  name: "Mux API Vocabulary",
44
  phrases: [
45
    "Mux",
46
    "Live Stream",
47
    "Playback ID",
48
    "video encoding",
49
    "RTMP",
50
    "Stream Key"
51
  ]
52
});
53

54
console.log(`Created vocabulary: ${vocabulary.id}`);
55
```
56

57
### Transcription Vocabulary Retrieval
58

59
Retrieve details of existing transcription vocabularies.
60

61
```typescript { .api }
62
/**
63
 * Retrieve a Transcription Vocabulary by ID
64
 * @param transcriptionVocabularyId - Unique vocabulary identifier
65
 * @returns Promise resolving to the vocabulary details
66
 */
67
retrieve(
68
  transcriptionVocabularyId: string,
69
  options?: Core.RequestOptions
70
): Core.APIPromise<TranscriptionVocabulary>;
71
```
72

73
**Usage Example:**
74

75
```typescript
76
const vocabulary = await mux.video.transcriptionVocabularies.retrieve(
77
  "TRANSCRIPTION_VOCABULARY_ID"
78
);
79

80
console.log(`Vocabulary "${vocabulary.name}" contains ${vocabulary.phrases?.length} phrases`);
81
```
82

83
### Transcription Vocabulary Updates
84

85
Update existing vocabularies while maintaining live stream associations.
86

87
```typescript { .api }
88
/**
89
 * Update a Transcription Vocabulary
90
 * @param transcriptionVocabularyId - Vocabulary to update
91
 * @param body - Updated vocabulary parameters
92
 * @returns Promise resolving to the updated vocabulary
93
 */
94
update(
95
  transcriptionVocabularyId: string,
96
  body: TranscriptionVocabularyUpdateParams,
97
  options?: Core.RequestOptions
98
): Core.APIPromise<TranscriptionVocabulary>;
99

100
interface TranscriptionVocabularyUpdateParams {
101
  /** Updated phrases, words, or proper names */
102
  phrases: Array<string>;
103
  /** Updated name for the vocabulary */
104
  name?: string;
105
  /** Updated metadata (max 255 characters) */
106
  passthrough?: string;
107
}
108
```
109

110
**Usage Example:**
111

112
```typescript
113
const updatedVocabulary = await mux.video.transcriptionVocabularies.update(
114
  "TRANSCRIPTION_VOCABULARY_ID",
115
  {
116
    name: "Mux API Vocabulary - Updated",
117
    phrases: ["Mux", "Live Stream", "RTMP", "Stream Key", "HLS", "DASH"]
118
  }
119
);
120
```
121

122
### Transcription Vocabulary Listing
123

124
List and paginate through all transcription vocabularies.
125

126
```typescript { .api }
127
/**
128
 * List all Transcription Vocabularies with pagination
129
 * @param query - Optional pagination parameters
130
 * @returns PagePromise for iterating through vocabularies
131
 */
132
list(
133
  query?: TranscriptionVocabularyListParams,
134
  options?: Core.RequestOptions
135
): Core.PagePromise<TranscriptionVocabulariesBasePage, TranscriptionVocabulary>;
136

137
interface TranscriptionVocabularyListParams extends BasePageParams {
138
  /** Page number for pagination */
139
  page?: number;
140
  /** Number of items per page */
141
  limit?: number;
142
}
143
```
144

145
**Usage Example:**
146

147
```typescript
148
// Auto-pagination through all vocabularies
149
for await (const vocabulary of mux.video.transcriptionVocabularies.list()) {
150
  console.log(`Vocabulary: ${vocabulary.name} (${vocabulary.phrases?.length} phrases)`);
151
}
152

153
// Manual pagination
154
const page = await mux.video.transcriptionVocabularies.list({
155
  page: 1,
156
  limit: 10
157
});
158
```
159

160
### Transcription Vocabulary Deletion
161

162
Delete vocabularies while preserving active live stream associations.
163

164
```typescript { .api }
165
/**
166
 * Delete a Transcription Vocabulary
167
 * @param transcriptionVocabularyId - Vocabulary to delete
168
 * @returns Promise that resolves when deletion completes
169
 */
170
delete(
171
  transcriptionVocabularyId: string,
172
  options?: Core.RequestOptions
173
): Core.APIPromise<void>;
174
```
175

176
**Usage Example:**
177

178
```typescript
179
await mux.video.transcriptionVocabularies.delete("TRANSCRIPTION_VOCABULARY_ID");
180
console.log("Vocabulary deleted successfully");
181
```
182

183
## Types
184

185
```typescript { .api }
186
interface TranscriptionVocabulary {
187
  /** Unique identifier for the Transcription Vocabulary */
188
  id: string;
189
  /** Creation timestamp (Unix seconds since epoch) */
190
  created_at: string;
191
  /** Last update timestamp (Unix seconds since epoch) */
192
  updated_at: string;
193
  /** Optional user-supplied name */
194
  name?: string;
195
  /** Optional metadata (max 255 characters) */
196
  passthrough?: string;
197
  /** Array of phrases, words, or proper names */
198
  phrases?: Array<string>;
199
}
200

201
interface TranscriptionVocabularyResponse {
202
  data: TranscriptionVocabulary;
203
}
204

205
/** Pagination wrapper for vocabulary listing */
206
class TranscriptionVocabulariesBasePage extends BasePage<TranscriptionVocabulary> {}
207
```
208

209
## Integration with Live Streams
210

211
Transcription vocabularies are used with live streams to improve subtitle accuracy:
212

213
```typescript
214
// Create a live stream with transcription vocabulary
215
const liveStream = await mux.video.liveStreams.create({
216
  playback_policy: ["public"],
217
  generated_subtitles: [
218
    {
219
      name: "English",
220
      language_code: "en",
221
      transcription_vocabulary_ids: [vocabulary.id]
222
    }
223
  ]
224
});
225
```
226

227
## Best Practices
228

229
- **Phrase Selection**: Include domain-specific terminology, proper names, and technical jargon
230
- **Update Strategy**: Updates to vocabularies don't affect active live streams until they restart
231
- **Performance**: Optimal vocabulary size is 50-500 phrases for best recognition performance
232
- **Lifecycle**: Vocabularies can be safely deleted while associated with active streams