@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/vehicle/audioImport.js

@@ -0,0 +1,610 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIX_DEFAULTS = exports.MIX_FIELDS = exports.NOT_CONSUMED = exports.SLOT_BUFFER = exports.AUDIO_IMPORT_VERSION = void 0;
+exports.resolveMix = resolveMix;
+exports.pluginBin = pluginBin;
+exports.runInventory = runInventory;
+exports.readPcm16 = readPcm16;
+exports.applyTrim = applyTrim;
+exports.composeWavs = composeWavs;
+exports.blendName = blendName;
+exports.stockEvent = stockEvent;
+exports.importVehicleAudio = importVehicleAudio;
+exports.notFittedReason = notFittedReason;
+exports.formatAudioImport = formatAudioImport;
+/**
+ * `helix vehicle audio-import` — a car's sounds, taken from the sim mod that carries them, never synthesised.
+ *
+ *   helix vehicle audio-import <mod dir | mod .zip | Assetto Corsa car dir | .bank> --out <dir>
+ *     [--sim beamng|ac|auto] [--vehicle <beamng id>] [--config <file.pc>] [--map <slot-map.json>]
+ *     [--beamng-root <BeamNG.drive install>] [--cylinders N] [--prefer exterior|interior] [--ac-native-rungs] [--json]
+ *
+ * Each source is read by `plugins/beamng-vehicle/bin/sim_audio_import.py` (BeamNG jbeam + blends + stock FMOD banks,
+ * Assetto Corsa FMOD banks), which decodes the recordings into a staging folder and reports what it found. This module
+ * merges the sources a `--map` names, gives every one of the 31 HELIX slots a real recording (or a legitimate absence),
+ * writes `<out>/audio/*.wav` (16-bit PCM) and `<out>/audio.json` (the package `audio` block: bank + slots, every
+ * consumed slot, bank sample and blend carrying `provenance`) and `<out>/audio-import.json` (the full report).
+ *
+ * Slot map (all optional; paths relative to the map file):
+ *   {
+ *     "sources": { "ac": { "path": "../assettocorsa/content/cars/ferrari_f40", "sim": "ac" } },
+ *     "slots":   { "horn": { "source": "ac", "sample": "horn" }, "reverseBeep": { "notFitted": "no beeper" },
+ *                  "doorOpen": { "source": "ac" } },
+ *     "ladder":  { "source": "main", "rpm": { "F40_ex_on_mid": 5700 }, "prefer": "exterior", "nativeRungs": false },
+ *     "cylinders": 8, "strokes": 4, "bankId": "ferrari-f40", "modUrl": "https://..."
+ *   }
+ * The positional source is `main`. A slot routed to a source takes that source's pick for the slot (or the named
+ * `sample` / jbeam `field` / event value); everything else comes from `main`, then (with --beamng-root) the BeamNG base
+ * game's own default for that slot.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const audioSlots_1 = require("./audioSlots");
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+exports.AUDIO_IMPORT_VERSION = 1;
+/** The buffer name the runtime plays each slot's sample under (engine-core PACKAGE_SLOT_TO_RUNTIME_SOUND). */
+exports.SLOT_BUFFER = {
+    startup: 'vehicle.ignition', shutdown: 'vehicle.shutdown', shiftUp: 'vehicle.shift.up', shiftDown: 'vehicle.shift.down',
+    clutch: 'vehicle.clutch', transmissionWhine: 'vehicle.transmission.whine', turboSpool: 'vehicle.turbo.whine',
+    blowOff: 'vehicle.turbo.blowoff', intake: 'vehicle.intake', revLimiter: 'vehicle.rev-limiter', backfire: 'vehicle.backfire',
+    suspension: 'vehicle.suspension', impactLight: 'vehicle.impact.light', impactMedium: 'vehicle.impact.medium',
+    impactHeavy: 'vehicle.impact.heavy', tyreSqueal: 'vehicle.tyre.scrub', tyreScrub: 'vehicle.tyre.scrub',
+    tyreSpin: 'vehicle.tyre.spin', tyreRollSlow: 'vehicle.tyre.roll.slow', tyreRollFast: 'vehicle.tyre.roll.fast',
+    indicatorTick: 'vehicle.indicator.tick', skid: 'vehicle.skid', brakeSqueal: 'vehicle.brake-squeal',
+    handbrake: 'vehicle.handbrake', reverseBeep: 'vehicle.reverse-beep', horn: 'vehicle.horn', doorOpen: 'vehicle.door.open',
+    doorClose: 'vehicle.door.close', idle: 'vehicle.idle',
+};
+/** Slots whose recording is kept but that today's portable runtime does not play from a package. */
+exports.NOT_CONSUMED = {
+    transmissionWhine: 'the runtime plays a recorded gear whine only with a declared native pitch (gearWhineNativeHz), which a vehicle package cannot carry yet; the recording is kept for when it can',
+    intake: 'the portable runtime has no intake layer yet; the recording is kept for when it has',
+};
+/**
+ * The runtime reads these five from every audio block; one missing reaches Web Audio as NaN (`setValueAtTime ...
+ * non-finite`), which stops the frame loop: the car boards, never moves, and plays nothing (R34 1.0.9).
+ */
+exports.MIX_FIELDS = ['engineGainDb', 'exhaustGainDb', 'minLoadMix', 'maxLoadMix', 'muffling'];
+/** The engine's own BeamNG-blend defaults (engine-core beamngBlend.ts: importBeamngBlend / buildBeamngBank). */
+exports.MIX_DEFAULTS = { engineGainDb: -8, exhaustGainDb: -5, minLoadMix: 0.15, maxLoadMix: 1, muffling: 0.25 };
+/** Where each mix field comes from: --map, then --base-package, then the ladder's mod, then the main mod, then the default. */
+function resolveMix(layers) {
+    const values = {};
+    const from = {};
+    for (const field of exports.MIX_FIELDS) {
+        const hit = layers.find((l) => typeof l.values?.[field] === 'number' && Number.isFinite(l.values[field]));
+        values[field] = hit ? Number(hit.values[field]) : exports.MIX_DEFAULTS[field];
+        from[field] = hit ? `${hit.label}${hit.from?.[field] ? ` ${hit.from[field]}` : ''}` : 'default (the engine\'s BeamNG-blend default)';
+    }
+    return { values, from };
+}
+function readBaseAudio(file) {
+    const path = (0, node_fs_1.existsSync)((0, node_path_1.join)(file, 'vehicle-package.json')) ? (0, node_path_1.join)(file, 'vehicle-package.json') : file;
+    let doc;
+    try {
+        doc = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`--base-package ${file}: ${error.message}`);
+    }
+    const audio = isRecord(doc) && isRecord(doc.audio) ? doc.audio : isRecord(doc) && Array.isArray(doc.slots) ? doc : undefined;
+    if (!audio)
+        throw new Error(`--base-package ${path} has no audio block`);
+    return audio;
+}
+function pluginBin() {
+    const candidates = [(0, node_path_1.resolve)(__dirname, '..', '..', 'plugins', 'beamng-vehicle', 'bin'), (0, node_path_1.resolve)(__dirname, '..', '..', '..', 'plugins', 'beamng-vehicle', 'bin')];
+    const hit = candidates.find((dir) => (0, node_fs_1.existsSync)((0, node_path_1.join)(dir, 'sim_audio_import.py')));
+    if (!hit)
+        throw new Error('the sim audio importer (plugins/beamng-vehicle/bin/sim_audio_import.py) is missing from this install');
+    return hit;
+}
+function runInventory(source, staging, sim, options, python = process.env.HELIX_PYTHON || 'python3') {
+    (0, node_fs_1.mkdirSync)(staging, { recursive: true });
+    const optionsFile = (0, node_path_1.join)(staging, 'options.json');
+    (0, node_fs_1.writeFileSync)(optionsFile, JSON.stringify(options));
+    const run = (0, node_child_process_1.spawnSync)(python, [(0, node_path_1.join)(pluginBin(), 'sim_audio_import.py'), '--source', source, '--staging', staging, '--sim', sim, '--options', optionsFile], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, env: process.env });
+    if (run.error)
+        throw new Error(`could not run ${python}: ${run.error.message} (set HELIX_PYTHON to a Python 3.10+ interpreter)`);
+    if (run.status !== 0)
+        throw new Error(`${(0, node_path_1.basename)(source)}: ${(run.stderr || run.stdout || '').trim().split('\n').slice(-3).join(' ')}`);
+    return JSON.parse(run.stdout);
+}
+const sha256File = (path) => (0, node_crypto_1.createHash)('sha256').update((0, node_fs_1.readFileSync)(path)).digest('hex');
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'vehicle';
+}
+class Writer {
+    dir;
+    bySha = new Map();
+    names = new Set();
+    constructor(out) {
+        this.dir = (0, node_path_1.join)(out, 'audio');
+        (0, node_fs_1.mkdirSync)(this.dir, { recursive: true });
+    }
+    /** Copy a staged WAV to audio/<name>.wav once per distinct content; returns the file name and its row fields. */
+    put(wav, stem) {
+        const sha = sha256File(wav);
+        let file = this.bySha.get(sha);
+        if (!file) {
+            const base = stem.replace(/\.wav$/i, '').replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._-]+|[._-]+$/g, '').slice(0, 80) || 'sample';
+            file = `${base}.wav`;
+            if (this.names.has(file))
+                file = `${base}-${sha.slice(0, 8)}.wav`;
+            this.names.add(file);
+            this.bySha.set(sha, file);
+            (0, node_fs_1.copyFileSync)(wav, (0, node_path_1.join)(this.dir, file));
+        }
+        return { file, bytes: (0, node_fs_1.readFileSync)((0, node_path_1.join)(this.dir, file)).length, checksumSha256: sha };
+    }
+}
+/** A 16-bit PCM WAV's format and sample bytes (what the importer writes). */
+function readPcm16(path) {
+    const buf = (0, node_fs_1.readFileSync)(path);
+    if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WAVE')
+        throw new Error(`${(0, node_path_1.basename)(path)} is not a WAV`);
+    let at = 12;
+    let fmt;
+    while (at + 8 <= buf.length) {
+        const id = buf.toString('ascii', at, at + 4);
+        const size = buf.readUInt32LE(at + 4);
+        if (id === 'fmt ')
+            fmt = { tag: buf.readUInt16LE(at + 8), channels: buf.readUInt16LE(at + 10), rate: buf.readUInt32LE(at + 12), bits: buf.readUInt16LE(at + 22) };
+        if (id === 'data') {
+            if (!fmt || fmt.tag !== 1 || fmt.bits !== 16)
+                throw new Error(`${(0, node_path_1.basename)(path)} is not 16-bit PCM`);
+            const data = buf.subarray(at + 8, Math.min(buf.length, at + 8 + size));
+            return { rate: fmt.rate, channels: fmt.channels, data: data.subarray(0, data.length - (data.length % (2 * fmt.channels))) };
+        }
+        at += 8 + size + (size % 2);
+    }
+    throw new Error(`${(0, node_path_1.basename)(path)} has no data chunk`);
+}
+function writePcm16(path, pcm) {
+    const align = pcm.channels * 2;
+    const header = Buffer.alloc(44);
+    header.write('RIFF', 0, 'ascii');
+    header.writeUInt32LE(36 + pcm.data.length, 4);
+    header.write('WAVE', 8, 'ascii');
+    header.write('fmt ', 12, 'ascii');
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(pcm.channels, 22);
+    header.writeUInt32LE(pcm.rate, 24);
+    header.writeUInt32LE(pcm.rate * align, 28);
+    header.writeUInt16LE(align, 32);
+    header.writeUInt16LE(16, 34);
+    header.write('data', 36, 'ascii');
+    header.writeUInt32LE(pcm.data.length, 40);
+    (0, node_fs_1.writeFileSync)(path, Buffer.concat([header, pcm.data]));
+}
+function trimPcm(pcm, trim) {
+    if (!trim)
+        return pcm;
+    const frame = pcm.channels * 2;
+    const frames = pcm.data.length / frame;
+    const start = Math.max(0, Math.min(frames, Math.round((trim.startS ?? 0) * pcm.rate)));
+    const end = Math.max(start, Math.min(frames, trim.endS === undefined ? frames : Math.round(trim.endS * pcm.rate)));
+    if (end - start < Math.round(0.01 * pcm.rate))
+        throw new Error(`trim ${JSON.stringify(trim)} leaves less than 10 ms of a ${(frames / pcm.rate).toFixed(2)} s recording`);
+    return { ...pcm, data: pcm.data.subarray(start * frame, end * frame) };
+}
+/** Cut a recording to a window (a blow-off take inside a 41 s file); recorded as a `trim` transform. */
+function applyTrim(emitted, trim, dir, slot) {
+    if (!trim || (trim.startS === undefined && trim.endS === undefined))
+        return emitted;
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const pcm = trimPcm(readPcm16(emitted.wav), trim);
+    const target = (0, node_path_1.join)(dir, `${slot}-trim-${(0, node_crypto_1.createHash)('sha256').update(pcm.data).digest('hex').slice(0, 8)}.wav`);
+    writePcm16(target, pcm);
+    const transforms = [...(Array.isArray(emitted.provenance.transforms) ? emitted.provenance.transforms : []),
+        { kind: 'trim', startS: trim.startS ?? 0, ...(trim.endS !== undefined ? { endS: trim.endS } : {}), tool: 'helix audio-import' }];
+    return { ...emitted, wav: target, provenance: { ...emitted.provenance, transforms } };
+}
+/** Several real recordings played in order as one (a stock horn's start + loop + end). Formats must match. */
+function composeWavs(pieces, dir, slot) {
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const loaded = pieces.map((p) => ({ pcm: trimPcm(readPcm16(p.wav), p.trim), repeat: p.repeat, wav: p.wav }));
+    const { rate, channels } = loaded[0].pcm;
+    for (const p of loaded) {
+        if (p.pcm.rate !== rate || p.pcm.channels !== channels) {
+            throw new Error(`concat for ${slot}: ${(0, node_path_1.basename)(p.wav)} is ${p.pcm.rate} Hz ${p.pcm.channels} ch, the first piece ${rate} Hz ${channels} ch; pick pieces from one take`);
+        }
+    }
+    const data = Buffer.concat(loaded.flatMap((p) => Array.from({ length: p.repeat }, () => p.pcm.data)));
+    const target = (0, node_path_1.join)(dir, `${slot}-concat-${(0, node_crypto_1.createHash)('sha256').update(data).digest('hex').slice(0, 8)}.wav`);
+    writePcm16(target, { rate, channels, data });
+    return target;
+}
+function wavStem(path) {
+    // Staged names are "<stem>-<sha8>.wav"; keep the stem.
+    return (0, node_path_1.basename)(path).replace(/-[0-9a-f]{8}\.wav$/i, '').replace(/\.wav$/i, '');
+}
+function readMap(path) {
+    if (!path)
+        return { map: {}, base: process.cwd() };
+    const file = (0, node_path_1.resolve)(path);
+    const map = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    if (!isRecord(map))
+        throw new Error(`${file} is not a JSON object`);
+    for (const slot of Object.keys(map.slots ?? {})) {
+        if (!audioSlots_1.VEHICLE_AUDIO_SLOTS.includes(slot))
+            throw new Error(`--map names slot "${slot}", which is not a HELIX audio slot (${audioSlots_1.VEHICLE_AUDIO_SLOTS.join(', ')})`);
+    }
+    return { map, base: (0, node_path_1.dirname)(file) };
+}
+/** `art/sound/blends/RB26DETT_ENG.sfxBlend2D.json` or `RB26DETT_ENG` -> `RB26DETT_ENG`. */
+function blendName(value) {
+    if (!value)
+        return undefined;
+    return value.replace(/\\/g, '/').split('/').pop().replace(/\.sfxBlend2D\.json$/i, '');
+}
+/** A stock event as the map writes it (`event:>A>B`, `event:/A/B`, or `A/B (a note)`) -> `event:/A/B`; else undefined. */
+function stockEvent(value) {
+    if (!value)
+        return undefined;
+    const clean = value.replace(/\s*\(.*\)\s*$/, '').trim();
+    if (clean.startsWith('event:>'))
+        return `event:/${clean.slice('event:>'.length).replace(/>/g, '/')}`;
+    if (clean.startsWith('event:/'))
+        return clean;
+    if (/^[A-Z][\w ]*\/[\w/ -]+$/.test(clean))
+        return `event:/${clean}`;
+    return undefined;
+}
+const BNG = '_beamng-base';
+function importVehicleAudio(opts) {
+    const out = (0, node_path_1.resolve)(opts.out);
+    (0, node_fs_1.mkdirSync)(out, { recursive: true });
+    const { map, base } = readMap(opts.map);
+    const baseAudio = opts.basePackage ? readBaseAudio((0, node_path_1.resolve)(opts.basePackage)) : undefined; // fail before any extraction
+    const sources = { main: { path: (0, node_path_1.resolve)(opts.source), sim: opts.sim ?? 'auto', vehicle: opts.vehicle, config: opts.config, modUrl: opts.modUrl ?? map.modUrl, prefer: opts.prefer } };
+    for (const [id, src] of Object.entries(map.sources ?? {})) {
+        if (id === 'main')
+            throw new Error('--map sources may not redefine "main" (the positional source)');
+        const path = src.path ? ((0, node_path_1.isAbsolute)(src.path) ? src.path : (0, node_path_1.resolve)(base, src.path)) : (src.sim === 'beamng-base' ? opts.beamngRoot : src.sim === 'recording' ? base : undefined);
+        if (!path)
+            throw new Error(`--map source "${id}" has no path${src.sim === 'beamng-base' ? ' (and no --beamng-root)' : ''}`);
+        sources[id] = { ...src, path };
+    }
+    const slotsMap = map.slots ?? {};
+    // engineLadder / exhaustLadder entries are another way to say `ladder`.
+    const engineEntry = slotsMap.engineLadder;
+    const exhaustEntry = slotsMap.exhaustLadder;
+    const ladderSource = map.ladder?.source ?? engineEntry?.source ?? exhaustEntry?.source ?? 'main';
+    if (exhaustEntry?.source && exhaustEntry.source !== ladderSource)
+        throw new Error('--map: engineLadder and exhaustLadder must come from the same source (one recorded bank)');
+    const engineBlendPick = blendName(map.ladder?.blend ?? map.ladder?.engineBlend ?? engineEntry?.blend);
+    const engineEventPick = stockEvent(map.ladder?.event ?? engineEntry?.event);
+    const exhaustBlendPick = blendName(map.ladder?.exhaustBlend ?? exhaustEntry?.blend);
+    // Where each pick goes: its source, or the BeamNG install for a stock event no source was named for.
+    const routeOf = (pick, fallback = 'main') => {
+        if (pick.source)
+            return pick.source;
+        if (stockEvent(pick.event) && !stockEvent(pick.event).startsWith('event:/cars/'))
+            return BNG;
+        return fallback;
+    };
+    const requests = {};
+    const want = (id, req) => { (requests[id] ??= []).push(req); };
+    for (const [slot, entry] of Object.entries(slotsMap)) {
+        if (slot === 'engineLadder' || slot === 'exhaustLadder' || entry.notFitted || entry.absent || entry.empty)
+            continue;
+        if (entry.concat?.length) {
+            entry.concat.forEach((piece, i) => want(routeOf(piece, routeOf(entry)), { id: `${slot}#${i}`, slot, sample: piece.sample, field: piece.field, event: stockEvent(piece.event) ?? piece.event, file: piece.file }));
+        }
+        else if (entry.sample || entry.field || entry.event || entry.file) {
+            want(routeOf(entry), { id: slot, slot, sample: entry.sample, field: entry.field, event: stockEvent(entry.event) ?? entry.event, file: entry.file });
+        }
+        else if (entry.source) {
+            want(entry.source, { id: slot, slot });
+        }
+    }
+    if (requests[BNG] && !sources[BNG]) {
+        if (!opts.beamngRoot)
+            throw new Error('--map names BeamNG stock events without a source: pass --beamng-root (or HELIX_BEAMNG_ROOT)');
+        sources[BNG] = { path: (0, node_path_1.resolve)(opts.beamngRoot), sim: 'beamng-base' };
+    }
+    const needed = new Set(['main', ladderSource, ...Object.keys(requests)]);
+    for (const id of needed)
+        if (!sources[id])
+            throw new Error(`--map refers to source "${id}", which its "sources" does not define`);
+    const inventories = {};
+    for (const id of needed) {
+        const src = sources[id];
+        if (src.sim === 'beamng-base' || src.sim === 'recording') {
+            if (id === ladderSource && !(src.sim === 'beamng-base' && engineEventPick))
+                throw new Error(`--map: a ${src.sim} source holds no engine ladder${src.sim === 'beamng-base' ? ' (name the stock motor event with engineLadder.event)' : ''}`);
+            inventories[id] = runInventory(src.path, (0, node_path_1.join)(out, '.staging', id), src.sim, { requests: requests[id] ?? [], traits: {}, modName: src.mod, modUrl: src.modUrl, vgmstream: opts.vgmstream, cacheDir: opts.cacheDir,
+                ...(id === ladderSource ? { engineEvent: engineEventPick, ladderRpms: map.ladder?.rungs, maxRpm: map.ladder?.maxRpm } : {}) }, opts.python);
+            continue;
+        }
+        const options = {
+            vehicle: src.vehicle, config: src.config, modUrl: src.modUrl, modName: src.mod, kind: src.kind, requests: requests[id] ?? [],
+            beamngRoot: opts.beamngRoot, vgmstream: opts.vgmstream, cacheDir: opts.cacheDir,
+            prefer: id === ladderSource ? (map.ladder?.prefer ?? src.prefer ?? opts.prefer ?? 'exterior') : (src.prefer ?? 'exterior'),
+            nativeOnly: id === ladderSource ? (map.ladder?.nativeRungs ?? opts.acNativeRungs ?? false) : false,
+            rpm: id === ladderSource ? map.ladder?.rpm : undefined,
+            engineBlend: id === ladderSource ? engineBlendPick : undefined,
+            engineEvent: id === ladderSource ? engineEventPick : undefined,
+            ladderRpms: id === ladderSource ? map.ladder?.rungs : undefined,
+            maxRpm: id === ladderSource ? map.ladder?.maxRpm : undefined,
+            exhaustBlend: id === ladderSource ? exhaustBlendPick : undefined,
+            cylinders: opts.cylinders ?? map.cylinders,
+            noLadder: id !== ladderSource,
+            // With --beamng-root a BeamNG car's slots include what the game itself plays for it (impacts, tyres ...), for a
+            // routed source as much as for main.
+        };
+        inventories[id] = runInventory(src.path, (0, node_path_1.join)(out, '.staging', id), src.sim ?? 'auto', options, opts.python);
+    }
+    const main = inventories.main;
+    const traits = main.traits ?? {};
+    const notes = [...(inventories[ladderSource].ladderNotes ?? []).map((n) => `ladder: ${n}`)];
+    const warnings = Object.entries(inventories).flatMap(([id, inv]) => (inv.warnings ?? []).map((w) => `${id}: ${w}`));
+    // ---- engine / exhaust ladders ---------------------------------------------------------------------------------------
+    const writer = new Writer(out);
+    const ladders = inventories[ladderSource].ladders;
+    const bankAssets = [];
+    const blends = {};
+    const assetRow = (emitted, role, name) => {
+        const put = writer.put(emitted.wav, wavStem(emitted.wav));
+        return { name: name ?? put.file, file: put.file, path: `audio/${put.file}`, role, mediaType: 'audio/wav', bytes: put.bytes,
+            checksumSha256: put.checksumSha256, cid: `cid:sha256:${put.checksumSha256}`, provenance: emitted.provenance };
+    };
+    // A ladder recorded from an electric motor (an event ladder, or a recorded blend whose source car's powertrain is an
+    // electric motor) has no firing order: its provenance says so, which is how audio-check knows it judges a motor.
+    const ladderIsMotor = (ladder) => Boolean(ladder?.motor || inventories[ladderSource].traits?.electric);
+    const addLadder = (ladder) => {
+        if (!ladder)
+            return undefined;
+        const rows = ladder.rows.map((row) => row.map((rung) => {
+            const asset = assetRow(rung, 'vehicle.audio.bank.sample');
+            if (!bankAssets.some((a) => a.name === asset.name))
+                bankAssets.push(asset);
+            return [String(asset.name), Number(rung.rpm)];
+        }));
+        const provenance = ladderIsMotor(ladder) && isRecord(ladder.provenance) ? { ...ladder.provenance, motor: true } : ladder.provenance;
+        blends[ladder.name] = { eventName: ladder.eventName ?? 'event:>Engine>default', samples: rows, provenance };
+        return ladder.name;
+    };
+    const engineBlend = addLadder(ladders.engine);
+    const exhaustWanted = !(exhaustEntry?.notFitted || exhaustEntry?.absent === audioSlots_1.ABSENT_NOT_FITTED);
+    const exhaustBlend = exhaustWanted && ladders.exhaust && ladders.exhaust.name !== ladders.engine?.name ? addLadder(ladders.exhaust) : undefined;
+    // ---- one-shot slots ---------------------------------------------------------------------------------------------------
+    const composeDir = (0, node_path_1.join)(out, '.staging', 'compose');
+    /** The recording a slot's --map entry asks for (one pick, or several pieces in order), trimmed if asked. */
+    const fromMap = (slot, entry) => {
+        const lookup = (sourceId, id) => inventories[sourceId]?.requested?.[id] ?? { reason: `source ${sourceId} answered nothing for ${id}` };
+        if (entry.concat?.length) {
+            const pieces = [];
+            for (const [i, piece] of entry.concat.entries()) {
+                const got = lookup(routeOf(piece, routeOf(entry)), `${slot}#${i}`);
+                if ('reason' in got)
+                    return { origin: routeOf(entry), reason: `piece ${i + 1}: ${got.reason}` };
+                pieces.push({ emitted: got, repeat: Math.max(1, Math.min(64, Math.round(piece.repeat ?? 1))), trim: piece.trim });
+            }
+            const composed = composeWavs(pieces.map((p) => ({ wav: p.emitted.wav, repeat: p.repeat, trim: p.trim })), composeDir, slot);
+            const first = pieces[0].emitted.provenance;
+            const provenance = {
+                ...first,
+                pieces: pieces.map((p) => ({ ...p.emitted.provenance, ...(p.repeat > 1 ? { repeat: p.repeat } : {}), ...(p.trim ? { trim: p.trim } : {}) })),
+                transforms: [...(Array.isArray(first.transforms) ? first.transforms : []),
+                    { kind: 'concat', detail: `${pieces.length} pieces in order (${pieces.map((p) => `${String(p.emitted.provenance.sample ?? p.emitted.provenance.sourceFile)}${p.repeat > 1 ? ` x${p.repeat}` : ''}`).join(' + ')})`, tool: 'helix audio-import' }],
+            };
+            return { emitted: applyTrim({ wav: composed, provenance }, entry.trim, composeDir, slot), origin: routeOf(entry) };
+        }
+        const got = lookup(routeOf(entry), slot);
+        if ('reason' in got)
+            return { origin: routeOf(entry), reason: got.reason };
+        return { emitted: applyTrim(got, entry.trim, composeDir, slot), origin: routeOf(entry) };
+    };
+    const hasPick = (entry) => Boolean(entry && !entry.notFitted && !entry.absent && !entry.empty
+        && (entry.concat?.length || entry.sample || entry.field || entry.event || entry.file || entry.source));
+    let baseInventory;
+    const emptyNow = () => audioSlots_1.VEHICLE_AUDIO_SLOTS.filter((slot) => slot !== 'engineLadder' && slot !== 'exhaustLadder'
+        && !slotsMap[slot] && !main.slots[slot]);
+    if (opts.beamngRoot && main.sim !== 'beamng' && emptyNow().length) {
+        // A non-BeamNG car (Assetto Corsa) still gets BeamNG's generic stock recordings for what it lacks (doors, tyres,
+        // impacts ...), the sourcing order's second tier.
+        const taken = Object.values(inventories).flatMap((inv) => Object.values(inv.slots).map((s) => String(s.provenance.sample ?? '')));
+        baseInventory = runInventory((0, node_path_1.resolve)(opts.beamngRoot), (0, node_path_1.join)(out, '.staging', 'beamng-base'), 'beamng-base', { slots: emptyNow(), traits, taken, vgmstream: opts.vgmstream, cacheDir: opts.cacheDir }, opts.python);
+    }
+    const decisions = [];
+    const slotRows = [];
+    const shaOfConsumed = new Map();
+    const ladderNote = (ladder) => ladder?.note;
+    for (const slot of audioSlots_1.VEHICLE_AUDIO_SLOTS) {
+        if (slot === 'exhaustLadder' && (exhaustEntry?.notFitted || exhaustEntry?.absent === audioSlots_1.ABSENT_NOT_FITTED)) {
+            const reason = exhaustEntry.notFitted ?? exhaustEntry.reason ?? 'the real car has no exhaust';
+            slotRows.push({ slot, buffers: [], consumed: false, absent: audioSlots_1.ABSENT_NOT_FITTED, reason });
+            decisions.push({ slot, status: 'not-fitted', consumed: false, reason });
+            continue;
+        }
+        if (slot === 'engineLadder' || slot === 'exhaustLadder') {
+            const ladder = slot === 'engineLadder' ? ladders.engine : (exhaustBlend ? ladders.exhaust : null);
+            const blend = slot === 'engineLadder' ? engineBlend : exhaustBlend;
+            if (blend && ladder) {
+                slotRows.push({ slot, buffers: [`blend:${blend}`], consumed: true, note: ladderNote(ladder), provenance: ladder.provenance });
+                decisions.push({ slot, status: 'sourced', consumed: true, source: ladderSource, provenance: ladder.provenance, reason: ladder.note });
+            }
+            else if (slot === 'exhaustLadder' && engineBlend) {
+                const reason = 'the source records engine and exhaust as one combined set (it declares no separate exhaust ladder); it plays on the engine layer';
+                slotRows.push({ slot, buffers: [], consumed: false, absent: audioSlots_1.ABSENT_COMBINED_WITH_ENGINE, reason });
+                decisions.push({ slot, status: 'combined-with-engine', consumed: false, reason });
+            }
+            else {
+                const reason = (inventories[ladderSource].ladderNotes ?? []).join('; ') || 'the source carries no engine recordings';
+                slotRows.push({ slot, buffers: [], consumed: false, reason: `no recorded ${slot === 'engineLadder' ? 'engine' : 'exhaust'} ladder: ${reason}` });
+                decisions.push({ slot, status: 'empty', consumed: false, reason });
+            }
+            continue;
+        }
+        const mapped = slotsMap[slot];
+        if (mapped?.notFitted || mapped?.absent === audioSlots_1.ABSENT_NOT_FITTED) {
+            const reason = mapped.notFitted ?? mapped.reason ?? 'the real car has no such part';
+            slotRows.push({ slot, buffers: [], consumed: false, absent: audioSlots_1.ABSENT_NOT_FITTED, reason });
+            decisions.push({ slot, status: 'not-fitted', consumed: false, reason });
+            continue;
+        }
+        let emitted;
+        let origin = 'main';
+        let pickReason;
+        if (mapped && hasPick(mapped)) {
+            const got = fromMap(slot, mapped);
+            emitted = got.emitted;
+            origin = got.origin;
+            pickReason = got.reason;
+        }
+        else if (!mapped?.empty) {
+            emitted = main.slots[slot] ? applyTrim(main.slots[slot], mapped?.trim, composeDir, slot) : undefined;
+            if (!emitted && baseInventory?.slots[slot]) {
+                emitted = baseInventory.slots[slot];
+                origin = 'beamng-base';
+            }
+        }
+        if (emitted) {
+            const buffer = exports.SLOT_BUFFER[slot] ?? `vehicle.${slot}`;
+            const asset = assetRow(emitted, `vehicle.audio.slot.${slot}`, buffer);
+            const sha = String(asset.checksumSha256);
+            let consumed = !exports.NOT_CONSUMED[slot];
+            let reason = exports.NOT_CONSUMED[slot];
+            const twin = shaOfConsumed.get(sha);
+            if (consumed && twin) {
+                consumed = false;
+                reason = `the same recording as ${twin}: the source has one take for both, and the runtime would play it twice under different roles`;
+            }
+            else if (consumed)
+                shaOfConsumed.set(sha, slot);
+            slotRows.push({ slot, buffers: [buffer], assets: [asset], consumed, ...(reason ? { reason } : {}), provenance: emitted.provenance });
+            decisions.push({ slot, status: 'sourced', consumed, source: origin, file: String(asset.file), provenance: emitted.provenance, reason, alternatives: emitted.alternatives });
+            continue;
+        }
+        if (pickReason) {
+            const reason = `no recording: --map ${slot}: ${pickReason}`;
+            slotRows.push({ slot, buffers: [], consumed: false, reason });
+            decisions.push({ slot, status: 'empty', consumed: false, source: origin, reason });
+            continue;
+        }
+        // Derived and legitimately absent slots.
+        if (slot === 'idle' && ladders.engine) {
+            const row0 = [...(ladders.engine.rows[0] ?? [])].sort((a, b) => Number(a.rpm) - Number(b.rpm));
+            const lowest = row0[0];
+            if (lowest) {
+                const asset = assetRow(lowest, 'vehicle.audio.slot.idle', 'vehicle.idle');
+                const reason = `idle plays from the engine ladder; this is its lowest off-throttle rung (${lowest.rpm} rpm), kept here so the slot names its recording`;
+                slotRows.push({ slot, buffers: ['vehicle.idle'], assets: [asset], consumed: false, reason, provenance: { ...lowest.provenance, role: 'engine-ladder lowest rung' } });
+                decisions.push({ slot, status: 'from-engine-ladder', consumed: false, file: String(asset.file), provenance: lowest.provenance, reason });
+                continue;
+            }
+        }
+        if (slot === 'tyreSqueal' && !mapped?.empty) {
+            // Resolved after tyreScrub (below): the legacy aggregate slot names the scrub recording.
+            slotRows.push({ slot, pending: 'tyreScrub' });
+            decisions.push({ slot, status: 'alias', consumed: false });
+            continue;
+        }
+        const absent = notFittedReason(slot, traits);
+        if (absent) {
+            slotRows.push({ slot, buffers: [], consumed: false, absent: audioSlots_1.ABSENT_NOT_FITTED, reason: absent });
+            decisions.push({ slot, status: 'not-fitted', consumed: false, reason: absent });
+            continue;
+        }
+        const why = mapped?.empty ?? main.reasons?.[slot] ?? baseInventory?.reasons?.[slot]
+            ?? (main.absentReason ?? 'the source has no {slot} sound').replace('{slot}', slot);
+        const reason = `no recording: ${why}${opts.beamngRoot || main.sim === 'beamng' ? '' : ' (pass --beamng-root to take BeamNG\'s stock recording for it)'}`;
+        slotRows.push({ slot, buffers: [], consumed: false, reason });
+        decisions.push({ slot, status: 'empty', consumed: false, reason });
+    }
+    for (const row of slotRows.filter((r) => r.pending === 'tyreScrub')) {
+        const scrub = slotRows.find((r) => r.slot === 'tyreScrub' && Array.isArray(r.assets));
+        const decision = decisions.find((d) => d.slot === row.slot);
+        delete row.pending;
+        if (!scrub) {
+            Object.assign(row, { buffers: [], consumed: false, reason: 'no recording: tyreScrub has none either' });
+            Object.assign(decision, { status: 'empty', reason: row.reason });
+            continue;
+        }
+        const asset = { ...scrub.assets[0], name: 'vehicle.tyre.scrub', role: 'vehicle.audio.slot.tyreSqueal' };
+        const reason = 'legacy aggregate slot: the runtime plays the tyre scrub recording through tyreScrub';
+        Object.assign(row, { buffers: ['vehicle.tyre.scrub'], assets: [asset], consumed: false, reason, provenance: scrub.provenance });
+        Object.assign(decision, { file: String(asset.file), provenance: scrub.provenance, reason });
+    }
+    // ---- the audio block --------------------------------------------------------------------------------------------------
+    // A count the BeamNG importer only defaulted (no layout anywhere in the selected parts) is a guess: ask for it.
+    const derived = inventories[ladderSource].cylinders;
+    const cylinders = opts.cylinders ?? map.cylinders ?? (derived?.state === 'defaulted' ? undefined : derived?.count ?? undefined);
+    // A motor ladder has no firing order: the runtime's playback rate is rpm / rung rpm whatever the count (it cancels).
+    const motor = ladderIsMotor(ladders.engine);
+    if (engineBlend && !motor && !(typeof cylinders === 'number' && cylinders > 0)) {
+        throw new Error(`the recorded engine's cylinder count is unknown (${inventories[ladderSource].cylinders?.detail ?? 'the source does not say'}): pass --cylinders N (or "cylinders" in --map)`);
+    }
+    const name = String(main.source.name ?? (0, node_path_1.basename)(opts.source));
+    const mixOf = (inv) => inv?.mix
+        ? { values: Object.fromEntries(Object.entries(inv.mix).map(([k, v]) => [k, v?.value])), from: Object.fromEntries(Object.entries(inv.mix).map(([k, v]) => [k, v?.from ?? ''])) }
+        : { values: undefined, from: undefined };
+    const mix = resolveMix([
+        { label: '--map', values: map },
+        { label: '--base-package', values: baseAudio },
+        { label: `the ladder source (${ladderSource})`, ...mixOf(inventories[ladderSource]) },
+        { label: 'the main source', ...mixOf(main) },
+    ]);
+    const audio = {
+        bankId: map.bankId ?? `${slug(name)}-${slug(String(ladders.engine?.name ?? 'audio'))}`,
+        ...(cylinders ? { sampleCylinderCount: cylinders } : motor ? { sampleCylinderCount: 1 } : {}),
+        strokes: map.strokes ?? 4,
+        ...(map.crankLayout ? { crankLayout: map.crankLayout } : {}),
+        ...(engineBlend ? { engineBlend } : {}),
+        ...(exhaustBlend ? { exhaustBlend } : {}),
+        ...(engineBlend ? { bank: { blends, assets: bankAssets } } : {}),
+        ...mix.values,
+        slots: slotRows,
+    };
+    const audioJson = (0, node_path_1.join)(out, 'audio.json');
+    const reportJson = (0, node_path_1.join)(out, 'audio-import.json');
+    (0, node_fs_1.writeFileSync)(audioJson, `${JSON.stringify(audio, null, 2)}\n`);
+    const empty = decisions.filter((d) => d.status === 'empty').map((d) => d.slot);
+    const sourceReport = {};
+    for (const [id, inv] of Object.entries(inventories)) {
+        sourceReport[id] = { sim: inv.sim, ...inv.source, traits: inv.traits, cylinders: inv.cylinders, unmapped: inv.unmapped, stockEvents: inv.stockEvents };
+    }
+    if (baseInventory)
+        sourceReport['beamng-base'] = { sim: 'beamng', ...baseInventory.source, stockEvents: baseInventory.stockEvents };
+    const result = { ok: empty.length === 0 && Boolean(engineBlend), out, audioJson, reportJson, audio, slots: decisions, empty, sources: sourceReport, mix: mix.from, notes, warnings };
+    (0, node_fs_1.writeFileSync)(reportJson, `${JSON.stringify({ version: exports.AUDIO_IMPORT_VERSION, ...result, audio: undefined }, null, 2)}\n`);
+    return result;
+}
+/** A slot the real car physically lacks, from what the source says the car is fitted with. */
+function notFittedReason(slot, traits = {}) {
+    if ((slot === 'turboSpool' || slot === 'blowOff') && traits?.induction !== 'turbo') {
+        return traits?.induction === 'supercharger'
+            ? `supercharged, no turbocharger: the car has no ${slot === 'turboSpool' ? 'turbo spool' : 'blow-off valve'}`
+            : `naturally aspirated: the selected parts fit no turbocharger, so the car has no ${slot === 'turboSpool' ? 'turbo spool' : 'blow-off valve'}`;
+    }
+    if (slot === 'reverseBeep')
+        return 'a road car without a reverse warning beeper (the source fits none)';
+    if (slot === 'clutch' && traits?.gearbox && /^(automatic|cvt)$/i.test(traits.gearbox))
+        return `a ${traits.gearbox} gearbox has no clutch to engage`;
+    return undefined;
+}
+function formatAudioImport(result) {
+    const lines = [];
+    for (const [id, src] of Object.entries(result.sources)) {
+        lines.push(`source ${id}: ${String(src.sim)} ${String(src.name ?? '')} ${String(src.path ?? '')}`.trimEnd());
+    }
+    for (const d of result.slots) {
+        const p = d.provenance;
+        const where = p ? [p.kind, p.sim, p.mod, p.sourceFile, p.event, p.sample].filter(Boolean).join(' | ') : '';
+        const mark = d.status === 'empty' ? '✖' : '✔';
+        lines.push(`${mark} ${d.slot.padEnd(17)} ${d.status}${d.consumed ? '' : ' (not consumed)'}${d.file ? `  ${d.file}` : ''}${where ? `  ${where}` : ''}${d.reason && d.status !== 'sourced' ? `  — ${d.reason}` : ''}`);
+    }
+    lines.push(`  mix: ${exports.MIX_FIELDS.map((f) => `${f} ${String(result.audio[f])} (${result.mix[f]})`).join('; ')}`);
+    for (const n of result.notes)
+        lines.push(`  note: ${n}`);
+    for (const w of result.warnings)
+        lines.push(`  ⚠ ${w}`);
+    lines.push(`${result.ok ? '✔' : '✖'} wrote ${result.audioJson} (${result.slots.filter((d) => d.status !== 'empty').length}/${result.slots.length} slots${result.empty.length ? `, EMPTY: ${result.empty.join(', ')}` : ''}); report ${result.reportJson}`);
+    lines.push('  next: merge audio.json into vehicle-package.json "audio" (copy audio/ beside it), then `helix vehicle audio-check <package dir>`');
+    return lines.join('\n');
+}
+//# sourceMappingURL=audioImport.js.map