@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

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

@@ -0,0 +1,287 @@
+"""Tiny, generated stand-ins for simulator sound files (no binaries are committed).
+
+  build_fsb5(samples)                 an FSB5 block of PCM16 samples with names
+  build_ac_bank(path, ...)            an Assetto Corsa style FMOD Studio 1.x bank (FMT 0x50): an engine_ext event whose
+                                      instruments sit on an rpm sheet with auto-pitch references and volume fades, and a
+                                      horn / door timeline event; plus the GUIDs.txt the game ships
+  build_beamng_root(root)             a BeamNG.drive install with content/art_sound.zip (a 2.x strings bank, a metadata
+                                      bank and an assets bank for two stock events) and content/vehicles/common.zip
+  build_beamng_mod(root)              a BeamNG vehicle mod: jbeam (engine naming a stock starter, a soundscape horn slot),
+                                      a .pc, its own sfxBlend2D ladder (one WAV with the mmbng-993 malformed header) and a
+                                      loose door recording
+
+Used by test_sim_audio.py and by the jest specs (``python3 sim_audio_fixtures.py <kind> <dir>``).
+"""
+from __future__ import annotations
+
+import json
+import math
+import struct
+import sys
+import uuid
+import zipfile
+from pathlib import Path
+
+
+def tone(freq: float, seconds: float = 0.5, rate: int = 44100, amp: float = 0.4, channels: int = 1) -> bytes:
+    frames = int(seconds * rate)
+    out = bytearray()
+    for i in range(frames):
+        v = 0.0
+        for h in range(1, 9):
+            v += math.sin(2 * math.pi * freq * h * i / rate) / h
+        s = int(max(-1.0, min(1.0, v * amp * 0.5)) * 32767)
+        out += struct.pack("<h", s) * channels
+    return bytes(out)
+
+
+def wav(pcm: bytes, rate: int = 44100, channels: int = 1, *, malformed: bool = False) -> bytes:
+    align = channels * 2
+    # malformed: the mmbng 993 mod's header (2 channels declared, byteRate/blockAlign of mono)
+    block = 2 if malformed else align
+    return (b"RIFF" + struct.pack("<I", 36 + len(pcm)) + b"WAVE" + b"fmt " +
+            struct.pack("<IHHIIHH", 16, 1, channels, rate, rate * block, block, 16) + b"data" + struct.pack("<I", len(pcm)) + pcm)
+
+
+def chunk(cid: bytes, body: bytes) -> bytes:
+    return cid + struct.pack("<I", len(body)) + body + (b"\0" if len(body) & 1 else b"")
+
+
+def listing(form: bytes, *children: bytes) -> bytes:
+    return chunk(b"LIST", form + b"".join(children))
+
+
+def guid() -> bytes:
+    return uuid.uuid4().bytes_le
+
+
+def build_fsb5(samples: list[tuple[str, bytes, int, int]]) -> bytes:
+    """samples: (name, pcm16 bytes, rate, channels)."""
+    freq_index = {8000: 1, 11000: 2, 11025: 3, 16000: 4, 22050: 5, 24000: 6, 32000: 7, 44100: 8, 48000: 9}
+    headers = b""
+    data = b""
+    for name, pcm, rate, channels in samples:
+        offset = len(data)
+        frames = len(pcm) // (2 * channels)
+        packed = (freq_index[rate] << 1) | ((1 if channels == 2 else 0) << 5) | ((offset // 16) << 6) | (frames << 34)
+        headers += struct.pack("<Q", packed)
+        data += pcm + b"\0" * ((16 - len(pcm) % 16) % 16)
+    names_blob = b""
+    offsets = []
+    base = 4 * len(samples)
+    for name, *_ in samples:
+        offsets.append(base + len(names_blob))
+        names_blob += name.encode() + b"\0"
+    names = struct.pack(f"<{len(samples)}I", *offsets) + names_blob
+    names += b"\0" * ((16 - len(names) % 16) % 16)
+    header = b"FSB5" + struct.pack("<6I", 1, len(samples), len(headers), len(names), len(data), 2)
+    header += b"\0" * (0x3C - len(header))
+    return header + headers + names + data
+
+
+def fev(fmt: int, proj_children: list[bytes], snd: bytes | None = None) -> bytes:
+    body = b"FEV " + chunk(b"FMT ", struct.pack("<II", fmt, 0x46)) + listing(b"PROJ", *proj_children)
+    if snd is not None:
+        body += chunk(b"SND ", b"\0" * 8 + snd)
+    return chunk(b"RIFF", body)
+
+
+# ------------------------------------------------------------------------------------------------
+# Assetto Corsa (FMOD Studio 1.x, FMT 0x50)
+# ------------------------------------------------------------------------------------------------
+
+def _inst_v1(parent: bytes | None, autopitch: float) -> bytes:
+    inst = bytearray(123)
+    struct.pack_into("<f", inst, 16, 0.0)
+    if parent:
+        inst[53:69] = parent
+        struct.pack_into("<f", inst, 69, autopitch)
+    return bytes(inst)
+
+
+def _curve(owner: bytes, points: list[tuple[float, float]]) -> bytes:
+    body = guid() + owner + b"\x05\x00\x10\x00"
+    for x, y in points:
+        body += struct.pack("<ffff", x, y, 0.0, 0.0)
+    return body
+
+
+def build_ac_bank(directory: Path, car: str = "test_car") -> dict:
+    """An AC car folder: <dir>/content/cars/<car>/sfx/<car>.bank + <dir>/content/sfx/GUIDs.txt. Returns GUID facts."""
+    rate = 44100
+    # Engine samples: on-throttle idle (1150), low (2300 native), mid (4600 reference, placed at 5700 by its plateau).
+    samples = [("TST_ex_on_idle", tone(1150 / 15), rate, 1), ("TST_ex_on_low", tone(2300 / 15), rate, 1),
+               ("TST_ex_on_mid", tone(4600 / 15), rate, 1), ("TST_ex_off_low", tone(2300 / 15), rate, 1),
+               ("TST_ex_off_mid", tone(4600 / 15), rate, 1), ("horn", tone(420, 0.4), rate, 1),
+               ("door_open", tone(900, 0.2), rate, 1), ("door_close", tone(700, 0.2), rate, 1)]
+    fsb = build_fsb5(samples)
+    ev_engine, ev_horn, ev_door = guid(), guid(), guid()
+    sheet_rpm, param_rpm, tl_horn, tl_door = guid(), guid(), guid(), guid()
+    wav_ids = [guid() for _ in samples]
+    inst_ids = [guid() for _ in samples]
+    wav_records = [listing(b"WAVS", *[chunk(b"WAV ", w + struct.pack("<HHHIHHH", 0x0C, 0, 0, i, 0, 0, 0)[:14])
+                                      for i, w in enumerate(wav_ids)])]
+    # engine instruments: (index, autopitch, fades as [(x0,y0),(x1,y1)] lists)
+    engine = [(0, 1150.0, [[(1600, 1.0), (2000, 0.0)]]),
+              (1, 2300.0, [[(1600, 0.0), (2000, 1.0)], [(3500, 1.0), (4000, 0.0)]]),
+              (2, 4600.0, [[(4500, 0.0), (5000, 1.0)], [(5600, 1.0), (5800, 0.0)]]),
+              (3, 2300.0, [[(3500, 1.0), (4000, 0.0)]]),
+              (4, 4600.0, [[(3500, 0.0), (4000, 1.0)]])]
+    waits = []
+    ctrls = []
+    curves = []
+    for index, autopitch, fades in engine:
+        waits.append(listing(b"WAIT", chunk(b"WAIB", inst_ids[index] + wav_ids[index]),
+                             chunk(b"INST", _inst_v1(sheet_rpm, autopitch))))
+        for fade in fades:
+            ctrl = guid()
+            curve = _curve(ctrl, fade)
+            ctrls.append(chunk(b"CTRL", ctrl + inst_ids[index] + sheet_rpm + curve[:16] + struct.pack("<I", 4)))
+            curves.append(chunk(b"CURV", curve))
+    for index in (5, 6, 7):
+        waits.append(listing(b"WAIT", chunk(b"WAIB", inst_ids[index] + wav_ids[index]), chunk(b"INST", _inst_v1(None, 0))))
+    proj = [
+        listing(b"EVTS", *[listing(b"EVNT", chunk(b"EVTB", e + b"\0" * 40)) for e in (ev_engine, ev_horn, ev_door)]),
+        listing(b"TLNS", listing(b"TMLN", chunk(b"TLNB", tl_horn + ev_horn + b"\0" * 4 + inst_ids[5])),
+                listing(b"TMLN", chunk(b"TLNB", tl_door + ev_door + b"\0" * 4 + inst_ids[6] + inst_ids[7]))),
+        listing(b"PMLS", listing(b"PMLO", chunk(b"PMLB", sheet_rpm + param_rpm + ev_engine + b"\0" * 8))),
+        listing(b"PRMS", listing(b"PARM", chunk(b"PRMB", param_rpm + b"\0" * 5 + b"\x04\x00" + b"rpms" + struct.pack("<ff", 0, 9000)))),
+        listing(b"CTRS", *ctrls), listing(b"CRVS", *curves), listing(b"WAIS", *waits), *wav_records,
+    ]
+    car_dir = directory / "content" / "cars" / car
+    (car_dir / "sfx").mkdir(parents=True, exist_ok=True)
+    (car_dir / "ui").mkdir(exist_ok=True)
+    (car_dir / "sfx" / f"{car}.bank").write_bytes(fev(0x50, proj, fsb))
+    sfx = directory / "content" / "sfx"
+    sfx.mkdir(parents=True, exist_ok=True)
+    text = lambda g: "{" + str(uuid.UUID(bytes_le=g)) + "}"  # noqa: E731
+    (sfx / "GUIDs.txt").write_text("\n".join([
+        f"{text(ev_engine)} event:/cars/{car}/engine_ext",
+        f"{text(ev_horn)} event:/cars/{car}/horn",
+        f"{text(ev_door)} event:/cars/{car}/door",
+    ]) + "\n")
+    return {"car_dir": str(car_dir), "bank": str(car_dir / "sfx" / f"{car}.bank")}
+
+
+# ------------------------------------------------------------------------------------------------
+# BeamNG (FMOD Studio 2.x, FMT 0x92)
+# ------------------------------------------------------------------------------------------------
+
+def build_strings_bank(paths: dict[str, bytes]) -> bytes:
+    """A 2.x strings bank: a flat radix tree (root -> one leaf node per path)."""
+    items = sorted(paths.items())
+    pool = b""
+    nodes = [struct.pack("<I", 0x00FFFFFF) + struct.pack("<I", 1 | (len(items) << 24))]
+    ends = []
+    for index, (path, _) in enumerate(items):
+        offset = len(pool)
+        pool += path.encode() + b"\0"
+        nodes.append(struct.pack("<I", offset | (ord(path[0]) << 24)) + struct.pack("<I", index))
+        ends.append(index + 1)
+    parents = [0xFFFFFF] + [0] * len(items)
+    u24 = lambda v: struct.pack("<I", v)[:3]  # noqa: E731
+    stdt = struct.pack("<I", 1)
+    stdt += struct.pack("<HH", (len(nodes) << 1) | 1, 8) + b"".join(nodes)
+    stdt += struct.pack("<HH", (len(items) << 1) | 1, 16) + b"".join(g for _, g in items)
+    stdt += struct.pack("<H", len(pool)) + pool
+    stdt += struct.pack("<H", len(ends)) + b"".join(u24(e) for e in ends)
+    stdt += struct.pack("<H", len(parents)) + b"".join(u24(p) for p in parents)
+    return fev(0x92, [chunk(b"STDT", stdt)])
+
+
+def build_beamng_root(root: Path) -> dict:
+    """content/art_sound.zip with two stock events (a starter and a horn) and content/vehicles/common.zip."""
+    rate = 44100
+    events = {"event:/Engine/Starter/test_eng": [("starter_start_test", tone(180, 0.6))],
+              "event:/Vehicle/Electrics/Horns/TEST_HORN": [("horn_start_test", tone(400, 0.1)),
+                                                           ("horn_loop_test", tone(400, 0.6))]}
+    paths = {path: guid() for path in events}
+    meta = []
+    wavs = []
+    fsb_samples = []
+    for path, takes in events.items():
+        timeline = guid()
+        meta.append(listing(b"EVNT", chunk(b"EVTB", paths[path] + b"\0" * 16 + timeline + b"\0" * 32)))
+        meta.append(listing(b"TMLN", chunk(b"TLNB", timeline + paths[path] + b"\0" * 44)))
+        for name, pcm in takes:
+            inst, wave = guid(), guid()
+            inst_body = bytearray(130)
+            inst_body[0:16] = timeline
+            meta.append(listing(b"WAIT", chunk(b"WAIB", inst + wave), chunk(b"INST", bytes(inst_body))))
+            wavs.append(chunk(b"WAV ", wave + struct.pack("<HHH", 0x0C, 0, 0) + struct.pack("<I", len(fsb_samples)) + b"\0" * 4))
+            fsb_samples.append((name, pcm, rate, 1))
+    # An EV motor event: one loop on the timeline, re-pitched by RPM through a pitch automation on its master bus.
+    motor_path = "event:/Engine/Bands/Real/test_motor"
+    paths[motor_path] = guid()
+    timeline, master, sheet, param, ctrl = guid(), guid(), guid(), guid(), guid()
+    meta.append(listing(b"EVNT", chunk(b"EVTB", paths[motor_path] + b"\0" * 16 + timeline + b"\0" * 16 + master + b"\0" * 17 + sheet)))
+    meta.append(listing(b"TMLN", chunk(b"TLNB", timeline + paths[motor_path] + b"\0" * 44)))
+    meta.append(listing(b"PMLO", chunk(b"PMLB", sheet + param + b"\0" * 6)))
+    meta.append(listing(b"PARM", chunk(b"PRMB", param + b"\0" * 8 + b"\x03\x00" + b"RPM" + struct.pack("<ff", 0.0, 50000.0) + b"\0" * 8)))
+    meta.append(chunk(b"CTRL", ctrl + master + ctrl + struct.pack("<I", 1)))
+    meta.append(chunk(b"CURV", guid() + ctrl + b"\x05\x00\x10\x00" + struct.pack("<ffff", 0.0, -1.0, 0, 0) + struct.pack("<ffff", 20000.0, 1.0, 0, 0)))
+    inst, wave = guid(), guid()
+    inst_body = bytearray(130)
+    inst_body[0:16] = timeline
+    meta.append(listing(b"WAIT", chunk(b"WAIB", inst + wave), chunk(b"INST", bytes(inst_body))))
+    wavs.append(chunk(b"WAV ", wave + struct.pack("<HHH", 0x0C, 0, 0) + struct.pack("<I", len(fsb_samples)) + b"\0" * 4))
+    fsb_samples.append(("motor_whine_test", tone(900, 1.0), rate, 1))
+    vehicle_bank = fev(0x92, meta)
+    assets_bank = fev(0x92, [listing(b"WAVS", *wavs)], build_fsb5(fsb_samples))
+    strings = build_strings_bank(paths)
+    content = root / "content"
+    (content / "vehicles").mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(content / "art_sound.zip", "w") as z:
+        z.writestr("art/sound/fmod/desktop/main_preload.strings.bank", strings)
+        z.writestr("art/sound/fmod/desktop/vehicle.bank", vehicle_bank)
+        z.writestr("art/sound/fmod/desktop/vehicle.assets.bank", assets_bank)
+        z.writestr("art/sound/blends/TestMotor.sfxBlend2D.json",
+                   json.dumps({"header": {"version": 1}, "eventName": "event:>Engine>Bands>Real>test_motor", "samples": []}))
+    soundscape = {"soundscape_horn_1": {"information": {"name": "Test horn"}, "slotType": "soundscape_horn",
+                                        "soundscape": [["name", "src"], ["horn", "event:>Vehicle>Electrics>Horns>TEST_HORN"]]}}
+    with zipfile.ZipFile(content / "vehicles" / "common.zip", "w") as z:
+        z.writestr("vehicles/common/sounds/soundscape.jbeam", json.dumps(soundscape))
+    return {"root": str(root)}
+
+
+def build_beamng_mod(root: Path) -> dict:
+    vehicle = root / "vehicles" / "testcar"
+    vehicle.mkdir(parents=True, exist_ok=True)
+    jbeam = {
+        "testcar": {"information": {"name": "Test Car"}, "slotType": "main",
+                    "slots": [["type", "default", "description"], ["testcar_engine", "testcar_engine", "Engine"],
+                              ["soundscape_horn", "soundscape_horn_1", "Horn"]]},
+        "testcar_engine": {"information": {"name": "2.0L I4 Engine"}, "slotType": "testcar_engine",
+                           "mainEngine": {"torque": [["rpm", "torque"], [0, 0], [6000, 300]],
+                                          "soundConfig": "soundConfig", "soundConfigExhaust": "soundConfigExhaust",
+                                          "starterSample": "event:>Engine>Starter>test_eng"},
+                           "soundConfig": {"sampleName": "TST"}, "soundConfigExhaust": {"sampleName": "0"}},
+    }
+    (vehicle / "testcar.jbeam").write_text(json.dumps(jbeam))
+    (vehicle / "testcar.pc").write_text(json.dumps({"format": 2, "model": "testcar", "parts": {}}))
+    blends = root / "art" / "sound" / "blends"
+    engine = root / "art" / "sound" / "engine" / "TST"
+    blends.mkdir(parents=True, exist_ok=True)
+    engine.mkdir(parents=True, exist_ok=True)
+    ladder = [["art/sound/engine/TST/1000.wav", 1000], ["art/sound/engine/TST/3000.wav", 3000]]
+    (blends / "TST.sfxBlend2D.json").write_text(json.dumps({"eventName": "event:>Engine>default", "samples": [ladder, ladder]}))
+    (engine / "1000.wav").write_bytes(wav(tone(1000 / 30, 0.5, channels=2), channels=2, malformed=True))
+    (engine / "3000.wav").write_bytes(wav(tone(3000 / 30, 0.5), channels=1))
+    # A second set the mod ships but no part names (an Automation export's leftover): reachable with --map ladder.blend.
+    alt = root / "art" / "sound" / "engine" / "ALT"
+    alt.mkdir(parents=True, exist_ok=True)
+    (alt / "2000.wav").write_bytes(wav(tone(2000 / 30, 0.5)))
+    (alt / "5000.wav").write_bytes(wav(tone(5000 / 30, 0.5)))
+    alt_ladder = [["art/sound/engine/ALT/2000.wav", 2000], ["art/sound/engine/ALT/5000.wav", 5000]]
+    (blends / "ALT.sfxBlend2D.json").write_text(json.dumps({"eventName": "event:>Engine>default", "samples": [alt_ladder, alt_ladder]}))
+    sounds = vehicle / "sounds"
+    sounds.mkdir(exist_ok=True)
+    (sounds / "door_open.wav").write_bytes(wav(tone(800, 0.2)))
+    return {"root": str(root)}
+
+
+if __name__ == "__main__":
+    kind, target = sys.argv[1], Path(sys.argv[2])
+    target.mkdir(parents=True, exist_ok=True)
+    result = {"ac": build_ac_bank, "beamng-root": build_beamng_root, "beamng-mod": build_beamng_mod}[kind](target)
+    print(json.dumps(result))

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Extract one simulator source's sound set into a staging directory and print its inventory as JSON.
+
+Used by ``helix vehicle audio-import`` (src/vehicle/audioImport.ts), which runs this once per source, then merges the
+sources a ``--map`` names, picks one recording per HELIX slot and writes the package ``audio`` block.
+
+    sim_audio_import.py --source <mod dir | mod .zip | AC car dir | .bank> --staging <dir>
+                        [--sim beamng|ac|auto] [--options <json file>]
+
+Options JSON (all optional): vehicle, config, beamngRoot, vgmstream, modName, modUrl, kind, prefer
+(exterior|interior), nativeOnly, noLadder, cylinders, rpm {sample: rpm}, pick {slot: sample|field|value}.
+Exit 0 with the inventory on stdout; exit 2 with a one-line reason on stderr.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def detect_sim(source: Path) -> str:
+    if source.is_file():
+        suffix = source.suffix.lower()
+        if suffix in (".bank", ".fsb"):
+            return "ac"
+        if suffix == ".zip":
+            return "beamng"
+        raise ValueError(f"{source.name}: expected a mod folder, a .zip, an Assetto Corsa car folder or a .bank")
+    if (source / "vehicles").is_dir():
+        return "beamng"
+    if (source / "sfx").is_dir() or any(source.glob("*.bank")):
+        return "ac"
+    if (source / "ui").is_dir() and (source / "data.acd").exists() is False and not (source / "sfx").exists():
+        raise ValueError(f"{source} looks like an Assetto Corsa car without sfx/ (a DLC car this install does not own)")
+    raise ValueError(f"{source}: cannot tell the simulator (no vehicles/ for BeamNG, no sfx/*.bank for Assetto Corsa); "
+                     "pass --sim")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source", required=True)
+    parser.add_argument("--staging", required=True)
+    parser.add_argument("--sim", default="auto", choices=["auto", "beamng", "ac", "beamng-base", "recording"])
+    parser.add_argument("--options")
+    args = parser.parse_args()
+    options = json.loads(Path(args.options).read_text()) if args.options else {}
+    if not options.get("beamngRoot") and os.environ.get("HELIX_BEAMNG_ROOT"):
+        options["beamngRoot"] = os.environ["HELIX_BEAMNG_ROOT"]
+    source = Path(args.source).expanduser().resolve()
+    staging = Path(args.staging).resolve()
+    staging.mkdir(parents=True, exist_ok=True)
+    try:
+        if not source.exists():
+            raise ValueError(f"{source} does not exist")
+        sim = detect_sim(source) if args.sim == "auto" else args.sim
+        if sim == "beamng-base":
+            # The BeamNG base game's own defaults for the requested slots (source = the BeamNG.drive install).
+            import beamng_stock_events
+            from sim_audio_beamng import base_game_slots, stock_event_to_fmod
+            stock = beamng_stock_events.StockEvents(source, staging / "bng-stock", options.get("vgmstream"),
+                                                    Path(options["cacheDir"]) if options.get("cacheDir") else None)
+            slots, reasons = base_game_slots(stock, list(options.get("slots") or []), options.get("traits") or {},
+                                             set(options.get("taken") or []), options.get("events") or {})
+            from sim_audio_beamng import extract_exact
+            requested = {}
+            for req in options.get("requests") or []:
+                if req.get("event"):
+                    requested[str(req["id"])] = extract_exact(stock, stock_event_to_fmod(str(req["event"])), req.get("slot"), req.get("sample"))
+                else:
+                    filled, failed = base_game_slots(stock, [req.get("slot")], options.get("traits") or {}, set())
+                    requested[str(req["id"])] = filled.get(req.get("slot")) or {"reason": failed.get(req.get("slot"), "no base-game default for this slot")}
+            ladders: dict = {"engine": None, "exhaust": None}
+            ladder_notes: list = []
+            if options.get("engineEvent"):
+                from sim_audio_beamng import event_ladder, motor_rungs
+                event = stock_event_to_fmod(str(options["engineEvent"]))
+                guid = stock.lower.get(event.lower())
+                curve = stock.events[guid].pitch_curve if guid in stock.events else []
+                rpms = [float(r) for r in options.get("ladderRpms") or motor_rungs(float(options.get("maxRpm") or max((x for x, _ in curve), default=8000.0)))]
+                name = event.rsplit("/", 1)[-1].upper().replace("-", "_")
+                engine, reason = event_ladder(stock, event, rpms, staging, name)
+                if engine:
+                    ladders = {"engine": engine, "exhaust": event_ladder(stock, event, rpms, staging, name + "_L2", layer=1)[0]}
+                else:
+                    ladder_notes.append(f"engine: {reason}")
+            inventory = {"requested": requested, "sim": "beamng", "source": {"path": str(source), "name": "BeamNG.drive base game"},
+                         "ladders": ladders, "ladderNotes": ladder_notes, "slots": slots,
+                         "reasons": reasons, "unmapped": [], "warnings": [], "cylinders": None,
+                         "traits": options.get("traits") or {}, "stockEvents": stock.report()}
+            json.dump(inventory, sys.stdout, default=str)
+            return 0
+        if sim == "recording":
+            # Real recordings of the car (field recordings, a manufacturer clip): each request names a file.
+            from sim_audio import normalize_wav, sha256_file, staged_name
+            import shutil
+            requested = {}
+            for req in options.get("requests") or []:
+                path = Path(str(req.get("file") or req.get("sample") or ""))
+                if not path.is_absolute():
+                    path = (source if source.is_dir() else source.parent) / path
+                if not path.is_file():
+                    requested[str(req["id"])] = {"reason": f"no recording at {path}"}
+                    continue
+                out = staging / f"rec-{sha256_file(path)[:16]}.wav"
+                transforms = normalize_wav(path, out)
+                final = staging / staged_name(path.stem, sha256_file(out))
+                if not final.exists():
+                    shutil.copyfile(out, final)
+                requested[str(req["id"])] = {"wav": str(final), "provenance": {
+                    "kind": "recording", "mod": options.get("modName") or path.stem, "sourceFile": path.name,
+                    "sourceSha256": sha256_file(path), "extractor": "helix sim_audio_import (recording)",
+                    **({"modUrl": options["modUrl"]} if options.get("modUrl") else {}),
+                    **({"transforms": transforms} if transforms else {})}}
+            json.dump({"requested": requested, "sim": "recording", "source": {"path": str(source), "name": options.get("modName") or source.name},
+                       "ladders": {"engine": None, "exhaust": None}, "slots": {}, "reasons": {}, "traits": {}}, sys.stdout, default=str)
+            return 0
+        if sim == "ac":
+            from sim_audio_ac import AcInventory
+            inventory = AcInventory(source, staging, options).inventory()
+        else:
+            from sim_audio_beamng import BeamngInventory
+            inventory = BeamngInventory(source, staging, options).inventory()
+    except Exception as error:  # noqa: BLE001 - one line for the CLI
+        print(f"{type(error).__name__}: {error}" if not isinstance(error, ValueError) else str(error), file=sys.stderr)
+        return 2
+    json.dump(inventory, sys.stdout, default=str)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,124 @@
+"""Cylinder-count derivation and the JBeam laxities BeamNG's own reader accepts."""
+from __future__ import annotations
+
+import json
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from beamng_engine import derive_cylinders, layout_cylinders, sound_identifier_cylinders  # noqa: E402
+from beamng_jbeam import normalize_jbeam, parse_jbeam, parse_jbeam_text, parse_jbeam_with_diagnostics  # noqa: E402
+
+FIXTURES = Path(__file__).resolve().parents[3] / "src" / "fixtures" / "beamng-jbeam-laxity"
+
+
+def engine(name: str | None = None, **main: object) -> tuple[str, dict]:
+    body: dict = {"mainEngine": {"torque": [["rpm", "torque"], [0, 0], [3000, 200]], **main}}
+    if name is not None:
+        body["information"] = {"name": name}
+    return ("test_engine", body)
+
+
+class LayoutNames(unittest.TestCase):
+    def test_real_engine_part_names(self) -> None:
+        # Names lifted from the base game and shipped mods.
+        self.assertEqual(layout_cylinders("1.6L F4 Engine"), 4)
+        self.assertEqual(layout_cylinders("3.5L V8 Engine"), 8)
+        self.assertEqual(layout_cylinders("2.0L I4 Turbo"), 4)
+        self.assertEqual(layout_cylinders("3.0L L6"), 6)
+        self.assertEqual(layout_cylinders("3.6L Flat-6"), 6)
+        self.assertEqual(layout_cylinders("4.0 Flat six"), 6)
+        self.assertEqual(layout_cylinders("W12 Twin Turbo"), 12)
+
+    def test_names_without_a_layout_say_nothing(self) -> None:
+        for text in ("Car Engine", "Stock 3.2L", "Stage 2 Performance Long Block", "Version 8", "1.5L 4 cyl"):
+            self.assertIsNone(layout_cylinders(text), text)
+
+    def test_sound_identifiers(self) -> None:
+        self.assertEqual(sound_identifier_cylinders("event:>Engine>Starter>box4_2006_eng"), 4)
+        self.assertEqual(sound_identifier_cylinders("event:>Engine>Starter>v8flat_1986_eng"), 8)
+        self.assertEqual(sound_identifier_cylinders("b4p_1995_02000cc_modified_01_engine"), 4)
+        self.assertEqual(sound_identifier_cylinders("i6_2010_eng"), 6)
+        # An opaque content hash and a plain label carry no layout.
+        self.assertIsNone(sound_identifier_cylinders("4DB80CD3493DEBDB6C4740AD8738A2C9"))
+        self.assertIsNone(sound_identifier_cylinders("forza_355gts"))
+        self.assertIsNone(sound_identifier_cylinders("PSH"))
+        self.assertIsNone(sound_identifier_cylinders("ex_v2_engine"))
+
+
+class Derivation(unittest.TestCase):
+    def test_declared_sound_field_beats_a_conflicting_name(self) -> None:
+        found = derive_cylinders([engine("3.2L V8 Engine")], {"fundamentalFrequencyCylinderCount": 6}, {})
+        self.assertEqual((found["count"], found["state"]), (6, "declared"))
+        self.assertIn("soundConfig.fundamentalFrequencyCylinderCount", found["source"])
+        self.assertTrue(any("says 8" in row for row in found["conflicts"]))
+
+    def test_layout_name_then_sound_name(self) -> None:
+        by_name = derive_cylinders([engine("1.6L F4 Engine", starterSample="event:>Engine>Starter>v8flat_1986_eng")], {}, {})
+        self.assertEqual((by_name["count"], by_name["state"]), (4, "layout-name"))
+        self.assertEqual(len(by_name["conflicts"]), 1)
+        by_sound = derive_cylinders([engine("Car Engine", starterSample="event:>Engine>Starter>box4_2006_eng")], {}, {})
+        self.assertEqual((by_sound["count"], by_sound["state"]), (4, "sound-name"))
+
+    def test_firing_order_is_a_declaration(self) -> None:
+        found = derive_cylinders([engine(firingOrder=[1, 5, 3, 6, 2, 4])], {}, {})
+        self.assertEqual((found["count"], found["state"]), (6, "declared"))
+        bad = derive_cylinders([engine(firingOrder=[1, 1, 3])], {}, {})
+        self.assertEqual(bad["state"], "defaulted")
+
+    def test_default_is_four_and_says_so(self) -> None:
+        found = derive_cylinders([engine("Car Engine")], {"sampleName": "4DB80CD3493DEBDB6C4740AD8738A2C9"}, {})
+        self.assertEqual((found["count"], found["state"]), (4, "defaulted"))
+        self.assertIn("defaulted to 4", found["detail"])
+        self.assertIn("beamngEngine", found["detail"])
+
+    def test_operator_override_wins_and_is_validated(self) -> None:
+        found = derive_cylinders([engine("3.2L V8 Engine")], {}, {}, {"cylinders": 6, "reason": "993 is a flat-six"})
+        self.assertEqual((found["count"], found["state"]), (6, "operator"))
+        self.assertIn("993 is a flat-six", found["detail"])
+        for bad in ({"cylinders": 0}, {"cylinders": 17}, {"cylinders": "6"}, {"cylinders": 5.5}, {}):
+            with self.assertRaises(ValueError):
+                derive_cylinders([engine()], {}, {}, bad)
+
+    def test_only_engine_defining_parts_are_read(self) -> None:
+        overlay = ("ecu", {"information": {"name": "V12 Race ECU"}, "mainEngine": {"revLimiterRPM": 9000}})
+        found = derive_cylinders([overlay, engine("2.0L I4 Turbo")], {}, {})
+        self.assertEqual(found["count"], 4)
+
+
+class JBeamLaxities(unittest.TestCase):
+    def test_stray_closing_braces_after_the_root_load(self) -> None:
+        # The mmbng 993's Porsh_engine.jbeam ends `},\n},\n}`: BeamNG ignores the extra closer.
+        value, diagnostics = parse_jbeam_with_diagnostics(FIXTURES / "stray-closers.jbeam")
+        self.assertEqual(list(value), ["Porsh_engine"])
+        self.assertEqual(value["Porsh_engine"]["information"]["name"], "3.2L V8 Engine")
+        self.assertEqual(diagnostics["strayClosers"], 1)
+        value, diagnostics = parse_jbeam_text('{"a":{"b":1},},}]}')
+        self.assertEqual(value, {"a": {"b": 1}})
+        self.assertEqual(diagnostics["strayClosers"], 3)
+
+    def test_only_closers_may_trail_the_root(self) -> None:
+        for text in ('{"a":1} {"b":2}', '{"a":1} x', '{"a":1}}"junk"', '{"a":1}} 5'):
+            with self.assertRaises(ValueError, msg=text):
+                parse_jbeam_text(text)
+        with self.assertRaises(ValueError):
+            parse_jbeam_text('[1,2]}')  # root must stay an object
+
+    def test_a_comma_run_is_one_separator(self) -> None:
+        # assalto_gts camso_engine.jbeam burnEfficiency table: a lone `,` line after a trailing comma.
+        value = parse_jbeam(FIXTURES / "comma-run.jbeam")
+        table = value["camso_engine"]["mainEngine"]["burnEfficiency"]
+        self.assertEqual(table[-1], [1.0, 0.3])
+        self.assertEqual(len(table), 5)
+        self.assertEqual(json.loads(normalize_jbeam('{"a":[1,,,2,,],,"b":3,}')[0]), {"a": [1, 2], "b": 3})
+
+    def test_existing_forms_are_unchanged(self) -> None:
+        normalized, diagnostics = normalize_jbeam('{/* header\nline */"rows":[,"a" "b",,00,],// tail\n}')
+        self.assertEqual(json.loads(normalized), {"rows": ["a", "b", 0]})
+        self.assertEqual(diagnostics, {"leadingZeroValues": 1})
+
+
+if __name__ == "__main__":
+    unittest.main()