0
# Playback Control
1

2
Playback utilities and access control including playback IDs, restrictions, DRM configurations, and content delivery for secure video streaming.
3

4
## Capabilities
5

6
### Playback ID Management
7

8
Manage playback identifiers for controlling video access and security policies.
9

10
```typescript { .api }
11
/**
12
 * Retrieve playback ID information
13
 * @param playbackId - The playback ID
14
 * @returns Promise resolving to playback ID details
15
 */
16
retrieve(playbackId: string): Promise<PlaybackIDRetrieveResponse>;
17

18
interface PlaybackIDRetrieveResponse {
19
  /** Playback ID data */
20
  data?: PlaybackIDData;
21
}
22

23
interface PlaybackIDData {
24
  /** Playback ID */
25
  id: string;
26
  /** Access policy */
27
  policy: PlaybackPolicy;
28
  /** Associated object type */
29
  object?: {
30
    type: 'asset' | 'live_stream';
31
    id: string;
32
  };
33
  /** DRM configuration if applicable */
34
  drm_configuration_id?: string;
35
}
36
```
37

38
### Playback Restrictions
39

40
Create and manage access restrictions for playback content including referrer and user agent filtering.
41

42
```typescript { .api }
43
/**
44
 * Create a playback restriction
45
 * @param body - Restriction creation parameters
46
 * @returns Promise resolving to the created restriction
47
 */
48
create(body: PlaybackRestrictionCreateParams): Promise<PlaybackRestriction>;
49

50
interface PlaybackRestrictionCreateParams {
51
  /** Referrer domain restrictions (required) */
52
  referrer: ReferrerRestriction;
53
  /** User agent restrictions (required) */
54
  user_agent: UserAgentRestriction;
55
}
56

57
interface PlaybackRestriction {
58
  /** Restriction identifier */
59
  id: string;
60
  /** Referrer restrictions */
61
  referrer?: ReferrerRestriction;
62
  /** User agent restrictions */
63
  user_agent?: UserAgentRestriction;
64
  /** Creation timestamp */
65
  created_at: string;
66
}
67

68
interface ReferrerRestriction {
69
  /** Allowed referrer domains */
70
  allowed_domains?: Array<string>;
71
  /** Whether to allow requests with no referrer */
72
  allow_no_referrer?: boolean;
73
}
74

75
interface UserAgentRestriction {
76
  /** Whether to allow requests with no user agent */
77
  allow_no_user_agent?: boolean;
78
  /** Whether to allow requests from high-risk user agents */
79
  allow_high_risk_user_agent?: boolean;
80
}
81

82
/**
83
 * Update referrer restrictions
84
 * @param playbackRestrictionId - The restriction identifier
85
 * @param body - Referrer update parameters
86
 * @returns Promise resolving to updated restriction
87
 */
88
updateReferrer(
89
  playbackRestrictionId: string,
90
  body: PlaybackRestrictionUpdateReferrerParams
91
): Promise<PlaybackRestriction>;
92

93
/**
94
 * Update user agent restrictions
95
 * @param playbackRestrictionId - The restriction identifier
96
 * @param body - User agent update parameters
97
 * @returns Promise resolving to updated restriction
98
 */
99
updateUserAgent(
100
  playbackRestrictionId: string,
101
  body: PlaybackRestrictionUpdateUserAgentParams
102
): Promise<PlaybackRestriction>;
103
```
104

105
### DRM Configurations
106

107
Manage DRM (Digital Rights Management) configurations for protected content delivery.
108

109
```typescript { .api }
110
/**
111
 * Retrieve DRM configuration details
112
 * @param drmConfigurationId - The DRM configuration identifier
113
 * @returns Promise resolving to DRM configuration
114
 */
115
retrieve(drmConfigurationId: string): Promise<DRMConfiguration>;
116

117
/**
118
 * List DRM configurations
119
 * @param query - Listing parameters
120
 * @returns Paginated list of DRM configurations
121
 */
122
list(query?: DRMConfigurationListParams): PagePromise<DRMConfigurationsBasePage, DRMConfiguration>;
123

124
interface DRMConfiguration {
125
  /** DRM configuration identifier */
126
  id: string;
127
  /** DRM scheme type */
128
  scheme_id?: string;
129
  /** Content key policy */
130
  content_key_policy?: ContentKeyPolicy;
131
  /** License policy */
132
  license_policy?: LicensePolicy;
133
}
134

135
interface ContentKeyPolicy {
136
  /** Key policy identifier */
137
  id?: string;
138
  /** Policy name */
139
  name?: string;
140
}
141

142
interface LicensePolicy {
143
  /** License policy identifier */
144
  id?: string;
145
  /** Policy name */
146
  name?: string;
147
  /** Rental duration in seconds */
148
  rental_duration?: number;
149
  /** License duration in seconds */
150
  license_duration?: number;
151
}
152
```
153

154
### Media Content Delivery
155

156
Retrieve various media formats and content including HLS manifests, MP4 files, thumbnails, and storyboards.
157

158
```typescript { .api }
159
/**
160
 * Get HLS manifest for playback
161
 * @param playbackId - The playback ID
162
 * @param query - HLS parameters
163
 * @returns Promise resolving to HLS manifest response
164
 */
165
hls(playbackId: string, query?: PlaybackHlsParams): Promise<Response>;
166

167
interface PlaybackHlsParams {
168
  /** Token for signed playback IDs */
169
  token?: string;
170
  /** Additional query parameters */
171
  [key: string]: string | undefined;
172
}
173

174
/**
175
 * Get MP4 static rendition
176
 * @param playbackId - The playback ID
177
 * @param query - Static rendition parameters
178
 * @returns Promise resolving to MP4 file response
179
 */
180
staticRendition(playbackId: string, query?: PlaybackStaticRenditionParams): Promise<Response>;
181

182
interface PlaybackStaticRenditionParams {
183
  /** Token for signed playback IDs */
184
  token?: string;
185
  /** Download filename */
186
  download?: string;
187
}
188

189
/**
190
 * Get thumbnail image
191
 * @param playbackId - The playback ID
192
 * @param extension - Image format extension ('jpg' | 'png' | 'webp')
193
 * @param query - Thumbnail parameters
194
 * @returns Promise resolving to thumbnail image response
195
 */
196
thumbnail(playbackId: string, extension: 'jpg' | 'png' | 'webp', query?: PlaybackThumbnailParams): Promise<Response>;
197

198
interface PlaybackThumbnailParams {
199
  /** Token for signed playback IDs */
200
  token?: string;
201
  /** Thumbnail timestamp */
202
  time?: number;
203
  /** Image width */
204
  width?: number;
205
  /** Image height */
206
  height?: number;
207
  /** Fit mode */
208
  fit_mode?: 'preserve' | 'crop' | 'fill' | 'smartcrop';
209
}
210

211
/**
212
 * Get animated GIF or WebP
213
 * @param playbackId - The playback ID
214
 * @param extension - Image format extension ('gif' | 'webp')
215
 * @param query - Animated image parameters
216
 * @returns Promise resolving to animated image response
217
 */
218
animated(playbackId: string, extension: 'gif' | 'webp', query?: PlaybackAnimatedParams): Promise<Response>;
219

220
interface PlaybackAnimatedParams {
221
  /** Token for signed playback IDs */
222
  token?: string;
223
  /** Start time for animation */
224
  start?: number;
225
  /** End time for animation */
226
  end?: number;
227
  /** Image width */
228
  width?: number;
229
  /** Image height */
230
  height?: number;
231
  /** Frame rate */
232
  fps?: number;
233
}
234
```
235

236
### Storyboard Access
237

238
Retrieve storyboard images and metadata for video scrubbing and preview functionality.
239

240
```typescript { .api }
241
/**
242
 * Get storyboard images
243
 * @param playbackId - The playback ID
244
 * @param extension - Image format extension ('jpg' | 'png' | 'webp')
245
 * @param query - Storyboard parameters
246
 * @returns Promise resolving to storyboard response
247
 */
248
storyboard(playbackId: string, extension: 'jpg' | 'png' | 'webp', query?: PlaybackStoryboardParams): Promise<Response>;
249

250
/**
251
 * Get storyboard metadata
252
 * @param playbackId - The playback ID
253
 * @param query - Storyboard metadata parameters
254
 * @returns Promise resolving to storyboard metadata
255
 */
256
storyboardMeta(
257
  playbackId: string,
258
  query?: PlaybackStoryboardMetaParams
259
): Promise<PlaybackStoryboardMetaResponse>;
260

261
/**
262
 * Get storyboard VTT file
263
 * @param playbackId - The playback ID
264
 * @param query - Storyboard VTT parameters
265
 * @returns Promise resolving to VTT response
266
 */
267
storyboardVtt(
268
  playbackId: string,
269
  query?: PlaybackStoryboardVttParams
270
): Promise<PlaybackStoryboardVttResponse>;
271

272
interface PlaybackStoryboardMetaResponse {
273
  /** Storyboard metadata */
274
  data?: StoryboardMeta;
275
}
276

277
interface StoryboardMeta {
278
  /** Number of storyboard images */
279
  total_count?: number;
280
  /** Image width */
281
  width?: number;
282
  /** Image height */
283
  height?: number;
284
  /** Time interval between images */
285
  interval?: number;
286
}
287
```
288

289
### Track and Transcript Access
290

291
Retrieve subtitle tracks and transcript data for accessibility and content analysis.
292

293
```typescript { .api }
294
/**
295
 * Get track data (subtitles/audio)
296
 * @param playbackId - The playback ID
297
 * @param query - Track parameters
298
 * @returns Promise resolving to track response
299
 */
300
track(playbackId: string, query?: PlaybackTrackParams): Promise<PlaybackTrackResponse>;
301

302
interface PlaybackTrackParams {
303
  /** Token for signed playback IDs */
304
  token?: string;
305
  /** Track language code */
306
  language_code?: string;
307
  /** Track type */
308
  type?: 'subtitles' | 'captions';
309
}
310

311
interface PlaybackTrackResponse {
312
  /** Track data */
313
  data?: string;
314
}
315

316
/**
317
 * Get transcript data
318
 * @param playbackId - The playback ID
319
 * @param query - Transcript parameters
320
 * @returns Promise resolving to transcript response
321
 */
322
transcript(playbackId: string, query?: PlaybackTranscriptParams): Promise<PlaybackTranscriptResponse>;
323

324
interface PlaybackTranscriptParams {
325
  /** Token for signed playback IDs */
326
  token?: string;
327
  /** Language code for transcript */
328
  language_code?: string;
329
}
330

331
interface PlaybackTranscriptResponse {
332
  /** Transcript data */
333
  data?: TranscriptData;
334
}
335

336
interface TranscriptData {
337
  /** Transcript text */
338
  text?: string;
339
  /** Word-level timestamps */
340
  words?: Array<TranscriptWord>;
341
}
342

343
interface TranscriptWord {
344
  /** Word text */
345
  text: string;
346
  /** Start time in seconds */
347
  start: number;
348
  /** End time in seconds */
349
  end: number;
350
}
351
```
352

353
## Usage Examples
354

355
```typescript
356
// Get playback information
357
const playbackInfo = await mux.video.playbackIds.retrieve('your-playback-id');
358

359
// Create domain-based playback restriction
360
const restriction = await mux.video.playbackRestrictions.create({
361
  referrer: {
362
    allowed_domains: ['https://myapp.example.com', 'https://cdn.example.com'],
363
    allow_no_referrer: false,
364
  },
365
  user_agent: {
366
    allow_no_user_agent: false,
367
    allow_high_risk_user_agent: false,
368
  },
369
});
370

371
// Get HLS manifest with token
372
const hlsResponse = await mux.video.playback.hls('your-playback-id', {
373
  token: 'signed-playback-token',
374
});
375

376
// Get thumbnail at specific time
377
const thumbnail = await mux.video.playback.thumbnail('your-playback-id', 'jpg', {
378
  time: 30, // 30 seconds
379
  width: 640,
380
  height: 360,
381
  fit_mode: 'smartcrop',
382
});
383

384
// Get storyboard metadata
385
const storyboard = await mux.video.playback.storyboardMeta('your-playback-id');
386
console.log(`${storyboard.data?.total_count} storyboard images available`);
387
```
388

389
## Types
390

391
```typescript { .api }
392
type PlaybackPolicy = 'public' | 'signed' | 'drm';
393

394
interface PlaybackID {
395
  id: string;
396
  policy: PlaybackPolicy;
397
  drm_configuration_id?: string;
398
}
399

400
type FitMode = 'preserve' | 'crop' | 'fill' | 'smartcrop';
401
```