mediabunny 1.0.2 → 1.0.4

package/src/mp3/mp3-demuxer.ts

@@ -0,0 +1,228 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { AudioCodec } from '../codec';
+import { Demuxer } from '../demuxer';
+import { Input } from '../input';
+import { InputAudioTrack, InputAudioTrackBacking } from '../input-track';
+import { PacketRetrievalOptions } from '../media-sink';
+import { assert, binarySearchExact, binarySearchLessOrEqual, last, UNDETERMINED_LANGUAGE } from '../misc';
+import { EncodedPacket, PLACEHOLDER_DATA } from '../packet';
+import { FrameHeader, getXingOffset, INFO, XING } from './mp3-misc';
+import { Mp3Reader } from './mp3-reader';
+
+type Sample = {
+	timestamp: number;
+	duration: number;
+	dataStart: number;
+	dataSize: number;
+};
+
+export class Mp3Demuxer extends Demuxer {
+	reader: Mp3Reader;
+
+	metadataPromise: Promise<void> | null = null;
+	firstFrameHeader: FrameHeader | null = null;
+	allSamples: Sample[] = [];
+
+	tracks: InputAudioTrack[] = [];
+
+	constructor(input: Input) {
+		super(input);
+
+		this.reader = new Mp3Reader(input._mainReader);
+	}
+
+	async readMetadata() {
+		return this.metadataPromise ??= (async () => {
+			const fileSize = await this.input.source.getSize();
+			this.reader.fileSize = fileSize;
+
+			// Just load the entire file. Primitive, but the only way to actually ensure 100% correct timestamps.
+			// Random access in MP3 can be flaky and unreliable.
+			await this.reader.reader.loadRange(0, fileSize);
+
+			const id3Tag = this.reader.readId3();
+			if (id3Tag) {
+				this.reader.pos += id3Tag.size;
+			}
+
+			let nextTimestampInSamples = 0;
+
+			// Let's read all samples
+			while (true) {
+				const header = this.reader.readNextFrameHeader();
+				if (!header) {
+					break;
+				}
+
+				const xingOffset = getXingOffset(header.mpegVersionId, header.channel);
+				this.reader.pos = header.startPos + xingOffset;
+				const word = this.reader.readU32();
+				const isXing = word === XING || word === INFO;
+
+				this.reader.pos = header.startPos + header.totalSize - 1; // -1 in case the frame is 1 byte too short
+
+				if (isXing) {
+					// There's no actual audio data in this frame, so let's skip it
+					continue;
+				}
+
+				if (!this.firstFrameHeader) {
+					this.firstFrameHeader = header;
+				}
+
+				const sampleDuration = header.audioSamplesInFrame / header.sampleRate;
+				const sample: Sample = {
+					timestamp: nextTimestampInSamples / header.sampleRate,
+					duration: sampleDuration,
+					dataStart: header.startPos,
+					dataSize: header.totalSize,
+				};
+
+				this.allSamples.push(sample);
+				nextTimestampInSamples += header.audioSamplesInFrame;
+			}
+
+			if (!this.firstFrameHeader) {
+				throw new Error('No MP3 frames found.');
+			}
+
+			this.tracks = [new InputAudioTrack(new Mp3AudioTrackBacking(this))];
+		})();
+	}
+
+	async getMimeType() {
+		return 'audio/mpeg';
+	}
+
+	async getTracks() {
+		await this.readMetadata();
+		return this.tracks;
+	}
+
+	async computeDuration() {
+		await this.readMetadata();
+
+		const lastSample = last(this.allSamples);
+		assert(lastSample);
+
+		return lastSample.timestamp + lastSample.duration;
+	}
+}
+
+class Mp3AudioTrackBacking implements InputAudioTrackBacking {
+	constructor(public demuxer: Mp3Demuxer) {}
+
+	getId() {
+		return 1;
+	}
+
+	async getFirstTimestamp() {
+		return 0;
+	}
+
+	getTimeResolution() {
+		assert(this.demuxer.firstFrameHeader);
+		return this.demuxer.firstFrameHeader.sampleRate / this.demuxer.firstFrameHeader.audioSamplesInFrame;
+	}
+
+	computeDuration() {
+		return this.demuxer.computeDuration();
+	}
+
+	getLanguageCode() {
+		return UNDETERMINED_LANGUAGE;
+	}
+
+	getCodec(): AudioCodec {
+		return 'mp3';
+	}
+
+	getNumberOfChannels() {
+		assert(this.demuxer.firstFrameHeader);
+		return this.demuxer.firstFrameHeader.channel === 3 ? 1 : 2;
+	}
+
+	getSampleRate() {
+		assert(this.demuxer.firstFrameHeader);
+		return this.demuxer.firstFrameHeader.sampleRate;
+	}
+
+	async getDecoderConfig(): Promise<AudioDecoderConfig> {
+		assert(this.demuxer.firstFrameHeader);
+
+		return {
+			codec: 'mp3',
+			numberOfChannels: this.demuxer.firstFrameHeader.channel === 3 ? 1 : 2,
+			sampleRate: this.demuxer.firstFrameHeader.sampleRate,
+		};
+	}
+
+	getPacketAtIndex(sampleIndex: number, options: PacketRetrievalOptions) {
+		if (sampleIndex === -1) {
+			return null;
+		}
+
+		const rawSample = this.demuxer.allSamples[sampleIndex];
+		if (!rawSample) {
+			return null;
+		}
+
+		let data: Uint8Array;
+		if (options.metadataOnly) {
+			data = PLACEHOLDER_DATA;
+		} else {
+			this.demuxer.reader.pos = rawSample.dataStart;
+			data = this.demuxer.reader.readBytes(rawSample.dataSize);
+		}
+
+		return new EncodedPacket(
+			data,
+			'key',
+			rawSample.timestamp,
+			rawSample.duration,
+			sampleIndex,
+			rawSample.dataSize,
+		);
+	}
+
+	async getFirstPacket(options: PacketRetrievalOptions) {
+		return this.getPacketAtIndex(0, options);
+	}
+
+	async getNextPacket(packet: EncodedPacket, options: PacketRetrievalOptions) {
+		const sampleIndex = binarySearchExact(
+			this.demuxer.allSamples,
+			packet.timestamp,
+			x => x.timestamp,
+		);
+		if (sampleIndex === -1) {
+			throw new Error('Packet was not created from this track.');
+		}
+
+		return this.getPacketAtIndex(sampleIndex + 1, options);
+	}
+
+	async getPacket(timestamp: number, options: PacketRetrievalOptions) {
+		const index = binarySearchLessOrEqual(
+			this.demuxer.allSamples,
+			timestamp,
+			x => x.timestamp,
+		);
+		return this.getPacketAtIndex(index, options);
+	}
+
+	getKeyPacket(timestamp: number, options: PacketRetrievalOptions) {
+		return this.getPacket(timestamp, options);
+	}
+
+	getNextKeyPacket(packet: EncodedPacket, options: PacketRetrievalOptions) {
+		return this.getNextPacket(packet, options);
+	}
+}

package/src/mp3/mp3-misc.ts

@@ -0,0 +1,154 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+export const FRAME_HEADER_SIZE = 4;
+
+// These are in kbps:
+export const MPEG_V1_BITRATES: Record<number, number[]> = {
+	// Layer 3
+	1: [-1, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, -1],
+	// Layer 2
+	2: [-1, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, -1],
+	// Layer 1
+	3: [-1, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448, -1],
+};
+export const MPEG_V2_BITRATES: Record<number, number[]> = {
+	// Layer 3
+	1: [-1, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256, -1],
+	// Layer 2
+	2: [-1, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, -1],
+	// Layer 1
+	3: [-1, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160, -1],
+};
+export const SAMPLING_RATES: Record<number, number[]> = {
+	// MPEG Version 2.5
+	0: [11025, 12000, 8000, -1],
+	// MPEG Version 2 (ISO/IEC 13818-3)
+	2: [22050, 24000, 16000, -1],
+	// MPEG Version 1 (ISO/IEC 11172-3)
+	3: [44100, 48000, 32000, -1],
+};
+
+/** 'Xing' */
+export const XING = 0x58696e67;
+/** 'Info' */
+export const INFO = 0x496e666f;
+
+export type FrameHeader = {
+	startPos: number;
+	totalSize: number;
+	mpegVersionId: number;
+	layer: number;
+	bitrate: number;
+	frequencyIndex: number;
+	sampleRate: number;
+	channel: number;
+	modeExtension: number;
+	copyright: number;
+	original: number;
+	emphasis: number;
+	audioSamplesInFrame: number;
+};
+
+export const computeMp3FrameSize = (layer: number, bitrate: number, sampleRate: number, padding: number) => {
+	if (layer === 3) {
+		// Layer 1
+		return Math.floor((12 * bitrate / sampleRate + padding) * 4);
+	} else {
+		return Math.floor((144 * bitrate / sampleRate) + padding);
+	}
+};
+
+export const getXingOffset = (mpegVersionId: number, channel: number) => {
+	return mpegVersionId === 3
+		? (channel === 3 ? 21 : 36)
+		: (channel === 3 ? 13 : 21);
+};
+
+export const readFrameHeader = (word: number, reader: { pos: number; fileSize: number | null }): FrameHeader | null => {
+	const startPos = reader.pos;
+
+	const firstByte = word >>> 24;
+	const secondByte = (word >>> 16) & 0xff;
+	const thirdByte = (word >>> 8) & 0xff;
+	const fourthByte = word & 0xff;
+
+	if (firstByte !== 0xff && secondByte !== 0xff && thirdByte !== 0xff && fourthByte !== 0xff) {
+		reader.pos += 4;
+		return null;
+	}
+
+	reader.pos += 1;
+
+	if ((secondByte & 0xe0) !== 0xe0) {
+		return null;
+	}
+
+	const mpegVersionId = (secondByte >> 3) & 0x3;
+	const layer = (secondByte >> 1) & 0x3;
+
+	const bitrateIndex = (thirdByte >> 4) & 0xf;
+	const frequencyIndex = (thirdByte >> 2) & 0x3;
+	const padding = (thirdByte >> 1) & 0x1;
+
+	const channel = (fourthByte >> 6) & 0x3;
+	const modeExtension = (fourthByte >> 4) & 0x3;
+	const copyright = (fourthByte >> 3) & 0x1;
+	const original = (fourthByte >> 2) & 0x1;
+	const emphasis = fourthByte & 0x3;
+
+	const kilobitRate = mpegVersionId === 3
+		? MPEG_V1_BITRATES[layer]?.[bitrateIndex]
+		: MPEG_V2_BITRATES[layer]?.[bitrateIndex];
+	if (!kilobitRate || kilobitRate === -1) {
+		return null;
+	}
+
+	const bitrate = kilobitRate * 1000;
+
+	const sampleRate = SAMPLING_RATES[mpegVersionId]?.[frequencyIndex];
+	if (!sampleRate || sampleRate === -1) {
+		return null;
+	}
+
+	const frameLength = computeMp3FrameSize(layer, bitrate, sampleRate, padding);
+
+	if (reader.fileSize !== null && reader.fileSize - startPos < frameLength) {
+		// The frame doesn't fit into the rest of the file
+		return null;
+	}
+
+	let audioSamplesInFrame: number;
+	if (mpegVersionId === 3) {
+		audioSamplesInFrame = layer === 3 ? 384 : 1152;
+	} else {
+		if (layer === 3) {
+			audioSamplesInFrame = 384;
+		} else if (layer === 2) {
+			audioSamplesInFrame = 1152;
+		} else {
+			audioSamplesInFrame = 576;
+		}
+	}
+
+	return {
+		startPos: startPos,
+		totalSize: frameLength,
+		mpegVersionId,
+		layer,
+		bitrate,
+		frequencyIndex,
+		sampleRate,
+		channel,
+		modeExtension,
+		copyright,
+		original,
+		emphasis,
+		audioSamplesInFrame,
+	};
+};

package/src/mp3/mp3-muxer.ts

@@ -0,0 +1,153 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { assert, toDataView } from '../misc';
+import { Muxer } from '../muxer';
+import { Output, OutputAudioTrack } from '../output';
+import { Mp3OutputFormat } from '../output-format';
+import { EncodedPacket } from '../packet';
+import { Writer } from '../writer';
+import { getXingOffset, INFO, readFrameHeader, XING } from './mp3-misc';
+import { Mp3Writer, XingFrameData } from './mp3-writer';
+
+export class Mp3Muxer extends Muxer {
+	private format: Mp3OutputFormat;
+	private writer: Writer;
+	private mp3Writer: Mp3Writer;
+	private xingFrameData: XingFrameData | null = null;
+	private frameCount = 0;
+	private framePositions: number[] = [];
+
+	constructor(output: Output, format: Mp3OutputFormat) {
+		super(output);
+
+		this.format = format;
+		this.writer = output._writer;
+		this.mp3Writer = new Mp3Writer(output._writer);
+	}
+
+	async start() {
+		// Nothing needed here
+	}
+
+	async getMimeType() {
+		return 'audio/mpeg';
+	}
+
+	async addEncodedVideoPacket() {
+		throw new Error('MP3 does not support video.');
+	}
+
+	async addEncodedAudioPacket(
+		track: OutputAudioTrack,
+		packet: EncodedPacket,
+	) {
+		const release = await this.mutex.acquire();
+
+		try {
+			if (!this.xingFrameData) {
+				const view = toDataView(packet.data);
+				if (view.byteLength < 4) {
+					throw new Error('Invalid MP3 header in sample.');
+				}
+
+				const word = view.getUint32(0, false);
+				const header = readFrameHeader(word, { pos: 0, fileSize: null });
+				if (!header) {
+					throw new Error('Invalid MP3 header in sample.');
+				}
+
+				const xingOffset = getXingOffset(header.mpegVersionId, header.channel);
+				if (view.byteLength >= xingOffset + 4) {
+					const word = view.getUint32(xingOffset, false);
+					const isXing = word === XING || word === INFO;
+
+					if (isXing) {
+						// This is not a data frame, so let's completely ignore this sample
+						return;
+					}
+				}
+
+				this.xingFrameData = {
+					mpegVersionId: header.mpegVersionId,
+					layer: header.layer,
+					frequencyIndex: header.frequencyIndex,
+					channel: header.channel,
+					modeExtension: header.modeExtension,
+					copyright: header.copyright,
+					original: header.original,
+					emphasis: header.emphasis,
+
+					frameCount: null,
+					fileSize: null,
+					toc: null,
+				};
+
+				// Write a Xing frame because this muxer doesn't make any bitrate constraints, meaning we don't know if
+				// this will be a constant or variable bitrate file. Therefore, always write the Xing frame.
+				this.mp3Writer.writeXingFrame(this.xingFrameData);
+
+				this.frameCount++;
+			}
+
+			this.validateAndNormalizeTimestamp(track, packet.timestamp, packet.type === 'key');
+
+			this.framePositions.push(this.writer.getPos());
+			this.writer.write(packet.data);
+			this.frameCount++;
+
+			await this.writer.flush();
+		} finally {
+			release();
+		}
+	}
+
+	async addSubtitleCue() {
+		throw new Error('MP3 does not support subtitles.');
+	}
+
+	async finalize() {
+		if (!this.xingFrameData) {
+			return;
+		}
+
+		const release = await this.mutex.acquire();
+
+		const endPos = this.writer.getPos();
+
+		this.writer.seek(0);
+
+		const toc = new Uint8Array(100);
+		for (let i = 0; i < 100; i++) {
+			const index = Math.floor(this.framePositions.length * (i / 100));
+			assert(index !== -1 && index < this.framePositions.length);
+
+			const byteOffset = this.framePositions[index]!;
+			toc[i] = 256 * (byteOffset / endPos);
+		}
+
+		this.xingFrameData.frameCount = this.frameCount;
+		this.xingFrameData.fileSize = endPos;
+		this.xingFrameData.toc = toc;
+
+		if (this.format._options.onXingFrame) {
+			this.writer.startTrackingWrites();
+		}
+
+		this.mp3Writer.writeXingFrame(this.xingFrameData);
+
+		if (this.format._options.onXingFrame) {
+			const { data, start } = this.writer.stopTrackingWrites();
+			this.format._options.onXingFrame(data, start);
+		}
+
+		this.writer.seek(endPos);
+
+		release();
+	}
+}

package/src/mp3/mp3-reader.ts

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) 2025-present, Vanilagy and contributors
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { assert } from '../misc';
+import { Reader } from '../reader';
+import { FRAME_HEADER_SIZE, FrameHeader, readFrameHeader } from './mp3-misc';
+
+export class Mp3Reader {
+	pos = 0;
+	fileSize: number | null = null;
+
+	constructor(public reader: Reader) {}
+
+	readBytes(length: number) {
+		const { view, offset } = this.reader.getViewAndOffset(this.pos, this.pos + length);
+		this.pos += length;
+
+		return new Uint8Array(view.buffer, offset, length);
+	}
+
+	readU16() {
+		const { view, offset } = this.reader.getViewAndOffset(this.pos, this.pos + 2);
+		this.pos += 2;
+
+		return view.getUint16(offset, false);
+	}
+
+	readU32() {
+		const { view, offset } = this.reader.getViewAndOffset(this.pos, this.pos + 4);
+		this.pos += 4;
+
+		return view.getUint32(offset, false);
+	}
+
+	readAscii(length: number) {
+		const { view, offset } = this.reader.getViewAndOffset(this.pos, this.pos + length);
+		this.pos += length;
+
+		let str = '';
+		for (let i = 0; i < length; i++) {
+			str += String.fromCharCode(view.getUint8(offset + i));
+		}
+		return str;
+	}
+
+	readId3() {
+		const tag = this.readAscii(3);
+		if (tag !== 'ID3') {
+			this.pos -= 3;
+			return null;
+		}
+
+		this.pos += 3;
+
+		const size = decodeSynchsafe(this.readU32());
+		return { size };
+	}
+
+	readNextFrameHeader(until?: number): FrameHeader | null {
+		assert(this.fileSize);
+		until ??= this.fileSize;
+
+		while (this.pos < until - FRAME_HEADER_SIZE) {
+			const word = this.readU32();
+			this.pos -= 4;
+
+			const header = readFrameHeader(word, this);
+			if (header) {
+				return header;
+			}
+		}
+
+		return null;
+	}
+}
+
+export const decodeSynchsafe = (synchsafed: number) => {
+	let mask = 0x7f000000;
+	let unsynchsafed = 0;
+
+	while (mask !== 0) {
+		unsynchsafed >>= 1;
+		unsynchsafed |= synchsafed & mask;
+		mask >>= 8;
+	}
+
+	return unsynchsafed;
+};