@helix3/helix-cli 0.1.18-helix3.352 → 0.1.18-helix3.353

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.18-helix3.352",
+  "version": "0.1.18-helix3.353",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",

package/plugins/beamng-vehicle/README.md

@@ -65,6 +65,19 @@ Selected tires lower one exact common or vehicle-local leaf per axle. Pressure,
 
 Selected suspension evidence is lowered only from the chosen strut/coilover leaf part on each axle. Matching left/right spring, slow/fast bump, slow/fast rebound, velocity-split, precompression, and bound rows are retained with beam-space frequency and damping-ratio derivations. Structural parent/subframe beams and swaybar construction beams are explicitly excluded by part custody. Selected torsionbar stiffness is retained in `N.m/rad`, but the runtime suspension remains fail-closed: BeamNG element rates need motion-ratio geometry to become HELIX wheel rates, and the current package has one global damping triplet with no axle-specific fast/slow channels. The emitted HELIX suspension therefore remains an explicit fallback and `functionalDomains.suspension` remains false until those exact runtime mappings exist. Raw Lua/controller and other unsupported expressions remain explicit provenance instead of being presented as literal runtime parity. Soft-body deformation, fluids, wear, and detailed damage remain out of scope. Rigid panel poses are semantic on every device, physical bodies begin at `medium`, and detachment remains disabled on every production tier while source break groups are retained as future eligibility. Simulation, authority, package identity, and Build selection are quality-invariant. Bridge currently seals one canonical source GLB and truthfully maps every tier to it; optimized mesh/texture rendition IDs must not be selected until the optimizer has materialized and sealed those artifacts.
 
+## Engine recordings
+
+BeamNG names an engine sound with `soundConfig.sampleName` (and `soundConfigExhaust.sampleName`), which resolves to the mod's `art/sound/blends/<sampleName>.sfxBlend2D.json`. That blend is the mapping from recordings to rpm: `samples` is a list of load rows, each an rpm-ordered ladder of `["art/sound/engine/<set>/<file>.wav", rpm]`. (There is no `.sbeng` format in BeamNG; the blend JSON is the whole definition.) `lower-beamng.py` (via `bin/beamng_audio.py`) reads it and emits, for a mod that ships its own recordings:
+
+- `<out>/audio/<name>.wav` for every recording the selected blend names. A 16-bit PCM WAV at 44.1 or 48 kHz is copied byte for byte. OGG, FLAC, 24-bit or other-rate WAVs are transcoded with `ffmpeg` (`pcm_s16le`, channels kept, one bank sample rate: the most common one among the files); the import is **refused with a clear message when ffmpeg is needed and not installed** (`HELIX_FFMPEG` overrides the lookup). Bare-number file names are prefixed with their folder (`PSH_1768.wav`).
+- `audio.bank.blends.<sampleName>`: the source's own ladders, `[[file, rpm], ...]`, rpm values copied from the blend (sorted ascending; a repeated rpm makes the blend unusable rather than guessed at).
+- `audio.bank.assets[]`: `{ name, file, path: "audio/<name>", role: "vehicle.audio.bank.sample", mediaType: "audio/wav", bytes, checksumSha256, cid }` and **no `url`**. The url is the public address of the sealed object, so `helix vehicle publish` uploads each file (found at `<package JSON dir>/<path>`) and fills it. The engine validator rejects a row with checksum/bytes but no url, so this plugin validates with a `pending-publish://` placeholder and emits the rows untouched; `helix vehicle validate` on an unpublished package reports exactly those url errors.
+- `engineBlend` / `exhaustBlend`, `sampleCylinderCount` from `fundamentalFrequencyCylinderCount` (BeamNG has no field for the recorded engine's cylinder count, so it defaults to 4 and is recorded as `defaulted` provenance when the source omits it; set it by hand for a V6/V8 recording), `strokes: 4`, and `engineLadder` / `exhaustLadder` slots with `buffers: ["blend:<NAME>"]`, `consumed: true`. When the source declines a separate exhaust sample (`sampleName: "0"` or unset, as the 993 does), the one recording serves both ladders. A layer that is stock while the other ships is left out (no `exhaustBlend` naming a blend the bank does not hold) and its slot says why.
+
+When the sampleName has no blend file inside the mod it is a stock BeamNG FMOD event whose recordings live in the game's own banks; nothing can be extracted and nothing is fabricated. Today's behaviour is kept (no `bank`, `engineBlend`/`exhaustBlend` name the event) and the slot reads `consumed: false`, `reason: "source uses BeamNG stock FMOD event <name>; no recording ships in the mod — platform fallback engine"`. A blend that names missing or path-escaping files, or an invalid ladder, is treated the same way with the cause in the reason. Starter, shut-off, horn and the other one-shot slots are not extracted: BeamNG ships those as stock FMOD events, not files.
+
+Packaging copies the WAVs to `assets/audio/` beside `<id>.vehicle-package.json`, re-hashing each against its package row. The Bridge consumes an unpacked mod directory; unzip a mod archive first.
+
 ABS is the first portable controller adapter. Version 1 recognizes only the
 fingerprinted BeamNG 0.39.4 wheel-core shape: one selected `enableABS=true`, one
 unambiguous brake owner per axle, the stock 100 Hz update rate, and equal

package/plugins/beamng-vehicle/bin/beamng-vehicle.mjs

@@ -516,8 +516,57 @@ function confinedNewAsset(assets, file) {
   return path;
 }
 
+// A bank row the importer extracted carries bytes + checksum + cid but no `url`: the url is the public
+// transport address of the sealed object, which only exists after `helix vehicle publish` uploads the
+// file. The engine validator rejects any row with runtime fields and no url, so validate the package
+// with an explicit pending placeholder and leave the emitted rows untouched.
+function withPendingBankUrls(pkg) {
+  const rows = pkg?.audio?.bank?.assets;
+  if (!Array.isArray(rows)) return pkg;
+  return { ...pkg, audio: { ...pkg.audio, bank: { ...pkg.audio.bank, assets: rows.map((row) => (
+    row && row.url === undefined && typeof row.checksumSha256 === 'string'
+      ? { ...row, url: `pending-publish://sha256/${row.checksumSha256}` } : row)) } } };
+}
+
+// Copy the WAVs the importer extracted next to the vehicle package, re-hashing each against the row
+// the (already hash-bound) package declares. The package JSON is written to `assets/`, so a row's
+// `path` ("audio/<name>.wav") resolves relative to it for `helix vehicle publish`.
+function packageAudioSamples(vehiclePackage, importedGlb, assets, outputDir, candidateId) {
+  const rows = vehiclePackage?.audio?.bank?.assets;
+  if (!Array.isArray(rows) || rows.length === 0) return [];
+  const sourceDirectory = join(dirname(importedGlb), 'audio');
+  const destinationDirectory = join(assets, 'audio');
+  if (existsSync(destinationDirectory)) {
+    const info = lstatSync(destinationDirectory);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('BeamNG vehicle packaging audio destination must be a non-symlink directory');
+  } else {
+    mkdirSync(destinationDirectory);
+  }
+  const artifacts = [];
+  for (const row of rows) {
+    const name = row?.name;
+    if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.wav$/.test(name) || row.path !== `audio/${name}`) {
+      throw new Error(`BeamNG vehicle packaging refused a non-portable audio sample row: ${String(name)}`);
+    }
+    const source = join(sourceDirectory, name);
+    if (!existsSync(source) || lstatSync(source).isSymbolicLink() || !lstatSync(source).isFile()) {
+      throw new Error(`BeamNG vehicle packaging cannot find the extracted audio sample ${name} beside the converted GLB`);
+    }
+    const identity = sha256FileSync(source);
+    if (identity.sha256 !== row.checksumSha256 || identity.sizeBytes !== row.bytes) {
+      throw new Error(`BeamNG vehicle packaging audio sample ${name} does not match its package checksum`);
+    }
+    const destination = confinedNewAsset(destinationDirectory, name);
+    copyFileSync(source, destination, constants.COPYFILE_EXCL);
+    artifacts.push({ kind: 'helix.package.asset', path: relative(outputDir, destination),
+      metadata: { role: 'vehicle-audio-bank-sample', vehicle: candidateId, mediaType: 'audio/wav',
+        sha256: identity.sha256, sizeBytes: identity.sizeBytes } });
+  }
+  return artifacts;
+}
+
 function assertValidVehiclePackage(pkg, boundary) {
-  const errors = validateVehiclePackage(pkg).filter((issue) => issue.level === 'error');
+  const errors = validateVehiclePackage(withPendingBankUrls(pkg)).filter((issue) => issue.level === 'error');
   if (errors.length > 0) {
     throw new Error(`${boundary} rejected invalid Vehicle Package v2:\n${errors
       .map((issue) => `- ${issue.path}: ${issue.message}`).join('\n')}`);
@@ -996,6 +1045,8 @@ function lowerFunctionalVehicle({ source, candidate, sourceManifest, conversion,
   const sourcePath = join(outputDir, `.${candidate.id}.lowering-source.json`);
   const geometryPath = join(outputDir, `.${candidate.id}.lowering-geometry.json`);
   const bundlePath = join(outputDir, `${candidate.id}.functional-lowering.json`);
+  const audioDir = join(outputDir, 'audio');
+  rmSync(audioDir, { recursive: true, force: true });
   let lowered;
   let bundle;
   try {
@@ -1005,6 +1056,7 @@ function lowerFunctionalVehicle({ source, candidate, sourceManifest, conversion,
     lowered = spawnSync('python3', [executable,
       '--source-root', source, '--vehicle-root', candidate.root, '--configuration', configuration,
       '--vehicle-source', sourcePath, '--geometry', geometryPath, '--output', bundlePath,
+      '--audio-dir', audioDir,
       '--part-index', selectedPartIndexArtifact.path,
       ...(absControllerReceipt ? ['--abs-controller-receipt', absControllerReceipt] : []),
       ...(commonRoot ? ['--common-root', commonRoot] : []),
@@ -1099,6 +1151,7 @@ function packageVehicleSource(request) {
     artifacts.push({ kind: 'helix.package.asset', path: relative(request.outputDir, path),
       metadata: { role, schemaVersion: value.schemaVersion, vehicle: candidateId } });
   }
+  artifacts.push(...packageAudioSamples(functional.vehiclePackage, input.path, assets, request.outputDir, candidateId));
   return { artifacts };
 }
 
@@ -1195,6 +1248,7 @@ async function main() {
       path: basename(sourceManifestPath), sha256: sourceManifestDigest.sha256 },
     functionalVehicle: { schemaVersion: functionalVehicle.schemaVersion,
       vehiclePackage: functionalVehicle.vehiclePackage.id,
+      audioBankAssets: functionalVehicle.vehiclePackage.audio?.bank?.assets?.length ?? 0,
       explicitSelections: functionalVehicle.coverage.explicitSelections,
       resolvedSelectionPercent: functionalVehicle.coverage.resolvedSelectionPercent },
     qa,

package/plugins/beamng-vehicle/bin/beamng_audio.py

@@ -0,0 +1,370 @@
+"""Extract a BeamNG mod's own engine recordings into HELIX vehicle-audio bank rows.
+
+BeamNG names an engine sound by ``soundConfig.sampleName`` (and ``soundConfigExhaust.sampleName``).
+That name resolves to ``art/sound/blends/<sampleName>.sfxBlend2D.json``. The blend is the whole
+mapping from recordings to rpm::
+
+    { "eventName": "event:>Engine>default",
+      "samples": [ [ ["art/sound/engine/PSH/1768.wav", 1768], ["...", 2238], ... ],     # load row 0
+                   [ ["art/sound/engine/PSH/1768.wav", 1768], ... ] ] }                # load row 1
+
+Each row is an rpm-ordered ladder; the HELIX bank blend keeps the same ``[[file, rpm], ...]`` shape.
+
+A ``sampleName`` with no blend file inside the mod is a stock game event whose recordings live in
+the game's own FMOD banks. Nothing ships in the mod, so nothing can be extracted and nothing is
+fabricated: the caller keeps the platform fallback engine and states that in the slot reason.
+
+Only the mod's real bytes are ever used. A 16-bit PCM WAV is copied verbatim. OGG, FLAC and WAVs
+that are not 16-bit PCM are transcoded with ``ffmpeg`` (``pcm_s16le``, channels preserved); the
+conversion is refused with a clear message when ``ffmpeg`` is not installed.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import struct
+import subprocess
+import tempfile
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from beamng_jbeam import parse_jbeam_text
+
+BLEND_SUFFIX = ".sfxBlend2D.json"
+BLEND_DIRECTORY = ("art", "sound", "blends")
+MAX_BLEND_BYTES = 1024 * 1024
+MAX_SAMPLE_FILES = 400
+MAX_SAMPLE_BYTES = 128 * 1024 * 1024
+MAX_TOTAL_BYTES = 768 * 1024 * 1024
+MAX_WALK_ENTRIES = 200_000
+BANK_RATES = (44100, 48000)
+DEFAULT_RATE = 44100
+ASSET_ROLE = "vehicle.audio.bank.sample"
+TRANSCODE_EXTENSIONS = {".ogg", ".flac", ".mp3", ".opus", ".aif", ".aiff"}
+# BeamNG treats a sampleName it cannot resolve as "no sound for this layer"; modders use "0".
+DISABLED_SAMPLE_NAMES = {"", "0", "none", "null", "false"}
+
+
+class AudioExtractionError(ValueError):
+    """The mod ships audio the importer must not silently drop or guess at (refuse the import)."""
+
+
+class AudioUnavailable(AudioExtractionError):
+    """The mod's own blend is unusable (missing files, malformed ladder, over a limit).
+
+    The importer keeps the platform fallback engine and records this text as the slot reason.
+    """
+
+
+# ---------------------------------------------------------------------------------------------
+# WAV inspection
+# ---------------------------------------------------------------------------------------------
+
+def inspect_wav(path: Path) -> dict[str, int] | None:
+    """Return ``{format, channels, rate, bits}`` for a RIFF/WAVE file, or ``None`` if it is not one.
+
+    ``format`` is the effective format tag: WAVE_FORMAT_EXTENSIBLE is resolved to its sub-format.
+    """
+    try:
+        with path.open("rb") as handle:
+            head = handle.read(12)
+            if len(head) < 12 or head[:4] != b"RIFF" or head[8:12] != b"WAVE":
+                return None
+            while True:
+                chunk = handle.read(8)
+                if len(chunk) < 8:
+                    return None
+                tag, size = chunk[:4], struct.unpack("<I", chunk[4:])[0]
+                if tag == b"fmt ":
+                    body = handle.read(min(size, 40))
+                    if len(body) < 16:
+                        return None
+                    fmt, channels, rate, _byte_rate, _align, bits = struct.unpack("<HHIIHH", body[:16])
+                    if fmt == 0xFFFE and len(body) >= 26:
+                        fmt = struct.unpack("<H", body[24:26])[0]
+                    return {"format": fmt, "channels": channels, "rate": rate, "bits": bits}
+                handle.seek(size + (size & 1), os.SEEK_CUR)
+    except OSError:
+        return None
+
+
+def is_runtime_pcm(info: dict[str, int] | None) -> bool:
+    return bool(info) and info["format"] == 1 and info["bits"] == 16 and info["channels"] in (1, 2)
+
+
+# ---------------------------------------------------------------------------------------------
+# Source resolution
+# ---------------------------------------------------------------------------------------------
+
+def _is_safe_sample_name(name: str) -> bool:
+    return bool(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.\- ]{0,200}", name))
+
+
+def _ci_child(directory: Path, name: str) -> Path | None:
+    """Case-insensitive child lookup (BeamNG runs on Windows, so mods routinely mismatch case)."""
+    exact = directory / name
+    if os.path.lexists(exact):
+        return exact
+    lowered = name.lower()
+    try:
+        for entry in os.scandir(directory):
+            if entry.name.lower() == lowered:
+                return Path(entry.path)
+    except OSError:
+        return None
+    return None
+
+
+def confine(source_root: Path, portable: str) -> Path | None:
+    """Resolve a mod-relative path inside ``source_root`` without following symlinks."""
+    if not isinstance(portable, str):
+        return None
+    portable = portable.replace("\\", "/").lstrip("/") if not re.match(r"^[A-Za-z]:", portable) else ""
+    if not portable:
+        return None
+    current = source_root
+    for piece in portable.split("/"):
+        if piece in ("", ".", ".."):
+            return None
+        found = _ci_child(current, piece)
+        if found is None or found.is_symlink():
+            return None
+        current = found
+    try:
+        current.resolve().relative_to(source_root.resolve())
+    except ValueError:
+        return None
+    return current if current.is_file() else None
+
+
+def find_blend(source_root: Path, sample_name: str) -> Path | None:
+    """The ``<sampleName>.sfxBlend2D.json`` the mod ships, or ``None`` when it is a stock event."""
+    if not _is_safe_sample_name(sample_name):
+        return None
+    wanted = (sample_name + BLEND_SUFFIX).lower()
+    standard = confine(source_root, "/".join((*BLEND_DIRECTORY, sample_name + BLEND_SUFFIX)))
+    if standard is not None:
+        return standard
+    seen = 0
+    for directory, subdirectories, files in os.walk(source_root, followlinks=False):
+        subdirectories[:] = [d for d in subdirectories if not os.path.islink(os.path.join(directory, d))]
+        for name in files:
+            seen += 1
+            if seen > MAX_WALK_ENTRIES:
+                return None
+            if name.lower() == wanted and not os.path.islink(os.path.join(directory, name)):
+                return Path(directory, name)
+    return None
+
+
+def parse_blend(path: Path) -> dict[str, Any]:
+    """Parse a sfxBlend2D file into ``{eventName, ladders: [[[portable, rpm], ...], ...]}``.
+
+    Rpm values come straight from the file. Each ladder is sorted by rpm; a ladder with fewer than
+    two distinct rungs, a non-numeric rpm or a duplicate rpm is refused rather than repaired.
+    """
+    if path.stat().st_size > MAX_BLEND_BYTES:
+        raise AudioUnavailable(f"sound blend {path.name} exceeds {MAX_BLEND_BYTES} bytes")
+    try:
+        body, _ = parse_jbeam_text(path.read_text(errors="ignore"))
+    except (ValueError, json.JSONDecodeError) as error:
+        raise AudioUnavailable(f"sound blend {path.name} is not valid JSON: {error}") from error
+    rows = body.get("samples")
+    if not isinstance(rows, list) or not rows:
+        raise AudioUnavailable(f"sound blend {path.name} has no `samples` ladders")
+    ladders: list[list[list[Any]]] = []
+    for row_index, row in enumerate(rows):
+        if not isinstance(row, list) or not row:
+            raise AudioUnavailable(f"sound blend {path.name} ladder {row_index} is empty")
+        ladder: list[list[Any]] = []
+        for rung in row:
+            if (not isinstance(rung, list) or len(rung) < 2 or not isinstance(rung[0], str) or not rung[0]
+                    or isinstance(rung[1], bool) or not isinstance(rung[1], (int, float)) or rung[1] <= 0):
+                raise AudioUnavailable(
+                    f"sound blend {path.name} ladder {row_index} has a rung that is not [file, rpm]: {rung!r}")
+            rpm = rung[1]
+            ladder.append([rung[0], int(rpm) if float(rpm).is_integer() else float(rpm)])
+        ladder.sort(key=lambda rung: rung[1])
+        rpms = [rung[1] for rung in ladder]
+        if len(set(rpms)) != len(rpms):
+            raise AudioUnavailable(f"sound blend {path.name} ladder {row_index} repeats an rpm value")
+        ladders.append(ladder)
+    event = body.get("eventName")
+    return {"eventName": event if isinstance(event, str) and event else "event:>Engine>default", "ladders": ladders}
+
+
+# ---------------------------------------------------------------------------------------------
+# Transcoding
+# ---------------------------------------------------------------------------------------------
+
+def locate_ffmpeg() -> str | None:
+    explicit = os.environ.get("HELIX_FFMPEG")
+    if explicit:
+        return explicit if os.access(explicit, os.X_OK) else None
+    return shutil.which("ffmpeg")
+
+
+def transcode_to_pcm16(ffmpeg: str, source: Path, target: Path, rate: int | None) -> None:
+    command = [ffmpeg, "-nostdin", "-v", "error", "-y", "-i", str(source), "-map", "0:a:0",
+               "-c:a", "pcm_s16le", "-fflags", "+bitexact", "-flags:a", "+bitexact"]
+    if rate:
+        command += ["-ar", str(rate)]
+    command.append(str(target))
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=180)
+    except subprocess.TimeoutExpired as error:
+        raise AudioExtractionError(f"ffmpeg timed out transcoding {source.name}") from error
+    if result.returncode != 0 or not target.is_file() or target.stat().st_size == 0:
+        raise AudioExtractionError(f"ffmpeg could not transcode {source.name}: {result.stderr.strip()[:300]}")
+
+
+def sha256_bytes(path: Path) -> tuple[str, int]:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+            size += len(chunk)
+    return digest.hexdigest(), size
+
+
+def asset_file_name(source_path: str, taken: dict[str, str], source_digest: str) -> str:
+    """A portable ``<stem>.wav`` name. Bare numbers (``1768.wav``) take their folder as a prefix and a
+    name already used by different bytes gets the content hash appended, so names stay unique."""
+    clean = lambda value: re.sub(r"[^A-Za-z0-9._-]+", "_", value).strip("._-")  # noqa: E731
+    path = Path(source_path.replace("\\", "/"))
+    stem = clean(path.stem) or "sample"
+    if stem.isdigit() and clean(path.parent.name):
+        stem = f"{clean(path.parent.name)}_{stem}"
+    name = f"{stem}.wav"
+    if taken.get(name, source_digest) != source_digest:
+        name = f"{stem}-{source_digest[:8]}.wav"
+    return name
+
+
+# ---------------------------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------------------------
+
+def stock_reason(event: str) -> str:
+    return (f"source uses BeamNG stock FMOD event {event}; no recording ships in the mod "
+            "— platform fallback engine")
+
+
+def resolve_layers(source_root: Path, engine_name: str | None, exhaust_name: str | None) -> dict[str, Any]:
+    """Classify the engine and exhaust layers as shipped-in-the-mod, stock-only, or absent."""
+    layers: dict[str, Any] = {}
+    for layer, name in (("engine", engine_name), ("exhaust", exhaust_name)):
+        clean = name.strip() if isinstance(name, str) else ""
+        if clean.lower() in DISABLED_SAMPLE_NAMES:
+            layers[layer] = {"state": "absent", "name": clean or None}
+            continue
+        blend = find_blend(source_root, clean)
+        layers[layer] = ({"state": "shipped", "name": clean, "blend": blend} if blend is not None
+                         else {"state": "stock", "name": clean})
+    return layers
+
+
+def extract_engine_bank(source_root: Path, layers: dict[str, Any], audio_dir: Path,
+                        ffmpeg: str | None = None) -> dict[str, Any]:
+    """Write the WAVs for every shipped layer into ``audio_dir`` and return the bank description.
+
+    Returns ``{"blends": {NAME: {eventName, samples}}, "assets": [row, ...], "sources": [...],
+    "blendNames": {"engine": NAME | None, "exhaust": NAME | None}}``. Raises ``AudioExtractionError``
+    when the mod ships audio that cannot be turned into a faithful PCM WAV.
+    """
+    source_root = source_root.resolve()
+    shipped: dict[str, dict[str, Any]] = {}
+    for layer, info in layers.items():
+        if info["state"] != "shipped":
+            continue
+        parsed = parse_blend(info["blend"])
+        shipped[info["name"]] = {"parsed": parsed, "blend": info["blend"]}
+
+    # Gather every distinct recording the shipped blends name, in blend then ladder order.
+    resolved: dict[str, Path] = {}
+    for name, entry in shipped.items():
+        missing: list[str] = []
+        for ladder in entry["parsed"]["ladders"]:
+            for portable, _rpm in ladder:
+                if portable in resolved:
+                    continue
+                path = confine(source_root, portable)
+                if path is None:
+                    missing.append(portable)
+                else:
+                    resolved[portable] = path
+        if missing:
+            raise AudioUnavailable(
+                f"sound blend {name} names {len(missing)} recording(s) the mod does not contain, "
+                f"for example {missing[0]}")
+    if len(resolved) > MAX_SAMPLE_FILES:
+        raise AudioUnavailable(f"the mod's engine blends name {len(resolved)} recordings (limit {MAX_SAMPLE_FILES})")
+    total = 0
+    inspected: dict[str, dict[str, int] | None] = {}
+    for portable, path in resolved.items():
+        size = path.stat().st_size
+        if size > MAX_SAMPLE_BYTES:
+            raise AudioUnavailable(f"recording {portable} is {size} bytes (limit {MAX_SAMPLE_BYTES})")
+        total += size
+        inspected[portable] = inspect_wav(path)
+    if total > MAX_TOTAL_BYTES:
+        raise AudioUnavailable(f"the mod's engine recordings total {total} bytes (limit {MAX_TOTAL_BYTES})")
+
+    # One bank sample rate: the most common rate among the recordings, else 44.1 kHz.
+    rates = Counter(info["rate"] for info in inspected.values() if info)
+    bank_rate = next((rate for rate, _ in sorted(rates.items(), key=lambda kv: (-kv[1], kv[0]))
+                      if rate in BANK_RATES), DEFAULT_RATE)
+
+    def needs_transcode(portable: str) -> tuple[bool, int | None]:
+        info = inspected[portable]
+        if info is None or not is_runtime_pcm(info):
+            return True, bank_rate if (info is None or info["rate"] != bank_rate) else None
+        return (info["rate"] != bank_rate), (bank_rate if info["rate"] != bank_rate else None)
+
+    ffmpeg_needed = [p for p in resolved if needs_transcode(p)[0]]
+    if ffmpeg_needed and ffmpeg is None:
+        raise AudioExtractionError(
+            f"{len(ffmpeg_needed)} engine recording(s) (for example {ffmpeg_needed[0]}) are not 16-bit PCM WAV "
+            f"at {BANK_RATES[0]}/{BANK_RATES[1]} Hz and need ffmpeg to convert; install ffmpeg (or set "
+            "HELIX_FFMPEG) and run the import again. The importer never ships OGG/FLAC or fabricates samples.")
+
+    audio_dir.mkdir(parents=True, exist_ok=True)
+    names_by_source: dict[str, str] = {}
+    digest_by_name: dict[str, str] = {}
+    rows: dict[str, dict[str, Any]] = {}
+    sources: list[dict[str, Any]] = []
+    with tempfile.TemporaryDirectory(prefix="beamng-audio-") as scratch:
+        for portable, path in resolved.items():
+            source_digest, _ = sha256_bytes(path)
+            name = asset_file_name(portable, digest_by_name, source_digest)
+            digest_by_name[name] = source_digest
+            names_by_source[portable] = name
+            target = audio_dir / name
+            transcode, rate = needs_transcode(portable)
+            if transcode:
+                staged = Path(scratch) / name
+                transcode_to_pcm16(ffmpeg, path, staged, rate)  # type: ignore[arg-type]
+                shutil.move(str(staged), target)
+            else:
+                shutil.copyfile(path, target)
+            checksum, size = sha256_bytes(target)
+            rows[name] = {"name": name, "file": name, "path": f"audio/{name}", "role": ASSET_ROLE,
+                          "mediaType": "audio/wav", "bytes": size, "checksumSha256": checksum,
+                          "cid": f"cid:sha256:{checksum}"}
+            sources.append({"asset": name, "sourcePath": portable, "sourceSha256": source_digest,
+                            "transcoded": transcode})
+
+    blends: dict[str, dict[str, Any]] = {}
+    for name, entry in shipped.items():
+        blends[name] = {"eventName": entry["parsed"]["eventName"],
+                        "samples": [[[names_by_source[portable], rpm] for portable, rpm in ladder]
+                                    for ladder in entry["parsed"]["ladders"]]}
+    return {"blends": blends, "assets": [rows[name] for name in sorted(rows)], "sources": sources,
+            "sampleRate": bank_rate,
+            "blendNames": {layer: (info["name"] if info["state"] == "shipped" else None)
+                           for layer, info in layers.items()}}

package/plugins/beamng-vehicle/bin/lower-beamng.py

@@ -25,6 +25,8 @@ from beamng_jbeam import (JBeamDocumentCache, MAX_SELECTED_PART_INDEX_BYTES,
                           resolve_part_closure, selected_part_axle)
 from beamng_expression import ExpressionResolution, resolve_beamng_expression
 from beamng_abs import lower_selected_abs
+from beamng_audio import (AudioExtractionError, AudioUnavailable, extract_engine_bank, locate_ffmpeg,
+                          resolve_layers, stock_reason)
 
 SCHEMA = "helix.beamng-functional-lowering/3"
 SOURCE_SCHEMA = "helix.beamng-vehicle-source/1"
@@ -1525,6 +1527,8 @@ def main() -> None:
     parser.add_argument("--part-index")
     parser.add_argument("--abs-controller-receipt")
     parser.add_argument("--common-root", action="append", default=[])
+    parser.add_argument("--audio-dir", help="where the mod's own engine recordings are written as PCM WAV "
+                                           "(default: <output dir>/audio)")
     args = parser.parse_args()
 
     source_root = Path(args.source_root).resolve()
@@ -2045,12 +2049,87 @@ def main() -> None:
         candidate_sample = next((x for x in indexed_values(value_index, "sampleName")
                                  if isinstance(x, str) and "exhaust" in x.lower()), None)
         if candidate_sample: exhaust_sample = candidate_sample
-    cylinders = int(sound.get("fundamentalFrequencyCylinderCount", 4) or 4)
+    declared_cylinders = sound.get("fundamentalFrequencyCylinderCount")
+    cylinders = int(declared_cylinders) if isinstance(declared_cylinders, (int, float)) \
+        and not isinstance(declared_cylinders, bool) and declared_cylinders >= 1 else 4
+    audio_layers = resolve_layers(source_root, engine_sample, exhaust_sample)
+    audio_bank: dict[str, Any] | None = None
+    audio_unavailable: str | None = None
+    if any(layer["state"] == "shipped" for layer in audio_layers.values()):
+        try:
+            audio_bank = extract_engine_bank(source_root, audio_layers,
+                                             Path(args.audio_dir) if args.audio_dir else Path(args.output).parent / "audio",
+                                             locate_ffmpeg())
+        except AudioUnavailable as exc:
+            audio_unavailable = str(exc)
+    engine_sample = engine_sample if isinstance(engine_sample, str) and audio_layers["engine"]["state"] != "absent" else None
+    exhaust_sample = exhaust_sample if isinstance(exhaust_sample, str) and audio_layers["exhaust"]["state"] != "absent" else None
+
+    def layer_reason(layer: str) -> str:
+        state, name = audio_layers[layer]["state"], audio_layers[layer]["name"]
+        if audio_unavailable and state == "shipped":
+            return f"source blend {name} is unusable ({audio_unavailable}); platform fallback engine"
+        if state == "stock":
+            return stock_reason(name)
+        return f"source declares no {layer} sound sample (sampleName {name!r}); platform fallback engine"
+
+    bank_blends = audio_bank["blends"] if audio_bank else {}
+    engine_blend = audio_bank["blendNames"]["engine"] if audio_bank else None
+    exhaust_blend = audio_bank["blendNames"]["exhaust"] if audio_bank else None
+    exhaust_shares_engine = False
+    if audio_bank and engine_blend and audio_layers["exhaust"]["state"] == "absent":
+        # BeamNG mods such as the 993 disable the exhaust layer (sampleName "0") because the single
+        # recording already carries the exhaust; the same set serves both HELIX ladders.
+        exhaust_blend, exhaust_shares_engine = engine_blend, True
+
+    def ladder_note(blend_name: str) -> str:
+        ladders = bank_blends[blend_name]["samples"]
+        rungs = [rung[1] for rung in ladders[0]]
+        return (f"{len(ladders[0])} rungs {min(rungs):g}-{max(rungs):g} rpm from the mod's own recording "
+                f"(sfxBlend2D {blend_name}), {len(ladders)} load row(s).")
+
     audio_slots = []
     for slot_name in AUDIO_SLOTS:
-        sample = engine_sample if slot_name == "engineLadder" else exhaust_sample if slot_name == "exhaustLadder" else None
-        audio_slots.append({"slot": slot_name, "buffers": [sample] if sample else [], "consumed": bool(sample),
-                            **({} if sample else {"reason": "No selected source event was mapped to this HELIX slot."})})
+        row: dict[str, Any] = {"slot": slot_name, "buffers": [], "consumed": False,
+                               "reason": "No selected source event was mapped to this HELIX slot."}
+        if slot_name in ("engineLadder", "exhaustLadder"):
+            layer = "engine" if slot_name == "engineLadder" else "exhaust"
+            blend_name = engine_blend if layer == "engine" else exhaust_blend
+            sample = engine_sample if layer == "engine" else exhaust_sample
+            if blend_name:
+                note = ladder_note(blend_name)
+                if layer == "exhaust" and exhaust_shares_engine:
+                    declared = audio_layers["exhaust"]["name"]
+                    note = (f"The source declares no separate exhaust sample (sampleName {declared!r}); the engine "
+                            "recording is one combined set used on both ladders. " + note) if declared is not None else \
+                           ("The source declares no separate exhaust sample; the engine recording is one combined "
+                            "set used on both ladders. " + note)
+                row = {"slot": slot_name, "buffers": [f"blend:{blend_name}"], "consumed": True, "note": note}
+            else:
+                row = {"slot": slot_name, "buffers": [sample] if sample and not audio_bank else [],
+                       "consumed": False, "reason": layer_reason(layer)}
+        audio_slots.append(row)
+
+    if audio_bank:
+        bank_source = source_label(Path(audio_layers["engine"]["blend"] if audio_layers["engine"]["state"] == "shipped"
+                                        else audio_layers["exhaust"]["blend"]))
+        for layer, info in audio_layers.items():
+            if info["state"] == "shipped":
+                prov(f"audio.bank.blends.{info['name']}", source_label(info["blend"]), "source-literal",
+                     "rpm ladders copied from the mod's own sfxBlend2D file; rpm values are the source's.")
+        for origin in audio_bank["sources"]:
+            prov(f"audio.bank.assets.{origin['asset']}", source_label(source_root / origin["sourcePath"]),
+                 "derived" if origin["transcoded"] else "source-literal",
+                 "Recording shipped in the mod; transcoded to 16-bit PCM WAV." if origin["transcoded"]
+                 else "Recording shipped in the mod, copied byte for byte.")
+        if not isinstance(declared_cylinders, (int, float)):
+            prov("audio.sampleCylinderCount", bank_source, "defaulted",
+                 "BeamNG does not declare how many cylinders the recorded engine had; defaulted to 4. "
+                 "Set audio.sampleCylinderCount to the recorded engine's cylinder count.")
+    elif audio_unavailable or engine_sample or exhaust_sample:
+        prov("audio.bank", "selected soundConfig sampleName", "unsupported",
+             audio_unavailable or "Source uses BeamNG stock FMOD events; no recording ships in the mod, so the "
+             "platform fallback engine plays.")
 
     engine_spec = {"torqueCurve": {"points": torque_curve}, "idleRpm": idle, "limiterRpm": limiter,
                    "revLimiterType": "soft", "inertia": inertia, "friction": friction,
@@ -2144,7 +2223,9 @@ def main() -> None:
                            else sourced(fallback, unit, note="Provisional functional acceptance target; no BeamNG literal supplied.")) | {"tolerance": .35}
                   for name, (raw, fallback, unit) in target_specs.items()},
       "audio": {"bankId": package_id, "sampleCylinderCount": cylinders, "strokes": 4,
-                  **({"engineBlend": engine_sample} if engine_sample else {}), **({"exhaustBlend": exhaust_sample} if exhaust_sample else {}),
+                  **({"engineBlend": engine_blend} if engine_blend else {"engineBlend": engine_sample} if engine_sample and not audio_bank else {}),
+                  **({"exhaustBlend": exhaust_blend} if exhaust_blend else {"exhaustBlend": exhaust_sample} if exhaust_sample and not audio_bank else {}),
+                  **({"bank": {"blends": audio_bank["blends"], "assets": audio_bank["assets"]}} if audio_bank else {}),
                   "slots": audio_slots, "engineGainDb": float(sound.get("mainGain", 0) or 0), "exhaustGainDb": float(exhaust.get("mainGain", 0) or 0),
                   "minLoadMix": float(sound.get("minLoadMix", 0) or 0), "maxLoadMix": float(sound.get("maxLoadMix", 1) or 1), "muffling": float(sound.get("intakeMuffling", 0) or 0)},
       "lights": {"lamps": lamps, "indicatorHz": 1.5, "decelBrakeLightThreshold": 4},

package/plugins/beamng-vehicle/bridge-plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": "helix.bridge-plugin/1",
   "id": "hypersonic.beamng-vehicle",
   "name": "BeamNG Vehicle Importer",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "trust": "local-untrusted",
   "description": "Assess, convert, texture, lower, and acceptance-test a BeamNG vehicle plus its exact configuration before HELIX packaging.",
   "permissions": [