@needle-tools/gltf-build-pipeline 2.16.0-next.85db3ce → 2.16.0-next.8ceb45e

package/README.md

@@ -14,10 +14,10 @@ Includes support for generating LOD quality level for textures and meshes. Use w
 In general all files that have been processed by this package are valid glTF/GLB files.    
 The glTF Build Pipeline package is meant to be used as a last step before delivery.   
 That means:
-- files are meant to be loaded e.g. in a web runtime like three.js 
+- files are meant to be loaded by [Needle Engine](https://needle.tools) (and other three.js based runtimes)
 - files are not to be opened in Blender again to be further edited    
 
-To load progressively enhanced glTF files in any three.js based engine see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
+To load progressively enhanced glTF files in Needle Engine or another three.js based runtime, see examples at [@needle-tools/gltf-progressive](https://www.npmjs.com/package/@needle-tools/gltf-progressive)
 
 ### Installation
 
@@ -26,6 +26,33 @@ To load progressively enhanced glTF files in any three.js based engine see examp
 ### Commands
 - `help` - use help to view options
 
+### Configuration
+
+The pipeline reads an optional `needle.config.json` from the working directory (or any parent directory). Configure pipeline behaviour under the `gltf` key:
+
+```json
+{
+  "gltf": {
+    "usecase": "product",
+    "textures": { "lods": true },
+    "meshes":   { "lods": true },
+    "audio":    { "enabled": true, "bitrate": 64 },
+    "exr":      { "enabled": true }
+  }
+}
+```
+
+The `gltf` value may also be a string shorthand for `usecase` — `"gltf": "product"` is equivalent to `"gltf": { "usecase": "product" }`.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `usecase` | `"default" \| "product" \| "world"` | `"default"` | High-level optimisation profile. |
+| `textures.lods` | `boolean` | `true` | Generate progressive texture LODs. |
+| `meshes.lods` | `boolean` | `true` | Generate progressive mesh LODs. |
+| `audio.enabled` | `boolean` | `true` | Compress externally referenced `.wav` audio files to Opus in an `.ogg` container, rewriting the URIs in the glTF. Lossy formats (`.mp3`, `.ogg`, `.m4a`, `.aac`) pass through unchanged to avoid compounding compression artifacts. Requires `ffmpeg` with `libopus` on `PATH`; when missing the build logs a warning and leaves the audio files untouched. |
+| `audio.bitrate` | `number` (kbps) | `128` | Opus encoding bitrate. 96 is near-transparent for most music; 128 matches YouTube's music tier and is the safe "won't sound bad" default. Drop to 48–64 for known mono/UI-only assets. |
+| `exr.enabled` | `boolean` | `true` | Convert EXR textures to KTX2 HDR via PMREM. When `false`, EXR textures (bundled and externally referenced) are left as-is so a downstream step can handle them. |
+
 # Contact
 
 For licensing questions please contact us.

package/dist/cache/cache.d.ts

@@ -2,6 +2,7 @@
 /// <reference types="node" resolution-mode="require"/>
 import { ExtensibleProperty } from "@gltf-transform/core";
 import { Logger } from "@donmccurdy/caporal";
+export declare function ensureHashReady(): Promise<void>;
 /**
  * Clear the cache.
  * This will remove all files in the cache directory.

package/dist/cache/cache.js

@@ -6,9 +6,16 @@ import { getVersion } from "../utils/version.js";
 // import * as CHECKDISCSPACE from 'check-disk-space'
 import xxhash from "xxhash-wasm";
 let xxHashModule = null;
-xxhash().then(module => {
-    xxHashModule = module;
-}).catch(() => { });
+// Single shared promise that resolves once the WASM module is loaded (or has failed).
+// Callers should `await ensureHashReady()` once before any synchronous hash call to
+// avoid a race where early calls use the JS fallback and later calls use WASM —
+// producing different cache keys for the same input within one process.
+const xxHashReady = xxhash()
+    .then(module => { xxHashModule = module; })
+    .catch(() => { });
+export function ensureHashReady() {
+    return xxHashReady;
+}
 /**
  * Get the available space on the cache directory in bytes.
  */
@@ -179,6 +186,17 @@ export function getKeyWithHash(property) {
     const key = `${prefix}-${hash}`;
     return { key, hash };
 }
+/**
+ * Combine two 32-bit hashes with mixing. Plain `a + b` is commutative and
+ * has poor diffusion — swapping two attribute buffers collides. This uses a
+ * boost::hash_combine-style mix: xor in the new bits, then bit-shift mix so
+ * order matters and unrelated changes don't cancel out.
+ */
+function combineHash(seed, value) {
+    // 0x9e3779b9 = golden-ratio constant used by boost / fnv variants
+    seed = (seed ^ (value + 0x9e3779b9 + ((seed << 6) | 0) + (seed >>> 2))) | 0;
+    return seed;
+}
 /**
  * Get the hash for a property or an object.
  * @param property The property to get the hash for.
@@ -186,27 +204,26 @@ export function getKeyWithHash(property) {
  * @returns The hash as a number.
  */
 export function getHash(property, level = 0) {
-    let hashStr = "";
     let hash = 0;
     if (property instanceof ExtensibleProperty) {
         const extensions = property.listExtensions();
         const extras = property.getExtras();
-        hash += hashObject({
+        hash = combineHash(hash, hashObject({
             extensions,
             extras,
-        });
+        }));
         if (property instanceof Texture) {
             const image = property.getImage();
             const bytes = image?.buffer;
             if (bytes)
-                hash += hashBuffer(bytes, image.byteOffset, image.byteLength);
+                hash = combineHash(hash, hashBuffer(bytes, image.byteOffset, image.byteLength));
         }
         else if (property instanceof Mesh) {
             const weights = property.getWeights();
-            hash += hashObject(weights);
+            hash = combineHash(hash, hashObject(weights));
             const primitives = property.listPrimitives();
             for (const prim of primitives) {
-                hash += hashString(getHash(prim, level + 1));
+                hash = combineHash(hash, hashString(getHash(prim, level + 1)));
             }
         }
         else if (property instanceof Primitive) {
@@ -220,32 +237,35 @@ export function getHash(property, level = 0) {
                     name: s,
                 };
             });
-            hash += hashObject({
+            hash = combineHash(hash, hashObject({
                 indices,
                 attributes,
                 targets,
                 semantics: semanticsNames
-            });
+            }));
             if (indices) {
                 const indexBuffer = indices.getArray();
                 if (indexBuffer) {
-                    hash += hashBuffer(indexBuffer.buffer, indexBuffer.byteOffset, indexBuffer.byteLength);
+                    hash = combineHash(hash, hashBuffer(indexBuffer.buffer, indexBuffer.byteOffset, indexBuffer.byteLength));
                 }
             }
             // We can not pass the whole buffer into hashObject since very large meshes will cause errors when trying to stringify
             // See https://linear.app/needle/issue/NE-6414
+            // Mix the semantic name into each attribute hash so swapping two attributes (e.g. POSITION ↔ NORMAL)
+            // doesn't collide — without this, the commutative combine would erase attribute identity.
             for (const sem of semantics) {
                 const arr = property.getAttribute(sem)?.getArray();
                 if (arr) {
-                    hash += hashBuffer(arr.buffer, arr.byteOffset, arr.byteLength);
+                    hash = combineHash(hash, hashString(sem));
+                    hash = combineHash(hash, hashBuffer(arr.buffer, arr.byteOffset, arr.byteLength));
                 }
             }
         }
     }
     else {
-        hash += hashObject(property);
+        hash = combineHash(hash, hashObject(property));
     }
-    return hashStr + hash;
+    return String(hash);
 }
 const cleanBuildPipelineVersion = getVersion(false).replace(/[^a-zA-Z0-9]/g, "_");
 function getCacheDirectory(root) {

package/dist/cache/job-cache.d.ts

@@ -15,6 +15,8 @@ export declare function computeJobKey(options: JobCacheOptions, inputFilePath: s
 /**
  * Save the result of a completed job to the cache.
  * Stores the content of each output file and a manifest linking them.
+ * The caller should include all output files including external sidecar files
+ * (e.g. .pmrem.ktx2) collected via PackGLTFOptions.externalFiles.
  */
 export declare function saveJobResult(jobKey: string, outputFiles: string[], logger: ILogger): void;
 /**

package/dist/cache/job-cache.js

@@ -29,6 +29,8 @@ export function computeJobKey(options, inputFilePath) {
 /**
  * Save the result of a completed job to the cache.
  * Stores the content of each output file and a manifest linking them.
+ * The caller should include all output files including external sidecar files
+ * (e.g. .pmrem.ktx2) collected via PackGLTFOptions.externalFiles.
  */
 export function saveJobResult(jobKey, outputFiles, logger) {
     const entries = [];

package/dist/cli/index.js

@@ -5,15 +5,26 @@ import { printStats, writeFileStatsToFile } from '../utils/stats.js';
 import { getVersion } from '../utils/version.js';
 import { UsecaseOptions, createConfig, getConfig } from '../config/index.js';
 import { isLOD, make_progressive } from '../transforms/needle_progressive.js';
-import { cacheSizeLimit, clearCache, limitCacheSize } from '../cache/cache.js';
+import { cacheSizeLimit, clearCache, ensureHashReady, limitCacheSize } from '../cache/cache.js';
 import { computeJobKey, saveJobResult, tryRestoreJobResult } from '../cache/job-cache.js';
-import { existsSync, statSync } from 'fs';
+import { convertExrBytesToPmremKtx2, createPmremRuntime, disposePmremRuntime } from '../transforms/needle_pmrem.js';
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'fs';
 import { ensureIsDirectory, foreachGLTF, isDirectory } from '../utils/fileutils.js';
-import path, { dirname, resolve } from 'path';
+import path, { basename, dirname, resolve } from 'path';
 import { ERROR_CODES } from '../constants.js';
 import { trackPipelineStart, trackPipelineEnd, trackError } from '../utils/analytics.js';
 // For testing / dev you can run `npm link` in the package directory
 // For removing the link run `npm rm --global @needle-tools/gltf-build-pipeline`
+// Disable caporal's autoCast for positional arguments.
+//
+// caporal's autoCast uses /^true|false$/ (precedence bug — should be /^(true|false)$/),
+// which matches any string ending with "false" or starting with "true". An <output>
+// path like ".../out-shellfalse" gets coerced to the boolean false, then stringified
+// to "false", and the pipeline writes to "<inputDir>/false" instead of the requested
+// directory. Same shape applies to paths ending with "on" or starting with "yes"/"1".
+// Disabling autoCast at the program level forces positionals through String(...);
+// options with explicit BOOLEAN/STRING validators are unaffected.
+program.cast(false);
 program
     .command("version", "Print current version")
     .action(async ({ logger }) => {
@@ -35,6 +46,9 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
     .option("--verbose", "Enable verbose output", { validator: program.BOOLEAN, default: false })
     .action(async ({ logger, args, options }) => {
     logger.level = options.verbose ? "debug" : "info";
+    // Wait for the xxHash WASM module so any hashing inside calculateStats sees the
+    // same hash function on every call (otherwise the first calls use the JS fallback).
+    await ensureHashReady();
     logger.info("Calculating stats for \"" + args.input + "\"");
     const input = args.input.toString();
     const filestats = new Array();
@@ -60,8 +74,14 @@ Caches are limited to ${cacheSizeLimit} MB disc space by default.
 This will produce multiple versions of the input file, each with a different level of optimization.   
 Each version will be compressed and written to the output directory.
 `)
-    .argument('<input>', "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed")
-    .argument('<output>', "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null })
+    // Explicit STRING validators prevent caporal's autoCast() from silently coercing
+    // a path that ends with "false" / "on" (or starts with "true" / "yes" / "1") into
+    // a boolean — caporal's autoCast regex is missing parentheses and matches as
+    // /^true | false$/ rather than /^(true|false)$/. Without these validators, an
+    // output path like "out-shellfalse" gets cast to the boolean false → stringified
+    // → file written to "<inputDir>/false" instead of the named directory.
+    .argument('<input>', "The input glTF, GLB or VRM file that should be compressed OR a directory that contains files to be compressed", { validator: program.STRING })
+    .argument('<output>', "The output file or directory. It can be an absolute path or a relative path to the input file. If not provided, the input file will be overwritten.", { default: null, validator: program.STRING })
     .option("--compress", `When enabled files will be compressed`, { validator: program.BOOLEAN, default: true })
     .option("--progressive", `When enabled files will processed to be progressively loaded`, { validator: program.BOOLEAN, default: true })
     .option("--usecase <usecase>", `The usecase for the compression. This will set the compression settings. Possible options: [${UsecaseOptions.join(", ")}]`, { validator: program.STRING })
@@ -76,6 +96,10 @@ Each version will be compressed and written to the output directory.
         logger.error(`[Needle Build Pipeline] v${getVersion()} You need to enable at least one of the options: --compress or --progressive`);
         return;
     }
+    // Wait for the xxHash WASM module before any hashing happens. Without this the
+    // first hash calls in a process use the JS fallback while later ones use WASM,
+    // producing different cache keys for the same input within a single run.
+    await ensureHashReady();
     logger.info(`[Needle Build Pipeline] v${getVersion()} — Transform '${args.input}'`);
     const pipelineMode = [options.progressive && 'progressive', options.compress && 'compress'].filter(Boolean).join('+');
     trackPipelineStart({ mode: pipelineMode, usecase: options.usecase?.toString() });
@@ -164,7 +188,7 @@ Each version will be compressed and written to the output directory.
                         stats.totalFileSizeInMBBefore += inputFileSize;
                     }
                 }
-                logger.info(`→ [CACHE] Restored ${restored.length} file(s)for job ${jobKey}`);
+                logger.info(`→ [CACHE] Restored ${restored.length} file(s) for job ${jobKey}`);
                 return;
             }
         }
@@ -192,6 +216,7 @@ Each version will be compressed and written to the output directory.
                 console.log("Progressive results:\n", progressive_results);
             }
         }
+        const externalFiles = [];
         if (options.compress === true) {
             const opts = {
                 config,
@@ -204,6 +229,7 @@ Each version will be compressed and written to the output directory.
                 // When progressive ran first, inputFile points to the progressive output copy.
                 // Pass the original source path so extensions can resolve sibling assets (e.g. .exr files).
                 sourceFile: progressive_results.length > 0 ? file : undefined,
+                externalFiles,
             };
             // If we have produced progressive assets then the array already contains the input
             if (progressive_results.length > 0) {
@@ -228,7 +254,7 @@ Each version will be compressed and written to the output directory.
             const allOutputFiles = progressive_results.length > 0
                 ? progressive_results
                 : [output || file];
-            saveJobResult(jobKey, allOutputFiles, logger);
+            saveJobResult(jobKey, [...allOutputFiles, ...externalFiles], logger);
         }
     });
     printStats(stats, logger, config);
@@ -243,7 +269,112 @@ Each version will be compressed and written to the output directory.
     });
     if (useCache)
         limitCacheSize();
+})
+    .command("pmrem", "Convert EXR files to PMREM-processed KTX2 HDR (Needle PMREM)")
+    .help(`Runs the PMREM WASM + basisu encoder on .exr files, producing <name>.pmrem.ktx2.
+This is the same processing the Needle build pipeline applies to EXR textures inside
+GLB/GLTF files, exposed as a standalone command for raw .exr inputs.
+`)
+    .argument('<input>', "Path to an .exr file OR a directory containing .exr files (recursive)", { validator: program.STRING })
+    .argument('<output>', "Output file (when input is a single .exr) or output directory. Defaults to writing next to the input file.", { default: null, validator: program.STRING })
+    .option("--cache", "Use \"--cache False\" to disable caching.", { validator: program.BOOLEAN, default: true })
+    .option("--debug", "Enable verbose output with \"--debug True\"", { validator: program.BOOLEAN, default: false })
+    .option("--verbose", "Enable verbose output with \"--verbose True\"", { validator: program.BOOLEAN, default: false })
+    .hide()
+    .action(async ({ logger, args, options }) => {
+    logger.level = (options.debug || options.verbose) ? "debug" : "info";
+    await ensureHashReady();
+    const input = args.input.toString();
+    if (!existsSync(input)) {
+        logger.error(`Input does not exist: ${input}`);
+        process.exit(ERROR_CODES.INVALID_ARGS);
+    }
+    const exrFiles = [];
+    const inputIsDirectory = isDirectory(input);
+    if (inputIsDirectory) {
+        collectExrFiles(input, exrFiles);
+    }
+    else if (input.toLowerCase().endsWith('.exr')) {
+        exrFiles.push(input);
+    }
+    else {
+        logger.error(`Input is not an .exr file or directory: ${input}`);
+        process.exit(ERROR_CODES.INVALID_ARGS);
+    }
+    if (exrFiles.length === 0) {
+        logger.warn(`No .exr files found in ${input}`);
+        return;
+    }
+    // caporal's program.cast(false) forces String(null) → "null" for the
+    // missing positional default, so treat that literal as "no output given".
+    const rawOutput = args.output?.toString() || null;
+    let outputArg = (rawOutput && rawOutput !== 'null') ? rawOutput : null;
+    if (outputArg && !path.isAbsolute(outputArg)) {
+        const base = inputIsDirectory ? input : dirname(input);
+        outputArg = resolve(base, outputArg);
+    }
+    const useCache = options.cache !== false;
+    logger.info(`[Needle Build Pipeline] v${getVersion()} — pmrem: ${exrFiles.length} file(s)`);
+    const runtime = await createPmremRuntime(logger);
+    if (!runtime) {
+        logger.error('pmrem runtime is not available (WASM or basisu binary missing). Run `npm run build:pmrem` in the package directory.');
+        process.exit(ERROR_CODES.PACKING_FAILED);
+    }
+    try {
+        for (const exrPath of exrFiles) {
+            const outPath = resolvePmremOutputPath(exrPath, input, inputIsDirectory, outputArg);
+            logger.info(`→ pmrem ${exrPath} → ${outPath}`);
+            const exrBytes = readFileSync(exrPath);
+            const ktx2Bytes = await convertExrBytesToPmremKtx2(runtime, new Uint8Array(exrBytes.buffer, exrBytes.byteOffset, exrBytes.byteLength), { useCache, logLabel: `pmrem ${basename(exrPath)}` });
+            writeFileSync(outPath, ktx2Bytes);
+        }
+    }
+    finally {
+        await disposePmremRuntime(runtime);
+    }
+    if (useCache)
+        limitCacheSize();
 });
+function collectExrFiles(dir, out) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === 'node_modules' || entry.startsWith('.'))
+            continue;
+        const full = path.join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory()) {
+            collectExrFiles(full, out);
+        }
+        else if (entry.toLowerCase().endsWith('.exr')) {
+            out.push(full);
+        }
+    }
+}
+function resolvePmremOutputPath(exrPath, input, inputIsDirectory, outputArg) {
+    const outName = basename(exrPath).replace(/\.exr$/i, '.pmrem.ktx2');
+    if (!outputArg) {
+        // Default: write next to the input file
+        return path.join(dirname(exrPath), outName);
+    }
+    if (inputIsDirectory) {
+        // Mirror the directory layout under outputArg, treating it as a directory
+        const rel = path.relative(input, exrPath);
+        const relDir = dirname(rel);
+        const outDir = relDir === '.' ? outputArg : path.join(outputArg, relDir);
+        ensureIsDirectory(outDir);
+        return path.join(outDir, outName);
+    }
+    // Single-file input. outputArg may be an existing directory, or an explicit file path.
+    if (existsSync(outputArg) && isDirectory(outputArg)) {
+        return path.join(outputArg, outName);
+    }
+    if (outputArg.toLowerCase().endsWith('.ktx2')) {
+        ensureIsDirectory(dirname(outputArg));
+        return outputArg;
+    }
+    // Treat as a directory that does not exist yet
+    ensureIsDirectory(outputArg);
+    return path.join(outputArg, outName);
+}
 program.run().catch(err => {
     // Since we still invoke this package with paths when running npm scripts we need to ignore this error
     // We might want to move this code here into an extra package.

package/dist/config/index.d.ts

@@ -13,6 +13,17 @@ export type Config = {
     meshes?: {
         lods: boolean;
     };
+    audio?: {
+        /** Enable Opus/Ogg compression of externally referenced audio files. Default: true. */
+        enabled?: boolean;
+        /** Opus encoding bitrate in kbps. Default: 64. */
+        bitrate?: number;
+    };
+    exr?: {
+        /** Enable EXR -> KTX2 HDR conversion via PMREM. When false, EXR textures (bundled or
+         *  externally referenced) are left untouched. Default: true. */
+        enabled?: boolean;
+    };
 };
 /**
  * Create a config object with the given usecase.

package/dist/config/index.js

@@ -70,8 +70,11 @@ export function getConfig(configPath, fallbackSearchDirectory, opts) {
             throw new Error(`Failed parsing config at \"${configPath}\"`);
         }
     }
+    // Always return a fresh shallow copy. Callers (notably the CLI) mutate the
+    // returned object (`config.usecase = ...`); returning the cache by reference
+    // would let those mutations poison subsequent getConfig() calls.
     if (_cachedConfig !== undefined) {
-        return _cachedConfig;
+        return { ..._cachedConfig };
     }
     // Resolve the config once and cache it
     // Check if a needle.config.json exists in the directory from which the script is run (or any parent directory)
@@ -82,12 +85,14 @@ export function getConfig(configPath, fallbackSearchDirectory, opts) {
             logger.info(`Using config with usecase: ${_cachedConfig.usecase}`);
         }
     }
-    // If no config was found, use the default config
+    // If no config was found, use the default config. Store a copy in the cache
+    // so we never alias defaultConfig directly — that way even if a downstream
+    // bug ever returned the cache by reference, defaultConfig itself stays clean.
     if (!_cachedConfig) {
         logger.debug("No config found. Using default config.");
-        _cachedConfig = defaultConfig;
+        _cachedConfig = { ...defaultConfig };
     }
-    return _cachedConfig;
+    return { ..._cachedConfig };
 }
 let _cachedConfig = undefined;
 export function searchConfig(directory, logger) {

package/dist/extensions/NEEDLE_opaque/NEEDLE_opaque.d.ts

@@ -1,4 +1,4 @@
-import { WriterContext, PropertyType } from '@gltf-transform/core';
+import { Extension, WriterContext, PropertyType } from '@gltf-transform/core';
 declare interface IExtensibleProperty {
 }
 type DebugBreakPoint = boolean | "pointer:read";
@@ -23,5 +23,5 @@ export interface IExtensionWriter {
     write(context: WriterContext, prop: IExtensibleProperty): void;
 }
 export declare let currentGenerator: string;
-export declare function createOpaqueExtension(name: string, types: PropertyType | PropertyType[], opts?: Options): IOpaqueExtension;
+export declare function createOpaqueExtension(name: string, types: PropertyType | PropertyType[], opts?: Options): typeof Extension;
 export {};

package/dist/extensions/NEEDLE_opaque/NEEDLE_opaque.js

@@ -5,6 +5,7 @@ import { NEEDLE_progressive_texture_settings } from '../NEEDLE_progressive_textu
 import { testAssert } from '../../utils/test-assert.js';
 import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
+import { isAudioUri, isRelativeAudioUri, listAudioRefs, registerAudioRef } from '../../transforms/needle_audio_registry.js';
 const ALL_PROPERTY_TYPES = [];
 for (const key in PropertyType) {
     ALL_PROPERTY_TYPES.push(PropertyType[key]);
@@ -627,6 +628,25 @@ class JsonPointerHandler {
                         else
                             console.warn("WARN: failed registering pointer", fullPath, value);
                     }
+                    // External audio reference (e.g. "click.wav" or "music.mp3" on a NEEDLE_components AudioSource).
+                    // Audio is never embedded in the GLB — it stays as a sidecar file. We register the
+                    // (obj, key) location so `needle_audio_transform` can compress the file and so the
+                    // write-time pass can rewrite the JSON string to the new URI.
+                    if (!isTexturePointer && isAudioUri(value) && isRelativeAudioUri(value)) {
+                        const inputDir = getExtensionInputFile() ? dirname(getExtensionInputFile()) : '';
+                        const audioPath = inputDir ? join(inputDir, value) : '';
+                        if (audioPath && existsSync(audioPath)) {
+                            registerAudioRef({ obj, key, sourcePath: audioPath, sourceUri: value });
+                            if (this.debug)
+                                console.log(`Registered external audio "${value}" at ${fullPath}`);
+                        }
+                        else if (audioPath) {
+                            // Non-fatal: leave the URI untouched and warn. Mirrors EXR error path
+                            // but uses warn instead of testAssert since missing audio shouldn't
+                            // hard-fail the build.
+                            this.document.getLogger().warn(`NEEDLE_opaque: external audio not found: ${audioPath}`);
+                        }
+                    }
                     // External EXR file reference (e.g. "StudioHDRI_ferndale_studio_04_1k.exr" in a ReflectionProbe)
                     // Inject the file into the document as a Texture so PMREM can process it
                     if (!isTexturePointer && value.match(/\.exr$/i)) {
@@ -816,6 +836,16 @@ class JsonPointerHandler {
             if (ptr.resolve(context, step))
                 ptr.write();
         });
+        // Resolve external audio pointers: rewrite the JSON string from the original URI
+        // (e.g. "click.wav") to the compressed URI (e.g. "click.opus.ogg"). Refs whose
+        // `newUri` was never set (ffmpeg missing, compression skipped) are left untouched.
+        for (const ref of listAudioRefs()) {
+            if (ref.newUri && ref.obj[ref.key] === ref.sourceUri) {
+                if (this.debug)
+                    console.log(`< Resolved external audio: ${ref.sourceUri} → ${ref.newUri}`);
+                ref.obj[ref.key] = ref.newUri;
+            }
+        }
         // Resolve external EXR pointers: update component data with the texture's current URI
         for (const { obj, key, texture } of this.externalExrPointers) {
             const uri = texture.getURI() || texture.getName() || '';

package/dist/extensions/NEEDLE_opaque/index.d.ts

@@ -1,3 +1,2 @@
-import { Extension } from "@gltf-transform/core";
 export * from "./NEEDLE_opaque.js";
-export declare const ALL_EXTENSIONS: (typeof Extension)[];
+export declare const ALL_EXTENSIONS: typeof import("@gltf-transform/core").Extension[];

package/dist/scripts/pack-gltf.d.ts

@@ -11,6 +11,8 @@ export type PackGLTFOptions = {
     verbose?: boolean;
     /** Original source file path, used to resolve external assets (e.g. .exr files) when inputFile differs from the source (e.g. after progressive transform) */
     sourceFile?: string;
+    /** Populated by packGLTF with absolute paths to external sidecar files produced during processing (e.g. .pmrem.ktx2) */
+    externalFiles?: string[];
 };
 /** Compress a glTF file
  */

package/dist/scripts/pack-gltf.js

@@ -6,8 +6,8 @@ import { existsSync, readFileSync, statSync, writeFileSync } from 'fs';
 import { MeshoptDecoder, MeshoptEncoder } from 'meshoptimizer';
 import { dedup, metalRough, prune, resample } from '@gltf-transform/functions';
 import { ALL_EXTENSIONS as NEEDLE_EXTENSIONS, NEEDLE_compression_texture, NEEDLE_mesh_compression, NEEDLE_pmrem, NEEDLE_lightmaps_ext, setExtensionInputFile } from '../extensions/index.js';
-import { isLOD, isMeshLOD, needle_animation_transform, needle_asset, needle_mesh_transform, needle_texture_transform, } from '../transforms/index.js';
-import { copyExternalResources, getOutputPath, getVersion, ioTryReadWithMissingResources, writeNodeIO } from "../utils/index.js";
+import { clearAudioRegistry, isLOD, isMeshLOD, listAudioRefs, needle_animation_transform, needle_asset, needle_audio_transform, needle_mesh_transform, needle_texture_transform, } from '../transforms/index.js';
+import { copyExternalResources, getOutputPath, getVersion, isMaterialOnlyGLB, ioTryReadWithMissingResources, writeNodeIO } from "../utils/index.js";
 import { addToCache, getHash, tryGetFromCache, } from "../cache/index.js";
 import { TestAssertionError } from '../utils/test-assert.js';
 /** Compress a glTF file
@@ -70,6 +70,7 @@ export async function packGLTF(inputFile, outputFile, options) {
         // Use sourceFile when available (e.g. when inputFile is a progressive output copy)
         const assetSourceFile = options.sourceFile ?? inputFile;
         setExtensionInputFile(assetSourceFile);
+        clearAudioRegistry();
         const document = await ioTryReadWithMissingResources(io, inputFile);
         if (options.logger) {
             document.setLogger(options.logger);
@@ -96,6 +97,7 @@ export async function packGLTF(inputFile, outputFile, options) {
                 config,
             }),
             needle_mesh_transform({ file: inputFile, config }),
+            needle_audio_transform({ outfile: outputFile, useCache, config }),
             needle_animation_transform({}),
             resample({
                 tolerance: 1e-6, // NOTE: lowered from 1e-4 to 1e-6 to fix https://linear.app/needle/issue/NE-6872
@@ -105,8 +107,11 @@ export async function packGLTF(inputFile, outputFile, options) {
             dedup({ propertyTypes: [PropertyType.MESH, PropertyType.MATERIAL] }),
         ];
         const isProgressiveAsset = isLOD(inputFile);
-        // TODO: progressive mesh LODs should not be pruned right now because it will remove e.g. UVs from meshes (and probably blend shapes too) (so we just not do it for any progressive asset) 
-        if (!isProgressiveAsset) {
+        const materialOnly = isMaterialOnlyGLB(document);
+        // TODO: progressive mesh LODs should not be pruned right now because it will remove e.g. UVs from meshes (and probably blend shapes too) (so we just not do it for any progressive asset)
+        // Material-only GLBs should not be pruned at all — they have no meshes so
+        // prune would strip materials, textures, and buffers, producing an empty file.
+        if (!isProgressiveAsset && !materialOnly) {
             transforms.push(prune({
                 // Pruning animations is not supported yet (e.g. if the animation is only referenced by a component)
                 propertyTypes: [
@@ -123,6 +128,36 @@ export async function packGLTF(inputFile, outputFile, options) {
             }));
         }
         await document.transform(...transforms);
+        // Collect external sidecar files (e.g. .pmrem.ktx2) produced by transforms
+        if (options.externalFiles) {
+            const outDir = path.dirname(outputFile);
+            const root = document.getRoot();
+            for (const tex of root.listTextures()) {
+                const uri = tex.getURI();
+                if (uri && !uri.startsWith('data:')) {
+                    const absPath = path.resolve(outDir, uri);
+                    if (existsSync(absPath)) {
+                        options.externalFiles.push(absPath);
+                    }
+                }
+            }
+            for (const buf of root.listBuffers()) {
+                const uri = buf.getURI();
+                if (uri && !uri.startsWith('data:')) {
+                    const absPath = path.resolve(outDir, uri);
+                    if (existsSync(absPath)) {
+                        options.externalFiles.push(absPath);
+                    }
+                }
+            }
+            for (const ref of listAudioRefs()) {
+                const uri = ref.newUri ?? ref.sourceUri;
+                const absPath = path.resolve(outDir, uri);
+                if (existsSync(absPath)) {
+                    options.externalFiles.push(absPath);
+                }
+            }
+        }
         logger.debug(`← Writing to ${outputFile}`);
         await writeNodeIO(io, outputFile, document);
         if (useCache && cacheKey != undefined && existsSync(outputFile))

package/dist/transforms/index.d.ts

@@ -7,3 +7,6 @@ export * from "./needle_mesh_transform.js";
 export * from "./needle_common.js";
 export * from "./needle_texture_transform.js";
 export * from "./needle_animation_transform.js";
+export * from "./needle_audio.js";
+export * from "./needle_audio_registry.js";
+export * from "./needle_audio_ffmpeg.js";

package/dist/transforms/index.js

@@ -7,3 +7,6 @@ export * from "./needle_mesh_transform.js";
 export * from "./needle_common.js";
 export * from "./needle_texture_transform.js";
 export * from "./needle_animation_transform.js";
+export * from "./needle_audio.js";
+export * from "./needle_audio_registry.js";
+export * from "./needle_audio_ffmpeg.js";

package/dist/transforms/needle_audio.d.ts

@@ -0,0 +1,12 @@
+import { Transform } from '@gltf-transform/core';
+import { Config } from '../config/index.js';
+export type AudioTransformOptions = {
+    /** The path the GLB will be written to. Audio sidecars are placed alongside. */
+    outfile: string;
+    /** Disk cache toggle */
+    useCache: boolean;
+    config: Config;
+};
+export declare function needle_audio_transform(options: AudioTransformOptions): Transform;
+/** "click.wav" → "click.opus.ogg". Preserves the basename casing. */
+export declare function computeOpusOggUri(sourceUri: string): string;