fix: locate bundled lame binary in flattened dist builds

Author: jankarres

.github/workflows/ci.yml

@@ -43,6 +43,14 @@ jobs:
             - name: Build package
               run: pnpm run build
 
+            - name: Ensure bundled LAME binary
+              env:
+                  LAME_FORCE_DOWNLOAD: "1"
+              run: node ./scripts/install-lame.mjs
+
+            - name: Diagnose bundled LAME binary
+              run: node ./scripts/diagnose-lame.mjs
+
             - name: Run examples
               run: |
                   pnpm run example:wav-to-mp3

AI_AGENT_INSTRUCTIONS.md

@@ -133,3 +133,4 @@ You operate as a senior Node.js and TypeScript backend engineer focused on maint
 - Document behavioural changes in commit messages following Conventional Commit rules so the release tooling can derive `CHANGELOG.md` for future releases.
 - Manual edits to `CHANGELOG.md` are only allowed for the 2.0.0 release; subsequent entries must come from the automated workflow.
 - After finishing any feature implementation, include in your final response a Conventional Commit-style message suggestion that downstream tooling can use.
+- When referencing Node.js types, import them explicitly (e.g. `import type { ProcessEnv } from "node:process";`) instead of relying on the `NodeJS.*` namespace to keep ESLint satisfied.

scripts/diagnose-lame.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { platform } from "node:os";
+
+const {
+    resolveLameBinary,
+    resolveBundledLibraryDirectory,
+} = await import(new URL("../dist/index.cjs", import.meta.url));
+
+function logSection(title) {
+    console.log(`[lame-diagnostics] ${title}`);
+}
+
+const binaryPath = resolveLameBinary();
+logSection(`Resolved binary: ${binaryPath}`);
+
+try {
+    const stats = statSync(binaryPath);
+    logSection(
+        `File stats -> size=${stats.size} mode=${stats.mode.toString(8)} mtime=${stats.mtime.toISOString()}`,
+    );
+} catch (error) {
+    logSection(`stat() failed: ${error instanceof Error ? error.message : error}`);
+}
+
+const runCommand = (cmd, args) => {
+    const result = spawnSync(cmd, args, {
+        encoding: "utf-8",
+    });
+
+    logSection(
+        `${cmd} ${args.join(" ")} exited ${result.status} (signal: ${result.signal ?? "none"})`,
+    );
+
+    if (result.stdout) {
+        console.log(result.stdout.trim());
+    }
+
+    if (result.stderr) {
+        console.error(result.stderr.trim());
+    }
+};
+
+runCommand(binaryPath, ["--version"]);
+
+if (platform() === "linux") {
+    runCommand("ldd", [binaryPath]);
+}
+
+const libraryDir = resolveBundledLibraryDirectory();
+logSection(
+    `Bundled library directory: ${libraryDir ?? "not found (not expected on this platform?)"}`,
+);
+if (libraryDir && existsSync(libraryDir)) {
+    const entries = readdirSync(libraryDir);
+    if (entries.length === 0) {
+        logSection("Bundled library directory is empty");
+    } else {
+        logSection(
+            `Bundled libraries:\n${entries.map((entry) => ` - ${entry}`).join("\n")}`,
+        );
+    }
+}

scripts/install-lame.mjs

@@ -1,11 +1,14 @@
 import {
     chmodSync,
     copyFileSync,
+    cpSync,
     existsSync,
     mkdirSync,
     mkdtempSync,
     readdirSync,
+    rmSync,
     statSync,
+    writeFileSync,
 } from "node:fs";
 import { createWriteStream } from "node:fs";
 import { pipeline } from "node:stream/promises";
@@ -29,6 +32,9 @@ const INSTALL_BASE = join(
     `${PLATFORM}-${ARCH}`,
 );
 const TARGET_BINARY = join(INSTALL_BASE, `lame${EXECUTABLE_SUFFIX}`);
+const LIB_DIRECTORY = join(INSTALL_BASE, "lib");
+const LIB_DIRECTORY_MARKER = join(LIB_DIRECTORY, ".installed");
+const LIBSNDFILE_VERSION = "1.2.0-1+deb12u1";
 
 const DOWNLOAD_SOURCES = {
     "linux-x64": [
@@ -97,6 +103,45 @@ const DOWNLOAD_SOURCES = {
     ],
 };
 
+const LINUX_SHARED_LIBRARY_PACKAGES = {
+    "linux-x64": [
+        {
+            name: "libmp3lame0",
+            url: `https://deb.debian.org/debian/pool/main/l/lame/libmp3lame0_${LAME_VERSION}-6_amd64.deb`,
+            libraryRoot: "usr/lib/x86_64-linux-gnu",
+        },
+        {
+            name: "libsndfile1",
+            url: `https://deb.debian.org/debian/pool/main/libs/libsndfile/libsndfile1_${LIBSNDFILE_VERSION}_amd64.deb`,
+            libraryRoot: "usr/lib/x86_64-linux-gnu",
+        },
+    ],
+    "linux-arm64": [
+        {
+            name: "libmp3lame0",
+            url: `https://deb.debian.org/debian/pool/main/l/lame/libmp3lame0_${LAME_VERSION}-6_arm64.deb`,
+            libraryRoot: "usr/lib/aarch64-linux-gnu",
+        },
+        {
+            name: "libsndfile1",
+            url: `https://deb.debian.org/debian/pool/main/libs/libsndfile/libsndfile1_${LIBSNDFILE_VERSION}_arm64.deb`,
+            libraryRoot: "usr/lib/aarch64-linux-gnu",
+        },
+    ],
+    "linux-arm": [
+        {
+            name: "libmp3lame0",
+            url: `https://deb.debian.org/debian/pool/main/l/lame/libmp3lame0_${LAME_VERSION}-6_armhf.deb`,
+            libraryRoot: "usr/lib/arm-linux-gnueabihf",
+        },
+        {
+            name: "libsndfile1",
+            url: `https://deb.debian.org/debian/pool/main/libs/libsndfile/libsndfile1_${LIBSNDFILE_VERSION}_armhf.deb`,
+            libraryRoot: "usr/lib/arm-linux-gnueabihf",
+        },
+    ],
+};
+
 /**
  * Logs installer progress messages with a consistent prefix.
  */
@@ -385,6 +430,92 @@ function writeBinaryToVendorDirectory(fromPath) {
     logInstallerMessage(`Installed LAME binary to ${TARGET_BINARY}`);
 }
 
+function copyLibrariesIntoTarget(sourceDir) {
+    const entries = readdirSync(sourceDir);
+    for (const entry of entries) {
+        const fromPath = join(sourceDir, entry);
+        const toPath = join(LIB_DIRECTORY, entry);
+        cpSync(fromPath, toPath, {
+            recursive: true,
+            force: true,
+            errorOnExist: false,
+        });
+    }
+}
+
+async function downloadAndInstallSharedLibraryPackage(dependency) {
+    const tmpDir = mkdtempSync(join(tmpdir(), "node-lame-lib-"));
+    const archivePath = join(tmpDir, basename(new URL(dependency.url).pathname));
+
+    await downloadFileTo(dependency.url, archivePath);
+
+    const extractDir = join(tmpDir, "extract");
+    mkdirSync(extractDir, { recursive: true });
+
+    await runCommandAndWait("ar", ["x", archivePath, "data.tar.xz"], {
+        cwd: extractDir,
+    });
+    await runCommandAndWait("tar", ["-xf", "data.tar.xz"], {
+        cwd: extractDir,
+    });
+
+    const sourceDir = join(extractDir, dependency.libraryRoot);
+    if (!existsSync(sourceDir)) {
+        throw new Error(
+            `Unable to locate ${dependency.libraryRoot} in ${dependency.name} package`,
+        );
+    }
+
+    copyLibrariesIntoTarget(sourceDir);
+    logInstallerMessage(
+        `Installed shared libraries for ${dependency.name} from ${dependency.url}`,
+    );
+}
+
+async function installLinuxSharedLibraries() {
+    const platformKey = `${PLATFORM}-${ARCH}`;
+    const dependencies = LINUX_SHARED_LIBRARY_PACKAGES[platformKey];
+
+    if (!dependencies || dependencies.length === 0) {
+        logInstallerMessage(
+            `No shared library dependencies configured for ${platformKey}`,
+        );
+        return;
+    }
+
+    if (existsSync(LIB_DIRECTORY_MARKER) && existsSync(LIB_DIRECTORY)) {
+        logInstallerMessage(
+            `Bundled shared libraries already present at ${LIB_DIRECTORY}`,
+        );
+        return;
+    }
+
+    rmSync(LIB_DIRECTORY, { recursive: true, force: true });
+    mkdirSync(LIB_DIRECTORY, { recursive: true });
+
+    for (const dependency of dependencies) {
+        await downloadAndInstallSharedLibraryPackage(dependency);
+    }
+
+    writeFileSync(LIB_DIRECTORY_MARKER, String(Date.now()), "utf-8");
+    logInstallerMessage(
+        `Shared library installation complete at ${LIB_DIRECTORY}`,
+    );
+}
+
+async function installPlatformSpecificDependencies() {
+    if (PLATFORM === "linux") {
+        try {
+            await installLinuxSharedLibraries();
+        } catch (error) {
+            logInstallerMessage(
+                `Failed to install Linux shared libraries: ${error.message}`,
+            );
+            throw error;
+        }
+    }
+}
+
 /**
  * Ensures a suitable LAME binary exists in the vendor directory, downloading it if absent.
  */
@@ -393,6 +524,7 @@ async function ensureBundledBinaryAvailable() {
         logInstallerMessage(
             `Bundled LAME binary already present at ${TARGET_BINARY}`,
         );
+        await installPlatformSpecificDependencies();
         return;
     }
 
@@ -436,6 +568,7 @@ async function ensureBundledBinaryAvailable() {
         try {
             if (source.type === "zip") {
                 await downloadAndInstallZipBinary(source);
+                await installPlatformSpecificDependencies();
                 return;
             }
 
@@ -448,11 +581,13 @@ async function ensureBundledBinaryAvailable() {
                 }
 
                 await downloadAndInstallDebianBinary(source);
+                await installPlatformSpecificDependencies();
                 return;
             }
 
             if (source.type === "ghcr") {
                 await downloadAndInstallGhcrBinary(source);
+                await installPlatformSpecificDependencies();
                 return;
             }
 

src/core/lame-process.ts

@@ -1,10 +1,19 @@
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
-
-import type { LameProgressEmitter, LameStatus } from "../types";
-import { resolveLameBinary } from "../internal/binary/resolve-binary";
+import type { ProcessEnv } from "node:process";
+import { delimiter } from "node:path";
+
+import type {
+    LameProgressEmitter,
+    LameStatus,
+    LameStreamMode,
+} from "../types";
+import {
+    resolveBundledLibraryDirectory,
+    resolveLameBinary,
+} from "../internal/binary/resolve-binary";
 import { LameOptions } from "./lame-options";
 
-type ProgressKind = "encode" | "decode";
+type ProgressKind = LameStreamMode;
 
 const LAME_TAG_MESSAGE = "Writing LAME Tag...done";
 
@@ -168,7 +177,10 @@ function processProgressChunk(
     return {};
 }
 
-function getExitError(code: number | null): Error | null {
+function getExitError(
+    code: number | null,
+    executable: string,
+): Error | null {
     if (code === 0) {
         return null;
     }
@@ -179,13 +191,51 @@ function getExitError(code: number | null): Error | null {
         );
     }
 
+    if (code === 127) {
+        return new Error(
+            `lame: Failed to execute '${executable}'. Exit code 127 usually indicates missing shared libraries or an unreadable binary. Run scripts/diagnose-lame.mjs for details.`,
+        );
+    }
+
     if (code !== null) {
         return new Error(`lame: Process exited with code ${code}`);
     }
 
     return new Error("lame: Process exited unexpectedly");
 }
 
+function applyBundledLibraryPath(
+    env: ProcessEnv,
+    libraryDir: string | null,
+): ProcessEnv {
+    if (!libraryDir) {
+        return env;
+    }
+
+    let variable: "LD_LIBRARY_PATH" | "DYLD_LIBRARY_PATH" | "PATH" | null =
+        null;
+
+    if (process.platform === "linux") {
+        variable = "LD_LIBRARY_PATH";
+    } else if (process.platform === "darwin") {
+        variable = "DYLD_LIBRARY_PATH";
+    } else if (process.platform === "win32") {
+        variable = "PATH";
+    }
+
+    if (!variable) {
+        return env;
+    }
+
+    const currentValue = env[variable];
+    return {
+        ...env,
+        [variable]: currentValue
+            ? `${libraryDir}${delimiter}${currentValue}`
+            : libraryDir,
+    };
+}
+
 interface SpawnLameProcessOptions {
     binaryPath?: string;
     spawnArgs: string[];
@@ -231,7 +281,11 @@ function spawnLameProcess(
     status.eta = undefined;
 
     const executable = binaryPath ?? resolveLameBinary();
-    const child = spawn(executable, spawnArgs);
+    const libraryDir = resolveBundledLibraryDirectory();
+    const childEnv = applyBundledLibraryPath({ ...process.env }, libraryDir);
+    const child = spawn(executable, spawnArgs, {
+        env: childEnv,
+    });
 
     const progressTargets = new Set(progressSources);
     let hasSeenCliError = false;
@@ -323,7 +377,7 @@ function spawnLameProcess(
 
     child.on("error", emitCliError);
     child.on("close", (code) => {
-        const exitError = getExitError(code);
+        const exitError = getExitError(code, executable);
         if (exitError) {
             const bufferedLines = stderrBuffer
                 .split(/\r?\n/)