0
# Video Playback
1

2
Direct access to playback files and media resources for custom video player implementations. Provides HLS playlists, static renditions, thumbnails, storyboards, transcripts, and animated content for building advanced video experiences.
3

4
## Capabilities
5

6
### HLS Playlist Access
7

8
Retrieve HLS (HTTP Live Streaming) playlists with customizable playback behavior.
9

10
```typescript { .api }
11
/**
12
 * Fetch HLS playlist for video playback
13
 * @param playbackId - Playback ID of the video asset
14
 * @param query - Optional playback behavior parameters
15
 * @returns Promise resolving to Response containing m3u8 playlist
16
 */
17
hls(
18
  playbackId: string,
19
  query?: PlaybackHlsParams,
20
  options?: Core.RequestOptions
21
): Core.APIPromise<Response>;
22

23
interface PlaybackHlsParams {
24
  /** Start time for instant clipping (seconds) */
25
  asset_start_time?: number;
26
  /** End time for instant clipping (seconds) */
27
  asset_end_time?: number;
28
  /** Default subtitle language (BCP47 code) */
29
  default_subtitles_lang?: string;
30
  /** Exclude EXT-X-PROGRAM-DATE-TIME tags */
31
  exclude_pdt?: boolean;
32
  /** Maximum resolution in manifest */
33
  max_resolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p';
34
  /** Minimum resolution in manifest */
35
  min_resolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p';
36
  /** Live stream end time for clipping (epoch timestamp) */
37
  program_end_time?: number;
38
  /** Live stream start time for clipping (epoch timestamp) */
39
  program_start_time?: number;
40
  /** Include redundant delivery streams */
41
  redundant_streams?: boolean;
42
  /** Order renditions by quality */
43
  rendition_order?: 'desc';
44
  /** Enable Roku timeline hover previews */
45
  roku_trick_play?: boolean;
46
  /** Signed JWT token for secure playback */
47
  TOKEN?: string;
48
}
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import Mux from "@mux/mux-node";
55

56
const mux = new Mux({
57
  tokenId: process.env.MUX_TOKEN_ID,
58
  tokenSecret: process.env.MUX_TOKEN_SECRET,
59
});
60

61
// Basic HLS playlist retrieval
62
const playlistResponse = await mux.video.playback.hls("PLAYBACK_ID");
63
const playlistContent = await playlistResponse.text();
64
console.log("HLS Playlist:", playlistContent);
65

66
// HLS with quality restrictions and features
67
const customPlaylist = await mux.video.playback.hls("PLAYBACK_ID", {
68
  max_resolution: "1080p",
69
  min_resolution: "480p",
70
  redundant_streams: true,
71
  rendition_order: "desc"
72
});
73

74
// Secure HLS with JWT token
75
const securePlaylist = await mux.video.playback.hls("PLAYBACK_ID", {
76
  TOKEN: "jwt_token_here"
77
});
78

79
// Instant clipping (extract segment from video)
80
const clippedPlaylist = await mux.video.playback.hls("PLAYBACK_ID", {
81
  asset_start_time: 30,   // Start at 30 seconds
82
  asset_end_time: 120     // End at 2 minutes
83
});
84
```
85

86
### Static Rendition Access
87

88
Direct access to static MP4/M4A files for download or custom playback.
89

90
```typescript { .api }
91
/**
92
 * Fetch static video/audio rendition
93
 * @param playbackId - Playback ID of the video asset
94
 * @param filename - Static rendition filename
95
 * @param query - Optional parameters
96
 * @returns Promise resolving to Response containing media file
97
 */
98
staticRendition(
99
  playbackId: string,
100
  filename: 'capped-1080p.mp4' | 'audio.m4a' | 'low.mp4' | 'medium.mp4' | 'high.mp4',
101
  query?: PlaybackStaticRenditionParams,
102
  options?: Core.RequestOptions
103
): Core.APIPromise<Response>;
104

105
interface PlaybackStaticRenditionParams {
106
  /** Signed JWT token for secure playback */
107
  TOKEN?: string;
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
// Download high-quality MP4
115
const mp4Response = await mux.video.playback.staticRendition(
116
  "PLAYBACK_ID",
117
  "capped-1080p.mp4"
118
);
119
const mp4Blob = await mp4Response.blob();
120

121
// Get audio-only version
122
const audioResponse = await mux.video.playback.staticRendition(
123
  "PLAYBACK_ID",
124
  "audio.m4a"
125
);
126

127
// Various quality levels
128
const lowQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "low.mp4");
129
const mediumQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "medium.mp4");
130
const highQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "high.mp4");
131
```
132

133
### Thumbnail Generation
134

135
Generate static thumbnail images from video content with transformation options.
136

137
```typescript { .api }
138
/**
139
 * Generate thumbnail image from video
140
 * @param playbackId - Playback ID of the video asset
141
 * @param extension - Image format
142
 * @param query - Optional transformation parameters
143
 * @returns Promise resolving to Response containing image
144
 */
145
thumbnail(
146
  playbackId: string,
147
  extension: 'jpg' | 'png' | 'webp',
148
  query?: PlaybackThumbnailParams,
149
  options?: Core.RequestOptions
150
): Core.APIPromise<Response>;
151

152
interface PlaybackThumbnailParams {
153
  /** Image fitting mode */
154
  fit_mode?: 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'pad';
155
  /** Flip horizontally */
156
  flip_h?: boolean;
157
  /** Flip vertically */
158
  flip_v?: boolean;
159
  /** Image height in pixels */
160
  height?: number;
161
  /** Get latest frame from live stream */
162
  latest?: boolean;
163
  /** Time for live stream clipping (epoch timestamp) */
164
  program_time?: number;
165
  /** Rotation angle */
166
  rotate?: 90 | 180 | 270;
167
  /** Time to capture thumbnail (seconds) */
168
  time?: number;
169
  /** Signed JWT token for secure playback */
170
  TOKEN?: string;
171
  /** Image width in pixels */
172
  width?: number;
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
// Basic thumbnail at video midpoint
180
const thumbnailResponse = await mux.video.playback.thumbnail("PLAYBACK_ID", "jpg");
181
const thumbnailBlob = await thumbnailResponse.blob();
182

183
// Thumbnail at specific time with custom dimensions
184
const customThumbnail = await mux.video.playback.thumbnail("PLAYBACK_ID", "jpg", {
185
  time: 30,        // 30 seconds into video
186
  width: 480,
187
  height: 270,
188
  fit_mode: "crop"
189
});
190

191
// Latest frame from live stream
192
const liveThumbnail = await mux.video.playback.thumbnail("LIVE_PLAYBACK_ID", "jpg", {
193
  latest: true
194
});
195

196
// Transformed thumbnail
197
const rotatedThumbnail = await mux.video.playback.thumbnail("PLAYBACK_ID", "png", {
198
  rotate: 90,
199
  flip_h: true,
200
  width: 300,
201
  height: 300,
202
  fit_mode: "smartcrop"
203
});
204
```
205

206
### Animated GIF/WebP Generation
207

208
Create animated images from video segments for previews and social sharing.
209

210
```typescript { .api }
211
/**
212
 * Generate animated GIF or WebP from video segment
213
 * @param playbackId - Playback ID of the video asset
214
 * @param extension - Animation format
215
 * @param query - Optional animation parameters
216
 * @returns Promise resolving to Response containing animated image
217
 */
218
animated(
219
  playbackId: string,
220
  extension: 'gif' | 'webp',
221
  query?: PlaybackAnimatedParams,
222
  options?: Core.RequestOptions
223
): Core.APIPromise<Response>;
224

225
interface PlaybackAnimatedParams {
226
  /** Animation end time (seconds, max 10s duration) */
227
  end?: number;
228
  /** Frame rate (max 30 fps) */
229
  fps?: number;
230
  /** Animation height (max 640px) */
231
  height?: number;
232
  /** Animation start time (seconds) */
233
  start?: number;
234
  /** Signed JWT token for secure playback */
235
  TOKEN?: string;
236
  /** Animation width (max 640px) */
237
  width?: number;
238
}
239
```
240

241
**Usage Examples:**
242

243
```typescript
244
// Basic 5-second GIF from beginning
245
const animatedGif = await mux.video.playback.animated("PLAYBACK_ID", "gif");
246
const gifBlob = await animatedGif.blob();
247

248
// Custom segment with high frame rate
249
const customGif = await mux.video.playback.animated("PLAYBACK_ID", "gif", {
250
  start: 10,       // Start at 10 seconds
251
  end: 15,         // End at 15 seconds
252
  fps: 24,         // 24 fps
253
  width: 480,
254
  height: 270
255
});
256

257
// WebP format for better compression
258
const animatedWebP = await mux.video.playback.animated("PLAYBACK_ID", "webp", {
259
  start: 0,
260
  end: 3,
261
  fps: 15,
262
  width: 320
263
});
264
```
265

266
### Storyboard Images
267

268
Generate composite storyboard images for timeline hover previews.
269

270
```typescript { .api }
271
/**
272
 * Generate storyboard composite image
273
 * @param playbackId - Playback ID of the video asset
274
 * @param extension - Image format
275
 * @param query - Optional parameters
276
 * @returns Promise resolving to Response containing storyboard image
277
 */
278
storyboard(
279
  playbackId: string,
280
  extension: 'jpg' | 'png' | 'webp',
281
  query?: PlaybackStoryboardParams,
282
  options?: Core.RequestOptions
283
): Core.APIPromise<Response>;
284

285
interface PlaybackStoryboardParams {
286
  /** Start time for instant clipping */
287
  asset_start_time?: number;
288
  /** End time for instant clipping */
289
  asset_end_time?: number;
290
  /** Live stream end time for clipping */
291
  program_end_time?: number;
292
  /** Live stream start time for clipping */
293
  program_start_time?: number;
294
  /** Signed JWT token for secure playback */
295
  TOKEN?: string;
296
}
297
```
298

299
### Storyboard Metadata
300

301
Retrieve storyboard thumbnail coordinates and timing information.
302

303
```typescript { .api }
304
/**
305
 * Get storyboard metadata in JSON format
306
 * @param playbackId - Playback ID of the video asset
307
 * @param query - Optional parameters
308
 * @returns Promise resolving to JSON metadata string
309
 */
310
storyboardMeta(
311
  playbackId: string,
312
  query?: PlaybackStoryboardMetaParams,
313
  options?: Core.RequestOptions
314
): Core.APIPromise<string>;
315

316
/**
317
 * Get storyboard metadata in WebVTT format
318
 * @param playbackId - Playback ID of the video asset
319
 * @param query - Optional parameters
320
 * @returns Promise resolving to WebVTT metadata string
321
 */
322
storyboardVtt(
323
  playbackId: string,
324
  query?: PlaybackStoryboardVttParams,
325
  options?: Core.RequestOptions
326
): Core.APIPromise<string>;
327

328
interface PlaybackStoryboardMetaParams {
329
  /** Start time for instant clipping */
330
  asset_start_time?: number;
331
  /** End time for instant clipping */
332
  asset_end_time?: number;
333
  /** Storyboard image format preference */
334
  format?: 'jpg' | 'png' | 'webp';
335
  /** Live stream end time for clipping */
336
  program_end_time?: number;
337
  /** Live stream start time for clipping */
338
  program_start_time?: number;
339
  /** Signed JWT token for secure playback */
340
  TOKEN?: string;
341
}
342
```
343

344
**Usage Examples:**
345

346
```typescript
347
// Get storyboard image
348
const storyboardResponse = await mux.video.playback.storyboard("PLAYBACK_ID", "jpg");
349
const storyboardBlob = await storyboardResponse.blob();
350

351
// Get storyboard metadata for player integration
352
const metadataJson = await mux.video.playback.storyboardMeta("PLAYBACK_ID");
353
const metadata = JSON.parse(metadataJson);
354

355
// Get WebVTT format for HTML5 players
356
const webvttMetadata = await mux.video.playback.storyboardVtt("PLAYBACK_ID");
357
console.log("WebVTT metadata:", webvttMetadata);
358
```
359

360
### Text Track Access
361

362
Retrieve subtitle, caption, and transcript files.
363

364
```typescript { .api }
365
/**
366
 * Fetch WebVTT text track (subtitles/captions)
367
 * @param playbackId - Playback ID of the video asset
368
 * @param trackId - Text track identifier
369
 * @param query - Optional parameters
370
 * @returns Promise resolving to WebVTT content
371
 */
372
track(
373
  playbackId: string,
374
  trackId: string,
375
  query?: PlaybackTrackParams,
376
  options?: Core.RequestOptions
377
): Core.APIPromise<string>;
378

379
/**
380
 * Fetch plain text transcript
381
 * @param playbackId - Playback ID of the video asset
382
 * @param trackId - Transcript track identifier
383
 * @param query - Optional parameters
384
 * @returns Promise resolving to plain text transcript
385
 */
386
transcript(
387
  playbackId: string,
388
  trackId: string,
389
  query?: PlaybackTranscriptParams,
390
  options?: Core.RequestOptions
391
): Core.APIPromise<string>;
392

393
interface PlaybackTrackParams {
394
  /** Signed JWT token for secure playback */
395
  TOKEN?: string;
396
}
397

398
interface PlaybackTranscriptParams {
399
  /** Signed JWT token for secure playback */
400
  TOKEN?: string;
401
}
402
```
403

404
**Usage Examples:**
405

406
```typescript
407
// Get WebVTT subtitle track
408
const subtitleTrack = await mux.video.playback.track("PLAYBACK_ID", "TRACK_ID");
409
console.log("WebVTT subtitles:", subtitleTrack);
410

411
// Get plain text transcript
412
const transcript = await mux.video.playback.transcript("PLAYBACK_ID", "TRACK_ID");
413
console.log("Video transcript:", transcript);
414

415
// Secure access with JWT
416
const secureTranscript = await mux.video.playback.transcript("PLAYBACK_ID", "TRACK_ID", {
417
  TOKEN: "jwt_token_here"
418
});
419
```
420

421
## Types
422

423
```typescript { .api }
424
/** Response type aliases for text content */
425
type PlaybackStoryboardMetaResponse = string;
426
type PlaybackStoryboardVttResponse = string;
427
type PlaybackTrackResponse = string;
428
type PlaybackTranscriptResponse = string;
429

430
/** WebVTT parameter interfaces */
431
interface PlaybackStoryboardVttParams {
432
  asset_start_time?: number;
433
  asset_end_time?: number;
434
  program_end_time?: number;
435
  program_start_time?: number;
436
  TOKEN?: string;
437
}
438
```
439

440
## Integration Patterns
441

442
### Custom Video Player
443

444
```typescript
445
// Build custom video player with all playback resources
446
const playbackId = "PLAYBACK_ID";
447

448
// Get HLS playlist for adaptive streaming
449
const playlistResponse = await mux.video.playback.hls(playbackId, {
450
  max_resolution: "1080p",
451
  redundant_streams: true
452
});
453

454
// Get thumbnail for video poster
455
const posterResponse = await mux.video.playback.thumbnail(playbackId, "jpg", {
456
  time: 0,
457
  width: 1920,
458
  height: 1080
459
});
460

461
// Get storyboard for scrub bar previews
462
const storyboardResponse = await mux.video.playback.storyboard(playbackId, "jpg");
463
const storyboardMeta = await mux.video.playback.storyboardMeta(playbackId);
464

465
// Get subtitles
466
const subtitles = await mux.video.playback.track(playbackId, "subtitle_track_id");
467
```
468

469
### Social Media Integration
470

471
```typescript
472
// Generate content for social sharing
473
const socialGif = await mux.video.playback.animated("PLAYBACK_ID", "gif", {
474
  start: 30,
475
  end: 35,
476
  width: 480,
477
  height: 270,
478
  fps: 20
479
});
480

481
const socialThumbnail = await mux.video.playback.thumbnail("PLAYBACK_ID", "jpg", {
482
  time: 60,
483
  width: 1200,
484
  height: 630,
485
  fit_mode: "crop"
486
});
487
```
488

489
### Download Service
490

491
```typescript
492
// Provide download options
493
const downloadOptions = [
494
  { quality: "High", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "capped-1080p.mp4") },
495
  { quality: "Medium", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "medium.mp4") },
496
  { quality: "Low", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "low.mp4") },
497
  { quality: "Audio Only", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "audio.m4a") }
498
];
499
```
500

501
## Security Considerations
502

503
All playback methods support JWT token authentication for secure video access:
504

505
```typescript
506
// Generate secure tokens (see JWT signing documentation)
507
const playbackToken = await mux.jwt.signPlaybackId(playbackId, {
508
  exp: Math.floor(Date.now() / 1000) + 3600 // 1 hour expiry
509
});
510

511
// Use token with any playback method
512
const securePlaylist = await mux.video.playback.hls(playbackId, {
513
  TOKEN: playbackToken
514
});
515
```
516

517
## Best Practices
518

519
- **Format Selection**: Use WebP for better compression, JPEG for compatibility
520
- **Resolution Management**: Set appropriate max/min resolutions for bandwidth optimization
521
- **Caching**: Implement caching for thumbnails and storyboards to reduce API calls
522
- **Security**: Always use JWT tokens for sensitive content
523
- **Error Handling**: Handle network errors and implement retry logic for media requests