0
# Video Assets
1

2
Comprehensive video asset management including creation, processing, playback configuration, and metadata handling. Assets represent video files in the Mux platform with associated playback policies and processing options.
3

4
## Imports
5

6
```typescript
7
import { Mux } from "@mux/mux-node";
8

9
const mux = new Mux({
10
  tokenId: process.env.MUX_TOKEN_ID,
11
  tokenSecret: process.env.MUX_TOKEN_SECRET
12
});
13

14
// Access video assets API
15
const { assets } = mux.video;
16
```
17

18
## Capabilities
19

20
### Asset Creation
21

22
Create video assets from various input sources including URLs, direct uploads, and live stream recordings.
23

24
```typescript { .api }
25
/**
26
 * Create a new video asset
27
 * @param body - Asset creation parameters
28
 * @returns Promise resolving to the created asset
29
 */
30
create(body: AssetCreateParams): Promise<Asset>;
31

32
interface AssetCreateParams {
33
  /** Input sources for the asset */
34
  inputs: Array<InputSettings>;
35
  /** Array of advanced playback policy objects (required for DRM playback IDs) */
36
  advanced_playback_policies?: Array<AdvancedPlaybackPolicy>;
37
  /** If the created asset is a clip, controls whether overlays are copied from the source asset */
38
  copy_overlays?: boolean;
39
  /** @deprecated Use video_quality instead. Encoding tier: 'smart' | 'baseline' | 'premium' */
40
  encoding_tier?: 'smart' | 'baseline' | 'premium';
41
  /** Master file access settings */
42
  master_access?: 'none' | 'temporary';
43
  /** Max resolution tier for encoding, storage, and streaming (defaults to '1080p') */
44
  max_resolution_tier?: '1080p' | '1440p' | '2160p';
45
  /** Customer provided metadata about this asset */
46
  meta?: Record<string, string>;
47
  /** @deprecated Use static_renditions API instead. MP4 support level */
48
  mp4_support?: 'none' | 'standard' | 'capped-1080p' | 'audio-only' | 'audio-only,capped-1080p';
49
  /** Normalize the audio track loudness level (only for on-demand assets) */
50
  normalize_audio?: boolean;
51
  /** Custom passthrough data (max 255 characters) */
52
  passthrough?: string;
53
  /** @deprecated */
54
  per_title_encode?: boolean;
55
  /** Playback policies for the asset: 'public' | 'signed' */
56
  playback_policies?: Array<PlaybackPolicy>;
57
  /** Array of static renditions to create for this asset */
58
  static_renditions?: Array<StaticRendition>;
59
  /** Test mode flag - creates watermarked 10s asset deleted after 24hrs */
60
  test?: boolean;
61
  /** Video quality level: 'basic' | 'plus' | 'premium' (replaces encoding_tier) */
62
  video_quality?: 'basic' | 'plus' | 'premium';
63
}
64

65
interface InputSettings {
66
  /** URL of the input video file */
67
  url?: string;
68
  /** Overlay settings for the input */
69
  overlay_settings?: OverlaySettings;
70
  /** Generated subtitle settings */
71
  generated_subtitles?: Array<GeneratedSubtitleSettings>;
72
  /** Start time offset in seconds */
73
  start_time?: number;
74
  /** End time in seconds */
75
  end_time?: number;
76
  /** Asset type specification */
77
  type?: string;
78
}
79

80
interface Asset {
81
  /** Unique identifier for the asset */
82
  id: string;
83
  /** Creation timestamp (Unix timestamp in seconds) */
84
  created_at: string;
85
  /** @deprecated Use video_quality instead. Encoding tier */
86
  encoding_tier: 'smart' | 'baseline' | 'premium';
87
  /** Master file access setting */
88
  master_access: 'temporary' | 'none';
89
  /** Max resolution tier for encoding, storage, and streaming */
90
  max_resolution_tier: '1080p' | '1440p' | '2160p';
91
  /** Detailed state information about the asset ingest process */
92
  progress: AssetProgress;
93
  /** Current status of asset processing */
94
  status: 'preparing' | 'ready' | 'errored';
95
  /** Aspect ratio in the form of 'width:height' (e.g., '16:9') */
96
  aspect_ratio?: string;
97
  /** Duration in seconds (max 12 hours) */
98
  duration?: number;
99
  /** Object describing any errors during processing */
100
  errors?: AssetErrors;
101
  /** The type of ingest used to create the asset */
102
  ingest_type?: 'on_demand_url' | 'on_demand_direct_upload' | 'on_demand_clip' | 'live_rtmp' | 'live_srt';
103
  /** Indicates if the live stream that created this asset is currently active */
104
  is_live?: boolean;
105
  /** Unique identifier for the live stream (when created from live stream) */
106
  live_stream_id?: string;
107
  /** Current status of Master Access and link to Master MP4 file when ready */
108
  master?: AssetMaster;
109
  /** Maximum frame rate stored for the asset (-1 if cannot be determined) */
110
  max_stored_frame_rate?: number;
111
  /** @deprecated Use resolution_tier instead. Maximum resolution stored */
112
  max_stored_resolution?: 'Audio only' | 'SD' | 'HD' | 'FHD' | 'UHD';
113
  /** Customer provided metadata */
114
  meta?: Record<string, string>;
115
  /** @deprecated MP4 support level */
116
  mp4_support?: 'standard' | 'none' | 'capped-1080p' | 'audio-only' | 'audio-only,capped-1080p';
117
  /** Object containing reasons the input file is non-standard */
118
  non_standard_input_reasons?: AssetNonStandardInputReasons;
119
  /** Normalize the audio track loudness level */
120
  normalize_audio?: boolean;
121
  /** Custom passthrough data (max 255 characters) */
122
  passthrough?: string;
123
  /** @deprecated */
124
  per_title_encode?: boolean;
125
  /** Array of playback IDs for the asset */
126
  playback_ids?: Array<PlaybackID>;
127
  /** Array of individual live stream recording sessions */
128
  recording_times?: Array<AssetRecordingTime>;
129
  /** Resolution tier the asset was ingested at (affects billing) */
130
  resolution_tier?: 'audio-only' | '720p' | '1080p' | '1440p' | '2160p';
131
  /** Asset ID of the video used as source for creating the clip */
132
  source_asset_id?: string;
133
  /** Current status of any static renditions (MP4s) */
134
  static_renditions?: AssetStaticRenditions;
135
  /** Test asset flag */
136
  test?: boolean;
137
  /** Array of tracks (subtitles/audio/video) */
138
  tracks?: Array<Track>;
139
  /** Unique identifier for the Direct Upload (when created from direct upload) */
140
  upload_id?: string;
141
  /** Video quality level: 'basic' | 'plus' | 'premium' */
142
  video_quality?: 'basic' | 'plus' | 'premium';
143
}
144
```
145

146
**Usage Examples:**
147

148
```typescript
149
// Create asset from URL
150
const asset = await mux.video.assets.create({
151
  inputs: [{ url: "https://example.com/video.mp4" }],
152
  playback_policies: ["public"],
153
  mp4_support: "standard",
154
});
155

156
// Create asset with advanced options
157
const asset = await mux.video.assets.create({
158
  inputs: [
159
    {
160
      url: "https://example.com/video.mp4",
161
      start_time: 10.5,
162
      end_time: 120.0,
163
      generated_subtitles: [
164
        {
165
          language_code: "en",
166
          name: "English",
167
        },
168
      ],
169
    },
170
  ],
171
  playback_policies: ["signed"],
172
  normalize_audio: true,
173
  test: false,
174
});
175
```
176

177
### Asset Retrieval and Updates
178

179
Retrieve asset details and update asset properties after creation.
180

181
```typescript { .api }
182
/**
183
 * Retrieve asset details
184
 * @param assetId - The asset identifier
185
 * @returns Promise resolving to asset details
186
 */
187
retrieve(assetId: string): Promise<Asset>;
188

189
/**
190
 * Update asset properties
191
 * @param assetId - The asset identifier
192
 * @param body - Update parameters
193
 * @returns Promise resolving to updated asset
194
 */
195
update(assetId: string, body: AssetUpdateParams): Promise<Asset>;
196

197
interface AssetUpdateParams {
198
  /** Updated playback policy */
199
  playback_policies?: Array<PlaybackPolicy>;
200
  /** Master file access settings */
201
  master_access?: MasterAccess;
202
  /** MP4 support settings */
203
  mp4_support?: Mp4Support;
204
  /** Custom passthrough data (max 255 characters) */
205
  passthrough?: string;
206
}
207

208
/**
209
 * List assets with optional filtering and pagination
210
 * @param query - Listing parameters
211
 * @returns Paginated list of assets
212
 */
213
list(query?: AssetListParams): PagePromise<AssetsBasePage, Asset>;
214

215
interface AssetListParams extends BasePageParams {
216
  /** Filter by upload ID */
217
  upload_id?: string;
218
  /** Filter by live stream ID */
219
  live_stream_id?: string;
220
}
221
```
222

223
### Asset Deletion
224

225
Permanently delete video assets and associated data.
226

227
```typescript { .api }
228
/**
229
 * Delete an asset permanently
230
 * @param assetId - The asset identifier
231
 * @returns Promise that resolves when deletion is complete
232
 */
233
delete(assetId: string): Promise<void>;
234
```
235

236
### Playback ID Management
237

238
Manage playback IDs for controlling access to video assets.
239

240
```typescript { .api }
241
/**
242
 * Create a playback ID for an asset
243
 * @param assetId - The asset identifier
244
 * @param body - Playback ID creation parameters
245
 * @returns Promise resolving to the created playback ID
246
 */
247
createPlaybackId(
248
  assetId: string,
249
  body: AssetCreatePlaybackIDParams
250
): Promise<PlaybackID>;
251

252
interface AssetCreatePlaybackIDParams {
253
  /** Access policy for the playback ID */
254
  policy: PlaybackPolicy;
255
  /** DRM configuration ID (required for DRM policy) */
256
  drm_configuration_id?: string;
257
}
258

259
/**
260
 * Retrieve playback ID details
261
 * @param assetId - The asset identifier
262
 * @param playbackId - The playback ID
263
 * @returns Promise resolving to playback ID details
264
 */
265
retrievePlaybackId(assetId: string, playbackId: string): Promise<PlaybackID>;
266

267
/**
268
 * Delete a playback ID
269
 * @param assetId - The asset identifier
270
 * @param playbackId - The playback ID to delete
271
 * @returns Promise that resolves when deletion is complete
272
 */
273
deletePlaybackId(assetId: string, playbackId: string): Promise<void>;
274
```
275

276
### Static Renditions (MP4)
277

278
Create and manage MP4 renditions for offline downloads and specific use cases.
279

280
```typescript { .api }
281
/**
282
 * Create a static MP4 rendition
283
 * @param assetId - The asset identifier
284
 * @param body - Static rendition parameters
285
 * @returns Promise resolving to the created rendition response
286
 */
287
createStaticRendition(
288
  assetId: string,
289
  body: AssetCreateStaticRenditionParams
290
): Promise<AssetCreateStaticRenditionResponse>;
291

292
interface AssetCreateStaticRenditionParams {
293
  /** Resolution for the static rendition */
294
  resolution: 'highest' | 'audio-only' | '2160p' | '1440p' | '1080p' | '720p' | '540p' | '480p' | '360p' | '270p';
295
  /** Arbitrary user-supplied metadata (max 255 characters) */
296
  passthrough?: string;
297
}
298

299
interface AssetCreateStaticRenditionResponse {
300
  /** Static rendition identifier */
301
  id: string;
302
  /** Current status of rendition creation */
303
  status: 'preparing' | 'ready' | 'errored';
304
}
305

306
/**
307
 * Delete a static rendition
308
 * @param assetId - The asset identifier
309
 * @param staticRenditionId - The static rendition ID
310
 * @returns Promise that resolves when deletion is complete
311
 */
312
deleteStaticRendition(assetId: string, staticRenditionId: string): Promise<void>;
313
```
314

315
### Track Management
316

317
Add and manage subtitle and audio tracks for video assets.
318

319
```typescript { .api }
320
/**
321
 * Add a track (subtitle or audio) to an asset
322
 * @param assetId - The asset identifier
323
 * @param body - Track creation parameters
324
 * @returns Promise resolving to the created track
325
 */
326
createTrack(assetId: string, body: AssetCreateTrackParams): Promise<Track>;
327

328
interface AssetCreateTrackParams {
329
  /** URL of the track file */
330
  url: string;
331
  /** Track type */
332
  type: 'text' | 'audio';
333
  /** Text track type (for subtitle tracks) */
334
  text_type?: 'subtitles';
335
  /** Language code (ISO 639-1) */
336
  language_code?: string;
337
  /** Display name for the track */
338
  name?: string;
339
  /** Closed captions flag */
340
  closed_captions?: boolean;
341
  /** Passthrough data */
342
  passthrough?: string;
343
}
344

345
interface Track {
346
  /** Track identifier */
347
  id: string;
348
  /** Track type */
349
  type: 'text' | 'audio';
350
  /** Duration in seconds */
351
  duration?: number;
352
  /** Maximum width (for video tracks) */
353
  max_width?: number;
354
  /** Maximum height (for video tracks) */
355
  max_height?: number;
356
  /** Maximum frame rate */
357
  max_frame_rate?: number;
358
}
359

360
/**
361
 * Delete a track
362
 * @param assetId - The asset identifier
363
 * @param trackId - The track identifier
364
 * @returns Promise that resolves when deletion is complete
365
 */
366
deleteTrack(assetId: string, trackId: string): Promise<void>;
367
```
368

369
### Subtitle Generation
370

371
Automatically generate subtitles for video assets using AI transcription.
372

373
```typescript { .api }
374
/**
375
 * Generate subtitles automatically for an asset
376
 * @param assetId - The asset identifier
377
 * @param trackId - The audio track identifier to generate subtitles from
378
 * @param body - Subtitle generation parameters
379
 * @returns Promise resolving to the subtitle generation response
380
 */
381
generateSubtitles(
382
  assetId: string,
383
  trackId: string,
384
  body: AssetGenerateSubtitlesParams
385
): Promise<AssetGenerateSubtitlesResponse>;
386

387
interface AssetGenerateSubtitlesParams {
388
  /** Array of subtitle configurations to generate */
389
  generated_subtitles: Array<GeneratedSubtitle>;
390
}
391

392
interface GeneratedSubtitle {
393
  /** Language code for subtitle generation */
394
  language_code?: 'en' | 'es' | 'it' | 'pt' | 'de' | 'fr' | 'pl' | 'ru' | 'nl' | 'ca' | 'tr' | 'sv' | 'uk' | 'no' | 'fi' | 'sk' | 'el' | 'cs' | 'hr' | 'da' | 'ro' | 'bg';
395
  /** Display name for the generated subtitles */
396
  name?: string;
397
  /** Arbitrary metadata (max 255 characters) */
398
  passthrough?: string;
399
}
400

401
interface AssetGenerateSubtitlesResponse {
402
  /** Generated track identifier */
403
  id: string;
404
  /** Current status of subtitle generation */
405
  status: 'preparing' | 'ready' | 'errored';
406
}
407
```
408

409
### Input Information
410

411
Retrieve detailed metadata about the input source of an asset.
412

413
```typescript { .api }
414
/**
415
 * Retrieve input information for an asset
416
 * @param assetId - The asset identifier
417
 * @returns Promise resolving to input information
418
 */
419
retrieveInputInfo(assetId: string): Promise<AssetRetrieveInputInfoResponse>;
420

421
interface AssetRetrieveInputInfoResponse {
422
  /** Input file information */
423
  data?: Array<InputInfo>;
424
}
425

426
interface InputInfo {
427
  /** File settings used during ingestion */
428
  settings?: InputSettings;
429
  /** File information extracted from the input */
430
  file?: FileInfo;
431
}
432

433
interface FileInfo {
434
  /** Container format */
435
  container_format?: string;
436
  /** Array of video streams */
437
  video_streams?: Array<VideoStream>;
438
  /** Array of audio streams */
439
  audio_streams?: Array<AudioStream>;
440
}
441
```
442

443
### Master File Access
444

445
Control access to the original master file for downloading or processing.
446

447
```typescript { .api }
448
/**
449
 * Update master file access settings
450
 * @param assetId - The asset identifier
451
 * @param body - Master access parameters
452
 * @returns Promise resolving to updated asset
453
 */
454
updateMasterAccess(
455
  assetId: string,
456
  body: AssetUpdateMasterAccessParams
457
): Promise<Asset>;
458

459
interface AssetUpdateMasterAccessParams {
460
  /** Master file access setting */
461
  master_access: MasterAccess;
462
}
463

464
type MasterAccess = 'temporary' | 'none';
465
```
466

467
### MP4 Support Configuration
468

469
Enable or disable MP4 rendition generation for assets.
470

471
```typescript { .api }
472
/**
473
 * Update MP4 support settings for an asset
474
 * @param assetId - The asset identifier
475
 * @param body - MP4 support parameters
476
 * @returns Promise resolving to updated asset
477
 */
478
updateMP4Support(
479
  assetId: string,
480
  body: AssetUpdateMP4SupportParams
481
): Promise<Asset>;
482

483
interface AssetUpdateMP4SupportParams {
484
  /** MP4 support level */
485
  mp4_support: Mp4Support;
486
}
487

488
type Mp4Support = 'none' | 'standard' | 'capped-1080p';
489
```
490

491
## Types
492

493
```typescript { .api }
494
type PlaybackPolicy = 'public' | 'signed' | 'drm';
495

496
interface PlaybackID {
497
  id: string;
498
  policy: PlaybackPolicy;
499
  drm_configuration_id?: string;
500
}
501

502
interface GeneratedSubtitleSettings {
503
  language_code?: string;
504
  name?: string;
505
  passthrough?: string;
506
}
507

508
interface OverlaySettings {
509
  vertical_align?: 'top' | 'middle' | 'bottom';
510
  vertical_margin?: string;
511
  horizontal_align?: 'left' | 'center' | 'right';
512
  horizontal_margin?: string;
513
  width?: string;
514
  height?: string;
515
  opacity?: string;
516
}
517

518
interface VideoStream {
519
  width?: number;
520
  height?: number;
521
  frame_rate?: number;
522
  sample_aspect_ratio?: string;
523
  display_aspect_ratio?: string;
524
  pixel_format?: string;
525
}
526

527
interface AudioStream {
528
  channels?: number;
529
  sample_rate?: number;
530
  bit_depth?: number;
531
  channel_layout?: string;
532
}
533

534
interface AdvancedPlaybackPolicy {
535
  /** DRM configuration ID (must only be set when policy is 'drm') */
536
  drm_configuration_id?: string;
537
  /** Playback policy: 'public' | 'signed' | 'drm' */
538
  policy: 'public' | 'signed' | 'drm';
539
}
540

541
interface StaticRendition {
542
  /** Resolution for the static rendition */
543
  resolution: 'highest' | 'audio-only' | '2160p' | '1440p' | '1080p' | '720p' | '540p' | '480p' | '360p' | '270p';
544
  /** Arbitrary user-supplied metadata (max 255 characters) */
545
  passthrough?: string;
546
}
547

548
interface AssetProgress {
549
  /** Estimated completion percentage (0-100, or -1 when in 'live' or 'errored' state) */
550
  progress: number;
551
  /** Detailed state: 'ingesting' | 'transcoding' | 'completed' | 'live' | 'errored' */
552
  state: 'ingesting' | 'transcoding' | 'completed' | 'live' | 'errored';
553
}
554

555
interface AssetErrors {
556
  /** Array of error messages */
557
  messages?: Array<string>;
558
  /** Error type */
559
  type?: string;
560
}
561

562
interface AssetMaster {
563
  /** URL to the master MP4 file when available */
564
  url?: string;
565
  /** Status of master access */
566
  status?: 'ready' | 'preparing';
567
}
568

569
interface AssetNonStandardInputReasons {
570
  /** Array of reasons the input is non-standard */
571
  audio_codec?: string;
572
  audio_edit_list?: string;
573
  audio_track_count?: number;
574
  pixel_aspect_ratio?: string;
575
  unsupported_pixel_format?: string;
576
  video_codec?: string;
577
  video_edit_list?: string;
578
  video_frame_rate?: string;
579
  video_track_count?: number;
580
}
581

582
interface AssetRecordingTime {
583
  /** Start time of the recording session */
584
  started_at?: string;
585
  /** Duration of the recording session in seconds */
586
  duration?: number;
587
  /** Type of recording: 'content' | 'slate' */
588
  type?: 'content' | 'slate';
589
}
590

591
interface AssetStaticRenditions {
592
  /** Array of file objects */
593
  files?: Array<AssetStaticRenditionFile>;
594
  /** Status of downloadable MP4 versions */
595
  status?: 'ready' | 'preparing' | 'disabled' | 'errored';
596
}
597

598
interface AssetStaticRenditionFile {
599
  /** Static rendition identifier */
600
  name?: string;
601
  /** File extension */
602
  ext?: string;
603
  /** File size in bytes */
604
  filesize?: number;
605
  /** Width in pixels */
606
  width?: number;
607
  /** Height in pixels */
608
  height?: number;
609
  /** Bitrate in bits per second */
610
  bitrate?: number;
611
}
612
```