klaudio 0.4.1 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klaudio",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Add sound effects to your coding sessions — play sounds when tasks complete, notifications arrive, and more",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -7,6 +7,7 @@ import { getAvailableGames } from "./scanner.js";
 import { install, uninstall, getExistingSounds } from "./installer.js";
 import { getVgmstreamPath, findPackedAudioFiles, extractToWav } from "./extractor.js";
 import { extractUnityResource } from "./unity.js";
+import { extractBunFile, isBunFile } from "./scumm.js";
 import { getCachedExtraction, cacheExtraction, categorizeLooseFiles, getCategories, sortFilesByPriority } from "./cache.js";
 import { basename, dirname } from "node:path";
 import { tmpdir } from "node:os";
@@ -422,6 +423,12 @@ const CATEGORY_ICONS = {
   ambient: "🌿", music: "🎵", other: "📦", all: "📂",
 };
 
+const FileItem = ({ isSelected, label, usedTag }) =>
+  h(Box, null,
+    h(Text, { color: isSelected ? ACCENT : undefined, bold: isSelected }, label),
+    usedTag ? h(Text, { dimColor: true }, usedTag) : null,
+  );
+
 const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
   const eventIds = Object.keys(EVENTS);
   const [currentEvent, setCurrentEvent] = useState(0);
@@ -446,21 +453,10 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
   // Sort files: voice first, then by priority
   const sortedFiles = hasCategories ? sortFilesByPriority(game.files) : game.files;
 
-  // Fetch durations for visible files
-  useEffect(() => {
-    for (const f of sortedFiles.slice(0, 50)) {
-      if (!fileDurations[f.path]) {
-        getWavDuration(f.path).then((dur) => {
-          if (dur != null) setFileDurations((d) => ({ ...d, [f.path]: dur }));
-        });
-      }
-    }
-  }, [game.files]);
-
-  // Filter files by category
+  // Filter files by category (no hard cap — SelectInput handles visible window)
   const categoryFiles = activeCategory && activeCategory !== "all"
-    ? sortedFiles.filter((f) => f.category === activeCategory).slice(0, 50)
-    : sortedFiles.slice(0, 50);
+    ? sortedFiles.filter((f) => f.category === activeCategory)
+    : sortedFiles;
 
   // Stop current playback helper
   const stopPlayback = useCallback(() => {
@@ -472,6 +468,35 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
     setElapsed(0);
   }, []);
 
+  // Pre-fetch durations: first 15 on category enter, ±15 around highlighted file
+  useEffect(() => {
+    const end = Math.min(categoryFiles.length, 15);
+    for (let i = 0; i < end; i++) {
+      const f = categoryFiles[i];
+      if (!fileDurations[f.path]) {
+        getWavDuration(f.path).then((dur) => {
+          if (dur != null) setFileDurations((d) => ({ ...d, [f.path]: dur }));
+        });
+      }
+    }
+  }, [activeCategory]);
+
+  useEffect(() => {
+    if (!highlightedFile || highlightedFile === "_skip") return;
+    const idx = categoryFiles.findIndex((f) => f.path === highlightedFile);
+    if (idx < 0) return;
+    const start = Math.max(0, idx - 15);
+    const end = Math.min(categoryFiles.length, idx + 16);
+    for (let i = start; i < end; i++) {
+      const f = categoryFiles[i];
+      if (!fileDurations[f.path]) {
+        getWavDuration(f.path).then((dur) => {
+          if (dur != null) setFileDurations((d) => ({ ...d, [f.path]: dur }));
+        });
+      }
+    }
+  }, [highlightedFile, categoryFiles]);
+
   // Auto-preview: play sound when highlighted file changes (with debounce)
   useEffect(() => {
     if (!autoPreview || !highlightedFile || highlightedFile === "_skip") {
@@ -512,9 +537,6 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
       const hasSounds = Object.values(sounds).some(Boolean);
       const tabCount = hasSounds ? eventIds.length + 1 : eventIds.length;
       setCurrentEvent((i) => (i + 1) % tabCount);
-      setHighlightedFile(null);
-      setActiveCategory(null);
-      setFilter("");
     } else if (key.escape) {
       if (playing) {
         stopPlayback();
@@ -595,7 +617,7 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
     h(Text, { bold: true, color: nowPlayingFile ? "green" : ACCENT },
       `${game.name}`,
     ),
-    h(Box, { marginTop: 0, gap: 2 },
+    h(Box, { marginTop: 0, gap: 2, overflowX: "hidden" },
       ...eventIds.map((eid, i) => {
         const assigned = sounds[eid];
         const isCurrent = i === currentEvent;
@@ -699,16 +721,26 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
     );
   }
 
+  // Build a reverse map: filePath -> event name(s) it's assigned to
+  const assignedToMap = {};
+  for (const eid of eventIds) {
+    if (sounds[eid]) {
+      (assignedToMap[sounds[eid]] ||= []).push(EVENTS[eid].name);
+    }
+  }
+
   // Phase 1: Browse and pick files (auto-preview plays on highlight)
   const filterLower = filter.toLowerCase();
   const allFileItems = categoryFiles.map((f) => {
     const dur = fileDurations[f.path];
-    const durStr = dur != null ? ` (${dur > MAX_PLAY_SECONDS ? MAX_PLAY_SECONDS + "s max" : dur + "s"})` : "";
+    const durStr = dur != null ? ` (${dur}s${dur > MAX_PLAY_SECONDS ? `, preview ${MAX_PLAY_SECONDS}s` : ""})` : "";
     const catTag = (!activeCategory || activeCategory === "all") && f.category && f.category !== "other"
       ? `[${(CATEGORY_LABELS[f.category] || f.category).toUpperCase()}] ` : "";
     const name = f.displayName || f.name;
+    const usedFor = assignedToMap[f.path];
     return {
       label: `${catTag}${name}${durStr}`,
+      usedTag: usedFor ? `  ← ${usedFor.join(", ")}` : null,
       value: f.path,
     };
   });
@@ -748,7 +780,7 @@ const GameSoundsScreen = ({ game, sounds, onSelectSound, onDone, onBack }) => {
         : null,
     fileItems.length > 0
       ? h(Box, { marginLeft: 2 },
-          h(SelectInput, { indicatorComponent: Indicator, itemComponent: Item,
+          h(SelectInput, { indicatorComponent: Indicator, itemComponent: FileItem,
             items: fileItems,
             limit: 15,
             onHighlight: (item) => {
@@ -827,8 +859,31 @@ const ExtractingScreen = ({ game, onDone, onBack }) => {
           }
         }
 
-        // Convert extracted .fsb Vorbis files via vgmstream, or handle traditional packed audio
-        const needsVgmstream = fsbFiles.length > 0 || (allOutputs.length === 0 && !game.unityResources?.length);
+        // Scan for packed audio files (Wwise/FMOD/BUN)
+        let packedFiles = [];
+        if (allOutputs.length === 0 || !game.unityResources?.length) {
+          setStatus(`Scanning ${game.name} for packed audio...`);
+          packedFiles = await findPackedAudioFiles(game.path, 30);
+        }
+
+        // Extract BUN files natively (SCUMM engine audio)
+        const bunFiles = packedFiles.filter((f) => f.name.toLowerCase().endsWith(".bun"));
+        const nonBunFiles = packedFiles.filter((f) => !f.name.toLowerCase().endsWith(".bun"));
+
+        for (const file of bunFiles) {
+          if (cancelled) return;
+          setStatus(`Extracting SCUMM audio: ${file.name}`);
+          try {
+            const bunOutputs = await extractBunFile(file.path, outputDir, (msg) => {
+              if (!cancelled) setStatus(msg);
+            });
+            allOutputs.push(...bunOutputs);
+            setExtracted(allOutputs.length);
+          } catch { /* skip */ }
+        }
+
+        // Convert extracted .fsb Vorbis files via vgmstream, or handle non-BUN packed audio
+        const needsVgmstream = fsbFiles.length > 0 || nonBunFiles.length > 0;
         if (needsVgmstream) {
           // Get vgmstream-cli (downloads if needed)
           setStatus("Getting vgmstream-cli...");
@@ -847,32 +902,23 @@ const ExtractingScreen = ({ game, onDone, onBack }) => {
             } catch { /* skip */ }
           }
 
-          // Also scan for traditional packed audio (Wwise/FMOD)
-          if (allOutputs.length === 0 || !game.unityResources?.length) {
-            setStatus(`Scanning ${game.name} for packed audio...`);
-            const packedFiles = await findPackedAudioFiles(game.path, 30);
-
-            if (packedFiles.length === 0 && allOutputs.length === 0) {
-              if (!cancelled) onDone({ files: [], error: "No extractable audio files found" });
-              return;
-            }
-
-            setStatus(`Found ${packedFiles.length} files. Extracting...`);
-
-            for (const file of packedFiles) {
-              if (cancelled) return;
-              setStatus(`Extracting: ${file.name}`);
-              try {
-                const outputs = await extractToWav(file.path, outputDir, vgmstream);
-                allOutputs.push(...outputs);
-                setExtracted(allOutputs.length);
-              } catch {
-                // Skip files that fail
-              }
-            }
+          // Convert non-BUN packed audio via vgmstream
+          for (const file of nonBunFiles) {
+            if (cancelled) return;
+            setStatus(`Extracting: ${file.name}`);
+            try {
+              const outputs = await extractToWav(file.path, outputDir, vgmstream);
+              allOutputs.push(...outputs);
+              setExtracted(allOutputs.length);
+            } catch { /* skip */ }
           }
         }
 
+        if (allOutputs.length === 0 && fsbFiles.length === 0 && packedFiles.length === 0) {
+          if (!cancelled) onDone({ files: [], error: "No extractable audio files found" });
+          return;
+        }
+
         if (!cancelled) {
           // Cache the results with category metadata
           const rawFiles = allOutputs.map((p) => ({ path: p, name: basename(p) }));

package/src/extractor.js

@@ -8,7 +8,7 @@ import { pipeline } from "node:stream/promises";
 const TOOLS_DIR = join(homedir(), ".klaudio", "tools");
 
 // Packed audio formats that vgmstream-cli can convert to WAV
-const PACKED_EXTENSIONS = new Set([".wem", ".bnk", ".bank", ".fsb", ".pck"]);
+const PACKED_EXTENSIONS = new Set([".wem", ".bnk", ".bank", ".fsb", ".pck", ".bun"]);
 
 /**
  * Check if a file is a packed audio format we can extract.
@@ -140,7 +140,7 @@ export async function findPackedAudioFiles(gamePath, maxFiles = 50) {
           const ext = extname(entry.name).toLowerCase();
           // Formats vgmstream-cli can convert directly
           // (.bnk needs bnkextr preprocessing — skip for now)
-          if (ext === ".wem" || ext === ".fsb" || ext === ".bank") {
+          if (ext === ".wem" || ext === ".fsb" || ext === ".bank" || ext === ".bun") {
             results.push({ path: fullPath, name: entry.name, dir });
           }
         }

package/src/scanner.js

@@ -3,7 +3,7 @@ import { join, extname } from "node:path";
 import { platform, homedir } from "node:os";
 
 const AUDIO_EXTENSIONS = new Set([".wav", ".mp3", ".ogg", ".flac", ".aac"]);
-const PACKED_EXTENSIONS = new Set([".wem", ".bnk", ".bank", ".fsb", ".pck"]);
+const PACKED_EXTENSIONS = new Set([".wem", ".bnk", ".bank", ".fsb", ".pck", ".bun"]);
 const UNITY_RESOURCE_EXTENSIONS = new Set([".resource", ".ress"]);
 const MAX_DEPTH = 5;
 const MAX_FILES = 200;

package/src/scumm.js

@@ -0,0 +1,553 @@
+/**
+ * SCUMM engine .BUN audio extractor.
+ *
+ * Extracts audio resources from LucasArts SCUMM engine bundle files
+ * (Curse of Monkey Island, The Dig, Full Throttle, etc.).
+ *
+ * BUN files contain compressed iMUS audio resources. Each resource is
+ * decompressed block-by-block using LZ77 and/or IMA ADPCM codecs,
+ * producing raw PCM data that is written out as WAV files.
+ *
+ * Format details derived from the publicly documented ScummVM specifications.
+ */
+
+import { open, mkdir, writeFile } from "node:fs/promises";
+import { join, basename, extname } from "node:path";
+
+const CHUNK_SIZE = 0x2000; // 8192 bytes — standard decompressed block size
+
+// ── IMA Step Table (public domain, 89 values) ──────────────────
+const IMA_TABLE = [
+  7, 8, 9, 10, 11, 12, 13, 14,
+  16, 17, 19, 21, 23, 25, 28, 31,
+  34, 37, 41, 45, 50, 55, 60, 66,
+  73, 80, 88, 97, 107, 118, 130, 143,
+  157, 173, 190, 209, 230, 253, 279, 307,
+  337, 371, 408, 449, 494, 544, 598, 658,
+  724, 796, 876, 963, 1060, 1166, 1282, 1411,
+  1552, 1707, 1878, 2066, 2272, 2499, 2749, 3024,
+  3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484,
+  7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899,
+  15289, 16818, 18500, 20350, 22385, 24623, 27086, 29794,
+  32767,
+];
+
+// ── Step adjustment table indexed by [bitCount-2][data] ─────────
+const IMX_OTHER_TABLE = [
+  // bitcount=2 (2 entries)
+  [-1, 4],
+  // bitcount=3 (4 entries)
+  [-1, -1, 2, 8],
+  // bitcount=4 (8 entries)
+  [-1, -1, -1, -1, 1, 2, 4, 6],
+  // bitcount=5 (16 entries)
+  [-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 12, 16, 32],
+  // bitcount=6 (32 entries)
+  [
+    -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+    1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 32,
+  ],
+  // bitcount=7 (64 entries)
+  [
+    -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+    -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1,
+    1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16,
+    17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32,
+  ],
+];
+
+// ── Precomputed tables (built once at module load) ──────────────
+
+// _destImcTable[pos]: how many bits to read per IMA position (2-7)
+const DEST_IMC_TABLE = new Uint8Array(89);
+
+// _destImcTable2[pos*64 + n]: precomputed delta contribution
+const DEST_IMC_TABLE2 = new Int32Array(89 * 64);
+
+(function initTables() {
+  // Build _destImcTable
+  for (let pos = 0; pos <= 88; pos++) {
+    let put = 1;
+    let val = Math.trunc(Math.trunc(IMA_TABLE[pos] * 4 / 7) / 2);
+    while (val !== 0) {
+      val = Math.trunc(val / 2);
+      put++;
+    }
+    if (put < 3) put = 3;
+    if (put > 8) put = 8;
+    DEST_IMC_TABLE[pos] = put - 1;
+  }
+
+  // Build _destImcTable2
+  for (let n = 0; n < 64; n++) {
+    for (let pos = 0; pos <= 88; pos++) {
+      let count = 32;
+      let put = 0;
+      let tableValue = IMA_TABLE[pos];
+      do {
+        if ((count & n) !== 0) {
+          put += tableValue;
+        }
+        count = Math.trunc(count / 2);
+        tableValue = Math.trunc(tableValue / 2);
+      } while (count !== 0);
+      DEST_IMC_TABLE2[n + pos * 64] = put;
+    }
+  }
+})();
+
+// ── LZ77 decompressor ──────────────────────────────────────────
+
+function compDecode(src, dst) {
+  let sp = 0; // source pointer
+  let dp = 0; // dest pointer
+  let mask = src[sp] | (src[sp + 1] << 8); // LE uint16
+  sp += 2;
+  let bitsLeft = 16;
+
+  function nextBit() {
+    const bit = mask & 1;
+    mask >>>= 1;
+    bitsLeft--;
+    if (bitsLeft === 0) {
+      mask = src[sp] | (src[sp + 1] << 8);
+      sp += 2;
+      bitsLeft = 16;
+    }
+    return bit;
+  }
+
+  for (;;) {
+    if (nextBit()) {
+      // Literal byte
+      dst[dp++] = src[sp++];
+    } else {
+      let size, data;
+      if (!nextBit()) {
+        // Short back-reference
+        size = nextBit() << 1;
+        size = (size | nextBit()) + 3; // 3..6
+        data = src[sp++] | 0xffffff00; // sign-extend byte to negative offset
+      } else {
+        // Long back-reference
+        data = src[sp++];
+        size = src[sp++];
+        data |= 0xfffff000 + ((size & 0xf0) << 4); // 12-bit negative offset
+        size = (size & 0x0f) + 3; // 3..18
+
+        if (size === 3) {
+          // Size field was 0 — check terminator
+          if ((src[sp++] + 1) === 1) {
+            return dp; // done
+          }
+        }
+      }
+      // data is a negative offset (as signed 32-bit)
+      let refPos = dp + (data | 0); // ensure signed
+      for (let i = 0; i < size; i++) {
+        dst[dp++] = dst[refPos++];
+      }
+    }
+  }
+}
+
+// ── ADPCM decompressor ─────────────────────────────────────────
+
+function decompressADPCM(src, dst, channels) {
+  let sp = 0;
+  const firstWord = (src[sp] << 8) | src[sp + 1]; // BE uint16
+  sp += 2;
+
+  let dp = 0;
+  let outputSamplesLeft = 0x1000; // 4096 samples = 8192 bytes
+
+  if (firstWord !== 0) {
+    // Copy raw bytes
+    for (let i = 0; i < firstWord; i++) {
+      dst[dp++] = src[sp++];
+    }
+    outputSamplesLeft -= Math.trunc(firstWord / 2);
+  }
+
+  // Read seed values per channel
+  const initialTablePos = [];
+  const initialOutputWord = [];
+  if (firstWord === 0) {
+    for (let ch = 0; ch < channels; ch++) {
+      initialTablePos.push(src[sp]);
+      sp += 1;
+      sp += 4; // skip 4 bytes
+      initialOutputWord.push(
+        ((src[sp] << 24) | (src[sp + 1] << 16) | (src[sp + 2] << 8) | src[sp + 3]) | 0,
+      ); // BE int32
+      sp += 4;
+    }
+  }
+
+  let totalBitOffset = 0;
+  const bitStreamStart = sp;
+
+  for (let ch = 0; ch < channels; ch++) {
+    let curTablePos = initialTablePos[ch] || 0;
+    let outputWord = initialOutputWord[ch] || 0;
+    let destPos = dp + ch * 2;
+
+    let bound;
+    if (channels === 1) {
+      bound = outputSamplesLeft;
+    } else if (ch === 0) {
+      bound = Math.trunc((outputSamplesLeft + 1) / 2);
+    } else {
+      bound = Math.trunc(outputSamplesLeft / 2);
+    }
+
+    for (let i = 0; i < bound; i++) {
+      const curTableEntryBitCount = DEST_IMC_TABLE[curTablePos];
+
+      // Read variable-width packet from bitstream (big-endian)
+      const bytePos = bitStreamStart + (totalBitOffset >>> 3);
+      const bitShift = totalBitOffset & 7;
+      const readWord = ((src[bytePos] << 8) | (src[bytePos + 1] || 0)) << bitShift;
+      const packet = (readWord >>> (16 - curTableEntryBitCount)) & ((1 << curTableEntryBitCount) - 1);
+      totalBitOffset += curTableEntryBitCount;
+
+      // Extract sign and data
+      const signBitMask = 1 << (curTableEntryBitCount - 1);
+      const data = packet & (signBitMask - 1);
+
+      // Compute delta
+      const tmpA = data << (7 - curTableEntryBitCount);
+      const imcTableEntry = IMA_TABLE[curTablePos] >>> (curTableEntryBitCount - 1);
+      let delta = imcTableEntry + DEST_IMC_TABLE2[tmpA + curTablePos * 64];
+
+      if (packet & signBitMask) delta = -delta;
+
+      outputWord += delta;
+      if (outputWord < -0x8000) outputWord = -0x8000;
+      if (outputWord > 0x7fff) outputWord = 0x7fff;
+
+      // Write 16-bit LE
+      const uval = outputWord & 0xffff;
+      dst[destPos] = uval & 0xff;
+      dst[destPos + 1] = (uval >>> 8) & 0xff;
+      destPos += channels * 2;
+
+      // Adjust table position
+      const adj = IMX_OTHER_TABLE[curTableEntryBitCount - 2]?.[data] ?? -1;
+      curTablePos += adj;
+      if (curTablePos < 0) curTablePos = 0;
+      if (curTablePos > 88) curTablePos = 88;
+    }
+  }
+
+  return CHUNK_SIZE;
+}
+
+// ── Codec dispatcher ────────────────────────────────────────────
+
+function decompressCodec(codec, input, inputSize) {
+  const output = Buffer.alloc(CHUNK_SIZE);
+
+  if (codec === 0) {
+    // Raw copy
+    input.copy(output, 0, 0, Math.min(inputSize, CHUNK_SIZE));
+    return output;
+  }
+
+  if (codec === 1) {
+    compDecode(input, output);
+    return output;
+  }
+
+  if (codec === 2) {
+    // LZ77 + single delta
+    const size = compDecode(input, output);
+    for (let z = 1; z < size; z++) {
+      output[z] = (output[z] + output[z - 1]) & 0xff;
+    }
+    return output;
+  }
+
+  if (codec === 3) {
+    // LZ77 + double delta
+    const size = compDecode(input, output);
+    for (let z = 2; z < size; z++) {
+      output[z] = (output[z] + output[z - 1]) & 0xff;
+    }
+    for (let z = 1; z < size; z++) {
+      output[z] = (output[z] + output[z - 1]) & 0xff;
+    }
+    return output;
+  }
+
+  if (codec === 13) {
+    decompressADPCM(input, output, 1);
+    return output;
+  }
+
+  if (codec === 15) {
+    decompressADPCM(input, output, 2);
+    return output;
+  }
+
+  // Unsupported codec — return silence
+  return output;
+}
+
+// ── BUN directory parsing ───────────────────────────────────────
+
+async function readBE32(fh, offset) {
+  const buf = Buffer.alloc(4);
+  await fh.read(buf, 0, 4, offset);
+  return buf.readUInt32BE(0);
+}
+
+/**
+ * Parse the BUN file header and directory.
+ */
+export async function parseBunDirectory(fh) {
+  const tagBuf = Buffer.alloc(4);
+  await fh.read(tagBuf, 0, 4, 0);
+  const tag = tagBuf.toString("ascii");
+  const isCompressed = tag === "LB23";
+
+  const dirOffset = await readBE32(fh, 4);
+  const numFiles = await readBE32(fh, 8);
+
+  const entries = [];
+
+  if (isCompressed) {
+    // LB23 format: 24-byte filename + 4-byte offset + 4-byte size = 32 bytes per entry
+    const dirBuf = Buffer.alloc(numFiles * 32);
+    await fh.read(dirBuf, 0, dirBuf.length, dirOffset);
+
+    for (let i = 0; i < numFiles; i++) {
+      const base = i * 32;
+      const nameBuf = dirBuf.subarray(base, base + 24);
+      const nullIdx = nameBuf.indexOf(0);
+      const filename = nameBuf.subarray(0, nullIdx >= 0 ? nullIdx : 24).toString("ascii");
+      const offset = dirBuf.readUInt32BE(base + 24);
+      const size = dirBuf.readUInt32BE(base + 28);
+      entries.push({ filename, offset, size });
+    }
+  } else {
+    // Legacy format: 8-byte name + 4-byte ext + 4-byte offset + 4-byte size = 20 bytes
+    const dirBuf = Buffer.alloc(numFiles * 20);
+    await fh.read(dirBuf, 0, dirBuf.length, dirOffset);
+
+    for (let i = 0; i < numFiles; i++) {
+      const base = i * 20;
+      let name = "";
+      for (let j = 0; j < 8; j++) {
+        const ch = dirBuf[base + j];
+        if (ch === 0) break;
+        name += String.fromCharCode(ch);
+      }
+      let ext = "";
+      for (let j = 0; j < 4; j++) {
+        const ch = dirBuf[base + 8 + j];
+        if (ch === 0) break;
+        ext += String.fromCharCode(ch);
+      }
+      const filename = ext ? `${name}.${ext}` : name;
+      const offset = dirBuf.readUInt32BE(base + 12);
+      const size = dirBuf.readUInt32BE(base + 16);
+      entries.push({ filename, offset, size });
+    }
+  }
+
+  return { isCompressed, entries };
+}
+
+// ── COMP table loading ──────────────────────────────────────────
+
+/**
+ * Load the COMP block table for a resource at the given offset.
+ * Returns { isUncompressed, blocks[], lastBlockSize }
+ */
+async function loadCompTable(fh, offset) {
+  const tagBuf = Buffer.alloc(4);
+  await fh.read(tagBuf, 0, 4, offset);
+  const tag = tagBuf.toString("ascii");
+
+  if (tag !== "COMP") {
+    // Raw iMUS — not compressed
+    return { isUncompressed: true, blocks: [], lastBlockSize: 0 };
+  }
+
+  const numBlocks = await readBE32(fh, offset + 4);
+  // Skip 4 bytes at offset+8
+  const lastBlockSize = await readBE32(fh, offset + 12);
+
+  const blocks = [];
+  const tableBuf = Buffer.alloc(numBlocks * 16);
+  await fh.read(tableBuf, 0, tableBuf.length, offset + 16);
+
+  for (let i = 0; i < numBlocks; i++) {
+    const base = i * 16;
+    blocks.push({
+      offset: tableBuf.readUInt32BE(base),
+      size: tableBuf.readUInt32BE(base + 4),
+      codec: tableBuf.readUInt32BE(base + 8),
+      // skip 4 bytes at base+12
+    });
+  }
+
+  return { isUncompressed: false, blocks, lastBlockSize };
+}
+
+// ── iMUS resource parsing ───────────────────────────────────────
+
+/**
+ * Scan a decompressed buffer for FRMT and DATA chunks.
+ * Returns { sampleRate, bitsPerSample, channels, pcmData }
+ */
+function parseImusResource(buf) {
+  let sampleRate = 22050;
+  let bitsPerSample = 16;
+  let channels = 1;
+  let pcmData = null;
+
+  let pos = 0;
+  while (pos + 8 <= buf.length) {
+    const tag = buf.toString("ascii", pos, pos + 4);
+    const size = buf.readUInt32BE(pos + 4);
+    const chunkStart = pos + 8;
+
+    if (tag === "FRMT" && chunkStart + 20 <= buf.length) {
+      // Skip 8 bytes, then read bits, rate, channels
+      bitsPerSample = buf.readUInt32BE(chunkStart + 8);
+      sampleRate = buf.readUInt32BE(chunkStart + 12);
+      channels = buf.readUInt32BE(chunkStart + 16);
+    } else if (tag === "DATA") {
+      pcmData = buf.subarray(chunkStart, chunkStart + size);
+      break; // DATA is the last meaningful chunk
+    }
+
+    // For container tags (iMUS, MAP), descend into them
+    if (tag === "iMUS" || tag === "MAP\u0020" || tag === "MAP ") {
+      pos += 8; // descend
+    } else {
+      pos += 8 + size; // skip payload
+    }
+  }
+
+  return { sampleRate, bitsPerSample, channels, pcmData };
+}
+
+// ── WAV writer ──────────────────────────────────────────────────
+
+function createWav(pcmData, sampleRate, channels, bitsPerSample) {
+  const bytesPerSample = Math.trunc(bitsPerSample / 8);
+  const byteRate = sampleRate * channels * bytesPerSample;
+  const blockAlign = channels * bytesPerSample;
+  const dataSize = pcmData.length;
+  const headerSize = 44;
+
+  const wav = Buffer.alloc(headerSize + dataSize);
+  wav.write("RIFF", 0);
+  wav.writeUInt32LE(headerSize + dataSize - 8, 4);
+  wav.write("WAVE", 8);
+  wav.write("fmt ", 12);
+  wav.writeUInt32LE(16, 16); // fmt chunk size
+  wav.writeUInt16LE(1, 20);  // PCM format
+  wav.writeUInt16LE(channels, 22);
+  wav.writeUInt32LE(sampleRate, 24);
+  wav.writeUInt32LE(byteRate, 28);
+  wav.writeUInt16LE(blockAlign, 32);
+  wav.writeUInt16LE(bitsPerSample, 34);
+  wav.write("data", 36);
+  wav.writeUInt32LE(dataSize, 40);
+  pcmData.copy(wav, 44);
+
+  return wav;
+}
+
+// ── Main extraction entry point ─────────────────────────────────
+
+/**
+ * Extract all audio resources from a BUN file to WAV files.
+ *
+ * @param {string} bunPath - Path to the .BUN file
+ * @param {string} outputDir - Directory to write WAV files
+ * @param {(msg: string) => void} [onProgress] - Progress callback
+ * @returns {Promise<string[]>} Array of output WAV file paths
+ */
+export async function extractBunFile(bunPath, outputDir, onProgress) {
+  await mkdir(outputDir, { recursive: true });
+
+  const fh = await open(bunPath, "r");
+  const outputs = [];
+
+  try {
+    const { entries } = await parseBunDirectory(fh);
+
+    for (let ei = 0; ei < entries.length; ei++) {
+      const entry = entries[ei];
+      if (onProgress) onProgress(`Extracting ${ei + 1}/${entries.length}: ${entry.filename}`);
+
+      try {
+        const comp = await loadCompTable(fh, entry.offset);
+
+        let fullBuf;
+        if (comp.isUncompressed) {
+          // Read raw iMUS data
+          fullBuf = Buffer.alloc(entry.size);
+          await fh.read(fullBuf, 0, entry.size, entry.offset);
+        } else {
+          // Decompress all blocks
+          const totalSize = (comp.blocks.length - 1) * CHUNK_SIZE + comp.lastBlockSize;
+          fullBuf = Buffer.alloc(totalSize);
+          let outPos = 0;
+
+          for (let i = 0; i < comp.blocks.length; i++) {
+            const block = comp.blocks[i];
+            const inputBuf = Buffer.alloc(block.size + 1); // +1 CMI hack
+            await fh.read(inputBuf, 0, block.size, entry.offset + block.offset);
+            inputBuf[block.size] = 0; // zero padding
+
+            const decompressed = decompressCodec(block.codec, inputBuf, block.size);
+            const blockOutSize = i === comp.blocks.length - 1 ? comp.lastBlockSize : CHUNK_SIZE;
+            decompressed.copy(fullBuf, outPos, 0, blockOutSize);
+            outPos += blockOutSize;
+          }
+        }
+
+        // Parse the iMUS structure
+        const { sampleRate, bitsPerSample, channels, pcmData } = parseImusResource(fullBuf);
+        if (!pcmData || pcmData.length === 0) continue;
+
+        // Write WAV
+        const wav = createWav(pcmData, sampleRate, channels, bitsPerSample);
+        const safeName = entry.filename.replace(/[^a-zA-Z0-9._-]/g, "_");
+        const outName = safeName.replace(/\.[^.]+$/, "") + ".wav";
+        const outPath = join(outputDir, outName);
+        await writeFile(outPath, wav);
+        outputs.push(outPath);
+      } catch {
+        // Skip entries that fail to decompress
+      }
+    }
+  } finally {
+    await fh.close();
+  }
+
+  return outputs;
+}
+
+/**
+ * Quick magic-byte check for BUN files.
+ * Returns true if the file starts with 'LB23'.
+ */
+export async function isBunFile(filePath) {
+  try {
+    const fh = await open(filePath, "r");
+    const buf = Buffer.alloc(4);
+    await fh.read(buf, 0, 4, 0);
+    await fh.close();
+    const tag = buf.toString("ascii");
+    return tag === "LB23";
+  } catch {
+    return false;
+  }
+}