@mediabunny/mp3-encoder 1.6.1

package/src/encode.worker.ts

@@ -0,0 +1,212 @@
+/*!
+ * 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 createModule from '../build/lame';
+import type { WorkerCommand, WorkerResponse, WorkerResponseData } from './shared';
+
+type ExtendedEmscriptenModule = EmscriptenModule & {
+	cwrap: typeof cwrap;
+};
+
+let module: ExtendedEmscriptenModule;
+let lamePtr: number;
+let storedNumberOfChannels: number;
+let storedSampleRate: number;
+let storedBitrate: number;
+let needsReset = false;
+
+let initLame: (
+	numberOfChannels: number,
+	sampleRate: number,
+	bitrate: number
+) => number;
+let encodeSamples: (
+	lame: number,
+	leftPtr: number,
+	rightPtr: number,
+	sampleCount: number,
+	outputPtr: number,
+	outputSize: number
+) => number;
+let flushLame: (lame: number, outputPtr: number, outputSize: number) => number;
+let closeLame: (lame: number) => void;
+
+let inputSlice: Slice | null = null;
+let outputSlice: Slice | null = null;
+
+const init = async (numberOfChannels: number, sampleRate: number, bitrate: number) => {
+	storedNumberOfChannels = numberOfChannels;
+	storedSampleRate = sampleRate;
+	storedBitrate = bitrate;
+
+	module = (await createModule()) as ExtendedEmscriptenModule;
+
+	// Set up the functions
+	initLame = module.cwrap('init_lame', 'number', ['number', 'number', 'number']);
+	encodeSamples = module.cwrap(
+		'encode_samples',
+		'number',
+		['number', 'number', 'number', 'number', 'number', 'number'],
+	);
+	flushLame = module.cwrap('flush_lame', 'number', ['number', 'number', 'number']);
+	closeLame = module.cwrap('close_lame', null, ['number']);
+
+	lamePtr = initLame(numberOfChannels, sampleRate, bitrate);
+};
+
+const reset = () => {
+	closeLame(lamePtr);
+	lamePtr = initLame(storedNumberOfChannels, storedSampleRate, storedBitrate);
+};
+
+const encode = (audioData: ArrayBuffer, numberOfFrames: number) => {
+	if (needsReset) {
+		reset();
+		needsReset = false;
+	}
+
+	const audioBytes = new Uint8Array(audioData);
+	const sizePerChannel = audioBytes.length / storedNumberOfChannels;
+
+	inputSlice = maybeGrowSlice(inputSlice, audioBytes.length);
+	module.HEAPU8.set(audioBytes, inputSlice.ptr);
+
+	const requiredOutputSize = Math.ceil(1.25 * numberOfFrames + 7200);
+	outputSlice = maybeGrowSlice(outputSlice, requiredOutputSize);
+
+	const bytesWritten = encodeSamples(
+		lamePtr,
+		inputSlice.ptr,
+		inputSlice.ptr + (storedNumberOfChannels - 1) * sizePerChannel,
+		numberOfFrames,
+		outputSlice.ptr,
+		requiredOutputSize,
+	);
+
+	const result = module.HEAPU8.slice(outputSlice.ptr, outputSlice.ptr + bytesWritten);
+	return result.buffer;
+};
+
+const flush = () => {
+	if (needsReset) {
+		reset();
+		needsReset = false;
+	}
+
+	const requiredOutputSize = 7200;
+	outputSlice = maybeGrowSlice(outputSlice, requiredOutputSize);
+
+	const bytesWritten = flushLame(lamePtr, outputSlice.ptr, requiredOutputSize);
+
+	const result = module.HEAPU8.slice(outputSlice.ptr, outputSlice.ptr + bytesWritten);
+	needsReset = true; // After a flush, the encoder must be prepared to start a new encoding process
+
+	return result.buffer;
+};
+
+/** A "fat pointer" type thing. */
+type Slice = {
+	ptr: number;
+	size: number;
+};
+
+/** Either returns the existing slice, or allocates a new one if there's no existing slice or it was too small. */
+const maybeGrowSlice = (slice: Slice | null, requiredSize: number) => {
+	if (!slice || slice.size < requiredSize) {
+		if (slice) {
+			module._free(slice.ptr);
+		}
+
+		return {
+			ptr: module._malloc(requiredSize),
+			size: requiredSize,
+		};
+	}
+
+	return slice;
+};
+
+const onMessage = (data: { id: number; command: WorkerCommand }) => {
+	const { id, command } = data;
+
+	const handleCommand = async (): Promise<void> => {
+		try {
+			let result: WorkerResponseData;
+			const transferables: Transferable[] = [];
+
+			switch (command.type) {
+				case 'init': {
+					await init(
+						command.data.numberOfChannels,
+						command.data.sampleRate,
+						command.data.bitrate,
+					);
+					result = { success: true };
+				}; break;
+
+				case 'encode': {
+					const encodedData = encode(
+						command.data.audioData,
+						command.data.numberOfFrames,
+					);
+					result = { encodedData };
+					transferables.push(encodedData);
+				}; break;
+
+				case 'flush': {
+					const flushedData = flush();
+					result = { flushedData };
+					transferables.push(flushedData);
+				}; break;
+			}
+
+			const response: WorkerResponse = {
+				id,
+				success: true,
+				data: result,
+			};
+			sendMessage(response, transferables);
+		} catch (error) {
+			const response: WorkerResponse = {
+				id,
+				success: false,
+				error,
+			};
+			sendMessage(response);
+		}
+	};
+
+	void handleCommand();
+};
+
+const sendMessage = (data: unknown, transferables?: Transferable[]) => {
+	if (parentPort) {
+		parentPort.postMessage(data, transferables ?? []);
+	} else {
+		self.postMessage(data, { transfer: transferables ?? [] });
+	}
+};
+
+let parentPort: {
+	postMessage: (data: unknown, transferables?: Transferable[]) => void;
+	on: (event: string, listener: (data: never) => void) => void;
+} | null = null;
+
+if (typeof self === 'undefined') {
+	// We're in Node.js (or a runtime that mimics it)
+	const workerModule = 'worker_threads';
+	// eslint-disable-next-line @stylistic/max-len
+	// eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+	parentPort = require(workerModule).parentPort;
+}
+
+if (parentPort) {
+	parentPort.on('message', onMessage);
+} else {
+	self.addEventListener('message', event => onMessage(event.data as { id: number; command: WorkerCommand }));
+}

package/src/index.ts

@@ -0,0 +1,213 @@
+/*!
+ * 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 { CustomAudioEncoder, AudioCodec, AudioSample, EncodedPacket, registerEncoder } from 'mediabunny';
+import { FRAME_HEADER_SIZE, readFrameHeader } from '../../../shared/mp3-misc';
+import type { WorkerCommand, WorkerResponse, WorkerResponseData } from './shared';
+// @ts-expect-error An esbuild plugin handles this, TypeScript doesn't need to understand
+import createWorker from './encode.worker';
+
+class Mp3Encoder extends CustomAudioEncoder {
+	private worker: Worker | null = null;
+	private nextMessageId = 0;
+	private pendingMessages = new Map<number, {
+		resolve: (value: WorkerResponseData) => void;
+		reject: (reason?: unknown) => void;
+	}>();
+
+	private buffer = new Uint8Array(2 ** 16);
+	private currentBufferOffset = 0;
+	private currentTimestamp = 0;
+	private chunkMetadata: EncodedAudioChunkMetadata = {};
+
+	static override supports(codec: AudioCodec, config: AudioDecoderConfig): boolean {
+		return codec === 'mp3'
+			&& (config.numberOfChannels === 1 || config.numberOfChannels === 2)
+			&& (config.sampleRate === 32000 || config.sampleRate === 44100 || config.sampleRate === 48000);
+	}
+
+	async init() {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+		this.worker = (await createWorker()) as Worker; // The actual encoding takes place in this worker
+
+		const onMessage = (data: WorkerResponse) => {
+			const pending = this.pendingMessages.get(data.id);
+			assert(pending !== undefined);
+
+			this.pendingMessages.delete(data.id);
+			if (data.success) {
+				pending.resolve(data.data);
+			} else {
+				pending.reject(data.error);
+			}
+		};
+
+		if (this.worker.addEventListener) {
+			this.worker.addEventListener('message', event => onMessage(event.data as WorkerResponse));
+		} else {
+			const nodeWorker = this.worker as unknown as {
+				on: (event: string, listener: (data: never) => void) => void;
+			};
+			nodeWorker.on('message', onMessage);
+		}
+
+		assert(this.config.bitrate);
+
+		await this.sendCommand({
+			type: 'init',
+			data: {
+				numberOfChannels: this.config.numberOfChannels,
+				sampleRate: this.config.sampleRate,
+				bitrate: this.config.bitrate,
+			},
+		});
+
+		this.chunkMetadata = {
+			decoderConfig: {
+				codec: 'mp3',
+				numberOfChannels: this.config.numberOfChannels,
+				sampleRate: this.config.sampleRate,
+			},
+		};
+	}
+
+	async encode(audioSample: AudioSample) {
+		const sizePerChannel = audioSample.allocationSize({
+			format: 's16-planar',
+			planeIndex: 0,
+		});
+
+		const requiredBytes = audioSample.numberOfChannels * sizePerChannel;
+		const audioData = new ArrayBuffer(requiredBytes);
+		const audioBytes = new Uint8Array(audioData);
+
+		for (let i = 0; i < audioSample.numberOfChannels; i++) {
+			audioSample.copyTo(audioBytes.subarray(i * sizePerChannel), {
+				format: 's16-planar', // LAME wants it in this format
+				planeIndex: i,
+			});
+		}
+
+		const result = await this.sendCommand({
+			type: 'encode',
+			data: {
+				audioData,
+				numberOfFrames: audioSample.numberOfFrames,
+			},
+		}, [audioData]);
+
+		assert('encodedData' in result);
+		this.digestOutput(new Uint8Array(result.encodedData));
+	}
+
+	async flush() {
+		const result = await this.sendCommand({ type: 'flush' });
+
+		assert('flushedData' in result);
+		this.digestOutput(new Uint8Array(result.flushedData));
+	}
+
+	close() {
+		this.worker?.terminate();
+	}
+
+	/**
+	 * LAME returns data in chunks, but a chunk doesn't need to contain a full MP3 frame. Therefore, we must accumulate
+	 * these chunks and extract the MP3 frames only when they're complete.
+	 */
+	private digestOutput(bytes: Uint8Array) {
+		const requiredBufferSize = this.currentBufferOffset + bytes.length;
+		if (requiredBufferSize > this.buffer.length) {
+			// Grow the buffer to the required size
+			const newSize = 1 << Math.ceil(Math.log2(requiredBufferSize));
+			const newBuffer = new Uint8Array(newSize);
+			newBuffer.set(this.buffer);
+			this.buffer = newBuffer;
+		}
+
+		this.buffer.set(bytes, this.currentBufferOffset);
+		this.currentBufferOffset = requiredBufferSize;
+
+		let pos = 0;
+		while (pos <= this.currentBufferOffset - FRAME_HEADER_SIZE) {
+			const word = new DataView(this.buffer.buffer).getUint32(pos, false);
+			const header = readFrameHeader(word, { pos, fileSize: null });
+			if (!header) {
+				break;
+			}
+
+			const fits = header.totalSize <= this.currentBufferOffset - pos;
+			if (!fits) {
+				// The frame isn't complete yet
+				break;
+			}
+
+			const data = this.buffer.slice(pos, pos + header.totalSize);
+			const duration = header.audioSamplesInFrame / header.sampleRate;
+			this.onPacket(new EncodedPacket(data, 'key', this.currentTimestamp, duration), this.chunkMetadata);
+
+			if (this.currentTimestamp === 0) {
+				this.chunkMetadata = {}; // Mimic WebCodecs-like behavior
+			}
+
+			this.currentTimestamp += duration;
+			pos += header.totalSize;
+		}
+
+		if (pos > 0) {
+			// Shift the data
+			this.buffer.set(this.buffer.subarray(pos, this.currentBufferOffset), 0);
+			this.currentBufferOffset -= pos;
+		}
+	}
+
+	private sendCommand(
+		command: WorkerCommand,
+		transferables?: Transferable[],
+	) {
+		return new Promise<WorkerResponseData>((resolve, reject) => {
+			const id = this.nextMessageId++;
+			this.pendingMessages.set(id, { resolve, reject });
+
+			assert(this.worker);
+
+			if (transferables) {
+				this.worker.postMessage({ id, command }, transferables);
+			} else {
+				this.worker.postMessage({ id, command });
+			}
+		});
+	}
+}
+
+/**
+ * Registers the LAME MP3 encoder, which Mediabunny will then use automatically when applicable. Make sure to call this
+ * function before starting any encoding task.
+ *
+ * Preferably, wrap the call in a condition to avoid overriding any native MP3 encoder:
+ *
+ * ```ts
+ * import { canEncodeAudio } from 'mediabunny';
+ * import { registerMp3Encoder } from '@mediabunny/mp3-encoder';
+ *
+ * if (!(await canEncodeAudio('mp3'))) {
+ *     registerMp3Encoder();
+ * }
+ * ```
+ *
+ * @public
+ */
+export const registerMp3Encoder = () => {
+	registerEncoder(Mp3Encoder);
+};
+
+function assert(x: unknown): asserts x {
+	if (!x) {
+		throw new Error('Assertion failed.');
+	}
+}

package/src/lame-bridge.c

@@ -0,0 +1,40 @@
+/*!
+ * 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/.
+ */
+
+#include <emscripten.h>
+#include "../lib/lame.h"
+
+EMSCRIPTEN_KEEPALIVE
+lame_global_flags *init_lame(int number_of_channels, int sample_rate, int bitrate) {
+	lame_global_flags *gfp = lame_init();
+
+	lame_set_num_channels(gfp, number_of_channels);
+	lame_set_in_samplerate(gfp, sample_rate);
+	lame_set_out_samplerate(gfp, sample_rate);
+	lame_set_brate(gfp, bitrate / 1000); // MP3 wants "kilobitrate"
+	lame_set_bWriteVbrTag(gfp, 0);
+
+	int ret_code = lame_init_params(gfp);
+
+	return gfp;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int encode_samples(lame_global_flags *gfp, short int left_buf[], short int right_buf[], int sample_count, unsigned char *dest_buf, int dest_buf_size) {
+	return lame_encode_buffer(gfp, left_buf, right_buf, sample_count, dest_buf, dest_buf_size);
+}
+
+EMSCRIPTEN_KEEPALIVE
+int flush_lame(lame_global_flags *gfp, unsigned char *dest_buf, int dest_buf_size) {
+	return lame_encode_flush(gfp, dest_buf, dest_buf_size);
+}
+
+EMSCRIPTEN_KEEPALIVE
+void close_lame(lame_global_flags *gfp) {
+	lame_close(gfp);
+}

package/src/shared.ts

@@ -0,0 +1,42 @@
+/*!
+ * 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 type WorkerCommand = {
+	type: 'init';
+	data: {
+		numberOfChannels: number;
+		sampleRate: number;
+		bitrate: number;
+	};
+} | {
+	type: 'encode';
+	data: {
+		audioData: ArrayBuffer;
+		numberOfFrames: number;
+	};
+} | {
+	type: 'flush';
+};
+
+export type WorkerResponseData = {
+	success: boolean;
+} | {
+	encodedData: ArrayBuffer;
+} | {
+	flushedData: ArrayBuffer;
+};
+
+export type WorkerResponse = {
+	id: number;
+} & ({
+	success: true;
+	data: WorkerResponseData;
+} | {
+	success: false;
+	error: unknown;
+});

package/src/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"extends": "../../../tsconfig.json",
+	"compilerOptions": {
+		"outDir": "../dist/modules",
+		"declaration": true,
+		"declarationMap": true,
+		"stripInternal": true,
+		"noEmit": false,
+		"moduleResolution": "nodenext",
+		"module": "nodenext",
+		"allowJs": true,
+		"paths": {
+			"mediabunny": ["../../../src/index.ts"],
+		},
+	},
+	"include": [
+		"**/*",
+		"../../../shared/**/*"
+	],
+	"references": [
+        { "path": "../../../src" }
+    ]
+}