A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file audioCook.ts
* @brief Cook-time WAV → MP3 transcode. WAV parsing is plain RIFF walking
* (PCM 8/16/24/32-int and 32-float); encoding goes through the
* wasm-media-encoders LAME build (self-contained wasm, loaded lazily
* the first time a cook actually compresses audio). Already-compressed
* formats never come through here — the cook only routes `.wav`.
*/
interface ParsedWav {
channels: Float32Array[];
sampleRate: number;
}
/** Parse a RIFF/WAVE file into normalized float channels; null if not parseable. */
export function parseWav(bytes: Uint8Array): ParsedWav | null {
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
if (bytes.byteLength < 44) return null;
if (view.getUint32(0, false) !== 0x52494646 /* RIFF */) return null;
if (view.getUint32(8, false) !== 0x57415645 /* WAVE */) return null;
let formatTag = 0;
let channelCount = 0;
let sampleRate = 0;
let bitsPerSample = 0;
let dataOffset = -1;
let dataLength = 0;
let off = 12;
while (off + 8 <= bytes.byteLength) {
const id = view.getUint32(off, false);
const size = view.getUint32(off + 4, true);
const body = off + 8;
if (id === 0x666d7420 /* fmt */) {
formatTag = view.getUint16(body, true);
channelCount = view.getUint16(body + 2, true);
sampleRate = view.getUint32(body + 4, true);
bitsPerSample = view.getUint16(body + 14, true);
// WAVE_FORMAT_EXTENSIBLE: the real format sits in the SubFormat GUID.
if (formatTag === 0xfffe && size >= 40) {
formatTag = view.getUint16(body + 24, true);
}
} else if (id === 0x64617461 /* data */) {
dataOffset = body;
dataLength = Math.min(size, bytes.byteLength - body);
}
off = body + size + (size & 1); // chunks are word-aligned
}
if (dataOffset < 0 || channelCount < 1 || sampleRate <= 0) return null;
const isFloat = formatTag === 3;
const isPcm = formatTag === 1;
if (!isFloat && !isPcm) return null;
if (isFloat && bitsPerSample !== 32) return null;
if (isPcm && ![8, 16, 24, 32].includes(bitsPerSample)) return null;
const bytesPerSample = bitsPerSample / 8;
const frameSize = bytesPerSample * channelCount;
const frames = Math.floor(dataLength / frameSize);
// MP3 is mono/stereo; fold extra channels away by keeping the first two.
const outChannels = Math.min(2, channelCount);
const channels = Array.from({ length: outChannels }, () => new Float32Array(frames));
for (let f = 0; f < frames; f++) {
for (let c = 0; c < outChannels; c++) {
const p = dataOffset + f * frameSize + c * bytesPerSample;
let v: number;
if (isFloat) {
v = view.getFloat32(p, true);
} else if (bitsPerSample === 16) {
v = view.getInt16(p, true) / 0x8000;
} else if (bitsPerSample === 8) {
v = (view.getUint8(p) - 128) / 128;
} else if (bitsPerSample === 24) {
const u = view.getUint8(p) | (view.getUint8(p + 1) << 8) | (view.getUint8(p + 2) << 16);
v = (u >= 0x800000 ? u - 0x1000000 : u) / 0x800000;
} else {
v = view.getInt32(p, true) / 0x80000000;
}
channels[c][f] = Math.max(-1, Math.min(1, v));
}
}
return { channels, sampleRate };
}
/**
* Samples of silence an MP3 has before its sound once it is decoded: what the encoder holds back and what a decoder
* holds back, 576 and 529. It is the same at every rate and bitrate, and no player takes it off a file with no tag
* to say so, which these have not: a clip encoded here begins a fortieth of a second late and is longer than it was.
*/
export const MP3_LEAD_SAMPLES = 1105;
/** How long a clip was before it was encoded, and the silence the encoding puts in front of it, in seconds; null if it is not a WAV. */
export function encodedClipTrim(wav: Uint8Array): { seconds: number; lead: number } | null {
const parsed = parseWav(wav);
if (!parsed || !parsed.channels[0]?.length) return null;
return { seconds: parsed.channels[0].length / parsed.sampleRate, lead: MP3_LEAD_SAMPLES / parsed.sampleRate };
}
type Mp3Encoder = {
configure(opts: { sampleRate: number; channels: 1 | 2; bitrate: number }): void;
encode(channels: Float32Array[]): Uint8Array;
finalize(): Uint8Array;
};
let encoderPromise: Promise<Mp3Encoder> | null = null;
/** Transcode a WAV buffer to MP3 at `bitrateKbps`; null when the WAV doesn't parse. */
export async function encodeWavToMp3(wav: Uint8Array, bitrateKbps: number): Promise<Uint8Array | null> {
const parsed = parseWav(wav);
if (!parsed) return null;
encoderPromise ??= import('wasm-media-encoders').then((m) => m.createMp3Encoder() as Promise<Mp3Encoder>);
const encoder = await encoderPromise;
encoder.configure({
sampleRate: parsed.sampleRate,
channels: parsed.channels.length as 1 | 2,
bitrate: bitrateKbps,
});
// Both calls answer with a view of the encoder's own wasm memory, valid only
// until its next call: finalize() writes its last frames over the bytes encode()
// returned. Read without a copy, the file began with flush bytes and no frame
// sync, and a decoder dropped tens of milliseconds hunting for one — the attack
// of a short effect.
const head = encoder.encode(parsed.channels).slice();
const tail = encoder.finalize().slice();
const out = new Uint8Array(head.byteLength + tail.byteLength);
out.set(head, 0);
out.set(tail, head.byteLength);
return out;
}
/** What the importer asked of a clip when it is not left to the length, or null for `auto`. Read here, beside the other audio importer settings. */
export function audioLoadTypeOf(importer: Record<string, unknown> | undefined): 'streaming' | 'decompress' | null {
const type = importer?.loadType;
return type === 'streaming' || type === 'decompress' ? type : null;
}
/** Per-asset audio import settings from the `.meta` importer block (tolerant). */
export function audioImportSettings(importer: Record<string, unknown> | undefined): {
compress: boolean; bitrateKbps: number;
} {
const compress = importer?.compress;
const bitrate = importer?.bitrateKbps;
return {
compress: typeof compress === 'boolean' ? compress : true,
bitrateKbps: bitrate === 96 || bitrate === 128 || bitrate === 192 ? (bitrate as number) : 128,
};
}