tessl/npm-mux--mux-node

Official TypeScript library providing comprehensive client access to Mux's video infrastructure API including asset management, live streaming, analytics, and webhook handling

Overview

Eval results

Files

Video Playback

Name: tessl/npm-mux--mux-node
Author: tessl

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.

Capabilities

HLS Playlist Access

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

/**
 * Fetch HLS playlist for video playback
 * @param playbackId - Playback ID of the video asset
 * @param query - Optional playback behavior parameters
 * @returns Promise resolving to Response containing m3u8 playlist
 */
hls(
  playbackId: string,
  query?: PlaybackHlsParams,
  options?: Core.RequestOptions
): Core.APIPromise<Response>;

interface PlaybackHlsParams {
  /** Start time for instant clipping (seconds) */
  asset_start_time?: number;
  /** End time for instant clipping (seconds) */
  asset_end_time?: number;
  /** Default subtitle language (BCP47 code) */
  default_subtitles_lang?: string;
  /** Exclude EXT-X-PROGRAM-DATE-TIME tags */
  exclude_pdt?: boolean;
  /** Maximum resolution in manifest */
  max_resolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p';
  /** Minimum resolution in manifest */
  min_resolution?: '270p' | '360p' | '480p' | '540p' | '720p' | '1080p' | '1440p' | '2160p';
  /** Live stream end time for clipping (epoch timestamp) */
  program_end_time?: number;
  /** Live stream start time for clipping (epoch timestamp) */
  program_start_time?: number;
  /** Include redundant delivery streams */
  redundant_streams?: boolean;
  /** Order renditions by quality */
  rendition_order?: 'desc';
  /** Enable Roku timeline hover previews */
  roku_trick_play?: boolean;
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

Usage Examples:

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

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

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

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

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

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

Static Rendition Access

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

/**
 * Fetch static video/audio rendition
 * @param playbackId - Playback ID of the video asset
 * @param filename - Static rendition filename
 * @param query - Optional parameters
 * @returns Promise resolving to Response containing media file
 */
staticRendition(
  playbackId: string,
  filename: 'capped-1080p.mp4' | 'audio.m4a' | 'low.mp4' | 'medium.mp4' | 'high.mp4',
  query?: PlaybackStaticRenditionParams,
  options?: Core.RequestOptions
): Core.APIPromise<Response>;

interface PlaybackStaticRenditionParams {
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

Usage Examples:

// Download high-quality MP4
const mp4Response = await mux.video.playback.staticRendition(
  "PLAYBACK_ID",
  "capped-1080p.mp4"
);
const mp4Blob = await mp4Response.blob();

// Get audio-only version
const audioResponse = await mux.video.playback.staticRendition(
  "PLAYBACK_ID",
  "audio.m4a"
);

// Various quality levels
const lowQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "low.mp4");
const mediumQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "medium.mp4");
const highQuality = await mux.video.playback.staticRendition("PLAYBACK_ID", "high.mp4");

Thumbnail Generation

Generate static thumbnail images from video content with transformation options.

/**
 * Generate thumbnail image from video
 * @param playbackId - Playback ID of the video asset
 * @param extension - Image format
 * @param query - Optional transformation parameters
 * @returns Promise resolving to Response containing image
 */
thumbnail(
  playbackId: string,
  extension: 'jpg' | 'png' | 'webp',
  query?: PlaybackThumbnailParams,
  options?: Core.RequestOptions
): Core.APIPromise<Response>;

interface PlaybackThumbnailParams {
  /** Image fitting mode */
  fit_mode?: 'preserve' | 'stretch' | 'crop' | 'smartcrop' | 'pad';
  /** Flip horizontally */
  flip_h?: boolean;
  /** Flip vertically */
  flip_v?: boolean;
  /** Image height in pixels */
  height?: number;
  /** Get latest frame from live stream */
  latest?: boolean;
  /** Time for live stream clipping (epoch timestamp) */
  program_time?: number;
  /** Rotation angle */
  rotate?: 90 | 180 | 270;
  /** Time to capture thumbnail (seconds) */
  time?: number;
  /** Signed JWT token for secure playback */
  TOKEN?: string;
  /** Image width in pixels */
  width?: number;
}

Usage Examples:

// Basic thumbnail at video midpoint
const thumbnailResponse = await mux.video.playback.thumbnail("PLAYBACK_ID", "jpg");
const thumbnailBlob = await thumbnailResponse.blob();

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

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

// Transformed thumbnail
const rotatedThumbnail = await mux.video.playback.thumbnail("PLAYBACK_ID", "png", {
  rotate: 90,
  flip_h: true,
  width: 300,
  height: 300,
  fit_mode: "smartcrop"
});

Animated GIF/WebP Generation

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

/**
 * Generate animated GIF or WebP from video segment
 * @param playbackId - Playback ID of the video asset
 * @param extension - Animation format
 * @param query - Optional animation parameters
 * @returns Promise resolving to Response containing animated image
 */
animated(
  playbackId: string,
  extension: 'gif' | 'webp',
  query?: PlaybackAnimatedParams,
  options?: Core.RequestOptions
): Core.APIPromise<Response>;

interface PlaybackAnimatedParams {
  /** Animation end time (seconds, max 10s duration) */
  end?: number;
  /** Frame rate (max 30 fps) */
  fps?: number;
  /** Animation height (max 640px) */
  height?: number;
  /** Animation start time (seconds) */
  start?: number;
  /** Signed JWT token for secure playback */
  TOKEN?: string;
  /** Animation width (max 640px) */
  width?: number;
}

Usage Examples:

// Basic 5-second GIF from beginning
const animatedGif = await mux.video.playback.animated("PLAYBACK_ID", "gif");
const gifBlob = await animatedGif.blob();

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

// WebP format for better compression
const animatedWebP = await mux.video.playback.animated("PLAYBACK_ID", "webp", {
  start: 0,
  end: 3,
  fps: 15,
  width: 320
});

Storyboard Images

Generate composite storyboard images for timeline hover previews.

/**
 * Generate storyboard composite image
 * @param playbackId - Playback ID of the video asset
 * @param extension - Image format
 * @param query - Optional parameters
 * @returns Promise resolving to Response containing storyboard image
 */
storyboard(
  playbackId: string,
  extension: 'jpg' | 'png' | 'webp',
  query?: PlaybackStoryboardParams,
  options?: Core.RequestOptions
): Core.APIPromise<Response>;

interface PlaybackStoryboardParams {
  /** Start time for instant clipping */
  asset_start_time?: number;
  /** End time for instant clipping */
  asset_end_time?: number;
  /** Live stream end time for clipping */
  program_end_time?: number;
  /** Live stream start time for clipping */
  program_start_time?: number;
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

Storyboard Metadata

Retrieve storyboard thumbnail coordinates and timing information.

/**
 * Get storyboard metadata in JSON format
 * @param playbackId - Playback ID of the video asset
 * @param query - Optional parameters
 * @returns Promise resolving to JSON metadata string
 */
storyboardMeta(
  playbackId: string,
  query?: PlaybackStoryboardMetaParams,
  options?: Core.RequestOptions
): Core.APIPromise<string>;

/**
 * Get storyboard metadata in WebVTT format
 * @param playbackId - Playback ID of the video asset
 * @param query - Optional parameters
 * @returns Promise resolving to WebVTT metadata string
 */
storyboardVtt(
  playbackId: string,
  query?: PlaybackStoryboardVttParams,
  options?: Core.RequestOptions
): Core.APIPromise<string>;

interface PlaybackStoryboardMetaParams {
  /** Start time for instant clipping */
  asset_start_time?: number;
  /** End time for instant clipping */
  asset_end_time?: number;
  /** Storyboard image format preference */
  format?: 'jpg' | 'png' | 'webp';
  /** Live stream end time for clipping */
  program_end_time?: number;
  /** Live stream start time for clipping */
  program_start_time?: number;
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

Usage Examples:

// Get storyboard image
const storyboardResponse = await mux.video.playback.storyboard("PLAYBACK_ID", "jpg");
const storyboardBlob = await storyboardResponse.blob();

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

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

Text Track Access

Retrieve subtitle, caption, and transcript files.

/**
 * Fetch WebVTT text track (subtitles/captions)
 * @param playbackId - Playback ID of the video asset
 * @param trackId - Text track identifier
 * @param query - Optional parameters
 * @returns Promise resolving to WebVTT content
 */
track(
  playbackId: string,
  trackId: string,
  query?: PlaybackTrackParams,
  options?: Core.RequestOptions
): Core.APIPromise<string>;

/**
 * Fetch plain text transcript
 * @param playbackId - Playback ID of the video asset
 * @param trackId - Transcript track identifier
 * @param query - Optional parameters
 * @returns Promise resolving to plain text transcript
 */
transcript(
  playbackId: string,
  trackId: string,
  query?: PlaybackTranscriptParams,
  options?: Core.RequestOptions
): Core.APIPromise<string>;

interface PlaybackTrackParams {
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

interface PlaybackTranscriptParams {
  /** Signed JWT token for secure playback */
  TOKEN?: string;
}

Usage Examples:

// Get WebVTT subtitle track
const subtitleTrack = await mux.video.playback.track("PLAYBACK_ID", "TRACK_ID");
console.log("WebVTT subtitles:", subtitleTrack);

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

// Secure access with JWT
const secureTranscript = await mux.video.playback.transcript("PLAYBACK_ID", "TRACK_ID", {
  TOKEN: "jwt_token_here"
});

Types

/** Response type aliases for text content */
type PlaybackStoryboardMetaResponse = string;
type PlaybackStoryboardVttResponse = string;
type PlaybackTrackResponse = string;
type PlaybackTranscriptResponse = string;

/** WebVTT parameter interfaces */
interface PlaybackStoryboardVttParams {
  asset_start_time?: number;
  asset_end_time?: number;
  program_end_time?: number;
  program_start_time?: number;
  TOKEN?: string;
}

Integration Patterns

Custom Video Player

// Build custom video player with all playback resources
const playbackId = "PLAYBACK_ID";

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

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

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

// Get subtitles
const subtitles = await mux.video.playback.track(playbackId, "subtitle_track_id");

Social Media Integration

// Generate content for social sharing
const socialGif = await mux.video.playback.animated("PLAYBACK_ID", "gif", {
  start: 30,
  end: 35,
  width: 480,
  height: 270,
  fps: 20
});

const socialThumbnail = await mux.video.playback.thumbnail("PLAYBACK_ID", "jpg", {
  time: 60,
  width: 1200,
  height: 630,
  fit_mode: "crop"
});

Download Service

// Provide download options
const downloadOptions = [
  { quality: "High", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "capped-1080p.mp4") },
  { quality: "Medium", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "medium.mp4") },
  { quality: "Low", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "low.mp4") },
  { quality: "Audio Only", file: await mux.video.playback.staticRendition("PLAYBACK_ID", "audio.m4a") }
];

Security Considerations

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

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

// Use token with any playback method
const securePlaylist = await mux.video.playback.hls(playbackId, {
  TOKEN: playbackToken
});

Best Practices

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

Install with Tessl CLI

npx tessl i tessl/npm-mux--mux-node

tessl/npm-mux--mux-node

video-playback.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Video Playback

Capabilities

HLS Playlist Access

Static Rendition Access

Thumbnail Generation

Animated GIF/WebP Generation

Storyboard Images

Storyboard Metadata

Text Track Access

Types

Integration Patterns

Custom Video Player

Social Media Integration

Download Service

Security Considerations

Best Practices

video-playback.mddocs/