0
# MP4 Processing
1

2
Complete MP4 container format support including generation, parsing, transmuxing, and inspection. The MP4 module is the core component for creating MSE-compatible fragmented MP4 segments from transport streams.
3

4
## Capabilities
5

6
### Transmuxer
7

8
Main class for converting MPEG2-TS segments to fragmented MP4 segments compatible with Media Source Extensions.
9

10
```javascript { .api }
11
/**
12
 * MP4 Transmuxer for converting transport streams to fMP4
13
 * @param options - Configuration options for the transmuxer
14
 */
15
class Transmuxer {
16
  constructor(options?: TransmuxerOptions);
17
  
18
  /** Add transport stream data for processing */
19
  push(data: Uint8Array): void;
20
  
21
  /** Flush any remaining data and finalize processing */
22
  flush(): void;
23
  
24
  /** Register event listeners for processed segments */
25
  on(event: 'data', callback: (segment: TransmuxedSegment) => void): void;
26
  on(event: 'done', callback: () => void): void;
27
  
28
  /** Remove event listeners */
29
  off(event?: string): void;
30
}
31

32
interface TransmuxerOptions {
33
  /** Base Media Decode Time for the first segment (default: 0) */
34
  baseMediaDecodeTime?: number;
35
  
36
  /** Preserve original timestamps instead of rewriting to start at 0 (default: false) */
37
  keepOriginalTimestamps?: boolean;
38
  
39
  /** Remux audio and video into single MP4 segment (default: true) */
40
  remux?: boolean;
41
}
42

43
interface TransmuxedSegment {
44
  /** Initialization segment (ftyp + moov boxes) */
45
  initSegment: Uint8Array;
46
  
47
  /** Media segment (moof + mdat boxes) */
48
  data: Uint8Array;
49
  
50
  /** Extracted ID3 metadata frames */
51
  metadata: {
52
    frames: ID3Frame[];
53
  };
54
  
55
  /** Parsed caption data */
56
  captions: CaptionSet[];
57
}
58
```
59

60
**Usage Examples:**
61

62
```javascript
63
const muxjs = require("mux.js");
64

65
// Basic transmuxing setup
66
const transmuxer = new muxjs.mp4.Transmuxer({
67
  keepOriginalTimestamps: false,
68
  remux: true
69
});
70

71
// Handle processed segments
72
transmuxer.on('data', (segment) => {
73
  if (isFirstSegment) {
74
    // First segment needs both init and data
75
    const combined = new Uint8Array(
76
      segment.initSegment.byteLength + segment.data.byteLength
77
    );
78
    combined.set(segment.initSegment, 0);
79
    combined.set(segment.data, segment.initSegment.byteLength);
80
    sourceBuffer.appendBuffer(combined);
81
  } else {
82
    // Subsequent segments only need data
83
    sourceBuffer.appendBuffer(segment.data);
84
  }
85
  
86
  // Process captions
87
  segment.captions.forEach(captionSet => {
88
    captionSet.content.forEach(cue => {
89
      const vttCue = new VTTCue(cue.startTime, cue.endTime, cue.text);
90
      captionTrack.addCue(vttCue);
91
    });
92
  });
93
});
94

95
// Process transport stream data
96
transmuxer.push(transportStreamData);
97
transmuxer.flush();
98
```
99

100
### Audio Segment Stream
101

102
Specialized stream for processing audio segments in the transmuxing pipeline.
103

104
```javascript { .api }
105
/**
106
 * Stream for processing audio segments
107
 */
108
class AudioSegmentStream {
109
  constructor(track: Track, options?: SegmentOptions);
110
  push(data: PESData): void;
111
  flush(): void;
112
}
113
```
114

115
### Video Segment Stream
116

117
Specialized stream for processing video segments in the transmuxing pipeline.
118

119
```javascript { .api }
120
/**
121
 * Stream for processing video segments  
122
 */
123
class VideoSegmentStream {
124
  constructor(track: Track, options?: SegmentOptions);
125
  push(data: PESData): void;
126
  flush(): void;
127
}
128
```
129

130
### MP4 Generator
131

132
Utilities for generating MP4 box structures and segments.
133

134
```javascript { .api }
135
const generator: {
136
  /** Generate file type box (ftyp) */
137
  ftyp(): Uint8Array;
138
  
139
  /** Generate media data box (mdat) containing media samples */
140
  mdat(data: Uint8Array): Uint8Array;
141
  
142
  /** Generate movie fragment box (moof) for fragmented MP4 */
143
  moof(sequenceNumber: number, tracks: Track[]): Uint8Array;
144
  
145
  /** Generate movie box (moov) containing track metadata */
146
  moov(tracks: Track[], duration: number): Uint8Array;
147
  
148
  /** Generate complete initialization segment (ftyp + moov) */
149
  initSegment(tracks: Track[]): Uint8Array;
150
  
151
  /** Generate track fragment header box (tfhd) */
152
  tfhd(track: Track): Uint8Array;
153
  
154
  /** Generate track run box (trun) with sample data */
155
  trun(track: Track, samples: Sample[]): Uint8Array;
156
  
157
  /** Generate media header box (mdhd) */
158
  mdhd(timescale: number, duration: number): Uint8Array;
159
  
160
  /** Generate track header box (tkhd) */
161
  tkhd(track: Track): Uint8Array;
162
};
163
```
164

165
**Usage Examples:**
166

167
```javascript
168
const muxjs = require("mux.js");
169

170
// Generate initialization segment
171
const tracks = [{
172
  id: 1,
173
  codec: 'avc',
174
  type: 'video',
175
  timelineStartInfo: { baseMediaDecodeTime: 0 }
176
}];
177

178
const initSegment = muxjs.mp4.generator.initSegment(tracks);
179

180
// Generate media data box
181
const samples = new Uint8Array([/* sample data */]);
182
const mdatBox = muxjs.mp4.generator.mdat(samples);
183
```
184

185
### MP4 Probe
186

187
Utilities for analyzing and extracting metadata from MP4 files.
188

189
```javascript { .api }
190
const probe: {
191
  /** Find specific box type in MP4 data */
192
  findBox(data: Uint8Array, boxType: string): Uint8Array | null;
193
  
194
  /** Parse box type from binary data */
195
  parseType(data: Uint8Array): string;
196
  
197
  /** Extract timescale from MP4 */
198
  timescale(data: Uint8Array): number;
199
  
200
  /** Extract start time from MP4 in seconds */  
201
  startTime(data: Uint8Array): number;
202
  
203
  /** Extract composition start time */
204
  compositionStartTime(data: Uint8Array): number;
205
  
206
  /** Get array of video track IDs */
207
  videoTrackIds(data: Uint8Array): number[];
208
  
209
  /** Get track information for all tracks */
210
  tracks(data: Uint8Array): Track[];
211
  
212
  /** Extract timescale from media header box */
213
  getTimescaleFromMediaHeader(data: Uint8Array): number;
214
  
215
  /** Extract ID3 data from emsg boxes */
216
  getEmsgID3(data: Uint8Array): ID3Frame[];
217
};
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
const muxjs = require("mux.js");
224

225
// Analyze MP4 file
226
const mp4Data = new Uint8Array([/* MP4 file data */]);
227

228
// Get basic information
229
const timescale = muxjs.mp4.probe.timescale(mp4Data);
230
const startTime = muxjs.mp4.probe.startTime(mp4Data);
231
const tracks = muxjs.mp4.probe.tracks(mp4Data);
232

233
console.log(`Timescale: ${timescale}`);
234
console.log(`Start time: ${startTime}s`);
235
console.log(`Tracks: ${tracks.length}`);
236

237
// Find specific boxes
238
const moovBox = muxjs.mp4.probe.findBox(mp4Data, 'moov');
239
if (moovBox) {
240
  console.log('Found moov box');
241
}
242
```
243

244
### Caption Parser
245

246
Parser for extracting CEA-608 caption data from MP4 streams.
247

248
```javascript { .api }
249
/**
250
 * Parser for CEA-608 captions embedded in MP4 streams
251
 */
252
class CaptionParser {
253
  constructor();
254
  
255
  /** Parse caption data from MP4 stream */
256
  parse(data: Uint8Array): Caption[];
257
  
258
  /** Clear parser state */
259
  clearParsedCaptions(): void;
260
  
261
  /** Get parsed captions */
262
  getParsedCaptions(): Caption[];
263
}
264
```
265

266
### WebVTT Parser
267

268
Parser for extracting WebVTT caption data from MP4 streams.
269

270
```javascript { .api }
271
/**
272
 * Parser for WebVTT captions in MP4 streams
273
 */
274
class WebVttParser {
275
  constructor();
276
  
277
  /** Parse WebVTT data from MP4 stream */
278
  parse(data: Uint8Array): WebVttCue[];
279
}
280

281
interface WebVttCue {
282
  startTime: number;
283
  endTime: number;
284
  text: string;
285
  id?: string;
286
  settings?: string;
287
}
288
```
289

290
## Types
291

292
```javascript { .api }
293
interface Track {
294
  id: number;
295
  codec: 'avc' | 'adts' | string;
296
  type: 'video' | 'audio';
297
  timelineStartInfo: {
298
    baseMediaDecodeTime: number;
299
  };
300
  samplerate?: number;
301
  channelcount?: number;
302
  width?: number;
303
  height?: number;
304
}
305

306
interface Sample {
307
  duration: number;
308
  size: number;
309
  flags: {
310
    isLeading: number;
311
    dependsOn: number;
312
    isDependedOn: number;
313
    hasRedundancy: number;
314
    degradPrio: number;
315
    isNonSync: boolean;
316
  };
317
  compositionTimeOffset: number;
318
}
319

320
interface PESData {
321
  data: Uint8Array;
322
  pts?: number;
323
  dts?: number;
324
  streamType: number;
325
}
326

327
interface SegmentOptions {
328
  baseMediaDecodeTime?: number;
329
  keepOriginalTimestamps?: boolean;
330
}
331

332
interface ID3Frame {
333
  key: string;
334
  data: Uint8Array;
335
}
336

337
interface CaptionSet {
338
  startTime: number;
339
  endTime: number; 
340
  content: Caption[];
341
}
342

343
interface Caption {
344
  startTime: number;
345
  endTime: number;
346
  text: string;
347
  line: number;
348
  position: number;
349
}
350
```