@audio/decode-aac 1.5.0 → 1.6.0

package/README.md

@@ -54,6 +54,16 @@ let dec = await decoder({ alac })  // ALAC magic cookie
 
 This is how [@audio/decode-mp4](../decode-mp4), [@audio/decode-webm](../decode-webm) and [@audio/decode-avi](../decode-avi) decode AAC and ALAC tracks from video files.
 
+### Gapless
+
+An M4A is decoded gapless: the encoder's priming (Apple's encoders: 2112 samples) and padding are trimmed, so the output has the source's length and timing. The track's edit list says where the presentation starts when it has one media edit ([ISO/IEC 14496-12](https://www.iso.org/standard/83102.html) §8.6.6; several are an edit, not a trim: the track decodes whole), else iTunes' `iTunSMPB` tag; FAAD2's own delay (it withholds its first frame; SBR delays HE-AAC 962 samples more) is accounted for. A raw ADTS stream carries no such information and keeps the decoder's delay. A demuxer passes the window it read from its container:
+
+```js
+import { decoder, gapless } from '@audio/decode-aac'
+let dec = await decoder({ asc, gapless: gapless({ elst, mdhd, stts, mvhd, ilst, asc }) })  // box bodies
+// or directly: { gapless: { start, duration } } in seconds of the media timeline
+```
+
 ### `AudioData`
 
 ```ts

package/decode-aac.d.ts

@@ -18,7 +18,29 @@ export interface RawOptions {
   asc?: Uint8Array;
   /** ALAC magic cookie (24-byte ALACSpecificConfig, `alac` box body, or full atom) — decode raw ALAC frames */
   alac?: Uint8Array;
+  /** With `asc`/`alac`: trim the encoder's priming and padding to this window, as `gapless()` reads it from the container */
+  gapless?: GaplessWindow;
 }
 
+/** Seconds of the media timeline: the output starts at `start` and lasts `duration` (to the end when absent) */
+export interface GaplessWindow {
+  start: number;
+  duration?: number;
+}
+
+/** Box bodies of an MP4 audio track (`elst` `mdhd` `stts` `mvhd` `ilst`) and its codec config (`asc` or `alac`) */
+export interface GaplessBoxes {
+  elst?: Uint8Array;
+  mdhd?: Uint8Array;
+  stts?: Uint8Array;
+  mvhd?: Uint8Array;
+  ilst?: Uint8Array;
+  asc?: Uint8Array;
+  alac?: Uint8Array;
+}
+
+/** The track's gapless window: its edit list's one media edit, else iTunes' iTunSMPB; null without either, or with several media edits */
+export function gapless(boxes: GaplessBoxes): GaplessWindow | null;
+
 /** Create streaming decoder instance. Auto-detects M4A vs ADTS, or decodes raw frames when a config is given. */
 export function decoder(opts?: RawOptions): Promise<AACDecoder>;

package/decode-aac.js

@@ -40,13 +40,16 @@ export default async function decode(src) {
  * With `asc` (AudioSpecificConfig) or `alac` (ALAC magic cookie) it decodes raw access
  * units delivered out-of-band by a container demuxer (MP4, Matroska, AVI): each decode()
  * call takes one complete frame, or an array of frames.
- * @param {{ asc?: Uint8Array, alac?: Uint8Array }} [opts]
+ * `gapless` ({ start, duration } seconds of the media timeline, gapless() from the container's boxes)
+ * trims the encoder's priming and padding: the output starts at `start` and lasts `duration`.
+ * @param {{ asc?: Uint8Array, alac?: Uint8Array, gapless?: { start: number, duration?: number } }} [opts]
  * @returns {Promise<{decode(chunk: Uint8Array | Uint8Array[]): {channelData, sampleRate}, flush(), free()}>}
  */
 export async function decoder(opts) {
 	let dec = new AACDecoder(await getMod())
 	if (opts?.asc) { dec._initASC(opts.asc); dec._raw = true }
 	else if (opts?.alac) { dec._initALAC(opts.alac); dec._raw = true }
+	if (dec._raw && opts.gapless) dec._window(opts.gapless)
 	return dec
 }
 
@@ -69,13 +72,15 @@ class AACDecoder {
 		this._accumLen = 0
 		this._alac = null     // ALAC decoder when the M4A carries Apple Lossless
 		this._raw = false     // raw access units (config given up-front)
+		this._gap = null      // gapless trim: { skip, left } output samples (_window)
+		this._core = 0        // the AudioSpecificConfig's own rate (half the output's with SBR)
 	}
 
 	decode(data) {
 		if (this.done) throw Error('Decoder already freed')
 		if (this._raw) {
 			let frames = (Array.isArray(data) ? data : [data]).filter(f => f?.byteLength).map(f => f instanceof Uint8Array ? f : new Uint8Array(f))
-			return frames.length ? this._feedFrames(frames) : EMPTY
+			return frames.length ? this._trim(this._feedFrames(frames)) : EMPTY
 		}
 		if (!data || !data.byteLength) return EMPTY
 
@@ -126,10 +131,12 @@ class AACDecoder {
 		let buf = this._catAccum()
 		// tables are collected per trak — a second non-audio track (e.g. a QuickTime
 		// chapter/text track, github #48) must not clobber the audio track's tables
-		let traks = [], t = null, moov = false
+		let traks = [], t = null, moov = false, mvhd = null, smpb = null
 
 		parseBoxes(buf, 0, buf.length, (type, data) => {
 			if (type === 'moov') moov = true
+			else if (type === 'mvhd') mvhd = data
+			else if (type === 'ilst') smpb = data
 			else if (type === 'trak') traks.push(t = {})
 			else if (!t) return
 			else if (type === 'esds') t.asc = parseEsds(data)
@@ -138,10 +145,12 @@ class AACDecoder {
 			else if (type === 'stco') t.stco = parseStco(data)
 			else if (type === 'co64') t.stco = parseCo64(data)
 			else if (type === 'stsc') t.stsc = parseStsc(data)
+			else if (type === 'mdhd' || type === 'elst' || type === 'stts') t[type] = data
 		})
 
 		// the audio track: first trak with an audio config + sample tables
-		let { asc, alacCookie, stsz, stco, stsc } = traks.find(t => (t.asc || t.alacCookie) && t.stsz && t.stco?.length) ?? {}
+		let track = traks.find(t => (t.asc || t.alacCookie) && t.stsz && t.stco?.length) ?? {}
+		let { asc, alacCookie, stsz, stco, stsc } = track
 		if ((!asc && !alacCookie) || !stsz || !stco?.length) {
 			// the whole moov is here and still no AAC/ALAC track — other codecs live in @audio/decode-mp4
 			if (moov) throw Error('No AAC/ALAC audio track in MP4')
@@ -150,6 +159,8 @@ class AACDecoder {
 
 		if (alacCookie) this._initALAC(alacCookie)
 		else this._initASC(asc)
+		let g = gapless({ elst: track.elst, mdhd: track.mdhd, stts: track.stts, mvhd, ilst: smpb, asc, alac: alacCookie })
+		if (g) this._window(g)
 
 		// Streaming: walk sample tables by absolute file offset so chunk boundaries are irrelevant.
 		this._accum = null; this._accumLen = 0
@@ -180,6 +191,8 @@ class AACDecoder {
 		this.ch = m.getValue(chP, 'i8')
 		if (!this.ch) { m._aac_close(h); throw Error('AAC init: no channels in ASC') }
 		this.h = h
+		this._core = ascRate(asc) || this.sr
+		this._order = AAC_ORDER[(asc[1] >> 3) & 15]
 	}
 
 	_feedM4AData(buf) {
@@ -218,7 +231,26 @@ class AACDecoder {
 			this._left = null
 		}
 
-		return frames.length ? this._feedFrames(frames) : EMPTY
+		return frames.length ? this._trim(this._feedFrames(frames)) : EMPTY
+	}
+
+	// The presentation window in output samples. FAAD2 withholds its first frame (1024 samples, 2048 with
+	// SBR), so its output starts that far into the media; SBR's QMF filterbanks delay it by 962 samples (the
+	// offset of Apple's HE-AAC against its source). ALAC has no delay.
+	_window({ start = 0, duration }) {
+		let sbr = this.sr > this._core * 1.5 ? 2 : 1, offset = this._alac ? 0 : 1024 * sbr - (sbr > 1 ? SBR_DELAY : 0)
+		this._gap = { skip: Math.max(0, Math.round(start * this.sr) - offset), left: duration == null ? null : Math.round(duration * this.sr) }
+	}
+
+	// drop the priming, stop at the presentation's end
+	_trim(r) {
+		let g = this._gap
+		if (!g || !r.channelData.length) return r
+		let n = r.channelData[0].length, a = Math.min(n, g.skip), b = g.left == null ? n : Math.min(n, a + g.left)
+		g.skip -= a
+		if (g.left != null) g.left -= b - a
+		if (b <= a) return EMPTY
+		return a || b < n ? { ...r, channelData: r.channelData.map(c => c.subarray(a, b)) } : r
 	}
 
 	_alloc(len) {
@@ -243,6 +275,8 @@ class AACDecoder {
 			m.HEAPU8.set(buf, ptr)
 			let consumed = m._aac_init(h, ptr, buf.length, srP, chP)
 			if (consumed < 0) { m._aac_close(h); throw Error('ADTS init failed (code ' + consumed + ')') }
+			let a = adtsAt(buf)  // the first ADTS header: channel_configuration spans bytes 2 and 3
+			if (a >= 0) this._order = AAC_ORDER[((buf[a + 2] & 1) << 2) | (buf[a + 3] >> 6)]
 			this.sr = m.getValue(srP, 'i32')
 			this.ch = m.getValue(chP, 'i8')
 			if (!this.ch) {
@@ -301,9 +335,10 @@ class AACDecoder {
 		let channelData = Array.from({ length: channels }, () => new Float32Array(totalPerCh))
 		let pos = 0
 		for (let { data, ch, spc } of chunks) {
+			let order = ch === this._order?.length ? this._order : null
 			for (let c = 0; c < ch; c++) {
-				let out = channelData[c]
-				for (let s = 0; s < spc; s++) out[pos + s] = data[s * ch + c]
+				let out = channelData[c], k = order ? order[c] : c
+				for (let s = 0; s < spc; s++) out[pos + s] = data[s * ch + k]
 			}
 			pos += spc
 		}
@@ -331,6 +366,21 @@ class AACDecoder {
 }
 
 
+// The first ADTS header (ISO/IEC 14496-3 Annex 1.A): past an ID3v2 tag by its size, a 12-bit 0xFFF sync with layer 00,
+// and the next frame's sync where its length points, when the buffer holds it: a 0xFF inside a tag is no header
+function adtsAt(buf) {
+	let p = buf[0] === 0x49 && buf[1] === 0x44 && buf[2] === 0x33 && buf.length >= 10
+		? 10 + ((buf[6] & 0x7F) << 21 | (buf[7] & 0x7F) << 14 | (buf[8] & 0x7F) << 7 | buf[9] & 0x7F) + (buf[5] & 0x10 ? 10 : 0) : 0
+	const sync = i => buf[i] === 0xFF && (buf[i + 1] & 0xF6) === 0xF0
+	for (; p + 7 <= buf.length; p++) {
+		if (!sync(p)) continue
+		let n = p + ((buf[p + 3] & 3) << 11 | buf[p + 4] << 3 | buf[p + 5] >> 5)
+		if (n >= p + 7 && (n + 2 > buf.length || sync(n))) return p
+	}
+	return -1
+}
+
+
 // ===== M4A demuxer =====
 
 function append(left, buf) {
@@ -388,6 +438,91 @@ function parseSampleDesc(buf, off, len, cb) {
 	}
 }
 
+// Gapless: the presentation window of an MP4 audio track, { start, duration } in seconds of the media timeline
+// (null without gapless information). From the edit list (ISO/IEC 14496-12 §8.6.6): its one media edit's media_time
+// is where the presentation starts, past the encoder's priming; its length is the media's (stts) past that
+// start, capped by the edit's duration to within the movie timescale's tick (ffmpeg writes whole milliseconds,
+// floored); a duration of 0 leaves it open (§8.6.6: the edit runs to the media's end). Else iTunes' iTunSMPB tag (Apple's encoders): priming and length in samples at the codec's own rate
+// (the AudioSpecificConfig's, half the output's with SBR; ALAC's cookie's). The codec then drops its own delay
+// (decoder({ gapless })). Boxes are their bodies; `asc` or `alac` is the track's codec config.
+export function gapless({ elst, mdhd, stts, mvhd, ilst, asc, alac }) {
+	let rate = asc ? ascRate(asc) : alac?.length >= 24 ? r32(alac, alac.length - 4) : 0
+	let edits = mediaEdits(elst), edit = edits[0], ts = mdhd ? timescale(mdhd) : 0
+	// several media edits cut or repeat the media: no window of it presents them, so it decodes whole
+	if (edits.length > 1) return null
+	if (edit && ts) {
+		// a fragmented file's tables are empty (its samples ride in moof boxes): its length stays open
+		let start = edit.mediaTime / ts, media = stts ? sttsTotal(stts) / ts : 0, duration = media > start ? media - start : undefined
+		let mts = mvhd ? timescale(mvhd) : 0
+		if (edit.duration && mts) duration = Math.min(duration ?? Infinity, (edit.duration + (mts < ts ? 1 : 0)) / mts)
+		return { start, duration }
+	}
+	let smpb = ilst && parseSmpb(ilst)
+	if (smpb && rate) return { start: smpb.priming / rate, duration: smpb.total ? smpb.total / rate : undefined }
+	return null
+}
+
+const SBR_DELAY = 962
+
+// the edits that map media (media_time −1 is an empty edit: a pause, not a trim)
+function mediaEdits(data) {
+	let edits = []
+	if (!data) return edits
+	let v = data[0], n = r32(data, 4), p = 8
+	for (let i = 0; i < n; i++, p += v === 1 ? 20 : 12) {
+		let duration = v === 1 ? r32(data, p) * 2 ** 32 + r32(data, p + 4) : r32(data, p)
+		let hi = r32(data, v === 1 ? p + 8 : p + 4), mediaTime = v === 1 ? (hi | 0) * 2 ** 32 + r32(data, p + 12) : hi | 0
+		if (mediaTime >= 0) edits.push({ duration, mediaTime })
+	}
+	return edits
+}
+
+const timescale = d => r32(d, d[0] === 1 ? 20 : 12) // mvhd / mdhd: version(1) flags(3) created modified timescale
+
+function sttsTotal(d) {
+	let n = r32(d, 4), s = 0
+	for (let i = 0; i < n; i++) s += r32(d, 8 + i * 8) * r32(d, 12 + i * 8)
+	return s
+}
+
+// AAC channel configurations 3–6 put the centre first: C L R [Cs | Ls Rs [LFE]] (ISO/IEC 14496-3 Table 1.19).
+// Output channel j takes decoded channel AAC_ORDER[config][j]: SMPTE/WAV order (L R C LFE Ls Rs), as the family's
+// other decoders and `audio`'s loudness weights read them (ITU-R BS.1770)
+const AAC_ORDER = { 3: [1, 2, 0], 4: [1, 2, 0, 3], 5: [1, 2, 0, 3, 4], 6: [1, 2, 0, 5, 3, 4] }
+// 7 (8 channels) is not mapped: its second pair is outside front by that table, the sides to most 7.1 encoders
+
+// the AudioSpecificConfig's own sample rate (the core's, when SBR doubles the output)
+const ASC_RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350]
+function ascRate(asc) {
+	let i = ((asc[0] & 7) << 1) | (asc[1] >> 7)
+	if ((asc[0] >> 3) === 31) i = (asc[1] >> 1) & 15 // escaped object type: the index sits 6 bits later
+	return i === 15 ? ((asc[1] & 0x7F) << 17 | asc[2] << 9 | asc[3] << 1 | asc[4] >> 7) : ASC_RATES[i] || 0
+}
+
+// iTunes gapless tag (freeform '----' atom named iTunSMPB): hex fields, the 2nd priming, 3rd padding, 4th length
+function parseSmpb(ilst) {
+	for (let off = 0; off + 8 <= ilst.length;) {
+		let size = r32(ilst, off)
+		if (size < 8) break
+		if (ilst[off + 4] === 0x2D && ilst[off + 5] === 0x2D && ilst[off + 6] === 0x2D && ilst[off + 7] === 0x2D) {
+			let name = '', value = null
+			for (let p = off + 8; p + 8 <= off + size;) {
+				let sz = r32(ilst, p), ty = String.fromCharCode(ilst[p + 4], ilst[p + 5], ilst[p + 6], ilst[p + 7])
+				if (sz < 8) break
+				if (ty === 'name') name = String.fromCharCode(...ilst.subarray(p + 12, p + sz))
+				else if (ty === 'data') value = String.fromCharCode(...ilst.subarray(p + 16, p + sz))
+				p += sz
+			}
+			if (name === 'iTunSMPB' && value) {
+				let f = value.trim().split(/\s+/).map(h => parseInt(h, 16))
+				if (f.length >= 4 && f.every(Number.isFinite)) return { priming: f[1], padding: f[2], total: f[3] }
+			}
+		}
+		off += size
+	}
+	return null
+}
+
 function parseEsds(data) {
 	let off = 4
 	while (off < data.length - 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audio/decode-aac",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Decode AAC/M4A (FAAD2 WASM) and ALAC/Apple Lossless (pure JS) to PCM samples",
   "type": "module",
   "main": "decode-aac.js",