0
# mux.js
1

2
mux.js is a collection of lightweight utilities for inspecting and manipulating video container formats, specifically designed for web-based video streaming applications. It offers specialized transmuxers for converting MPEG2-TS segments to fragmented MP4 (fMP4) format suitable for Media Source Extensions (MSE), handling of various codecs including H.264 video and AAC audio, parsing and extraction of CEA-608 captions from video streams, tools for container inspection and debugging, and support for timed ID3 metadata extraction.
3

4
## Package Information
5

6
- **Package Name**: mux.js
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mux.js`
10

11
## Core Imports
12

13
```javascript
14
import muxjs from "mux.js";
15
// Access modules: muxjs.codecs, muxjs.mp4, muxjs.flv, muxjs.mp2t, muxjs.partial
16
```
17

18
For CommonJS:
19

20
```javascript
21
const muxjs = require("mux.js");
22
// Access modules: muxjs.codecs, muxjs.mp4, muxjs.flv, muxjs.mp2t, muxjs.partial
23
```
24

25
ES modules (if available with modern bundlers):
26

27
```javascript
28
import muxjs from "mux.js";
29
// Note: Destructuring may not be available depending on build configuration
30
// Use muxjs.codecs, muxjs.mp4, etc. to access modules
31
```
32

33
## Basic Usage
34

35
```javascript
36
const muxjs = require("mux.js");
37

38
// Create a transmuxer to convert TS to fragmented MP4
39
const transmuxer = new muxjs.mp4.Transmuxer();
40

41
transmuxer.on('data', function(segment) {
42
  // segment.initSegment - MP4 initialization segment  
43
  // segment.data - MP4 media segment
44
  if (segment.initSegment) {
45
    // Handle init segment (contains codec info)
46
    sourceBuffer.appendBuffer(segment.initSegment);
47
  }
48
  // Handle media data
49
  sourceBuffer.appendBuffer(segment.data);
50
});
51

52
// Push TS data and flush
53
transmuxer.push(tsData);
54
transmuxer.flush();
55
```
56

57
## Architecture
58

59
mux.js is architected around a streaming pipeline system that enables efficient processing of video data in real-time applications. The core components include:
60

61
- **Stream Base Class**: Event-driven processing foundation with consistent `push()`, `flush()`, and event handling patterns
62
- **Format-Specific Modules**: Separate modules for different container formats (MP4, FLV, MPEG-2 TS) with specialized processing
63
- **Codec Processing**: Dedicated parsers for H.264 video and ADTS/AAC audio streams with timing and metadata extraction
64
- **Transmuxing Pipeline**: Multi-stage processing that converts between formats while preserving timing, captions, and metadata
65
- **Inspection Tools**: Debugging utilities for analyzing container structure and data flow
66
- **CLI Interface**: Command-line tool for batch processing and testing
67

68
## Capabilities
69

70
### Codec Processing
71

72
Parsing and processing of H.264 video and ADTS/AAC audio codecs with support for timing analysis, metadata extraction, and stream validation.
73

74
```javascript { .api }
75
// H.264 stream processing
76
const h264Stream = new muxjs.codecs.h264.H264Stream();
77
const nalByteStream = new muxjs.codecs.h264.NalByteStream();
78

79
// ADTS/AAC stream processing  
80
const adtsStream = new muxjs.codecs.Adts();
81
```
82

83
[Codec Processing](./codecs.md)
84

85
### MP4 Generation and Transmuxing
86

87
Complete MP4 container support including box generation, transmuxing from transport streams, audio/video segment processing, and caption parsing.
88

89
```javascript { .api }
90
// Main transmuxer for TS to fMP4
91
const transmuxer = new muxjs.mp4.Transmuxer();
92

93
// MP4 analysis and probing
94
const tracks = muxjs.mp4.probe.tracks(initSegment);
95
const startTime = muxjs.mp4.probe.startTime(timescale, fragment);
96

97
// Box generation utilities
98
const moovBox = muxjs.mp4.generator.moov(tracks, duration);
99
```
100

101
[MP4 Processing](./mp4.md)
102

103
### FLV Format Support
104

105
FLV container manipulation including tag processing, header generation, and transmuxing capabilities.
106

107
```javascript { .api }
108
// FLV transmuxer
109
const flvTransmuxer = new muxjs.flv.Transmuxer();
110

111
// FLV header generation
112
const header = muxjs.flv.getFlvHeader(duration, hasAudio, hasVideo);
113
```
114

115
[FLV Processing](./flv.md)
116

117
### Transport Stream Processing
118

119
Comprehensive MPEG-2 Transport Stream support including packet parsing, PES reconstruction, caption extraction, metadata processing, and timestamp handling.
120

121
```javascript { .api }
122
// Core TS processing classes
123
const transportPacketStream = new muxjs.mp2t.TransportPacketStream();
124
const transportParseStream = new muxjs.mp2t.TransportParseStream();
125
const elementaryStream = new muxjs.mp2t.ElementaryStream();
126

127
// Specialized streams
128
const captionStream = new muxjs.mp2t.CaptionStream();
129
const metadataStream = new muxjs.mp2t.MetadataStream();
130
```
131

132
[Transport Stream Processing](./transport-streams.md)
133

134
### Tools and Inspection
135

136
Debugging and analysis tools for MP4, FLV, and transport stream containers with detailed structure parsing and text output.
137

138
```javascript { .api }
139
// MP4 inspection
140
const mp4Structure = muxjs.mp4.tools.inspectMp4(mp4Bytes);
141
const textOutput = muxjs.mp4.tools.textifyMp4(mp4Structure);
142

143
// Transport stream inspection  
144
const tsAnalysis = muxjs.mp2t.tools.inspect(tsBytes);
145

146
// FLV inspection
147
const flvStructure = muxjs.flv.tools.inspect(flvBytes);
148
```
149

150
[Tools and Inspection](./tools.md)
151

152
### Partial Segment Processing
153

154
Progressive segment processing for handling incomplete media segments and live streaming scenarios with automatic format detection and incremental processing.
155

156
```javascript { .api }
157
// Partial transmuxer with automatic format detection
158
const partialTransmuxer = new muxjs.partial.Transmuxer({
159
  realtime: true,
160
  keepOriginalTimestamps: false
161
});
162

163
// Specialized segment streams
164
const audioSegmentStream = new muxjs.partial.AudioSegmentStream(audioTrack);
165
const videoSegmentStream = new muxjs.partial.VideoSegmentStream(videoTrack);
166
```
167

168
[Partial Segment Processing](./partial.md)
169

170
### Utilities and Helpers
171

172
Shared utilities for time conversion, binary data handling, stream processing, and mathematical operations.
173

174
```javascript { .api }
175
// Time conversion utilities
176
const videoTs = muxjs.utils.clock.secondsToVideoTs(seconds);
177
const audioTs = muxjs.utils.clock.secondsToAudioTs(seconds, sampleRate);
178

179
// Stream base class for custom processing
180
class CustomStream extends muxjs.utils.Stream {
181
  // Implement custom stream logic
182
}
183
```
184

185
[Utilities and Helpers](./utilities.md)
186

187
## CLI Tool
188

189
mux.js includes a command-line transmuxer for converting transport streams and ADTS files to fragmented MP4:
190

191
```bash
192
# Basic usage
193
npx muxjs-transmux input.ts > output.mp4
194
npx muxjs-transmux input.ts -o output.mp4
195

196
# Pipe from curl
197
curl -s 'https://example.com/stream.ts' | npx muxjs-transmux -o output.mp4
198
```
199

200
## Error Handling
201

202
All stream classes emit standard events:
203
- `data` - Processed data output
204
- `done` - Processing completed  
205
- `error` - Processing errors
206
- `warning` - Non-fatal warnings
207

208
```javascript
209
transmuxer.on('error', function(error) {
210
  console.error('Transmuxing failed:', error);
211
});
212

213
transmuxer.on('warning', function(warning) {
214
  console.warn('Transmuxing warning:', warning);
215
});