@mediabunny/flac-encoder 1.36.0

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mediabunny/flac-encoder",
+  "author": "Vanilagy",
+  "version": "1.36.0",
+  "description": "FLAC encoder extension for Mediabunny, based on libFLAC.",
+  "main": "./dist/bundles/mediabunny-flac-encoder.mjs",
+  "module": "./dist/bundles/mediabunny-flac-encoder.mjs",
+  "types": "./dist/modules/src/index.d.ts",
+  "exports": {
+    "types": "./dist/modules/src/index.d.ts",
+    "import": "./dist/bundles/mediabunny-flac-encoder.mjs",
+    "require": "./dist/bundles/mediabunny-flac-encoder.mjs"
+  },
+  "files": [
+    "README.md",
+    "package.json",
+    "LICENSE",
+    "dist",
+    "src"
+  ],
+  "browser": {
+    "worker_threads": false
+  },
+  "sideEffects": false,
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vanilagy/mediabunny.git",
+    "directory": "packages/flac-encoder"
+  },
+  "bugs": {
+    "url": "https://github.com/Vanilagy/mediabunny/issues"
+  },
+  "homepage": "https://mediabunny.dev/guide/extensions/flac-encoder",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/Vanilagy"
+  },
+  "peerDependencies": {
+    "mediabunny": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/emscripten": "^1.40.1"
+  },
+  "keywords": [
+    "flac",
+    "encoding",
+    "codec",
+    "mediabunny",
+    "lossless",
+    "browser",
+    "wasm"
+  ]
+}

package/src/bridge.c

@@ -0,0 +1,255 @@
+/*!
+ * Copyright (c) 2026-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 <FLAC/stream_encoder.h>
+#include <stdbool.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define BITS_PER_SAMPLE 16
+#define COMPRESSION_LEVEL 5
+
+typedef struct {
+	int size;
+	int samples;
+} FrameInfo;
+
+typedef struct {
+	FLAC__StreamEncoder *encoder;
+
+	// Input buffer for interleaved int16 samples from JS
+	int16_t *input_buffer;
+	int input_buffer_size;
+
+	// Widened to int32 for libFLAC
+	FLAC__int32 *int32_buffer;
+	int int32_buffer_size;
+
+	// Contiguous output buffer for encoded frame data
+	uint8_t *output_buffer;
+	int output_size;
+	int output_capacity;
+
+	// Per-frame metadata so JS can split the output buffer into individual packets
+	FrameInfo *frames;
+	int frame_count;
+	int frames_capacity;
+
+	// Stream header captured during init (fLaC + metadata blocks)
+	uint8_t *header_buffer;
+	int header_size;
+	int header_capacity;
+	bool header_done;
+
+	int channels;
+} EncoderContext;
+
+static void ensure_output_capacity(EncoderContext *ctx, int needed) {
+	if (needed <= ctx->output_capacity) {
+		return;
+	}
+
+	int new_capacity = ctx->output_capacity;
+	if (new_capacity < 4096) {
+		new_capacity = 4096;
+	}
+	while (new_capacity < needed) {
+		new_capacity *= 2;
+	}
+
+	ctx->output_buffer = realloc(ctx->output_buffer, new_capacity);
+	ctx->output_capacity = new_capacity;
+}
+
+static FLAC__StreamEncoderWriteStatus write_callback(
+	const FLAC__StreamEncoder *encoder,
+	const FLAC__byte buffer[],
+	size_t bytes,
+	uint32_t samples,
+	uint32_t current_frame,
+	void *client_data
+) {
+	EncoderContext *ctx = (EncoderContext *)client_data;
+
+	// samples == 0 means this is metadata (stream header)
+	if (samples == 0) {
+		if (!ctx->header_done) {
+			int needed = ctx->header_size + bytes;
+			if (needed > ctx->header_capacity) {
+				int new_cap = ctx->header_capacity < 256 ? 256 : ctx->header_capacity;
+				while (new_cap < needed) { new_cap *= 2; }
+				ctx->header_buffer = realloc(ctx->header_buffer, new_cap);
+				ctx->header_capacity = new_cap;
+			}
+			memcpy(ctx->header_buffer + ctx->header_size, buffer, bytes);
+			ctx->header_size += bytes;
+		}
+
+		return FLAC__STREAM_ENCODER_WRITE_STATUS_OK;
+	}
+
+	ctx->header_done = true;
+
+	// Append encoded data
+	ensure_output_capacity(ctx, ctx->output_size + bytes);
+	memcpy(ctx->output_buffer + ctx->output_size, buffer, bytes);
+	ctx->output_size += bytes;
+
+	// Record frame metadata
+	if (ctx->frame_count >= ctx->frames_capacity) {
+		int new_cap = ctx->frames_capacity < 16 ? 16 : ctx->frames_capacity * 2;
+		ctx->frames = realloc(ctx->frames, new_cap * sizeof(FrameInfo));
+		ctx->frames_capacity = new_cap;
+	}
+	ctx->frames[ctx->frame_count].size = bytes;
+	ctx->frames[ctx->frame_count].samples = samples;
+	ctx->frame_count++;
+
+	return FLAC__STREAM_ENCODER_WRITE_STATUS_OK;
+}
+
+static void reset_output(EncoderContext *ctx) {
+	ctx->output_size = 0;
+	ctx->frame_count = 0;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int init_encoder(int channels, int sample_rate) {
+	EncoderContext *ctx = calloc(1, sizeof(EncoderContext));
+	if (!ctx) {
+		return 0;
+	}
+
+	ctx->channels = channels;
+
+	ctx->encoder = FLAC__stream_encoder_new();
+	if (!ctx->encoder) {
+		free(ctx);
+		return 0;
+	}
+
+	FLAC__stream_encoder_set_channels(ctx->encoder, channels);
+	FLAC__stream_encoder_set_sample_rate(ctx->encoder, sample_rate);
+	FLAC__stream_encoder_set_bits_per_sample(ctx->encoder, BITS_PER_SAMPLE);
+	FLAC__stream_encoder_set_compression_level(ctx->encoder, COMPRESSION_LEVEL);
+	FLAC__stream_encoder_set_verify(ctx->encoder, false);
+
+	FLAC__StreamEncoderInitStatus status = FLAC__stream_encoder_init_stream(
+		ctx->encoder,
+		write_callback,
+		NULL, // seek callback
+		NULL, // tell callback
+		NULL, // metadata callback
+		ctx
+	);
+
+	if (status != FLAC__STREAM_ENCODER_INIT_STATUS_OK) {
+		FLAC__stream_encoder_delete(ctx->encoder);
+		free(ctx);
+		return 0;
+	}
+
+	return (int)ctx;
+}
+
+EMSCRIPTEN_KEEPALIVE
+uint8_t *get_encode_input_ptr(int ctx_ptr, int size) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+
+	if (size > ctx->input_buffer_size) {
+		ctx->input_buffer = realloc(ctx->input_buffer, size);
+		ctx->input_buffer_size = size;
+	}
+
+	return (uint8_t *)ctx->input_buffer;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int send_samples(int ctx_ptr, int num_samples) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+
+	// Widen int16 to int32 for libFLAC
+	int total = num_samples * ctx->channels;
+	if (total > ctx->int32_buffer_size) {
+		ctx->int32_buffer = realloc(ctx->int32_buffer, total * sizeof(FLAC__int32));
+		ctx->int32_buffer_size = total;
+	}
+	for (int i = 0; i < total; i++) {
+		ctx->int32_buffer[i] = ctx->input_buffer[i];
+	}
+
+	reset_output(ctx);
+
+	FLAC__bool ok = FLAC__stream_encoder_process_interleaved(ctx->encoder, ctx->int32_buffer, num_samples);
+	return ok ? 0 : -1;
+}
+
+EMSCRIPTEN_KEEPALIVE
+uint8_t *get_output_data(int ctx_ptr) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->output_buffer;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int get_frame_count(int ctx_ptr) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->frame_count;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int get_frame_size(int ctx_ptr, int index) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->frames[index].size;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int get_frame_samples(int ctx_ptr, int index) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->frames[index].samples;
+}
+
+EMSCRIPTEN_KEEPALIVE
+uint8_t *get_header_data(int ctx_ptr) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->header_buffer;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int get_header_size(int ctx_ptr) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+	return ctx->header_size;
+}
+
+EMSCRIPTEN_KEEPALIVE
+int finish_encoder(int ctx_ptr) {
+	EncoderContext *ctx = (EncoderContext *)ctx_ptr;
+
+	reset_output(ctx);
+
+	FLAC__bool ok = FLAC__stream_encoder_finish(ctx->encoder);
+	if (!ok) {
+		return -1;
+	}
+
+	// finish() leaves the encoder uninitialized but retains configuration (channels, sample rate,
+	// etc.), so we just re-init the stream to be ready for the next batch of samples.
+	ctx->header_size = 0;
+	ctx->header_done = false;
+
+	FLAC__StreamEncoderInitStatus status = FLAC__stream_encoder_init_stream(
+		ctx->encoder,
+		write_callback,
+		NULL,
+		NULL,
+		NULL,
+		ctx
+	);
+
+	return status == FLAC__STREAM_ENCODER_INIT_STATUS_OK ? 0 : -1;
+}

package/src/encode.worker.ts

@@ -0,0 +1,193 @@
+/*!
+ * Copyright (c) 2026-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/flac';
+import type { PacketInfo, WorkerCommand, WorkerResponse, WorkerResponseData } from './shared';
+
+type ExtendedEmscriptenModule = EmscriptenModule & {
+	cwrap: typeof cwrap;
+};
+
+let module: ExtendedEmscriptenModule;
+let modulePromise: Promise<ExtendedEmscriptenModule> | null = null;
+
+let initEncoderFn: (channels: number, sampleRate: number) => number;
+let getEncodeInputPtr: (ctx: number, size: number) => number;
+let sendSamplesFn: (ctx: number, numSamples: number) => number;
+let getOutputData: (ctx: number) => number;
+let getFrameCount: (ctx: number) => number;
+let getFrameSize: (ctx: number, index: number) => number;
+let getFrameSamples: (ctx: number, index: number) => number;
+let getHeaderData: (ctx: number) => number;
+let getHeaderSize: (ctx: number) => number;
+let finishEncoderFn: (ctx: number) => number;
+
+const ensureModule = async () => {
+	if (!module) {
+		if (modulePromise) {
+			return modulePromise;
+		}
+
+		modulePromise = createModule() as Promise<ExtendedEmscriptenModule>;
+		module = await modulePromise;
+		modulePromise = null;
+
+		initEncoderFn = module.cwrap('init_encoder', 'number', ['number', 'number']);
+		getEncodeInputPtr = module.cwrap('get_encode_input_ptr', 'number', ['number', 'number']);
+		sendSamplesFn = module.cwrap('send_samples', 'number', ['number', 'number']);
+		getOutputData = module.cwrap('get_output_data', 'number', ['number']);
+		getFrameCount = module.cwrap('get_frame_count', 'number', ['number']);
+		getFrameSize = module.cwrap('get_frame_size', 'number', ['number', 'number']);
+		getFrameSamples = module.cwrap('get_frame_samples', 'number', ['number', 'number']);
+		getHeaderData = module.cwrap('get_header_data', 'number', ['number']);
+		getHeaderSize = module.cwrap('get_header_size', 'number', ['number']);
+		finishEncoderFn = module.cwrap('finish_encoder', 'number', ['number']);
+	}
+};
+
+const initEncoder = async (numberOfChannels: number, sampleRate: number) => {
+	await ensureModule();
+
+	const ctx = initEncoderFn(numberOfChannels, sampleRate);
+	if (ctx === 0) {
+		throw new Error('Failed to initialize FLAC encoder.');
+	}
+
+	const headerPtr = getHeaderData(ctx);
+	const headerSize = getHeaderSize(ctx);
+	const header = module.HEAPU8.slice(headerPtr, headerPtr + headerSize).buffer;
+
+	return { ctx, header };
+};
+
+const readPackets = (ctx: number) => {
+	const packets: PacketInfo[] = [];
+	const frameCount = getFrameCount(ctx);
+	const outputPtr = getOutputData(ctx);
+
+	let offset = 0;
+	for (let i = 0; i < frameCount; i++) {
+		const size = getFrameSize(ctx, i);
+		const samples = getFrameSamples(ctx, i);
+		const encodedData = module.HEAPU8.slice(outputPtr + offset, outputPtr + offset + size).buffer;
+		packets.push({ encodedData, samples });
+		offset += size;
+	}
+
+	return packets;
+};
+
+const encode = (ctx: number, audioData: ArrayBuffer, numSamples: number) => {
+	const audioBytes = new Uint8Array(audioData);
+
+	const inputPtr = getEncodeInputPtr(ctx, audioBytes.length);
+	if (inputPtr === 0) {
+		throw new Error('Failed to allocate encoder input buffer.');
+	}
+	module.HEAPU8.set(audioBytes, inputPtr);
+
+	const ret = sendSamplesFn(ctx, numSamples);
+	if (ret < 0) {
+		throw new Error(`Encode failed with error code ${ret}.`);
+	}
+
+	return readPackets(ctx);
+};
+
+const flush = (ctx: number) => {
+	const ret = finishEncoderFn(ctx);
+	if (ret < 0) {
+		throw new Error('Flush failed.');
+	}
+
+	return readPackets(ctx);
+};
+
+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': {
+					const { ctx, header } = await initEncoder(
+						command.data.numberOfChannels,
+						command.data.sampleRate,
+					);
+					result = { type: command.type, ctx, header };
+					transferables.push(header);
+				}; break;
+
+				case 'encode': {
+					const packets = encode(
+						command.data.ctx,
+						command.data.audioData,
+						command.data.numSamples,
+					);
+					for (const p of packets) {
+						transferables.push(p.encodedData);
+					}
+					result = { type: command.type, packets };
+				}; break;
+
+				case 'flush': {
+					const packets = flush(command.data.ctx);
+					for (const p of packets) {
+						transferables.push(p.encodedData);
+					}
+					result = { type: command.type, packets };
+				}; break;
+			}
+
+			const response: WorkerResponse = {
+				id,
+				success: true,
+				data: result,
+			};
+			sendMessage(response, transferables);
+		} catch (error: unknown) {
+			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') {
+	const workerModule = 'worker_threads';
+	// eslint-disable-next-line @stylistic/max-len
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-require-imports, @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/encoder.ts

@@ -0,0 +1,200 @@
+/*!
+ * Copyright (c) 2026-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 type { PacketInfo, WorkerCommand, WorkerResponse, WorkerResponseData } from './shared';
+// @ts-expect-error An esbuild plugin handles this, TypeScript doesn't need to understand
+import createWorker from './encode.worker';
+
+const FLAC_SAMPLE_RATES = [
+	8000, 16000, 22050, 24000, 32000, 44100, 48000, 88200, 96000, 176400, 192000,
+];
+
+class FlacEncoder extends CustomAudioEncoder {
+	private worker: Worker | null = null;
+	private nextMessageId = 0;
+	private pendingMessages = new Map<number, {
+		resolve: (value: WorkerResponseData) => void;
+		reject: (reason?: unknown) => void;
+	}>();
+
+	private ctx = 0;
+	private chunkMetadata: EncodedAudioChunkMetadata = {};
+	private description: Uint8Array | null = null;
+	private nextTimestampInSamples: number | null = null;
+
+	static override supports(codec: AudioCodec, config: AudioEncoderConfig): boolean {
+		return codec === 'flac'
+			&& config.numberOfChannels >= 1
+			&& config.numberOfChannels <= 8
+			&& FLAC_SAMPLE_RATES.includes(config.sampleRate);
+	}
+
+	async init() {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-call
+		this.worker = (await createWorker()) as 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);
+		}
+
+		const result = await this.sendCommand({
+			type: 'init',
+			data: {
+				numberOfChannels: this.config.numberOfChannels,
+				sampleRate: this.config.sampleRate,
+			},
+		});
+
+		this.ctx = result.ctx;
+
+		this.description = new Uint8Array(result.header);
+		this.resetInternalState();
+	}
+
+	private resetInternalState() {
+		this.nextTimestampInSamples = null;
+
+		this.chunkMetadata = {
+			decoderConfig: {
+				codec: 'flac',
+				numberOfChannels: this.config.numberOfChannels,
+				sampleRate: this.config.sampleRate,
+				description: this.description!,
+			},
+		};
+	}
+
+	async encode(audioSample: AudioSample) {
+		if (this.nextTimestampInSamples === null) {
+			this.nextTimestampInSamples = Math.round(audioSample.timestamp * this.config.sampleRate);
+		}
+
+		const totalBytes = audioSample.allocationSize({ format: 's16', planeIndex: 0 });
+		const audioBytes = new Uint8Array(totalBytes);
+		audioSample.copyTo(audioBytes, { format: 's16', planeIndex: 0 });
+
+		const audioData = audioBytes.buffer;
+		const result = await this.sendCommand({
+			type: 'encode',
+			data: {
+				ctx: this.ctx,
+				audioData,
+				numSamples: audioSample.numberOfFrames,
+			},
+		}, [audioData]);
+
+		this.emitPackets(result.packets);
+	}
+
+	async flush() {
+		const result = await this.sendCommand({ type: 'flush', data: { ctx: this.ctx } });
+		this.emitPackets(result.packets);
+
+		this.resetInternalState();
+	}
+
+	close() {
+		this.worker?.terminate();
+	}
+
+	private emitPackets(packets: PacketInfo[]) {
+		assert(this.nextTimestampInSamples !== null);
+
+		for (const p of packets) {
+			const data = new Uint8Array(p.encodedData);
+
+			const packet = new EncodedPacket(
+				data,
+				'key',
+				this.nextTimestampInSamples / this.config.sampleRate,
+				p.samples / this.config.sampleRate,
+			);
+			this.nextTimestampInSamples += p.samples;
+
+			this.onPacket(
+				packet,
+				this.chunkMetadata,
+			);
+
+			this.chunkMetadata = {};
+		}
+	}
+
+	private sendCommand<T extends string>(
+		command: WorkerCommand & { type: T },
+		transferables?: Transferable[],
+	) {
+		return new Promise<WorkerResponseData & { type: T }>((resolve, reject) => {
+			const id = this.nextMessageId++;
+			this.pendingMessages.set(id, {
+				resolve: resolve as (value: WorkerResponseData) => void,
+				reject,
+			});
+
+			assert(this.worker);
+
+			if (transferables) {
+				this.worker.postMessage({ id, command }, transferables);
+			} else {
+				this.worker.postMessage({ id, command });
+			}
+		});
+	}
+}
+
+/**
+ * Registers the FLAC 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 FLAC encoder:
+ *
+ * ```ts
+ * import { canEncodeAudio } from 'mediabunny';
+ * import { registerFlacEncoder } from '@mediabunny/flac-encoder';
+ *
+ * if (!(await canEncodeAudio('flac'))) {
+ *     registerFlacEncoder();
+ * }
+ * ```
+ *
+ * @group \@mediabunny/flac-encoder
+ * @public
+ */
+export const registerFlacEncoder = () => {
+	registerEncoder(FlacEncoder);
+};
+
+function assert(x: unknown): asserts x {
+	if (!x) {
+		throw new Error('Assertion failed.');
+	}
+}