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

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

@@ -0,0 +1,304 @@
+"""Read FMOD FSB5 sample banks (the audio half of an FMOD Studio ``.bank``) and decode subsongs to WAV.
+
+An FMOD Studio bank is a RIFF ``FEV `` file. Its ``SND `` chunk(s) hold one FSB5 block each; an FSB5 block is a
+header, one packed header per sample (rate, channels, length, data offset, optional chunks), a name table and the
+encoded sample data. Assetto Corsa ships one bank per car (``content/cars/<car>/sfx/<car>.bank``, metadata and samples
+in one file); BeamNG ships ``art/sound/fmod/desktop/vehicle.assets.bank`` (three FSB5 blocks, ~9,600 samples).
+
+Decoding:
+  * ``vgmstream-cli`` (``HELIX_VGMSTREAM`` or on PATH) decodes every codec FMOD uses and is preferred;
+  * without it, PCM8/16/24/32/float samples are decoded here byte for byte, and Vorbis samples are decoded with the
+    ``fsb5`` Python package (python-fsb5 + libvorbis) when it is importable;
+  * anything else is refused with an install message. Nothing is ever approximated.
+"""
+from __future__ import annotations
+
+import hashlib
+import io
+import os
+import re
+import shutil
+import struct
+import subprocess
+import tempfile
+import wave
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+FREQUENCIES = {1: 8000, 2: 11000, 3: 11025, 4: 16000, 5: 22050, 6: 24000, 7: 32000, 8: 44100, 9: 48000}
+CODECS = {0: "none", 1: "pcm8", 2: "pcm16", 3: "pcm24", 4: "pcm32", 5: "pcmfloat", 6: "gcadpcm", 7: "imaadpcm",
+          8: "vag", 9: "hevag", 10: "xma", 11: "mpeg", 12: "celt", 13: "at9", 14: "xwma", 15: "vorbis",
+          16: "fadpcm", 17: "opus"}
+PCM_CODECS = {"pcm8", "pcm16", "pcm24", "pcm32", "pcmfloat"}
+MAX_BANK_BYTES = 2 * 1024 * 1024 * 1024
+INSTALL_MESSAGE = (
+    "decoding {codec} FMOD samples needs vgmstream-cli: download a release from "
+    "https://github.com/vgmstream/vgmstream/releases (vgmstream-linux.zip / vgmstream-mac.zip / vgmstream-win64.zip), "
+    "put vgmstream-cli on PATH or set HELIX_VGMSTREAM=/path/to/vgmstream-cli, and run the import again "
+    "(for Vorbis banks `pip install fsb5` with libvorbis also works)")
+
+
+class FsbError(ValueError):
+    """The bank cannot be read, or a sample cannot be decoded faithfully."""
+
+
+@dataclass
+class FsbSample:
+    index: int          # global index across every FSB5 block in the file (vgmstream subsong = index + 1)
+    block: int          # which FSB5 block
+    local_index: int    # index inside the block
+    name: str
+    codec: str
+    rate: int
+    channels: int
+    frames: int
+    data_offset: int    # absolute offset of the encoded data in the file
+    data_size: int
+    loop: tuple[int, int] | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def duration(self) -> float:
+        return self.frames / self.rate if self.rate else 0.0
+
+
+def _riff_snd_offsets(data: bytes) -> list[int]:
+    """Offsets of every FSB5 block inside a RIFF FEV bank (or [0] for a bare .fsb)."""
+    if data[:4] == b"FSB5":
+        return [0]
+    if data[:4] != b"RIFF" or data[8:12] != b"FEV ":
+        found = data.find(b"FSB5")
+        if found < 0:
+            raise FsbError("not an FMOD bank or FSB5 file")
+        return [found]
+    out: list[int] = []
+
+    def walk(offset: int, end: int, depth: int) -> None:
+        while offset + 8 <= end and depth < 8:
+            cid = data[offset:offset + 4]
+            size = struct.unpack_from("<I", data, offset + 4)[0]
+            body = offset + 8
+            if cid in (b"RIFF", b"LIST"):
+                walk(body + 4, min(end, body + size), depth + 1)
+            elif cid == b"SND ":
+                hit = data.find(b"FSB5", body, min(end, body + size, body + 256))
+                if hit >= 0:
+                    out.append(hit)
+            offset = body + size + (size & 1)
+
+    walk(0, len(data), 0)
+    if not out:
+        raise FsbError("the bank holds no FSB5 sample data (a metadata-only bank: its samples live in a .assets.bank)")
+    return out
+
+
+def parse_fsb5(data: bytes, start: int, block: int, first_index: int) -> list[FsbSample]:
+    if data[start:start + 4] != b"FSB5":
+        raise FsbError(f"no FSB5 magic at {start}")
+    version, count, headers_size, names_size, data_size, mode = struct.unpack_from("<6I", data, start + 4)
+    if version not in (0, 1):
+        raise FsbError(f"unsupported FSB5 version {version}")
+    header = 0x3C if version == 1 else 0x40
+    codec = CODECS.get(mode, f"codec{mode}")
+    cursor = start + header
+    raw: list[tuple[int, int, int, int, dict[str, Any], tuple[int, int] | None]] = []
+    for _ in range(count):
+        packed = struct.unpack_from("<Q", data, cursor)[0]
+        cursor += 8
+        more = packed & 1
+        rate = FREQUENCIES.get((packed >> 1) & 0xF, 44100)
+        channels = 2 if (packed >> 5) & 1 else 1
+        offset = ((packed >> 6) & 0x0FFFFFFF) * 16
+        frames = (packed >> 34) & 0x3FFFFFFF
+        extra: dict[str, Any] = {}
+        loop = None
+        while more:
+            chunk = struct.unpack_from("<I", data, cursor)[0]
+            more = chunk & 1
+            size = (chunk >> 1) & 0xFFFFFF
+            kind = (chunk >> 25) & 0x7F
+            body = data[cursor + 4:cursor + 4 + size]
+            if kind == 1 and size >= 1:
+                channels = body[0]
+            elif kind == 2 and size >= 4:
+                rate = struct.unpack_from("<I", body)[0]
+            elif kind == 3 and size >= 8:
+                loop = struct.unpack_from("<II", body)
+            elif kind == 11 and size >= 4:
+                extra["vorbisCrc32"] = struct.unpack_from("<I", body)[0]
+            cursor += 4 + size
+        raw.append((rate, channels, frames, offset, extra, loop))
+    names_at = start + header + headers_size
+    names: list[str] = []
+    for index in range(count):
+        if names_size:
+            relative = struct.unpack_from("<I", data, names_at + 4 * index)[0]
+            end = data.index(b"\0", names_at + relative)
+            names.append(data[names_at + relative:end].decode("utf-8", errors="replace"))
+        else:
+            names.append(f"sample_{index}")
+    data_at = names_at + names_size
+    samples: list[FsbSample] = []
+    for index, (rate, channels, frames, offset, extra, loop) in enumerate(raw):
+        next_offset = raw[index + 1][3] if index + 1 < count else data_size
+        samples.append(FsbSample(first_index + index, block, index, names[index], codec, rate, channels, frames,
+                                 data_at + offset, max(0, next_offset - offset), loop, extra))
+    return samples
+
+
+@dataclass
+class FsbBank:
+    path: Path
+    sha256: str
+    samples: list[FsbSample]
+
+    def by_name(self, name: str) -> list[FsbSample]:
+        return [s for s in self.samples if s.name == name]
+
+
+def read_bank(path: str | Path) -> FsbBank:
+    path = Path(path)
+    size = path.stat().st_size
+    if size > MAX_BANK_BYTES:
+        raise FsbError(f"{path.name} is {size} bytes (limit {MAX_BANK_BYTES})")
+    data = path.read_bytes()
+    samples: list[FsbSample] = []
+    for block, start in enumerate(_riff_snd_offsets(data)):
+        samples.extend(parse_fsb5(data, start, block, len(samples)))
+    return FsbBank(path, hashlib.sha256(data).hexdigest(), samples)
+
+
+# ---------------------------------------------------------------------------------------------
+# Decoding
+# ---------------------------------------------------------------------------------------------
+
+def locate_vgmstream() -> str | None:
+    explicit = os.environ.get("HELIX_VGMSTREAM")
+    if explicit:
+        return explicit if os.access(explicit, os.X_OK) else None
+    return shutil.which("vgmstream-cli") or shutil.which("vgmstream_cli")
+
+
+def vgmstream_version(binary: str) -> str:
+    try:
+        out = subprocess.run([binary, "-V"], capture_output=True, text=True, timeout=30).stdout
+    except (OSError, subprocess.TimeoutExpired):
+        return "unknown"
+    match = re.search(r'"version"\s*:\s*"([^"]+)"', out)
+    return match.group(1) if match else "unknown"
+
+
+def _pcm_to_wav(sample: FsbSample, raw: bytes, target: Path) -> None:
+    width = {"pcm8": 1, "pcm16": 2, "pcm24": 3, "pcm32": 4, "pcmfloat": 4}[sample.codec]
+    frame = width * sample.channels
+    raw = raw[:sample.frames * frame] if sample.frames else raw[:len(raw) - len(raw) % frame]
+    if sample.codec == "pcm16":
+        pcm = raw
+    else:
+        values: list[int] = []
+        for at in range(0, len(raw) - width + 1, width):
+            if sample.codec == "pcm8":
+                v = (raw[at] - 128) << 8
+            elif sample.codec == "pcm24":
+                v = int.from_bytes(raw[at:at + 3], "little", signed=True) >> 8
+            elif sample.codec == "pcm32":
+                v = int.from_bytes(raw[at:at + 4], "little", signed=True) >> 16
+            else:
+                f = struct.unpack_from("<f", raw, at)[0]
+                v = int(max(-1.0, min(1.0, f)) * 32767)
+            values.append(max(-32768, min(32767, v)))
+        pcm = struct.pack(f"<{len(values)}h", *values)
+    with wave.open(str(target), "wb") as out:
+        out.setnchannels(sample.channels)
+        out.setsampwidth(2)
+        out.setframerate(sample.rate)
+        out.writeframes(pcm)
+
+
+def decode_sample(bank: FsbBank, sample: FsbSample, target: Path, vgmstream: str | None = None) -> str:
+    """Decode one sample to a 16-bit PCM WAV at ``target``. Returns the decoder used (for provenance)."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    binary = vgmstream if vgmstream is not None else locate_vgmstream()
+    if binary:
+        try:
+            return _decode_with_vgmstream(binary, bank, sample, target)
+        except FsbError:
+            if sample.codec not in PCM_CODECS:
+                raise
+            # PCM needs no codec: copy the samples ourselves when vgmstream cannot read this container.
+    if sample.codec in PCM_CODECS:
+        with bank.path.open("rb") as handle:
+            handle.seek(sample.data_offset)
+            raw = handle.read(sample.data_size)
+        _pcm_to_wav(sample, raw, target)
+        return f"helix fsb5.py ({sample.codec} copied)"
+    if sample.codec == "vorbis":
+        try:
+            import fsb5 as python_fsb5  # type: ignore[import-not-found]
+        except ImportError as error:
+            raise FsbError(INSTALL_MESSAGE.format(codec="Vorbis")) from error
+        failure = _python_fsb5_decode(python_fsb5, bank, sample, target)
+        if failure:
+            raise FsbError(failure)
+        return "python-fsb5 (libvorbis)"
+    raise FsbError(INSTALL_MESSAGE.format(codec=sample.codec.upper()))
+
+
+def _decode_with_vgmstream(binary: str, bank: FsbBank, sample: FsbSample, target: Path) -> str:
+    # vgmstream numbers subsongs across every FSB5 block of the bank; prove it is the sample we indexed.
+    meta = subprocess.run([binary, "-m", "-s", str(sample.index + 1), str(bank.path)], capture_output=True,
+                          text=True, timeout=120)
+    named = re.search(r"stream name:\s*(.*)", meta.stdout or "")
+    if named and named.group(1).strip() != sample.name:
+        raise FsbError(f"vgmstream subsong {sample.index + 1} of {bank.path.name} is {named.group(1).strip()!r}, "
+                       f"not {sample.name!r}: the bank's subsong numbering differs from its FSB5 order")
+    with tempfile.TemporaryDirectory(prefix="helix-fsb-") as scratch:
+        staged = Path(scratch) / "out.wav"
+        command = [binary, "-i", "-W", "1", "-s", str(sample.index + 1), "-o", str(staged), str(bank.path)]
+        result = subprocess.run(command, capture_output=True, text=True, timeout=600)
+        if result.returncode != 0 or not staged.is_file() or staged.stat().st_size <= 44:
+            raise FsbError(f"vgmstream could not decode subsong {sample.index + 1} ({sample.name}) of "
+                           f"{bank.path.name}: {(result.stderr or result.stdout).strip()[:300]}")
+        shutil.move(str(staged), target)
+    return f"vgmstream-cli {vgmstream_version(binary)}"
+
+
+def _python_fsb5_decode(module: Any, bank: FsbBank, sample: FsbSample, target: Path) -> str | None:
+    data = bank.path.read_bytes()
+    starts = _riff_snd_offsets(data)
+    start = starts[sample.block]
+    end = starts[sample.block + 1] if sample.block + 1 < len(starts) else len(data)
+    try:
+        fsb = module.FSB5(data[start:end])
+        decoded = fsb.rebuild_sample(fsb.samples[sample.local_index])
+    except Exception as error:  # noqa: BLE001 - third-party decoder failure is reported verbatim
+        return f"python-fsb5 could not decode {sample.name}: {error}"
+    # python-fsb5 returns an OGG for Vorbis; turn it into PCM with ffmpeg so nothing downstream sees OGG.
+    ffmpeg = os.environ.get("HELIX_FFMPEG") or shutil.which("ffmpeg")
+    if not ffmpeg:
+        return "python-fsb5 decoded an OGG but ffmpeg is needed to write PCM; install ffmpeg or vgmstream-cli"
+    with tempfile.TemporaryDirectory(prefix="helix-fsb-") as scratch:
+        ogg = Path(scratch) / "s.ogg"
+        ogg.write_bytes(decoded)
+        result = subprocess.run([ffmpeg, "-nostdin", "-v", "error", "-y", "-i", str(ogg), "-c:a", "pcm_s16le",
+                                 str(target)], capture_output=True, text=True, timeout=300)
+        if result.returncode != 0:
+            return f"ffmpeg could not convert {sample.name}: {result.stderr.strip()[:200]}"
+    return None
+
+
+def describe(bank: FsbBank) -> list[dict[str, Any]]:
+    return [{"index": s.index, "name": s.name, "codec": s.codec, "rate": s.rate, "channels": s.channels,
+             "frames": s.frames, "durationS": round(s.duration, 3)} for s in bank.samples]
+
+
+def wav_bytes_pcm16(samples: list[int], rate: int, channels: int = 1) -> bytes:
+    """A tiny PCM16 WAV in memory (used by tests to build fixtures)."""
+    buffer = io.BytesIO()
+    with wave.open(buffer, "wb") as out:
+        out.setnchannels(channels)
+        out.setsampwidth(2)
+        out.setframerate(rate)
+        out.writeframes(struct.pack(f"<{len(samples)}h", *samples))
+    return buffer.getvalue()

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

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { createBeamngCommonDependencyReceipt } from '../lib/common-dependency.mjs';
+
+const root = process.argv[2];
+if (!root) {
+  process.stderr.write('usage: index-beamng-common.mjs <base-game-root-or-vehicles/common>\n');
+  process.exitCode = 64;
+} else {
+  try {
+    process.stdout.write(`${JSON.stringify(createBeamngCommonDependencyReceipt(root), null, 2)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Create the exact selected BeamNG part/body index without requiring Blender."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from beamng_jbeam import (JBeamDocumentCache, build_part_catalog, build_selected_part_index,
+                          preselect_configuration, resolve_part_closure, selected_part_summary,
+                          write_bound_selected_part_index)
+
+
+def choose_configuration(vehicle_root: Path, candidate: str, hint: str | None) -> Path:
+    selected = preselect_configuration(vehicle_root, [candidate], hint)
+    if selected is not None:
+        return selected
+    raise ValueError("source GLB import requires an unambiguous selected .pc configuration or configuration hint")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source-root", required=True)
+    parser.add_argument("--vehicle-root", required=True)
+    parser.add_argument("--candidate", required=True)
+    parser.add_argument("--configuration-hint")
+    parser.add_argument("--configuration")
+    parser.add_argument("--common-root", action="append", default=[])
+    parser.add_argument("--bridge-plan-key", required=True)
+    parser.add_argument("--source-sha", required=True)
+    parser.add_argument("--common-closure")
+    parser.add_argument("--output", required=True)
+    args = parser.parse_args()
+
+    source_root = Path(args.source_root).resolve()
+    vehicle_root = Path(args.vehicle_root).resolve()
+    dependency_roots = [Path(value).resolve() for value in args.common_root]
+    requested_configuration = Path(args.configuration) if args.configuration else \
+        choose_configuration(vehicle_root, args.candidate, args.configuration_hint)
+    if requested_configuration.is_symlink():
+        raise ValueError("selected configuration must not be a symlink")
+    configuration_path = requested_configuration.resolve()
+    try:
+        configuration_path.relative_to(vehicle_root)
+    except ValueError as error:
+        raise ValueError("selected configuration escapes vehicle root") from error
+    cache = JBeamDocumentCache(source_root, dependency_roots)
+    ranked_roots = [(vehicle_root, 0), (source_root / "vehicles" / "common", 1),
+                    *((root / "vehicles" / "common", 2) for root in dependency_roots)]
+    admitted = [(root, rank) for root, rank in ranked_roots if root.is_dir()]
+    catalog, failures = build_part_catalog(
+        [root for root, _ in admitted], cache, [rank for _, rank in admitted])
+    configuration = cache.load(configuration_path)
+    if configuration.get("format") != 2 or not isinstance(configuration.get("parts"), dict):
+        raise ValueError("selected BeamNG configuration must be format 2 with a parts object")
+    main_part = configuration.get("mainPartName") or configuration.get("model") or args.candidate
+    closure = resolve_part_closure(catalog, configuration["parts"], main_part)
+    index = build_selected_part_index(args.candidate, configuration_path, closure, cache, catalog)
+    index["parseFailures"] = failures[:20]
+    index["parseCounts"] = {f"{cache.receipt(path)['root']}:{cache.receipt(path)['path']}": count
+                            for path, count in sorted(cache.parse_counts.items(), key=lambda row: str(row[0]))}
+    receipt = write_bound_selected_part_index(index, args.output, args.bridge_plan_key,
+                                              args.source_sha, args.common_closure)
+    print(json.dumps(selected_part_summary(index, receipt), sort_keys=True,
+                     separators=(",", ":"), ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()