lamejs

Common errors

• TypeError: Cannot read properties of undefined (reading 'Mp3Encoder')

  cause Attempting to access `lamejs.Mp3Encoder` from an incorrectly imported or required `lamejs` module in CommonJS or ESM.
  fix For CommonJS, use `const lamejs = require('lamejs');`. For ESM/TypeScript, use `import * as lamejs from 'lamejs';` or `import { Mp3Encoder } from 'lamejs';`.

• Argument of type 'Float32Array' is not assignable to parameter of type 'Int16Array'.

  cause TypeScript compilation error when passing Web Audio API `Float32Array` buffers directly to `encodeBuffer`.
  fix Convert `Float32Array` samples to `Int16Array` before passing them to `encodeBuffer`. Example: `const int16Samples = new Int16Array(float32Samples.length); for (let i = 0; i < float32Samples.length; i++) { int16Samples[i] = Math.max(-1, Math.min(1, float32Samples[i])) * 0x7FFF; }`

• Encoded MP3 file is truncated or silent after playback starts.

  cause The `flush()` method was not called, or its output was not appended to the final MP3 data.
  fix Ensure `mp3encoder.flush()` is called after all `encodeBuffer` calls, and its `Int8Array` result is included in the final MP3 data array.

Warnings

• gotcha lamejs expects audio samples as `Int16Array`. Providing `Float32Array` (common from Web Audio API) or other formats will lead to incorrect or silent output without explicit errors, requiring manual conversion.
  Fix: Ensure all audio input data is converted to `Int16Array` format before passing it to `encodeBuffer`. For Web Audio API `AudioBuffer`s, multiply by `32767` and `Math.min(1, Math.max(-1, value))` to clamp, then cast to `Int16Array`.
• breaking When migrating from older versions of lamejs (e.g., pre-1.2.1) to 1.2.1+ in a TypeScript project, direct `require` statements or global `lamejs` access might conflict with improved type definitions, leading to compilation errors or incorrect module resolution.
  Fix: For TypeScript, use `import * as lamejs from 'lamejs';` or `import { Mp3Encoder } from 'lamejs';` for proper type inference and module resolution. Update `tsconfig.json` if needed to ensure correct `moduleResolution` (e.g., `NodeNext`).
• gotcha It is crucial to call `mp3encoder.flush()` after all audio samples have been processed. Failing to flush will result in an incomplete or corrupted MP3 file, as the encoder might hold remaining buffered data internally.
  Fix: Always call `mp3encoder.flush()` once all `encodeBuffer()` calls are complete and append the returned `Int8Array` to your collected MP3 data.
• gotcha lamejs typically expects a `sampleBlockSize` that is a multiple of 576 for optimal performance and encoding efficiency, especially for stereo. While other sizes work, non-multiples can lead to less efficient processing.
  Fix: When segmenting your audio samples, try to use a `sampleBlockSize` of 1152 for stereo (2*576) or 576 for mono, or at least a multiple of 576 where possible.

Install

• npm install lamejs npm
• yarn add lamejs yarn
• pnpm add lamejs pnpm

Imports

• lamejs
  wrong:

  import lamejs from 'lamejs';

  correct:

  import * as lamejs from 'lamejs';

  When using ESM or TypeScript, import all exports as a namespace 'lamejs' to access `Mp3Encoder`. A default import is incorrect as 'lamejs' does not provide a default export.
• Mp3Encoder
  wrong:

  import { LamejsMp3Encoder } from 'lamejs';

  correct:

  import { Mp3Encoder } from 'lamejs';

  The primary class for encoding is `Mp3Encoder`. Ensure it's imported as a named export from the library, especially in TypeScript or modern JavaScript.
• lamejs
  wrong:

  const { Mp3Encoder } = require('lamejs');

  correct:

  const lamejs = require('lamejs');

  For CommonJS environments (like older Node.js scripts), use `require('lamejs')` to get the module object, then access `lamejs.Mp3Encoder`. Destructuring directly like `{ Mp3Encoder }` from `require('lamejs')` does not work as the module exports the full object.
• Global Access

  <script src='lame.all.js'></script>
  <script>
    const encoder = new lamejs.Mp3Encoder(...);
  </script>

  In browser environments using the bundled `lame.all.js` script, the `lamejs` object is exposed globally.

Quickstart

This quickstart demonstrates how to initialize the Mp3Encoder, feed it audio samples in chunks, and then flush the buffer to finalize the MP3 data. It covers both mono encoding and the necessary steps to collect the encoded segments.

import { Mp3Encoder } from 'lamejs';

const channels = 1; // 1 for mono, 2 for stereo
const sampleRate = 44100; // 44.1khz (normal mp3 samplerate)
const kbps = 128; // encode 128kbps mp3

// Create a new MP3 encoder instance
const mp3encoder = new Mp3Encoder(channels, sampleRate, kbps);

// Create some dummy audio samples (one second of silence in Int16Array)
const samples = new Int16Array(sampleRate * channels);

const sampleBlockSize = 1152; // Can be anything, but multiple of 576 is efficient
const mp3Data = [];

// Process audio samples in chunks
for (let i = 0; i < samples.length; i += sampleBlockSize) {
  const sampleChunk = samples.subarray(i, i + sampleBlockSize);
  const mp3buf = mp3encoder.encodeBuffer(sampleChunk);
  if (mp3buf.length > 0) {
    mp3Data.push(mp3buf);
  }
}

// Flush the encoder to get any remaining data
const mp3buf = mp3encoder.flush();
if (mp3buf.length > 0) {
    mp3Data.push(new Int8Array(mp3buf)); // Ensure it's Int8Array for Blob creation
}

// For browser environments, you can create a Blob and a URL
// const blob = new Blob(mp3Data, { type: 'audio/mp3' });
// const url = window.URL.createObjectURL(blob);
// console.log('Generated MP3 URL:', url);

// In Node.js, you might write to a file system
// import { writeFileSync } from 'fs';
// writeFileSync('output.mp3', Buffer.concat(mp3Data.map(arr => Buffer.from(arr))));

console.log('MP3 encoding complete. Total buffers:', mp3Data.length);
console.log('First buffer length:', mp3Data[0]?.length || 0);