0
# mux.js
1
2
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.
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
const muxjs = require("mux.js");
15
```
16
17
For specific modules:
18
19
```javascript
20
const { mp4, codecs, flv, mp2t, partial } = require("mux.js");
21
```
22
23
**Note**: This library uses CommonJS exports only. ES6 import syntax is not supported.
24
25
## Basic Usage
26
27
```javascript
28
const muxjs = require("mux.js");
29
30
// Create a transmuxer for MPEG2-TS to MP4 conversion
31
const transmuxer = new muxjs.mp4.Transmuxer();
32
33
// Set up event listener for processed segments
34
transmuxer.on('data', (segment) => {
35
// Create complete fMP4 segment (first segment needs init + data)
36
const data = new Uint8Array(
37
segment.initSegment.byteLength + segment.data.byteLength
38
);
39
data.set(segment.initSegment, 0);
40
data.set(segment.data, segment.initSegment.byteLength);
41
42
// Add to MSE source buffer
43
sourceBuffer.appendBuffer(data);
44
});
45
46
// Process MPEG2-TS data
47
transmuxer.push(transportStreamSegment);
48
transmuxer.flush();
49
```
50
51
## Architecture
52
53
mux.js is built around a streaming pipeline architecture with several key components:
54
55
- **Stream Processing**: Base `Stream` class provides event-driven pipeline processing
56
- **Module Organization**: Five main modules (codecs, mp4, flv, mp2t, partial) each handling specific format operations
57
- **Codec Support**: Specialized parsers for H.264 video and ADTS/AAC audio streams
58
- **Container Formats**: Support for MP4, FLV, and MPEG2-TS container manipulation
59
- **MSE Integration**: Direct compatibility with HTML5 Media Source Extensions
60
- **Debug Tools**: Comprehensive inspection utilities for troubleshooting media streams
61
62
## Capabilities
63
64
### MP4 Processing
65
66
Complete MP4 container format support including generation, parsing, transmuxing, and inspection. Essential for creating MSE-compatible fragmented MP4 segments from transport streams.
67
68
```javascript { .api }
69
// Core MP4 transmuxer
70
class Transmuxer {
71
constructor(options?: TransmuxerOptions);
72
push(data: Uint8Array): void;
73
flush(): void;
74
on(event: string, callback: Function): void;
75
}
76
77
// MP4 box generator utilities
78
const generator: {
79
ftyp(): Uint8Array;
80
mdat(data: Uint8Array): Uint8Array;
81
moof(sequenceNumber: number, tracks: Track[]): Uint8Array;
82
moov(tracks: Track[], duration: number): Uint8Array;
83
initSegment(tracks: Track[]): Uint8Array;
84
};
85
86
// MP4 probe utilities
87
const probe: {
88
findBox(data: Uint8Array, boxType: string): Uint8Array | null;
89
timescale(data: Uint8Array): number;
90
startTime(data: Uint8Array): number;
91
tracks(data: Uint8Array): Track[];
92
};
93
```
94
95
[MP4 Processing](./mp4.md)
96
97
### Codec Processing
98
99
Specialized codec parsers for H.264 video and ADTS/AAC audio streams. Handles bitstream parsing, NAL unit extraction, and audio frame processing.
100
101
```javascript { .api }
102
// H.264 processing
103
const h264: {
104
H264Stream: class H264Stream extends Stream;
105
NalByteStream: class NalByteStream extends Stream;
106
};
107
108
// ADTS/AAC processing
109
class Adts extends Stream {
110
constructor();
111
push(data: Uint8Array): void;
112
}
113
```
114
115
[Codec Processing](./codecs.md)
116
117
### Transport Stream Processing
118
119
MPEG-2 Transport Stream parsing and processing capabilities. Handles packet parsing, PES reconstruction, and metadata extraction from transport streams.
120
121
```javascript { .api }
122
const TransportPacketStream: class TransportPacketStream extends Stream;
123
const TransportParseStream: class TransportParseStream extends Stream;
124
const ElementaryStream: class ElementaryStream extends Stream;
125
const CaptionStream: class CaptionStream extends Stream;
126
127
// Constants
128
const PAT_PID: 0x0000;
129
const MP2T_PACKET_LENGTH: 188;
130
const H264_STREAM_TYPE: 0x1B;
131
const ADTS_STREAM_TYPE: 0x0F;
132
```
133
134
[Transport Stream Processing](./mp2t.md)
135
136
### Caption Processing
137
138
Comprehensive caption support for CEA-608, CEA-708, and WebVTT formats. Extracts and parses caption data from video streams for accessibility compliance.
139
140
```javascript { .api }
141
class CaptionParser {
142
constructor();
143
parse(data: Uint8Array): Caption[];
144
}
145
146
class WebVttParser {
147
constructor();
148
parse(data: Uint8Array): WebVttCue[];
149
}
150
151
// Caption stream processing
152
class Cea608Stream extends Stream;
153
class Cea708Stream extends Stream;
154
```
155
156
[Caption Processing](./captions.md)
157
158
### FLV Processing
159
160
Flash Video format support for legacy applications. Provides FLV transmuxing and inspection capabilities (maintenance mode).
161
162
```javascript { .api }
163
class Transmuxer extends Stream {
164
constructor();
165
push(data: Uint8Array): void;
166
}
167
168
function getFlvHeader(): Uint8Array;
169
170
const tag: class FlvTag;
171
```
172
173
[FLV Processing](./flv.md)
174
175
### Debug and Inspection Tools
176
177
Comprehensive debugging utilities for MP4, FLV, and transport stream inspection. Essential for troubleshooting streaming issues and understanding media structure.
178
179
```javascript { .api }
180
// MP4 inspection
181
const mp4Tools: {
182
inspect(data: Uint8Array): MP4Structure;
183
textify(structure: MP4Structure): string;
184
};
185
186
// Transport stream inspection
187
const mp2tTools: {
188
inspect(data: Uint8Array): TransportStreamStructure;
189
};
190
191
// FLV inspection
192
const flvTools: {
193
inspect(data: Uint8Array): FlvStructure;
194
textify(structure: FlvStructure): string;
195
};
196
```
197
198
[Debug and Inspection Tools](./tools.md)
199
200
### Partial Transmuxing
201
202
Partial transmuxing support for handling incomplete MPEG2-TS segments. Useful for live streaming scenarios where complete segments aren't immediately available.
203
204
```javascript { .api }
205
class Transmuxer {
206
constructor();
207
push(data: Uint8Array): void;
208
flush(): void;
209
on(event: string, callback: Function): void;
210
}
211
```
212
213
### Command Line Interface
214
215
mux.js includes a CLI tool for transmuxing files from the command line.
216
217
```bash { .api }
218
# Install globally to use CLI
219
npm install -g mux.js
220
221
# Transmux a transport stream file
222
muxjs-transmux input.ts output.mp4
223
```
224
225
## Types
226
227
```javascript { .api }
228
interface TransmuxerOptions {
229
baseMediaDecodeTime?: number;
230
keepOriginalTimestamps?: boolean;
231
remux?: boolean;
232
}
233
234
interface Track {
235
id: number;
236
codec: string;
237
type: 'video' | 'audio';
238
timelineStartInfo: {
239
baseMediaDecodeTime: number;
240
};
241
}
242
243
interface TransmuxedSegment {
244
initSegment: Uint8Array;
245
data: Uint8Array;
246
metadata: {
247
frames: ID3Frame[];
248
};
249
captions: CaptionSet[];
250
}
251
252
interface CaptionSet {
253
startTime: number;
254
endTime: number;
255
content: Caption[];
256
}
257
258
interface Caption {
259
startTime: number;
260
endTime: number;
261
text: string;
262
line: number;
263
position: number;
264
}
265
```