0
# Live Streaming
1

2
Live streaming functionality for creating, managing, and controlling real-time video streams with simulcast support, playback restrictions, and automatic recording options.
3

4
## Capabilities
5

6
### Live Stream Creation
7

8
Create and configure live streams for real-time video broadcasting.
9

10
```typescript { .api }
11
/**
12
 * Create a new live stream
13
 * @param body - Live stream creation parameters
14
 * @returns Promise resolving to the created live stream
15
 */
16
create(body: LiveStreamCreateParams): Promise<LiveStream>;
17

18
interface LiveStreamCreateParams {
19
  /** Playback policies for the live stream */
20
  playback_policies?: Array<PlaybackPolicy>;
21
  /** Asset settings for recorded content */
22
  new_asset_settings?: NewAssetSettings;
23
  /** Whether to reconnect automatically */
24
  reconnect_window?: number;
25
  /** Whether the stream should be reduced latency */
26
  reduced_latency?: boolean;
27
  /** Simulcast target configurations */
28
  simulcast_targets?: Array<CreateSimulcastTargetRequest>;
29
  /** Test mode flag */
30
  test?: boolean;
31
  /** Generated subtitle settings */
32
  generated_subtitles?: Array<LiveStreamGeneratedSubtitleSettings>;
33
  /** Embedded subtitle settings */
34
  embedded_subtitles?: Array<LiveStreamEmbeddedSubtitleSettings>;
35
}
36

37
interface LiveStream {
38
  /** Unique identifier for the live stream */
39
  id: string;
40
  /** Creation timestamp */
41
  created_at: string;
42
  /** Stream key for broadcasting */
43
  stream_key: string;
44
  /** Current status of the live stream */
45
  status?: 'idle' | 'active' | 'disabled';
46
  /** Array of playback IDs */
47
  playback_ids?: Array<PlaybackID>;
48
  /** RTMP ingest URL */
49
  rtmp?: RTMPSettings;
50
  /** SRT ingest settings */
51
  srt?: SRTSettings;
52
  /** Reconnection window in seconds */
53
  reconnect_window?: number;
54
  /** Recent asset IDs created from this stream */
55
  recent_asset_ids?: Array<string>;
56
}
57

58
interface NewAssetSettings {
59
  /** Playback policies for created assets */
60
  playback_policies?: Array<PlaybackPolicy>;
61
  /** MP4 support for created assets */
62
  mp4_support?: Mp4Support;
63
  /** Audio normalization for created assets */
64
  normalize_audio?: boolean;
65
}
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
// Basic live stream creation
72
const liveStream = await mux.video.liveStreams.create({
73
  playback_policies: ["public"],
74
  new_asset_settings: {
75
    playback_policies: ["public"],
76
    mp4_support: "standard",
77
  },
78
});
79

80
// Advanced live stream with simulcast
81
const liveStream = await mux.video.liveStreams.create({
82
  playback_policies: ["signed"],
83
  reduced_latency: true,
84
  reconnect_window: 60,
85
  simulcast_targets: [
86
    {
87
      url: "rtmp://live.twitch.tv/live/",
88
      stream_key: "your-twitch-stream-key",
89
    },
90
  ],
91
  generated_subtitles: [
92
    {
93
      language_code: "en",
94
      name: "English Auto-Generated",
95
    },
96
  ],
97
});
98
```
99

100
### Live Stream Management
101

102
Retrieve, update, and manage live stream settings.
103

104
```typescript { .api }
105
/**
106
 * Retrieve live stream details
107
 * @param liveStreamId - The live stream identifier
108
 * @returns Promise resolving to live stream details
109
 */
110
retrieve(liveStreamId: string): Promise<LiveStream>;
111

112
/**
113
 * Update live stream settings
114
 * @param liveStreamId - The live stream identifier
115
 * @param body - Update parameters
116
 * @returns Promise resolving to updated live stream
117
 */
118
update(liveStreamId: string, body: LiveStreamUpdateParams): Promise<LiveStream>;
119

120
interface LiveStreamUpdateParams {
121
  /** Updated playback policy */
122
  playback_policies?: Array<PlaybackPolicy>;
123
  /** Updated asset settings */
124
  new_asset_settings?: NewAssetSettings;
125
  /** Updated reconnection window */
126
  reconnect_window?: number;
127
  /** Updated latency mode */
128
  reduced_latency?: boolean;
129
}
130

131
/**
132
 * List live streams with optional filtering and pagination
133
 * @param query - Listing parameters
134
 * @returns Paginated list of live streams
135
 */
136
list(query?: LiveStreamListParams): PagePromise<LiveStreamsBasePage, LiveStream>;
137

138
interface LiveStreamListParams extends BasePageParams {
139
  /** Filter by stream status */
140
  status?: 'active' | 'idle' | 'disabled';
141
  /** Filter streams created after this timestamp */
142
  created_at_gte?: string;
143
}
144

145
/**
146
 * Delete a live stream
147
 * @param liveStreamId - The live stream identifier
148
 * @returns Promise that resolves when deletion is complete
149
 */
150
delete(liveStreamId: string): Promise<void>;
151
```
152

153
### Stream Control
154

155
Control live stream state and lifecycle operations.
156

157
```typescript { .api }
158
/**
159
 * Complete a live stream and create an asset
160
 * @param liveStreamId - The live stream identifier
161
 * @returns Promise that resolves when completion is initiated
162
 */
163
complete(liveStreamId: string): Promise<void>;
164

165
/**
166
 * Disable a live stream temporarily
167
 * @param liveStreamId - The live stream identifier
168
 * @returns Promise that resolves when stream is disabled
169
 */
170
disable(liveStreamId: string): Promise<void>;
171

172
/**
173
 * Enable a previously disabled live stream
174
 * @param liveStreamId - The live stream identifier
175
 * @returns Promise that resolves when stream is enabled
176
 */
177
enable(liveStreamId: string): Promise<void>;
178

179
/**
180
 * Reset the stream key for a live stream
181
 * @param liveStreamId - The live stream identifier
182
 * @returns Promise resolving to updated live stream with new stream key
183
 */
184
resetStreamKey(liveStreamId: string): Promise<LiveStream>;
185
```
186

187
### Playback ID Management
188

189
Manage playback IDs for live stream access control.
190

191
```typescript { .api }
192
/**
193
 * Create a playback ID for a live stream
194
 * @param liveStreamId - The live stream identifier
195
 * @param body - Playback ID creation parameters
196
 * @returns Promise resolving to the created playback ID
197
 */
198
createPlaybackId(
199
  liveStreamId: string,
200
  body: LiveStreamCreatePlaybackIDParams
201
): Promise<PlaybackID>;
202

203
interface LiveStreamCreatePlaybackIDParams {
204
  /** Access policy for the playback ID */
205
  policy: PlaybackPolicy;
206
  /** DRM configuration ID (required for DRM policy) */
207
  drm_configuration_id?: string;
208
}
209

210
/**
211
 * Retrieve playback ID details for a live stream
212
 * @param liveStreamId - The live stream identifier
213
 * @param playbackId - The playback ID
214
 * @returns Promise resolving to playback ID details
215
 */
216
retrievePlaybackId(liveStreamId: string, playbackId: string): Promise<PlaybackID>;
217

218
/**
219
 * Delete a playback ID from a live stream
220
 * @param liveStreamId - The live stream identifier
221
 * @param playbackId - The playback ID to delete
222
 * @returns Promise that resolves when deletion is complete
223
 */
224
deletePlaybackId(liveStreamId: string, playbackId: string): Promise<void>;
225
```
226

227
### Simulcast Management
228

229
Add and manage simulcast targets for broadcasting to multiple platforms simultaneously.
230

231
```typescript { .api }
232
/**
233
 * Create a simulcast target for a live stream
234
 * @param liveStreamId - The live stream identifier
235
 * @param body - Simulcast target creation parameters
236
 * @returns Promise resolving to the created simulcast target
237
 */
238
createSimulcastTarget(
239
  liveStreamId: string,
240
  body: LiveStreamCreateSimulcastTargetParams
241
): Promise<SimulcastTarget>;
242

243
interface LiveStreamCreateSimulcastTargetParams {
244
  /** RTMP URL for the simulcast target */
245
  url: string;
246
  /** Stream key for the target platform */
247
  stream_key?: string;
248
  /** Passthrough data */
249
  passthrough?: string;
250
}
251

252
interface SimulcastTarget {
253
  /** Simulcast target identifier */
254
  id: string;
255
  /** Target RTMP URL */
256
  url: string;
257
  /** Current status of the simulcast */
258
  status?: 'idle' | 'starting' | 'broadcasting' | 'errored';
259
  /** Error details if status is errored */
260
  error_severity?: 'normal' | 'fatal';
261
}
262

263
/**
264
 * Retrieve simulcast target details
265
 * @param liveStreamId - The live stream identifier
266
 * @param simulcastTargetId - The simulcast target identifier
267
 * @returns Promise resolving to simulcast target details
268
 */
269
retrieveSimulcastTarget(
270
  liveStreamId: string,
271
  simulcastTargetId: string
272
): Promise<SimulcastTarget>;
273

274
/**
275
 * Delete a simulcast target
276
 * @param liveStreamId - The live stream identifier
277
 * @param simulcastTargetId - The simulcast target identifier
278
 * @returns Promise that resolves when deletion is complete
279
 */
280
deleteSimulcastTarget(liveStreamId: string, simulcastTargetId: string): Promise<void>;
281
```
282

283
### Subtitle Configuration
284

285
Configure subtitle generation and embedding for live streams.
286

287
```typescript { .api }
288
/**
289
 * Update embedded subtitle settings for a live stream
290
 * @param liveStreamId - The live stream identifier
291
 * @param body - Embedded subtitle update parameters
292
 * @returns Promise resolving to updated live stream
293
 */
294
updateEmbeddedSubtitles(
295
  liveStreamId: string,
296
  body: LiveStreamUpdateEmbeddedSubtitlesParams
297
): Promise<LiveStream>;
298

299
interface LiveStreamUpdateEmbeddedSubtitlesParams {
300
  /** Array of embedded subtitle configurations */
301
  embedded_subtitles?: Array<LiveStreamEmbeddedSubtitleSettings>;
302
}
303

304
/**
305
 * Update generated subtitle settings for a live stream
306
 * @param liveStreamId - The live stream identifier
307
 * @param body - Generated subtitle update parameters
308
 * @returns Promise resolving to updated live stream
309
 */
310
updateGeneratedSubtitles(
311
  liveStreamId: string,
312
  body: LiveStreamUpdateGeneratedSubtitlesParams
313
): Promise<LiveStream>;
314

315
interface LiveStreamUpdateGeneratedSubtitlesParams {
316
  /** Array of generated subtitle configurations */
317
  generated_subtitles?: Array<LiveStreamGeneratedSubtitleSettings>;
318
}
319

320
interface LiveStreamEmbeddedSubtitleSettings {
321
  /** Display name for the subtitle track */
322
  name?: string;
323
  /** Language code (ISO 639-1) */
324
  language_code?: string;
325
  /** Passthrough data */
326
  passthrough?: string;
327
}
328

329
interface LiveStreamGeneratedSubtitleSettings {
330
  /** Display name for the subtitle track */
331
  name?: string;
332
  /** Language code for transcription */
333
  language_code?: string;
334
  /** Transcription vocabulary ID */
335
  transcription_vocabulary_id?: string;
336
  /** Passthrough data */
337
  passthrough?: string;
338
}
339
```
340

341
### Asset Recording Settings
342

343
Configure how recorded assets are created from live streams.
344

345
```typescript { .api }
346
/**
347
 * Update new asset settings for static renditions
348
 * @param liveStreamId - The live stream identifier
349
 * @param body - Static rendition update parameters
350
 * @returns Promise resolving to updated live stream
351
 */
352
updateNewAssetSettingsStaticRenditions(
353
  liveStreamId: string,
354
  body: LiveStreamUpdateNewAssetSettingsStaticRenditionsParams
355
): Promise<LiveStream>;
356

357
interface LiveStreamUpdateNewAssetSettingsStaticRenditionsParams {
358
  /** Static rendition settings for recorded assets */
359
  new_asset_settings?: {
360
    mp4_support?: Mp4Support;
361
    normalize_audio?: boolean;
362
    playback_policies?: Array<PlaybackPolicy>;
363
  };
364
}
365
```
366

367
## Types
368

369
```typescript { .api }
370
interface RTMPSettings {
371
  /** RTMP stream URL */
372
  stream_url?: string;
373
  /** RTMP stream key */
374
  stream_key?: string;
375
}
376

377
interface SRTSettings {
378
  /** SRT endpoint */
379
  endpoint?: string;
380
  /** SRT passphrase */
381
  passphrase?: string;
382
}
383

384
interface CreateSimulcastTargetRequest {
385
  /** Target RTMP URL */
386
  url: string;
387
  /** Stream key for target */
388
  stream_key?: string;
389
  /** Passthrough data */
390
  passthrough?: string;
391
}
392

393
type Mp4Support = 'none' | 'standard' | 'capped-1080p';
394
type PlaybackPolicy = 'public' | 'signed' | 'drm';
395

396
interface PlaybackID {
397
  id: string;
398
  policy: PlaybackPolicy;
399
  drm_configuration_id?: string;
400
}
401
```