Video Assets

import { Mux } from "@mux/mux-node";

const mux = new Mux({
  tokenId: process.env.MUX_TOKEN_ID,
  tokenSecret: process.env.MUX_TOKEN_SECRET
});

// Access video assets API
const { assets } = mux.video;

/**
 * Create a new video asset
 * @param body - Asset creation parameters
 * @returns Promise resolving to the created asset
 */
create(body: AssetCreateParams): Promise<Asset>;

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

interface InputSettings {
  /** URL of the input video file */
  url?: string;
  /** Overlay settings for the input */
  overlay_settings?: OverlaySettings;
  /** Generated subtitle settings */
  generated_subtitles?: Array<GeneratedSubtitleSettings>;
  /** Start time offset in seconds */
  start_time?: number;
  /** End time in seconds */
  end_time?: number;
  /** Asset type specification */
  type?: string;
}

interface Asset {
  /** Unique identifier for the asset */
  id: string;
  /** Creation timestamp (Unix timestamp in seconds) */
  created_at: string;
  /** @deprecated Use video_quality instead. Encoding tier */
  encoding_tier: 'smart' | 'baseline' | 'premium';
  /** Master file access setting */
  master_access: 'temporary' | 'none';
  /** Max resolution tier for encoding, storage, and streaming */
  max_resolution_tier: '1080p' | '1440p' | '2160p';
  /** Detailed state information about the asset ingest process */
  progress: AssetProgress;
  /** Current status of asset processing */
  status: 'preparing' | 'ready' | 'errored';
  /** Aspect ratio in the form of 'width:height' (e.g., '16:9') */
  aspect_ratio?: string;
  /** Duration in seconds (max 12 hours) */
  duration?: number;
  /** Object describing any errors during processing */
  errors?: AssetErrors;
  /** The type of ingest used to create the asset */
  ingest_type?: 'on_demand_url' | 'on_demand_direct_upload' | 'on_demand_clip' | 'live_rtmp' | 'live_srt';
  /** Indicates if the live stream that created this asset is currently active */
  is_live?: boolean;
  /** Unique identifier for the live stream (when created from live stream) */
  live_stream_id?: string;
  /** Current status of Master Access and link to Master MP4 file when ready */
  master?: AssetMaster;
  /** Maximum frame rate stored for the asset (-1 if cannot be determined) */
  max_stored_frame_rate?: number;
  /** @deprecated Use resolution_tier instead. Maximum resolution stored */
  max_stored_resolution?: 'Audio only' | 'SD' | 'HD' | 'FHD' | 'UHD';
  /** Customer provided metadata */
  meta?: Record<string, string>;
  /** @deprecated MP4 support level */
  mp4_support?: 'standard' | 'none' | 'capped-1080p' | 'audio-only' | 'audio-only,capped-1080p';
  /** Object containing reasons the input file is non-standard */
  non_standard_input_reasons?: AssetNonStandardInputReasons;
  /** Normalize the audio track loudness level */
  normalize_audio?: boolean;
  /** Custom passthrough data (max 255 characters) */
  passthrough?: string;
  /** @deprecated */
  per_title_encode?: boolean;
  /** Array of playback IDs for the asset */
  playback_ids?: Array<PlaybackID>;
  /** Array of individual live stream recording sessions */
  recording_times?: Array<AssetRecordingTime>;
  /** Resolution tier the asset was ingested at (affects billing) */
  resolution_tier?: 'audio-only' | '720p' | '1080p' | '1440p' | '2160p';
  /** Asset ID of the video used as source for creating the clip */
  source_asset_id?: string;
  /** Current status of any static renditions (MP4s) */
  static_renditions?: AssetStaticRenditions;
  /** Test asset flag */
  test?: boolean;
  /** Array of tracks (subtitles/audio/video) */
  tracks?: Array<Track>;
  /** Unique identifier for the Direct Upload (when created from direct upload) */
  upload_id?: string;
  /** Video quality level: 'basic' | 'plus' | 'premium' */
  video_quality?: 'basic' | 'plus' | 'premium';
}

// Create asset from URL
const asset = await mux.video.assets.create({
  inputs: [{ url: "https://example.com/video.mp4" }],
  playback_policies: ["public"],
  mp4_support: "standard",
});

// Create asset with advanced options
const asset = await mux.video.assets.create({
  inputs: [
    {
      url: "https://example.com/video.mp4",
      start_time: 10.5,
      end_time: 120.0,
      generated_subtitles: [
        {
          language_code: "en",
          name: "English",
        },
      ],
    },
  ],
  playback_policies: ["signed"],
  normalize_audio: true,
  test: false,
});

/**
 * Retrieve asset details
 * @param assetId - The asset identifier
 * @returns Promise resolving to asset details
 */
retrieve(assetId: string): Promise<Asset>;

/**
 * Update asset properties
 * @param assetId - The asset identifier
 * @param body - Update parameters
 * @returns Promise resolving to updated asset
 */
update(assetId: string, body: AssetUpdateParams): Promise<Asset>;

interface AssetUpdateParams {
  /** Updated playback policy */
  playback_policies?: Array<PlaybackPolicy>;
  /** Master file access settings */
  master_access?: MasterAccess;
  /** MP4 support settings */
  mp4_support?: Mp4Support;
  /** Custom passthrough data (max 255 characters) */
  passthrough?: string;
}

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

interface AssetListParams extends BasePageParams {
  /** Filter by upload ID */
  upload_id?: string;
  /** Filter by live stream ID */
  live_stream_id?: string;
}

/**
 * Delete an asset permanently
 * @param assetId - The asset identifier
 * @returns Promise that resolves when deletion is complete
 */
delete(assetId: string): Promise<void>;

/**
 * Create a playback ID for an asset
 * @param assetId - The asset identifier
 * @param body - Playback ID creation parameters
 * @returns Promise resolving to the created playback ID
 */
createPlaybackId(
  assetId: string,
  body: AssetCreatePlaybackIDParams
): Promise<PlaybackID>;

interface AssetCreatePlaybackIDParams {
  /** Access policy for the playback ID */
  policy: PlaybackPolicy;
  /** DRM configuration ID (required for DRM policy) */
  drm_configuration_id?: string;
}

/**
 * Retrieve playback ID details
 * @param assetId - The asset identifier
 * @param playbackId - The playback ID
 * @returns Promise resolving to playback ID details
 */
retrievePlaybackId(assetId: string, playbackId: string): Promise<PlaybackID>;

/**
 * Delete a playback ID
 * @param assetId - The asset identifier
 * @param playbackId - The playback ID to delete
 * @returns Promise that resolves when deletion is complete
 */
deletePlaybackId(assetId: string, playbackId: string): Promise<void>;

/**
 * Create a static MP4 rendition
 * @param assetId - The asset identifier
 * @param body - Static rendition parameters
 * @returns Promise resolving to the created rendition response
 */
createStaticRendition(
  assetId: string,
  body: AssetCreateStaticRenditionParams
): Promise<AssetCreateStaticRenditionResponse>;

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

interface AssetCreateStaticRenditionResponse {
  /** Static rendition identifier */
  id: string;
  /** Current status of rendition creation */
  status: 'preparing' | 'ready' | 'errored';
}

/**
 * Delete a static rendition
 * @param assetId - The asset identifier
 * @param staticRenditionId - The static rendition ID
 * @returns Promise that resolves when deletion is complete
 */
deleteStaticRendition(assetId: string, staticRenditionId: string): Promise<void>;

/**
 * Add a track (subtitle or audio) to an asset
 * @param assetId - The asset identifier
 * @param body - Track creation parameters
 * @returns Promise resolving to the created track
 */
createTrack(assetId: string, body: AssetCreateTrackParams): Promise<Track>;

interface AssetCreateTrackParams {
  /** URL of the track file */
  url: string;
  /** Track type */
  type: 'text' | 'audio';
  /** Text track type (for subtitle tracks) */
  text_type?: 'subtitles';
  /** Language code (ISO 639-1) */
  language_code?: string;
  /** Display name for the track */
  name?: string;
  /** Closed captions flag */
  closed_captions?: boolean;
  /** Passthrough data */
  passthrough?: string;
}

interface Track {
  /** Track identifier */
  id: string;
  /** Track type */
  type: 'text' | 'audio';
  /** Duration in seconds */
  duration?: number;
  /** Maximum width (for video tracks) */
  max_width?: number;
  /** Maximum height (for video tracks) */
  max_height?: number;
  /** Maximum frame rate */
  max_frame_rate?: number;
}

/**
 * Delete a track
 * @param assetId - The asset identifier
 * @param trackId - The track identifier
 * @returns Promise that resolves when deletion is complete
 */
deleteTrack(assetId: string, trackId: string): Promise<void>;

/**
 * Generate subtitles automatically for an asset
 * @param assetId - The asset identifier
 * @param trackId - The audio track identifier to generate subtitles from
 * @param body - Subtitle generation parameters
 * @returns Promise resolving to the subtitle generation response
 */
generateSubtitles(
  assetId: string,
  trackId: string,
  body: AssetGenerateSubtitlesParams
): Promise<AssetGenerateSubtitlesResponse>;

interface AssetGenerateSubtitlesParams {
  /** Array of subtitle configurations to generate */
  generated_subtitles: Array<GeneratedSubtitle>;
}

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

interface AssetGenerateSubtitlesResponse {
  /** Generated track identifier */
  id: string;
  /** Current status of subtitle generation */
  status: 'preparing' | 'ready' | 'errored';
}

/**
 * Retrieve input information for an asset
 * @param assetId - The asset identifier
 * @returns Promise resolving to input information
 */
retrieveInputInfo(assetId: string): Promise<AssetRetrieveInputInfoResponse>;

interface AssetRetrieveInputInfoResponse {
  /** Input file information */
  data?: Array<InputInfo>;
}

interface InputInfo {
  /** File settings used during ingestion */
  settings?: InputSettings;
  /** File information extracted from the input */
  file?: FileInfo;
}

interface FileInfo {
  /** Container format */
  container_format?: string;
  /** Array of video streams */
  video_streams?: Array<VideoStream>;
  /** Array of audio streams */
  audio_streams?: Array<AudioStream>;
}

/**
 * Update master file access settings
 * @param assetId - The asset identifier
 * @param body - Master access parameters
 * @returns Promise resolving to updated asset
 */
updateMasterAccess(
  assetId: string,
  body: AssetUpdateMasterAccessParams
): Promise<Asset>;

interface AssetUpdateMasterAccessParams {
  /** Master file access setting */
  master_access: MasterAccess;
}

type MasterAccess = 'temporary' | 'none';

/**
 * Update MP4 support settings for an asset
 * @param assetId - The asset identifier
 * @param body - MP4 support parameters
 * @returns Promise resolving to updated asset
 */
updateMP4Support(
  assetId: string,
  body: AssetUpdateMP4SupportParams
): Promise<Asset>;

interface AssetUpdateMP4SupportParams {
  /** MP4 support level */
  mp4_support: Mp4Support;
}

type Mp4Support = 'none' | 'standard' | 'capped-1080p';

type PlaybackPolicy = 'public' | 'signed' | 'drm';

interface PlaybackID {
  id: string;
  policy: PlaybackPolicy;
  drm_configuration_id?: string;
}

interface GeneratedSubtitleSettings {
  language_code?: string;
  name?: string;
  passthrough?: string;
}

interface OverlaySettings {
  vertical_align?: 'top' | 'middle' | 'bottom';
  vertical_margin?: string;
  horizontal_align?: 'left' | 'center' | 'right';
  horizontal_margin?: string;
  width?: string;
  height?: string;
  opacity?: string;
}

interface VideoStream {
  width?: number;
  height?: number;
  frame_rate?: number;
  sample_aspect_ratio?: string;
  display_aspect_ratio?: string;
  pixel_format?: string;
}

interface AudioStream {
  channels?: number;
  sample_rate?: number;
  bit_depth?: number;
  channel_layout?: string;
}

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

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

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

interface AssetErrors {
  /** Array of error messages */
  messages?: Array<string>;
  /** Error type */
  type?: string;
}

interface AssetMaster {
  /** URL to the master MP4 file when available */
  url?: string;
  /** Status of master access */
  status?: 'ready' | 'preparing';
}

interface AssetNonStandardInputReasons {
  /** Array of reasons the input is non-standard */
  audio_codec?: string;
  audio_edit_list?: string;
  audio_track_count?: number;
  pixel_aspect_ratio?: string;
  unsupported_pixel_format?: string;
  video_codec?: string;
  video_edit_list?: string;
  video_frame_rate?: string;
  video_track_count?: number;
}

interface AssetRecordingTime {
  /** Start time of the recording session */
  started_at?: string;
  /** Duration of the recording session in seconds */
  duration?: number;
  /** Type of recording: 'content' | 'slate' */
  type?: 'content' | 'slate';
}

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

interface AssetStaticRenditionFile {
  /** Static rendition identifier */
  name?: string;
  /** File extension */
  ext?: string;
  /** File size in bytes */
  filesize?: number;
  /** Width in pixels */
  width?: number;
  /** Height in pixels */
  height?: number;
  /** Bitrate in bits per second */
  bitrate?: number;
}