tessl/npm-mux-js

Lightweight utilities for inspecting and manipulating video container formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

mux.js

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

mux.js is a collection of lightweight utilities for inspecting and manipulating video container formats. It provides essential functionality for web video streaming applications, particularly for transmuxing MPEG2-TS segments into fragmented MP4 (fMP4) segments compatible with Media Source Extensions (MSE). The library supports various video and audio codecs including H.264, ADTS/AAC, and includes comprehensive tools for caption parsing (CEA-608, CEA-708, WebVTT) and format debugging.

Package Information

Package Name: mux.js
Package Type: npm
Language: JavaScript
Installation: npm install mux.js

Core Imports

const muxjs = require("mux.js");

For specific modules:

const { mp4, codecs, flv, mp2t, partial } = require("mux.js");

Note: This library uses CommonJS exports only. ES6 import syntax is not supported.

Basic Usage

const muxjs = require("mux.js");

// Create a transmuxer for MPEG2-TS to MP4 conversion
const transmuxer = new muxjs.mp4.Transmuxer();

// Set up event listener for processed segments
transmuxer.on('data', (segment) => {
  // Create complete fMP4 segment (first segment needs init + data)
  const data = new Uint8Array(
    segment.initSegment.byteLength + segment.data.byteLength
  );
  data.set(segment.initSegment, 0);
  data.set(segment.data, segment.initSegment.byteLength);
  
  // Add to MSE source buffer
  sourceBuffer.appendBuffer(data);
});

// Process MPEG2-TS data
transmuxer.push(transportStreamSegment);
transmuxer.flush();

Architecture

mux.js is built around a streaming pipeline architecture with several key components:

Stream Processing: Base Stream class provides event-driven pipeline processing
Module Organization: Five main modules (codecs, mp4, flv, mp2t, partial) each handling specific format operations
Codec Support: Specialized parsers for H.264 video and ADTS/AAC audio streams
Container Formats: Support for MP4, FLV, and MPEG2-TS container manipulation
MSE Integration: Direct compatibility with HTML5 Media Source Extensions
Debug Tools: Comprehensive inspection utilities for troubleshooting media streams

Capabilities

MP4 Processing

Complete MP4 container format support including generation, parsing, transmuxing, and inspection. Essential for creating MSE-compatible fragmented MP4 segments from transport streams.

// Core MP4 transmuxer
class Transmuxer {
  constructor(options?: TransmuxerOptions);
  push(data: Uint8Array): void;
  flush(): void;
  on(event: string, callback: Function): void;
}

// MP4 box generator utilities
const generator: {
  ftyp(): Uint8Array;
  mdat(data: Uint8Array): Uint8Array;
  moof(sequenceNumber: number, tracks: Track[]): Uint8Array;
  moov(tracks: Track[], duration: number): Uint8Array;
  initSegment(tracks: Track[]): Uint8Array;
};

// MP4 probe utilities
const probe: {
  findBox(data: Uint8Array, boxType: string): Uint8Array | null;
  timescale(data: Uint8Array): number;
  startTime(data: Uint8Array): number;
  tracks(data: Uint8Array): Track[];
};

MP4 Processing

Codec Processing

Specialized codec parsers for H.264 video and ADTS/AAC audio streams. Handles bitstream parsing, NAL unit extraction, and audio frame processing.

// H.264 processing
const h264: {
  H264Stream: class H264Stream extends Stream;
  NalByteStream: class NalByteStream extends Stream;
};

// ADTS/AAC processing  
class Adts extends Stream {
  constructor();
  push(data: Uint8Array): void;
}

Codec Processing

Transport Stream Processing

MPEG-2 Transport Stream parsing and processing capabilities. Handles packet parsing, PES reconstruction, and metadata extraction from transport streams.

const TransportPacketStream: class TransportPacketStream extends Stream;
const TransportParseStream: class TransportParseStream extends Stream;  
const ElementaryStream: class ElementaryStream extends Stream;
const CaptionStream: class CaptionStream extends Stream;

// Constants
const PAT_PID: 0x0000;
const MP2T_PACKET_LENGTH: 188;
const H264_STREAM_TYPE: 0x1B;
const ADTS_STREAM_TYPE: 0x0F;

Transport Stream Processing

Caption Processing

Comprehensive caption support for CEA-608, CEA-708, and WebVTT formats. Extracts and parses caption data from video streams for accessibility compliance.

class CaptionParser {
  constructor();
  parse(data: Uint8Array): Caption[];
}

class WebVttParser {  
  constructor();
  parse(data: Uint8Array): WebVttCue[];
}

// Caption stream processing
class Cea608Stream extends Stream;
class Cea708Stream extends Stream;

Caption Processing

FLV Processing

Flash Video format support for legacy applications. Provides FLV transmuxing and inspection capabilities (maintenance mode).

class Transmuxer extends Stream {
  constructor();
  push(data: Uint8Array): void;
}

function getFlvHeader(): Uint8Array;

const tag: class FlvTag;

FLV Processing

Debug and Inspection Tools

Comprehensive debugging utilities for MP4, FLV, and transport stream inspection. Essential for troubleshooting streaming issues and understanding media structure.

// MP4 inspection
const mp4Tools: {
  inspect(data: Uint8Array): MP4Structure;
  textify(structure: MP4Structure): string;
};

// Transport stream inspection  
const mp2tTools: {
  inspect(data: Uint8Array): TransportStreamStructure;  
};

// FLV inspection
const flvTools: {
  inspect(data: Uint8Array): FlvStructure;
  textify(structure: FlvStructure): string;
};

Debug and Inspection Tools

Partial Transmuxing

Partial transmuxing support for handling incomplete MPEG2-TS segments. Useful for live streaming scenarios where complete segments aren't immediately available.

class Transmuxer {
  constructor();
  push(data: Uint8Array): void;
  flush(): void;
  on(event: string, callback: Function): void;
}

Command Line Interface

mux.js includes a CLI tool for transmuxing files from the command line.

# Install globally to use CLI
npm install -g mux.js

# Transmux a transport stream file
muxjs-transmux input.ts output.mp4

Types

interface TransmuxerOptions {
  baseMediaDecodeTime?: number;
  keepOriginalTimestamps?: boolean; 
  remux?: boolean;
}

interface Track {
  id: number;
  codec: string;
  type: 'video' | 'audio';
  timelineStartInfo: {
    baseMediaDecodeTime: number;
  };
}

interface TransmuxedSegment {
  initSegment: Uint8Array;
  data: Uint8Array;
  metadata: {
    frames: ID3Frame[];
  };
  captions: CaptionSet[];
}

interface CaptionSet {
  startTime: number;
  endTime: number;
  content: Caption[];
}

interface Caption {
  startTime: number;
  endTime: number;
  text: string;
  line: number;
  position: number;
}