@audio/decode-mp4 1.1.1 → 1.3.0

package/README.md

@@ -33,7 +33,7 @@ dec.free()
 | `dtsc`, `dtsh`, `dtsl`, `dtse`, `mp4a` (0xA9) | DTS (core) | [@audio/decode-dts](../decode-dts) |
 | `ec-3`, `mp4a` (0xA6) | E-AC-3 (Dolby Digital Plus) | [@audio/decode-eac3](../decode-eac3) |
 
-TrueHD tracks throw an error naming the codec. Fragmented MP4 (`moof`) is not supported. QuickTime sound descriptions v0, v1 and v2 are handled, including `wave`-wrapped configs and `enda` endianness flags. When `moov` follows `mdat` (typical of camera and QuickTime output) the file is buffered until the header arrives.
+TrueHD tracks throw an error naming the codec. Fragmented MP4 (ISO/IEC 14496-12 §8.8, `moof`+`mdat` after an empty-table `moov`) streams fragment by fragment, holding only the bytes not yet read. QuickTime sound descriptions v0, v1 and v2 are handled, including `wave`-wrapped configs and `enda` endianness flags. When `moov` follows `mdat` (typical of camera and QuickTime output) the file is buffered until the header arrives.
 
 Codec packages are imported dynamically, which is unavailable inside an AudioWorklet — decode in the main thread or a Worker.
 

package/decode-mp4.js

@@ -41,6 +41,7 @@ class MP4Decoder {
 		this.pending = null   // codec load in flight
 		this.codec = null     // { feed(frames), flush(), free() }
 		this.st = null        // sample-table walker: { sizes, stco, stsc, idx, ci, sInC, spc, nextOff }
+		this.fr = null        // fragment walker (fragmented file): { id, trex, pos, queue, qi }
 		this.left = null      // unconsumed bytes
 		this.fileOff = 0      // absolute file offset of left[0]
 		this.skip = 0         // bytes to discard before the next sample
@@ -52,7 +53,7 @@ class MP4Decoder {
 		if (!data || !data.byteLength) return EMPTY
 		let buf = data instanceof Uint8Array ? data : new Uint8Array(data)
 		if (this.pending) return this.pending.then(() => this.decode(buf))
-		if (this.st) return this.feed(buf)
+		if (this.st || this.fr) return this.feed(buf)
 
 		this.accum.push(buf); this.accumLen += buf.length
 		let all = this.accum.length === 1 ? this.accum[0] : concat(this.accum, this.accumLen)
@@ -64,8 +65,10 @@ class MP4Decoder {
 			if (this.freed) { codec.free(); return EMPTY }
 			this.codec = codec
 			let { sizes, stco, stsc } = track
-			this.st = { sizes, stco, stsc, idx: 0, ci: 0, sInC: 0, spc: spcAt(0, stsc), nextOff: stco[0] }
 			this.left = all; this.fileOff = 0; this.skip = 0
+			// fragmented (ISO/IEC 14496-12 §8.8): samples come in moof+mdat pairs after the moov
+			if (track.fragmented) { this.fr = { id: track.id, trex: track.trex, pos: 0, queue: [], qi: 0 }; return this.fragments() }
+			this.st = { sizes, stco, stsc, idx: 0, ci: 0, sInC: 0, spc: spcAt(0, stsc), nextOff: stco[0] }
 			return this.extract()
 		})
 	}
@@ -78,7 +81,37 @@ class MP4Decoder {
 			if (!buf.length) return EMPTY
 		}
 		this.left = append(this.left, buf)
-		return this.extract()
+		return this.fr ? this.fragments() : this.extract()
+	}
+
+	// Top-level boxes in order: each complete moof queues its samples (absolute offsets), which are
+	// read out of the following mdat as its bytes arrive; bytes nobody needs any more are dropped.
+	fragments() {
+		let fr = this.fr, frames = []
+		for (;;) {
+			let q = fr.queue
+			for (; fr.qi < q.length; fr.qi++) {
+				let [off, sz] = q[fr.qi], b = off - this.fileOff
+				if (!this.left || b + sz > this.left.length) break
+				frames.push(this.left.subarray(b, b + sz))
+			}
+			if (fr.qi === q.length) { q.length = 0; fr.qi = 0 }
+			let b = fr.pos - this.fileOff, left = this.left
+			if (fr.pos === Infinity || !left || b < 0 || b + 8 > left.length) break
+			let size = r32(left, b), type = str4(left, b + 4)
+			if (size === 1) { if (b + 16 > left.length) break; size = r32(left, b + 8) * 0x100000000 + r32(left, b + 12) }
+			else if (size === 0) size = Infinity  // to the end of the file
+			if (type === 'moof') {
+				if (b + size > left.length) break  // wait for the whole moof
+				moofSamples(left, b, size, fr.pos, fr)
+			}
+			fr.pos += size
+		}
+		// keep bytes from the next queued sample or the next box, whichever comes first
+		let keep = Math.min(fr.pos, fr.qi < fr.queue.length ? fr.queue[fr.qi][0] : Infinity), end = this.fileOff + (this.left?.length || 0)
+		if (keep >= end && keep !== Infinity) { this.skip = keep - end; this.fileOff = end; this.left = null }
+		else if (keep > this.fileOff && keep !== Infinity) { this.left = this.left.subarray(keep - this.fileOff).slice(); this.fileOff = keep }
+		return frames.length ? this.codec.feed(frames) : EMPTY
 	}
 
 	// Walk sample tables by absolute file offset so chunk boundaries are irrelevant.
@@ -104,7 +137,6 @@ class MP4Decoder {
 		if (this.pending) return this.pending.then(() => this.flush())
 		this.freed = true
 		if (!this.codec) {
-			if (this.accumLen && findBox(concat(this.accum, this.accumLen), 'moof')) throw Error('Fragmented MP4 is not supported')
 			throw Error(this.accumLen ? 'No audio track found in MP4' : 'Not an MP4 file')
 		}
 		try { return this.codec.flush() } finally { this.codec.free(); this.codec = null; this.left = null }
@@ -114,14 +146,14 @@ class MP4Decoder {
 		if (this.freed) return
 		this.freed = true
 		this.codec?.free(); this.codec = null
-		this.accum = []; this.left = null; this.st = null
+		this.accum = []; this.left = null; this.st = null; this.fr = null
 	}
 }
 
 
 // ===== ISO BMFF demuxer =====
 
-const CONTAINERS = new Set(['moov', 'trak', 'mdia', 'minf', 'stbl', 'udta', 'edts', 'sinf', 'wave'])
+const CONTAINERS = new Set(['moov', 'trak', 'mdia', 'minf', 'stbl', 'udta', 'edts', 'sinf', 'wave', 'mvex', 'traf'])
 
 /** Walk boxes in [start, end), calling cb(type, body, bodyOff) for leaves and cb(type, null) at container boundaries. */
 function walk(buf, start, end, cb) {
@@ -144,10 +176,37 @@ function walk(buf, start, end, cb) {
 	return true
 }
 
-function findBox(buf, name) {
-	let found = false
-	walk(buf, 0, buf.length, type => { if (type === name) found = true })
-	return found
+/** Queue the samples a moof's track fragments place (ISO/IEC 14496-12 §8.8.7 tfhd, §8.8.8 trun):
+ *  absolute [offset, size] pairs, sizes from trun, else tfhd's default, else trex's. */
+function moofSamples(buf, start, size, abs, fr) {
+	let traf = null
+	walk(buf, start + 8, start + size, (type, d) => {
+		if (type === 'traf') traf = { base: abs, size: fr.trex.size || 0, mine: false, next: null }
+		else if (type === 'tfhd') {
+			let flags = (d[1] << 16) | (d[2] << 8) | d[3], p = 8
+			traf.mine = r32(d, 4) === fr.id
+			if (flags & 1) { traf.base = r32(d, p) * 0x100000000 + r32(d, p + 4); p += 8 }  // else: default-base-is-moof, or the first traf
+			if (flags & 2) p += 4
+			if (flags & 8) p += 4
+			if (flags & 0x10) traf.size = r32(d, p)
+		}
+		else if (type === 'trun' && traf?.mine) {
+			let flags = (d[1] << 16) | (d[2] << 8) | d[3], n = r32(d, 4), p = 8
+			let off = traf.next ?? traf.base
+			if (flags & 1) { off = traf.base + (r32(d, p) | 0); p += 4 }
+			if (flags & 4) p += 4
+			for (let i = 0; i < n; i++) {
+				if (flags & 0x100) p += 4
+				let sz = traf.size
+				if (flags & 0x200) { sz = r32(d, p); p += 4 }
+				if (flags & 0x400) p += 4
+				if (flags & 0x800) p += 4
+				fr.queue.push([off, sz])
+				off += sz
+			}
+			traf.next = off
+		}
+	})
 }
 
 // QuickTime sound sample description: v0 = 36-byte header, v1 adds 16 bytes, v2 declares its own size.
@@ -179,13 +238,17 @@ function parseStsd(buf, off, end, cb) {
 
 /** Parse the first audio track out of a complete moov. Returns null while moov is incomplete or absent. */
 function parseTrack(buf) {
-	let traks = [], t = null, moov = false
+	let traks = [], t = null, moov = false, trex = new Map(), movie = {}
 	walk(buf, 0, buf.length, (type, data, off) => {
 		if (type === 'moov') moov = true
+		else if (type === 'mvhd' || type === 'ilst' && !t) movie[type] = data  // movie timescale; iTunes tags
 		else if (type === 'trak') traks.push(t = { children: {} })
+		else if (type === '/trak') t = null
+		else if (type === 'trex') trex.set(r32(data, 4), { size: r32(data, 16) })
 		else if (!t) return
+		else if (type === 'tkhd') t.id = r32(data, data[0] === 1 ? 20 : 12)
 		else if (type === 'hdlr') t.handler = str4(data, 8)
-		else if (type === 'mdhd') t.timescale = r32(data, data[0] === 1 ? 20 : 12)
+		else if (type === 'mdhd') { t.timescale = r32(data, data[0] === 1 ? 20 : 12); t.children.mdhd = data }
 		else if (type === 'entry') t.entry ??= data
 		else if (type === 'stsz') t.sizes = parseStsz(data)
 		else if (type === 'stco') t.stco = parseStco(data)
@@ -196,8 +259,11 @@ function parseTrack(buf) {
 	if (!moov) return null
 	let track = traks.find(t => t.handler === 'soun' && t.entry) ?? traks.find(t => t.entry && AUDIO_TYPES.has(t.entry.type))
 	if (!track) throw Error('No audio track found in MP4')
-	if (!track.sizes || !track.stco?.length) throw Error('Audio track has no sample tables')
+	// movie fragments carry the samples when mvex is there and the tables are empty
+	if (trex.size && !track.sizes?.length) { track.fragmented = true; track.trex = trex.get(track.id) || {} }
+	else if (!track.sizes || !track.stco?.length) throw Error('Audio track has no sample tables')
 	if (!track.entry.sampleRate && track.timescale) track.entry.sampleRate = track.timescale
+	track.movie = movie
 	return track
 }
 
@@ -252,25 +318,27 @@ const MP3_OTI = new Set([0x69, 0x6B]), AAC_OTI = new Set([0x40, 0x66, 0x67, 0x68
 const UNSUPPORTED = { 0xE1: 'QCELP' }
 const DTS_TYPES = new Set(['dtsc', 'dtsh', 'dtsl', 'dtse']) // DTS-HD variants carry a decodable core
 
-async function createCodec({ entry, children }) {
+async function createCodec({ entry, children, movie }) {
 	let { type } = entry
+	// AAC and ALAC trim the encoder's priming and padding by the track's edit list or iTunSMPB, MP3 by the edit list (gapless)
+	let boxes = { elst: children.elst, mdhd: children.mdhd, stts: children.stts, mvhd: movie?.mvhd, ilst: movie?.ilst ?? children.ilst }
 	if (type === 'mp4a') {
 		let { oti, dsi } = children.esds ? parseEsds(children.esds) : {}
-		if (MP3_OTI.has(oti)) return frames(import('@audio/decode-mp3'))
+		if (MP3_OTI.has(oti)) return mp3(boxes)
 		if (oti === 0xA5) return frames(import('@audio/decode-ac3'))
 		if (oti === 0xA9) return frames(import('@audio/decode-dts'))
 		if (oti === 0xA6) return frames(import('@audio/decode-eac3'))
 		if (!oti || AAC_OTI.has(oti)) {
 			if (!dsi) throw Error('MP4 AAC track has no AudioSpecificConfig')
-			return aac({ asc: dsi })
+			return aac({ asc: dsi }, boxes)
 		}
 		throw unsupported(UNSUPPORTED[oti] || 'esds object type 0x' + oti.toString(16))
 	}
 	if (type === 'alac') {
 		if (!children.alac) throw Error('MP4 ALAC track has no magic cookie')
-		return aac({ alac: children.alac })
+		return aac({ alac: children.alac }, boxes)
 	}
-	if (type === '.mp3') return frames(import('@audio/decode-mp3'))
+	if (type === '.mp3') return mp3(boxes)
 	if (type === 'fLaC') {
 		if (!children.dfLa) throw Error('MP4 FLAC track has no dfLa box')
 		return flac(children.dfLa.subarray(4))
@@ -319,8 +387,9 @@ function pcmFormat(e, ch) {
 
 // --- adapters: { feed(frames: Uint8Array[]), flush(), free() } ---
 
-async function aac(opts) {
-	let dec = await (await import('@audio/decode-aac')).decoder(opts)
+async function aac(opts, boxes) {
+	let { decoder, gapless } = await import('@audio/decode-aac')
+	let dec = await decoder({ ...opts, gapless: gapless?.({ ...boxes, ...opts }) })
 	return { feed: frames => dec.decode(frames), flush: () => dec.flush(), free: () => dec.free() }
 }
 
@@ -330,6 +399,26 @@ async function frames(load) {
 	return { feed: frames => dec.decode(concat(frames)), flush: () => dec.flush?.() ?? EMPTY, free: () => dec.free() }
 }
 
+// MP3 samples carry no LAME tag, so mpg123 decodes from the media's first sample: the edit list's window drops the
+// encoder and decoder delay (1105 for LAME, as ffmpeg writes it) and the padding. decode-aac reads the window.
+async function mp3(boxes) {
+	let [codec, { gapless }] = await Promise.all([frames(import('@audio/decode-mp3')), import('@audio/decode-aac')])
+	let g = gapless?.(boxes)
+	if (!g) return codec
+	let skip = null, left = null
+	return {
+		feed(frames) {
+			let r = codec.feed(frames), n = r.channelData?.[0]?.length
+			if (!n) return r
+			skip ??= Math.round(g.start * r.sampleRate); left ??= g.duration == null ? Infinity : Math.round(g.duration * r.sampleRate)
+			let a = Math.min(n, skip), b = Math.min(n, a + left)
+			skip -= a; left -= b - a
+			return b <= a ? EMPTY : a || b < n ? { ...r, channelData: r.channelData.map(c => c.subarray(a, b)) } : r
+		},
+		flush: codec.flush, free: codec.free
+	}
+}
+
 async function flac(blocks) {
 	let dec = await (await import('@audio/decode-flac')).decoder()
 	let head = concat([new Uint8Array([0x66, 0x4C, 0x61, 0x43]), blocks]) // "fLaC" + METADATA_BLOCKs
@@ -341,12 +430,17 @@ async function flac(blocks) {
 	}
 }
 
+// Mapping family 1 orders 3–8 channels as Vorbis does (RFC 7845 §5.1.1.2): out in SMPTE/WAV order (L R C LFE Ls Rs …)
+// as decode-opus reorders Ogg Opus: output channel j takes the coded channel of Vorbis position OPUS_ORDER[n][j]
+const OPUS_ORDER = { 3: [0, 2, 1], 5: [0, 2, 1, 3, 4], 6: [0, 2, 1, 5, 3, 4], 7: [0, 2, 1, 6, 5, 3, 4], 8: [0, 2, 1, 7, 5, 6, 3, 4] }
+
 async function opus(dOps) {
 	let channels = dOps[1]
 	let opts = { channels, sampleRate: 48000, preSkip: r16(dOps, 2), outputGain: (r16(dOps, 8) << 16) >> 16 }
 	if (dOps[10] > 0) {
 		opts.streamCount = dOps[11]; opts.coupledStreamCount = dOps[12]
-		opts.channelMappingTable = Array.from(dOps.subarray(13, 13 + channels))
+		let table = Array.from(dOps.subarray(13, 13 + channels))
+		opts.channelMappingTable = dOps[10] === 1 && OPUS_ORDER[channels] ? OPUS_ORDER[channels].map(i => table[i]) : table
 	}
 	let dec = await (await import('@audio/decode-opus/core')).createOpusDecoder()
 	dec.configure(opts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audio/decode-mp4",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Decode the audio track of MP4, MOV, M4A, M4V and 3GP files (AAC, ALAC, MP3, FLAC, Opus, AMR, PCM) to PCM samples",
   "type": "module",
   "main": "decode-mp4.js",
@@ -27,13 +27,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@audio/decode-aac": "^1.5.0",
+    "@audio/decode-aac": "^1.6.0",
     "@audio/decode-ac3": "^1.0.0",
     "@audio/decode-amr": "^1.3.0",
     "@audio/decode-dts": "^1.0.0",
     "@audio/decode-flac": "^1.3.0",
     "@audio/decode-mp3": "^1.3.0",
-    "@audio/decode-opus": "^1.3.0",
+    "@audio/decode-opus": "^1.3.3",
     "@audio/decode-eac3": "^1.0.0"
   },
   "devDependencies": {