@hypersoniclabs/helix-mcp 0.2.4 → 0.2.12

package/skills/helix-vehicles/references/audio.md

@@ -0,0 +1,580 @@
+# Vehicle audio
+
+The contract is in section 10 of `read_doc({ name: "vehicles" })`. This reference covers how to
+fill it.
+
+## The hard rule (it overrides every older note)
+
+**Never generate or synthesise a vehicle sound.** Not spectral resynthesis, not an oscillator or
+physical model, not `generate_audio` (not even for a one-shot), not the engine's built-in
+synthesised or generated defaults, and not for a slot no source provides. **Always source real
+recorded sound, from BeamNG mods as much as possible, and a car ships a sourced recording for
+EVERY runtime slot** (the full table is in "Every slot, every car", below). `check_vehicle_audio`
+and `publish_vehicle` refuse audio that is synthesised or generated (`AUDIO_SYNTHESISED`), fail a
+car with no sourced engine audio (`AUDIO_ENGINE_UNSOURCED`), and fail **any empty slot and any
+slot that would fall back to a platform default** (`AUDIO_SLOT_UNSOURCED`). The only permitted empty slot is a
+component the real car physically lacks (see "The only empty slot"); nothing is ever filled with a
+synthesised stand-in or with another car's sound under this car's label.
+
+## Step one, whatever the mesh source
+
+The mesh may come from anywhere (a BeamNG mod, a downloaded model, a scan). The audio does not
+follow it. **Find the most accurate simulator mod of that exact car and extract its audio**:
+
+1. **BeamNG first** (the mod of that exact car; its `art/sound` blends, FMOD events and the
+   `soundscape`). Then, where theirs is more accurate for this car: **Assetto Corsa / ACC**
+   (`content/cars/<car>/sfx/<car>.bank` and its `GUIDs.txt`), **rFactor 2**, **Automobilista 2**.
+2. Extract with the bundled CLI:
+
+   ```
+   import_vehicle_audio({ source: "/abs/mod-or-car-dir-or.zip-or.bank", out: "/abs/car", sim: "beamng",
+                          vehicle: "<beamng vehicle id>", config: "<file.pc>", beamngRoot: "<BeamNG.drive dir>",
+                          cylinders: 8, modUrl: "https://…", basePackage: "/abs/car/vehicle-package.json" })
+   # the same call from a shell:
+   helix vehicle audio-import <mod dir | mod .zip | AC car dir | .bank> --out <dir> [--sim beamng|ac|auto] [--vehicle <id>]
+     [--config <file.pc>] [--map <slot-map.json>] [--beamng-root <BeamNG.drive>] [--cylinders N]
+     [--prefer exterior|interior] [--ac-native-rungs] [--mod-url <url>] [--base-package <pkg>] [--json]
+   ```
+
+   It writes `<out>/audio/*.wav` (16-bit PCM), `<out>/audio.json` (the package `audio` block with
+   **all 31 slots**: `bankId`, `sampleCylinderCount`, `strokes`, `engineBlend`, `exhaustBlend?`,
+   `bank`, `slots`; copy `audio/` beside `vehicle-package.json` and drop the block in) and
+   `<out>/audio-import.json` (the report: every slot's decision, source, alternatives and reason,
+   the unmapped source sounds, the stock events extracted). **Every consumed slot, slot asset, bank
+   sample and blend carries a `provenance`** (see "Provenance", below), inline, and it survives
+   publish.
+   - Options in short: `config` (the car configuration, whose `soundConfig` is wanted), `vehicle`,
+     `beamngRoot` (the BeamNG.drive install, so stock events and base-game defaults resolve),
+     `cylinders` (the RECORDED engine's count; **required for an Assetto Corsa car and for a
+     BeamNG mod whose count would only be a guess**), `prefer`, `acNativeRungs`, `modUrl`,
+     `basePackage` (re-importing a published car: keep its current mix). Every option, the decode
+     tools and the mix fields are in `read_skill({ name: "helix-vehicles", reference: "audio-import" })`.
+   - `map` builds one car from several sources ("`--map`", below).
+3. Map every extracted sound to the HELIX slots (next section) and run
+   `check_vehicle_audio({ target: <dir> })`.
+
+If the mesh came from a BeamNG mod, `bridge_import` already extracts that mod's own engine
+ladders. Treat that as the first candidate, not the answer: you still compare it with other
+candidates (next section), and you still run `import_vehicle_audio` for every slot the bridge did
+not fill and to stamp provenance.
+
+## Which mod is "most accurate"? Measure it, do not trust the mod's reputation
+
+Collect **at least two candidates** where they exist (several BeamNG mods of the car, an Assetto
+Corsa version, a stock BeamNG engine blend of the same engine), and **two or three real recordings
+of the car** (steady idle, a steady high-rpm hold or a pull, the rev limiter, a cold start; onboard
+or close exterior; fetch with `yt-dlp -x --audio-format wav <url>` and cut 10-30 s with
+`ffmpeg -ss 12 -t 20 -i in.wav -ac 1 -ar 44100 -c:a pcm_s16le clip.wav`). Then measure the same
+five things on a candidate's rungs and on the real clips, with the same script, and read them side
+by side:
+
+| Measure | What to compare | Candidate is accurate when |
+| --- | --- | --- |
+| **Firing-fundamental pitch track vs rpm** | each rung's f0 against its rpm label, and the real clips' f0 against the rpm they were at (`f0 = rpm x C / 120` even-firing; flat-plane V8 `rpm/15`; cross-plane V8 `rpm/60`) | every rung within 10 % of its label's pitch, f0 rising monotonically with rpm, and the idle and redline f0 matching the real car's idle and limiter rpm |
+| **Spectral centroid** | idle rung and top rung against the real idle clip and the real high-rpm clip | within 30 % of the real car at idle and at the top, and rising with rpm |
+| **Roughness / harmonic balance** | 8-60 Hz firing-modulation depth, and which orders carry the energy (a spectrogram of both) | roughness within x2 of the real car, the same dominant orders |
+| **Idle character** | idle rpm, lope, and cylinder-to-cylinder unevenness (the dominant envelope-modulation frequency at idle) | same idle rpm and the same lope as the real idle |
+| **Limiter cadence** | cuts per second when the car sits on its limiter (the dominant envelope-modulation frequency of the limiter clip) | within 25 % of the real car's cadence at the same limiter rpm |
+
+Field recordings of one car differ by x2-4 between takes (microphone distance, wind, EQ), so use
+the **median of several clips** and read a near miss as "listen and look at both spectrograms",
+not as proof. A mod that wins on pitch and loses on timbre, or the reverse, is not accurate: pick
+the candidate with the most measures inside tolerance, and write the measurements for every
+candidate into your ledger. Then **listen** to the winner beside a real clip.
+
+The measuring script (numpy + scipy; `ffmpeg` on the PATH for mp3/m4a input). It searches for the
+firing fundamental only inside the rpm range you give it, so it cannot latch onto a sub-harmonic:
+
+```python
+#!/usr/bin/env python3
+# measure-engine.py <clip> --cyl 8 [--strokes 4] [--layout flat|cross] [--rpm 600 9000]
+import argparse, subprocess, numpy as np
+from scipy.io import wavfile
+ap = argparse.ArgumentParser(); ap.add_argument('clip'); ap.add_argument('--cyl', type=int, required=True)
+ap.add_argument('--strokes', type=int, default=4); ap.add_argument('--layout', default='flat')
+ap.add_argument('--rpm', type=float, nargs=2, default=[500, 9000]); a = ap.parse_args()
+wav = a.clip
+if not wav.lower().endswith('.wav'):
+    wav = '/tmp/_measure.wav'; subprocess.run(['ffmpeg', '-y', '-v', 'error', '-i', a.clip, '-ac', '1', '-ar', '44100', wav], check=True)
+sr, x = wavfile.read(wav); x = x.astype(np.float64)
+if x.ndim > 1: x = x.mean(1)
+x /= (np.abs(x).max() or 1)
+orders = 1.0 if a.layout == 'cross' else (a.cyl / 2 if a.strokes == 4 else a.cyl)  # f0 = rpm/60 x orders
+N = int(0.372 * sr); fr = np.fft.rfftfreq(N, 1 / sr)
+cand = np.arange(a.rpm[0] / 60 * orders * 0.9, a.rpm[1] / 60 * orders * 1.1, 0.5)
+print('t_s    f0_Hz   rpm  centroid_Hz')
+for s in range(0, len(x) - N, int(0.25 * sr)):
+    sp = np.log1p(np.abs(np.fft.rfft(x[s:s + N] * np.hanning(N), n=2 * N)) * 50); df = sr / (2 * N)
+    score = [sum(sp[max(int(round(k * f / df)) - 1, 0):int(round(k * f / df)) + 2].max() / k ** 0.3
+                 for k in range(1, 7) if k * f / df < len(sp) - 2) for f in cand]
+    f0 = cand[int(np.argmax(score))]; mag = np.abs(np.fft.rfft(x[s:s + N] * np.hanning(N)))
+    print(f'{s / sr:5.1f} {f0:8.1f} {f0 * 60 / orders:6.0f} {(mag * fr).sum() / (mag.sum() + 1e-9):8.0f}')
+env = np.abs(x); e = np.abs(np.fft.rfft(env - env.mean())); ef = np.fft.rfftfreq(len(env), 1 / sr)
+b = (ef >= 8) & (ef <= 60)
+print('roughness (8-60 Hz envelope modulation / mean level): %.4f' % (np.sqrt((e[b] ** 2).sum()) / (len(env) * env.mean() + 1e-9)))
+c = (ef >= 2) & (ef <= 40)
+print('dominant envelope modulation: %.1f Hz  (idle lope, or limiter cut cadence on a limiter clip)' % ef[c][np.argmax(e[c])])
+```
+
+Control: a real F40 idle clip reads f0 about 64 Hz = 960 rpm (V8 flat-plane, `--cyl 8 --rpm 600 8000`),
+centroid about 1.1 kHz, roughness about 0.15. Run it the same way on a candidate's idle rung.
+
+**Never choose by reputation, download count or file size, and never keep a mod you did not
+measure.** A mod can ship a lovely 1,000 rpm loop and a top rung that is two octaves off.
+
+## Every slot, every car
+
+The engine defines **31 audio slots** (`VehicleAudioSlot` in the vehicle package format). A car
+ships **a sourced recording for every one**, each with its `provenance`. `consumed` says whether
+the runtime plays it today; it never says whether the sound is needed. A slot the runtime does not
+play (today `idle`, which the runtime idles on the ladder for, `transmissionWhine`, which it plays
+only with a declared native pitch, and `intake`, for which it has no layer) still carries its
+sourced recording, unconsumed, with the reason.
+
+Take each from, in order: **the car's own BeamNG mod; the BeamNG base game** (stock FMOD events
+in `content/art_sound.zip` `art/sound/fmod/desktop/vehicle.bank` and `vehicle_preload.bank` (with
+their `.assets` / `.streams` banks), `content/vehicles/common.zip` `vehicles/common/sounds/` (for
+example `turbo_01.ogg`, `turbo_03.ogg`, `turbo_whistle.ogg`, `turbo_bov.ogg`, `V8_default.ogg`) and
+its `soundscape.jbeam`, and the stock blends in `content/audio.zip`); **Assetto Corsa / ACC** car
+banks (`content/cars/<car>/sfx/<car>.bank`). List a bank's events first (`vgmstream-cli -m`, or the import's own
+listing where it prints one) and pick by role. The column below says where each slot
+usually comes from.
+
+| Slot | What it is | Where it usually comes from |
+| --- | --- | --- |
+| `engineLadder` | Engine-bay rpm ladder; row 0 off-throttle/low load, row 1 on-throttle | The car's BeamNG mod blend (`art/sound/blends/*.sfxBlend2D.json` + `art/sound/engine/<name>/NNN_RRRRR.flac`); AC `engine` event. **Separate from the exhaust blend.** |
+| `exhaustLadder` | Tailpipe rpm ladder, load rows as above | The mod's exhaust blend (`soundConfigExhaust.sampleName`). A mod with ONE combined recording (the mmbng 993 sets the exhaust `sampleName` to `"0"`) omits `exhaustBlend` and declares this slot `absent: "combined-with-engine"`; AC has one combined `engine_ext` set |
+| `idle` | Steady idle loop | The mod's idle loop, else the ladder's bottom rungs from the same source |
+| `startup` | Starter crank and catch | The mod's starter event; the base game's starter events in `vehicle.bank`; AC engine-start event |
+| `shutdown` | Key-off | The mod's shutdown event; the base game's engine-off event |
+| `shiftUp`, `shiftDown` | Gear change thump/clunk | The mod's shift events; the base game's shift events; AC gearbox events |
+| `clutch` | Pedal click / engagement | The mod's clutch event; the base game's clutch event; AC clutch event |
+| `transmissionWhine` | Gearbox/diff whine loop on road speed | The mod's gearbox whine; the base game's gearbox/diff loops; AC transmission event |
+| `turboSpool` | Turbo spool loop on shaft rpm | The mod's turbo events; base `vehicles/common/sounds/turbo_01.ogg`, `turbo_03.ogg`, `turbo_whistle.ogg`; AC turbo event |
+| `blowOff` | Blow-off / wastegate dump | The mod's blow-off; base `vehicles/common/sounds/turbo_bov.ogg`; AC blow-off event |
+| `intake` | Induction noise | The mod's intake event; the base game's intake event; AC intake event |
+| `revLimiter` | One short fuel-cut crack, retriggered at the limiter | The mod's limiter event; the base game's limiter / misfire events |
+| `backfire` | Overrun pop / bang | The mod's backfire; the base game's backfire events; AC backfire event |
+| `suspension` | Bump / suspension knock | The base game's suspension events; the mod's own |
+| `impactLight`, `impactMedium`, `impactHeavy` | Collision thumps by severity | The base game's collision events (`vehicle.bank`); the mod's own |
+| `tyreSqueal` | Tyre squeal on slip (the aggregate / brakes-and-skid squeal) | The base game's tyre/skid events; AC skid event |
+| `tyreScrub` | Slip loop (lateral scrub) | The base game's tyre-slip events; AC skid event |
+| `tyreSpin` | Wheelspin loop | The base game's wheelspin / tyre-spin events |
+| `tyreRollSlow`, `tyreRollFast` | Rolling noise, crossfaded by speed | The base game's tyre-roll / road-noise events; AC tyre events |
+| `indicatorTick` | Indicator relay click | The mod's indicator event; the base game's indicator event |
+| `skid` | Skid onset | The base game's skid events; AC skid event |
+| `brakeSqueal` | Light-braking squeal | The base game's brake events; AC brake event |
+| `handbrake` | Handbrake ratchet / pull | The base game's handbrake event; the mod's own |
+| `reverseBeep` | Reverse warning | The mod's reverse beep (trucks, vans); the base game's reverse-warning event. A car with none is the only case under "The only empty slot" |
+| `horn` | The car's horn; plays when the specialty declares a horn action | The car's own horn event; the base game's horn events only when the mod has none of its own |
+| `doorOpen`, `doorClose` | Door open / close | The mod's door events; the base game's door events |
+
+`import_vehicle_audio` resolves the stock banks and blends when you pass `beamngRoot`. **Row 0 / row 1** of each ladder are the load axis.
+**Doors are required** (`doorOpen`, `doorClose`): a sourced recording each, from the mod's door
+couplers or the base game's door latches; the engine is wiring the door edge. **There is no bonnet,
+boot or engine-cover slot yet** (the importer reports a mod's bonnet and boot latches as unmapped):
+do not invent a slot and do not promise a panel sound.
+
+**A different car's sound under this car's label is worse than an empty slot, and an empty slot
+fails the gate.** The way out is the next section, not a stand-in. (A whine recorded from another
+car's straight-cut race gearbox was rejected for exactly this reason.)
+
+## When the best mod lacks a slot
+
+Walk this order for the missing slot only, and record which step you used in its `provenance`:
+
+1. **Another BeamNG mod of the same engine or car family** (a sister trim, the same engine in
+   another body), then the **BeamNG base game** (stock FMOD banks, `vehicles/common` sounds,
+   stock blends) for anything generic (doors, horn, indicator, tyres, impacts, suspension).
+2. **Another simulator's mod or official car** (Assetto Corsa / ACC, rFactor 2, Automobilista 2).
+3. **Real recordings of the car** (onboard and exterior clips). Cut each per "Cutting a real
+   recording", below, and name the clip URL in the provenance.
+
+Never another car's sound under this car's label, and never a synthesised stand-in. If all three
+fail for a slot the car physically has, the car is **not publishable**: report it blocked and say
+what you tried (an empty `engineLadder` fails the gate for the same reason).
+
+The stock events BeamNG itself plays for a slot no part names, the `--map` slot-map file (one car
+from several sources, trims, concats, recordings) and the Assetto Corsa specifics are in
+`read_skill({ name: "helix-vehicles", reference: "audio-import" })`. **`shutdown`, `clutch`, `intake` and
+`revLimiter` have no base-game default**: BeamNG plays nothing for them unless a part names one,
+so they stay empty (and the gate fails) until a `--map` source provides one.
+
+## The only empty slots
+
+Two shapes are accepted, and nothing else:
+
+```json
+{ "slot": "turboSpool", "buffers": [], "consumed": false, "absent": "not-fitted", "reason": "naturally aspirated: the real car has no turbocharger" }
+{ "slot": "exhaustLadder", "buffers": [], "consumed": false, "absent": "combined-with-engine", "reason": "the mod records engine and exhaust as one set; it plays once on the engine layer" }
+```
+
+- **`absent: "not-fitted"`**: a component the real car physically lacks: `turboSpool` and `blowOff` without a
+  turbocharger (`physics.induction` absent or not `turbo`), `reverseBeep` (fitted equipment),
+  `clutch` on an automatic or CVT, and on an electric car every combustion slot (and the shift
+  slots on a single-speed drive). An EV's **engine ladder is a recording of the real motor** and
+  `transmissionWhine` stays required; `audio.drivetrain: "electric"` (the engine's synthesised
+  motor voice) **fails as `AUDIO_SYNTHESISED`**. See "Electric cars" in the `audio-import` reference.
+- **`combined-with-engine`**: `exhaustLadder` only, beside a **sourced** engine ladder.
+
+The reason must name the real component or the mod's combined recording. "No recording found" is
+not a reason: it is `AUDIO_SLOT_UNSOURCED`. A `not-fitted` claim the car's physics contradicts (a
+turbo car's `turboSpool`, a manual's `clutch`), or turbo sounds on a car with no
+`physics.induction`, fails as `AUDIO_SLOT_FITMENT_MISMATCH`.
+
+## Provenance (every slot, every bank)
+
+Every slot and bank states where its sound came from. `import_vehicle_audio` writes it; if you
+merge by hand, keep it exactly:
+
+```json
+"provenance": {
+  "kind": "sim-mod",                      // "sim-mod" | "sim-official" | "recording"
+  "sim": "beamng",                        // "beamng" | "assetto-corsa" (a recording: where it was filmed or fetched)
+  "mod": "mmbng",                         // the mod / car folder ("BeamNG.drive" for stock banks) / video title
+  "modUrl": "https://…",                  // when --mod-url or the map's modUrl is given
+  "sourceFile": "art/sound/engine/PSH/1768.wav",   // or "content/art_sound.zip:art/sound/fmod/desktop/vehicle.assets.bank"
+  "sourceSha256": "<sha256 of that source file>",
+  "event": "event:/Engine/Starter/v8flat_1986_eng",   // the FMOD event, where there is one
+  "sample": "<FMOD subsound name>", "subsong": 1234,
+  "extractor": "helix beamng_stock_events + vgmstream-cli r2117",
+  "transforms": [{ "kind": "wav-header-repair" }],   // wav-header-repair | decode | fmod-autopitch-varispeed | trim | concat
+  "jbeam": "Porsh_engine.starterSample",  // the field that named it (BeamNG)
+  "baseGameDefault": "lua/vehicle/…",     // when the game's own default filled the slot
+  "pieces": []                            // the parts of a concat
+}
+```
+
+It lives inline on `audio.slots[i]`, `audio.slots[i].assets[j]`, `audio.bank.assets[k]` and
+`audio.bank.blends[name]`. The only byte changes ever made to a recording are the recorded
+`transforms`: a malformed WAV header rebuilt around untouched samples, a codec decode, an FMOD
+auto-pitch varispeed (ratio recorded), a trim or a concat of real pieces. Nothing is mixed,
+filtered or generated, and `import_vehicle_audio` never alters a recording to pass a gate.
+
+`check_vehicle_audio` prints the provenance of every slot (sim, mod, source file, sha256,
+extractor) so you can read the whole chain at a glance. These are **errors**, and `publish_vehicle`
+refuses the same:
+
+| Code | When |
+| --- | --- |
+| `AUDIO_SYNTHESISED` | a provenance `kind` or transform that is generated or synthesised, or a slot `reason` / `note` that says so (a negated clause such as "rather than synthesised" is fine) |
+| `AUDIO_ENGINE_UNSOURCED` | no recorded engine ladder: the runtime would play its synthesised fallback engine (electric cars are exempt) |
+| `AUDIO_SLOT_UNSOURCED` | one of the 31 slots is missing, empty (outside the two shapes above) or only names a platform buffer (the runtime's default pack) |
+| `AUDIO_PROVENANCE_MISSING` | a recording (slot asset or ladder rung) that says nothing about where it came from |
+| `AUDIO_MIX_FIELDS_MISSING` | `engineGainDb` / `exhaustGainDb` missing or non-finite, or `minLoadMix` / `maxLoadMix` / `muffling` outside 0..1: the car boards but never moves or sounds (R34 1.0.9). `audio-import` writes all five; `basePackage` keeps a published car's own |
+| `AUDIO_SLOT_FITMENT_MISMATCH` | a `not-fitted` claim the physics contradicts, or turbo sounds on a car with no `physics.induction` |
+
+`AUDIO_ENGINE_EXHAUST_SHARED_RECORDING` (warn) is a package that points engine and exhaust blends
+at the same **sourced** recording: a real recording, just doubled; declare the combined shape
+instead. An asset with no traceable source is a defect: replace it.
+
+## Platform defaults are not an answer. Never rely on them.
+
+The engine ships its own sound for a slot a car leaves out: a `defaultSoundPack` of generated
+takes (55 of them), a synthetic starter, runtime noise for tyres, skids and the handbrake, and
+synthesised class engine banks (`inline4` and the others in `engine-core`; the multiplayer-vehicles
+template's `craftBanks` are synthesised too). **None of that is a sound for a published car.** A
+car ships its **own sourced sound for every slot**. Do not omit `audio.bank` to "let the platform play something", do
+not name one of those bank ids, and do not treat a quiet gate as "the defaults cover it": the gate
+**fails a car that would fall back to one** (`AUDIO_ENGINE_UNSOURCED` for the engine,
+`AUDIO_SLOT_UNSOURCED` for every other slot).
+
+## Cutting a real recording (fallback step 3, and a one-shot a mod lacks)
+
+A steady rung ladder from a real recording of the car, when no sim mod can supply it:
+
+- **A steady rpm ladder**: 6-12 rungs from idle to the limiter, each a steady-state stretch at one
+  rpm (read it off the tachometer in onboard footage, or from the firing frequency with the
+  script above: rpm = f0 x 60 / orders).
+- **On and off throttle**: load and overrun takes at the same rpm, for the load crossfade (row 1
+  and row 0).
+- **Turbo cars**: the spool rising under load, and the wastegate or blow-off on lift-off.
+- Ignition, limiter bounce and shifts, if the clip has them.
+
+Label every rung by the rpm it **measures**, not by a guess or a tach misread: the runtime places
+a rung on the ladder by its label. Verify every rung with "The rung-pitch self-check", below. Save
+the original audio stream, convert it to PCM WAV and build the rungs as "Preparing WAVs" says.
+
+## The rung-pitch self-check (run it on every rung before sealing)
+
+A rung's rpm label is what the runtime uses to place it on the ladder, so the label must describe
+the pitch the rung actually has. Round 4 shipped a top rung labelled `f40_eng_on_7822` (7,822 rpm,
+F40 V8) whose measured fundamental was **21.58 Hz** — the cycle frequency of about **2,600 rpm**, so
+the audio sat at **×0.33 of the rpm its label claimed** and the car lost its redline wail (the
+top-of-range firing read ~104 Hz where the limiter implies ~520 Hz). The cause was a rung labelled by a guess instead of by its
+measured pitch (a sub-order confusion at high rpm); it is mechanical to catch.
+
+**The model.** `sampleCylinderCount` (C) and `strokes` (S) describe **the recorded engine** and
+drive the pitch. A rung labelled `N` rpm has three related frequencies, and a comb estimator latches
+onto whichever is strongest:
+
+```
+firing  f_fire  = N/60 x (C/2 if S == 4 else C)     # the dominant bark, the loudest peak
+crank   f_crank = N/60                              # 1st order, one per revolution
+cycle   f_cycle = f_fire / C = N/120 (4-stroke)     # waveform repeats once per engine cycle
+```
+
+### The firing fundamental — which of those three is the car's voice, by crank layout
+
+**The firing fundamental is the number you must get right, and it depends on the crank layout as
+well as the cylinder count.** A 4-stroke engine fires each cylinder once per 2 crank revolutions,
+so it fires `C/2` times per revolution. Whether those firings are **evenly spaced** decides which
+frequency is the loudest, and that is the difference between two V8s that otherwise share every
+number:
+
+```
+flat-plane (even-firing)   f0 = C x rpm / 120       # evenly spaced: inline, boxer AND flat-plane V8
+                           V8: f0 = rpm / 15        # 4 evenly spaced firings per rev (the "scream")
+cross-plane V8 (uneven)    f0 = rpm / 60            # the crank-order "burble", 2 octaves below
+```
+
+- **Flat-plane** (even-firing — every inline and boxer engine, and the flat-plane V8): the pulses
+  are equally spaced, so the energy sits at the **firing frequency** `C·rpm/120`. A flat-plane V8's
+  `f0 = rpm/15`: ~65 Hz at a 950 rpm idle, ~516 Hz at the 7,750 rpm limiter. This is the bright,
+  high, screaming voice (Ferrari F120A/F40, GT350 Voodoo).
+- **Cross-plane** V8: the crank throws group the four firings unevenly (the classic burble), so the
+  dominant is the **crank order** `rpm/60` — two octaves below the flat-plane value, and the
+  half-order rumble of an LS or a small-block Chevy.
+
+Declare the layout in the package: **`audio.crankLayout`** is `"flat-plane"` (default; every
+inline/boxer engine and the flat-plane V8) or `"cross-plane"` (a cross-plane V8). The default is
+flat-plane because every non-V8 is even-firing and the flat-plane V8 is the one that must be named.
+The gate below uses `crankLayout` to pick which of `{f_fire, f_crank, f_cycle}` the rung's pitch
+must land on, and **rejects a rung an octave or more off** — which is exactly the round-7 failure:
+a flat-plane V8 ladder was authored at the crank order (~138 Hz at the limiter instead of
+~516 Hz) and the ladder played two octaves low.
+
+**Measure the fundamental.** Take each rung's fundamental `f_meas` with a **chance-corrected comb**:
+score every candidate `f0` in about 15–1300 Hz by how many spectral peaks fall near **integer
+multiples** of `f0` and how strong those peaks are, and take the best-scoring `f0`. **A single-lag
+autocorrelation or the single strongest FFT bin is not reliable on real engine audio** — broadband
+noise and non-harmonic orders move it and will mislabel a rung — so do not substitute one for the
+comb.
+
+**Normalise the order.** Take `f_meas` relative to the **closest** of `{f_cycle, f_crank, f_fire}`:
+`q = f_meas / closest`. `q ≈ 1` means the rung's pitch matches its label under that order. (Do not
+compare `f_meas` straight to `f_fire`; a rung whose comb landed on the crank or cycle order would
+false-fail.) Record `q` per rung beside its rpm in the ledger.
+
+**Pass/fail, on the whole ladder, before sealing:**
+
+- **PASS** when every rung's `q` is within **±165 cents (10 %)** of the ladder's **median** `q`, and
+  the fundamental **rises monotonically** with the labelled rpm (log–log slope ≈ 1.0). The runtime
+  plays rungs by **ratio** of labelled rpm, so a small *consistent* offset across the ladder is only
+  a slight absolute-pitch shift — a warning, not a fail.
+- **WARN** (record it, do not ship blind) when the median `q` is 6–25 % from 1 — the labels describe
+  the audio only to that tolerance.
+- **FAIL — relabel the rung to the rpm it really is, or re-extract it from the source (a wrong
+  rung in the mod's ladder means that mod is not accurate: back to "Which mod is most accurate?") — when:**
+  - a rung sits at **half or a third** of the ladder's pitch/label ratio (`q/median ≈ 1/2 or 1/3`).
+    This is the round-4 top-rung failure: the audio is really at **2× or 3× the rpm of its label**,
+    so it plays a fraction as high as the tach says and the redline never screams. **Never accept
+    this as an "order ambiguity" on the top rung** — the top rung is where it costs the most.
+  - the median `q` is more than **±386 cents (25 %)** from 1 — the labels do not describe these
+    recordings at all.
+  - the fundamental does not rise with the labelled rpm.
+
+**Controls (measured; reuse them):**
+
+```
+PASS (consistent)  a 993 flat-6 ladder (a real BeamNG import) (C 6, S 4), 11 rungs 1768-6388 rpm: q 0.918-0.924,
+                   median q 0.9187 (-147 cents), spread 0.23 %, log-log slope 0.998 -> the labels
+                   sit a consistent -8 % from the model convention, which the ratio playback
+                   absorbs: self-consistent, ships.
+FAIL               round-4 F40 f40_eng_on_7822.wav, label 7822 rpm (V8 4-stroke -> f_fire 521 Hz,
+                   f_cycle 65 Hz): f_meas 21.58 Hz = f_cycle of ~2,600 rpm -> q/median 0.33
+                   -> relabel, or re-extract.
+```
+
+The 993 control is real: the failure mode to catch is a **single** rung — above all the top one —
+that disagrees with the rest of the ladder, not a consistent offset the whole ladder shares.
+
+## The spectral-centroid check (the car's firing-order signature, not just its pitch)
+
+**Rung pitch and timbre are both necessary and neither is sufficient.** Pitch says *what note* the
+engine is on; the **spectral centroid** (the energy-weighted mean frequency, `Σ f·P(f) / Σ P(f)`)
+says *where the energy sits across the harmonics*, and that is what separates a flat-plane V8
+from a cross-plane one. A ladder from the wrong engine passes the pitch check and still does not
+read as the car: one earlier F40 ladder had an idle centroid of **294.7 Hz against the real car's
+1,779 Hz (×0.17)**, a cross-plane burble where a flat-plane scream belongs.
+
+- A **flat-plane** crank (Ferrari F120A/F40, GT350 Voodoo) fires evenly, so the ladder is
+  dominated by **high firing orders**: the centroid sits **high** (the real F40: about 1.8 kHz at
+  idle, 2.6-3.9 kHz at rev) and its firing fundamental is `rpm/15`.
+- A **cross-plane** crank (LS, SBC) piles energy into the **half-order rumble**: the centroid sits
+  **much lower**.
+
+**How to use it.** It is the second measure in "Which mod is most accurate?": measure the candidate's
+idle rung and its top rung, and the real car's idle and high-rpm clips, with `measure-engine.py`.
+**PASS** when the candidate's centroid is within **±30 %** of the real car at idle and at the top
+and **rises with rpm**. A candidate that fails is a different engine in that car's body: **choose
+another mod, or another BeamNG mod of the same engine; do not EQ it into shape, and never
+resynthesise it.** `check_vehicle_audio` gates pitch (against the firing fundamental, above) and
+broadband content but, unless you pass it a real-car reference, not the centroid: a green gate is
+not "the voice is the car's", so verify the centroid against the real recordings yourself.
+
+## Preparing WAVs
+
+- Use PCM WAV, 44.1 or 48 kHz, 16-bit, and keep one sample rate across the bank. `audio-import`
+  writes this for you; for a recording you cut yourself: `ffmpeg -i in.m4a -ac 1 -ar 48000 -c:a pcm_s16le out.wav`.
+- Ladder rungs must be steady-state loops. Trim each to a whole number of firing cycles and remove
+  any fades. Name files by rpm, as in `psh_3214.wav`.
+- Normalise the ladder rungs to each other, then set the overall level with `engineGainDb` and
+  `exhaustGainDb` (the 993 used −8 and −5). `muffling` 0.22 and `minLoadMix` 0.15 are reasonable
+  starting points. **Normalise with headroom** (peak −3 dBFS or lower) and never let a limiter or a
+  `tanh` drive flatten the peaks: see "Content gates", below.
+- `sampleCylinderCount` and `strokes` describe **the recorded engine**, and `crankLayout`
+  (`"flat-plane"` or `"cross-plane"`) names the crank. They drive the pitch model — and they are the
+  inputs to "The rung-pitch self-check" and the firing fundamental, above, before any rung is sealed.
+
+## Wiring it in the package
+
+```json
+"audio": {
+  "bankId": "<slug>", "sampleCylinderCount": 6, "strokes": 4, "crankLayout": "flat-plane",
+  "engineBlend": "MYENGINE", "exhaustBlend": "MYEXHAUST",
+  "bank": {
+    "blends": {
+      "MYENGINE": { "eventName": "event:>Engine>default",
+        "samples": [[["r1768.wav", 1768], ["r2238.wav", 2238], "…"], [["r1768.wav", 1768], "…"]] },
+      "MYEXHAUST": { "eventName": "event:>Exhaust>default",
+        "samples": [[["x1800.wav", 1800], ["x2300.wav", 2300], "…"]] }
+    },
+    "assets": [{ "name": "r1768.wav", "file": "r1768.wav", "role": "vehicle.audio.bank.sample",
+      "mediaType": "audio/wav", "bytes": 356236, "checksumSha256": "<sha256>",
+      "cid": "cid:sha256:<sha256>", "url": "<public URL of the sealed object>" }]
+  },
+  "slots": [
+    { "slot": "engineLadder", "buffers": ["blend:MYENGINE"], "consumed": true,
+      "provenance": { "kind": "sim-mod", "sim": "beamng", "mod": "…", "modUrl": "https://…",
+        "sourceFile": "art/sound/blends/….sfxBlend2D.json", "sourceSha256": "<sha256>", "extractor": "helix vehicle audio-import <version>" } },
+    { "slot": "exhaustLadder", "buffers": ["blend:MYEXHAUST"], "consumed": true, "provenance": { "…": "as above" } },
+    { "slot": "startup", "buffers": ["startup.wav"], "assets": [{ "…": "same asset shape" }], "consumed": true, "provenance": { "…": "as above" } },
+    { "slot": "turboSpool", "buffers": [], "consumed": false, "reason": "naturally aspirated" }
+  ],
+  "engineGainDb": -8, "exhaustGainDb": -5, "minLoadMix": 0.15, "maxLoadMix": 1, "muffling": 0.22
+}
+```
+
+Rules:
+
+- Every sample a selected blend names must be in `bank.assets`.
+- A slot's `assets` must be referenced by that slot's `buffers`.
+- No slot may be declared twice.
+- `audio.bank` and every consumed slot carry a `provenance` ("Provenance", above).
+
+## The URL closure and package closure (silent failure if skipped)
+
+**Every audio file must be a member of the sealed package closure.** A WAV a bank or slot names has
+to be listed in the package (`bank.assets`, or the slot's `assets`) and sealed by `publish_vehicle`.
+A slot that references a `cid` which is not inside the closure resolves to nothing and **404s at
+runtime** — silently.
+
+The runtime loads that sealed asset only when it carries a `url`, its `checksumSha256` and its
+`bytes`, and the URL serves exactly those bytes. **A `cid` alone plays nothing**, and nothing
+reports it.
+
+Do not compute URLs. Author each row with `name` and `file` (the WAV in the package directory or
+`audio/`), as in the example above, and let `publish_vehicle` close it: it uploads each WAV as a
+public object, confirms its content URL serves the exact bytes, writes `url`, `checksumSha256`,
+`bytes` and `cid` before the mint, and includes the file in the sealed closure. Every sample, a
+mod's one-shot included, is sealed the same way: the WAV from `audio-import` sits beside the
+package and `publish_vehicle` uploads and seals it. A `url` copied from the reference package's
+`bg_*` rows is not in your closure and 404s (and those rows are another car's sound).
+
+`check_vehicle_audio` is the proof, before and after:
+
+```
+check_vehicle_audio({ target: "/abs/car" })        # pre-publish: local files + any existing urls
+check_vehicle_audio({ target: "<vehicle item id>" }) # read-back: what the runtime receives
+```
+
+It selects samples exactly as the runtime does (each rung of the selected blends, each slot asset
+named by its slot's `buffers`), then fetches and decodes each one. It fails a missing row, a 404,
+a byte or digest mismatch, a non-PCM file and digital silence, and it prints the **provenance** of
+every slot and bank; it **refuses synthesised or generated audio** (`AUDIO_SYNTHESISED`) and a car
+whose engine or exhaust has no sourced audio (`AUDIO_ENGINE_UNSOURCED`). Three further gates are **errors**:
+
+- **Each ladder rung's pitch must match its rpm label against the firing fundamental.** Every engine
+  and exhaust rung is decoded, its fundamental measured with a chance-corrected comb, and compared
+  to the firing fundamental for the declared `sampleCylinderCount`/`strokes`/`crankLayout`
+  (`C·rpm/120` even-firing, `rpm/15` for a flat-plane V8, `rpm/60` for a cross-plane V8). A rung
+  **an octave or more off** from that frequency is refused — this is the round-7 failure, where the
+  flat-plane V8 ladders were authored at the crank order (~138 Hz at the limiter instead of
+  ~516 Hz) and played two octaves low. A correct ladder passes; an octave-low one fails. The
+  octave check (`AUDIO_RUNG_PITCH_OCTAVE_OFF`) decides on the spectral energy at the labelled
+  firing series (or its half-order series, which real flat-plane V8 and flat-six recordings
+  carry) before it trusts the pitch tracker, so real sim recordings pass.
+- **Engine and exhaust are separate recordings, unless the mod's is one combined set.** Pointing
+  `engineBlend` and `exhaustBlend` at one unsourced blend is refused
+  (`AUDIO_ENGINE_EXHAUST_SAME_BLEND`). A mod that records one set for both omits `exhaustBlend` and
+  declares `exhaustLadder` `absent: "combined-with-engine"`; pointing both blends at the same
+  *sourced* recording is only a warning (`AUDIO_ENGINE_EXHAUST_SHARED_RECORDING`).
+- **A rung must be a real broadband engine sound, not a near-pure tone.** Each engine and
+  exhaust rung is measured for spectral richness (autocorrelation and the spectral noise floor). A
+  near-pure tone — a handful of spectral lines, everything else down, autocorrelation ~1.0 — is
+  refused even when its pitch is correct (round 5 shipped an 11-rung ladder whose 1000 rpm rung was
+  exactly that). A recorded rung, with its real harmonic ladder and noise floor, passes.
+
+## Content gates (clipping, DC, copies, fixed formants, synthetic horn)
+
+`check_vehicle_audio` also measures what the sound is made of. Round 8's F40 passed every gate above
+and an owner listening to it still heard these, so each is now measured. Thresholds are calibrated
+so clean recordings pass (the 993, BeamNG's F355, the platform's recorded horns and 41 field
+recordings all pass untouched). A **warning** is reported, not blocking; an **error** blocks the mint.
+
+| Code | Means | Level | Fix |
+| --- | --- | --- | --- |
+| `AUDIO_CLIPPED` | Flat-topped runs (3+ identical samples with a steep knee) at full scale or at the file's own peak: clipped, then turned down. Real recordings: ≤ 0.04 % of samples. | warn from 0.1 %; error from 0.5 % on a ladder rung, 2 % on any other sample | Render with headroom (peak ≤ −3 dBFS); remove the hard limiter or `tanh` drive that flattens the crest, or lower its drive. Turning a clipped file down does not unclip it. |
+| `AUDIO_DC_OFFSET` | Mean sample value not zero (real: ≤ 0.015 full scale); the sample clicks when it starts or loops. | warn from 0.02; error from 0.05, or 50 % of RMS | Subtract the mean after the last nonlinearity, or high-pass at 25 Hz (`ffmpeg -af highpass=f=25`). Asymmetric waveshapers and limiters cause it. |
+| `AUDIO_LADDER_FIXED_FORMANTS` | Every rung has the same peaks and notches at the same absolute Hz, whatever the rpm: one resonator stack stamped on every rung (harmonic-envelope correlation across rungs ≥ 0.3; real ladders ≈ 0.0–0.1, the F40 0.64–0.73). | warn ≥ 0.3; error ≥ 0.5 | One resonator stack stamped on every rung is the signature of a generated ladder, and a refusal here is a sign the rungs did not come from a real engine. Take the ladder from the sim mod's own recordings (or another mod of the same engine), where the resonances move with rpm and load. |
+| `AUDIO_LADDER_FIXED_TONE` | A narrowband line at the same absolute frequency in most rungs while the firing fundamental moves (a fixed oscillator or ring); lines that are harmonics of the rung's own pitch are ignored. | warn when in ≥ 55 % of rungs; error ≥ 75 % | Remove or notch the fixed component. Only broad body resonances may stay put. |
+| `AUDIO_LADDER_RUNG_COPY` | A rung is the neighbouring rung time-stretched or resampled (aperiodic residual correlates ≥ 0.65 after undoing the pitch change; independent rungs ≤ 0.5). | warn ≥ 0.65; error ≥ 0.8 | Do not resample one rung into its neighbours. Use every rung from its own recorded take (own noise, own cycle-to-cycle variation); the runtime already pitch-shifts between rungs. |
+| `AUDIO_HORN_SYNTHETIC` | The `horn` slot repeats sample for sample (autocorrelation ≥ 0.9995: no pitch jitter, shimmer or noise floor); recorded horns measure 0.97–0.98. | warn | Use the car's recorded horn (the mod's horn event, then a real recording). A horn that repeats sample for sample was generated; replace it. |
+
+Two traps: a ladder whose rungs share one resonator set fails the fixed-formant gate even though
+no rung is a copy of another, which is the usual way a generated ladder ends up sounding like one
+voice at different pitches. And a **real BeamNG import**
+(993-style) may declare a bad WAV header (two channels, mono block alignment): the content gates
+decode it leniently and measure it normally.
+
+A real recording can still trip the content gates (Assetto Corsa's own exterior sets clip and carry
+DC offset). `import_vehicle_audio` never alters a recording to pass a gate; take another take or
+another source for that rung (the same car's other microphone set, another mod), never a processed
+or synthesised one.
+
+## Source gates: distinct recordings, the limiter, the real-car reference
+
+Every sound is a **real recording** of the car (or of a BeamNG mod of it). `check_vehicle_audio` also refuses sounds that are not distinct, recordings that are the wrong length for how the runtime plays them, and, when you give it a recording of the real car, an idle voice that does not sound like it.
+
+| Code | Means | Level | Fix |
+| --- | --- | --- | --- |
+| `AUDIO_NEAR_DUPLICATE_SOUNDS` | Two sounds that play as different roles (shift up / shift down, horn / an engine rung, an engine rung / an exhaust rung, door open / close, any two slots) are one recording: identical samples, or one retimed or pitched into the other (band-envelope correlation ≥ 0.93, or ≥ 0.8 with the same resonance line pattern; independent recordings ≤ 0.66). Inside one ladder the finding is `AUDIO_NEAR_DUPLICATE_RUNGS`. | error; `AUDIO_POSSIBLE_DUPLICATE_SOUNDS` (warn) for a 0.8-0.93 match the line pattern does not back | Use a distinct real recording for each role. A shift-down is not the shift-up retimed; an exhaust rung is not an engine rung resampled. A BeamNG mod of the car usually ships separate ones. Listen to a warned pair before accepting it. |
+| `AUDIO_REV_LIMITER_HELD` | The `revLimiter` sample is longer than the runtime plays it: the runtime re-fires the slot every 60 ms while the car sits on its limiter, so a 1.6 s recording puts about 27 copies in the air at once and plays as a held tone. The fuel-cut stutter **is** the retrigger. | warn > 0.2 s; error > 0.35 s | Use a real recording of this car cut down to one fuel-cut crack of 0.05-0.2 s with its natural decay; do not ship a long recording of the car held on its limiter. |
+
+### Compare with the real car (`reference`)
+
+```
+check_vehicle_audio({ target: "/abs/car", reference: ["/abs/real-idle-1.wav", "/abs/real-idle-2.wav"] })
+check_vehicle_audio({ target: "/abs/car", reference: ["horn=/abs/real-horn.wav", "startup=/abs/real-start.mp3"] })
+```
+
+- A bare path is a recording of the real engine **idling**; it is compared with the `idle` slot sample, else the lowest engine-ladder rung. `slot=path` compares that slot's sample instead. Repeat to give several clips: the median is used. WAV directly; mp3, m4a and ogg need `ffmpeg` on the PATH (or convert: `ffmpeg -i in.mp3 -ac 1 -ar 44100 -c:a pcm_s16le ref.wav`).
+- Use 10-30 s of **steady** idle, close to the car, with no speech or music. The same two measures are taken from your sample and the reference with one implementation: **spectral centroid** (how bright) and **roughness** (depth of the 8-60 Hz firing modulation). `AUDIO_REFERENCE_TIMBRE` is a **warning** beyond x2.5 and an **error** beyond x10. Two honest field recordings of one car differ by x2-4 (mic distance, wind, the recorder's EQ), so read a warning as "listen and compare spectrograms"; an error means a different engine or a heavily processed file.
+- Far duller or smoother than the reference: the sample is from a different engine, low-passed or heavily processed. Far brighter or rougher: a different engine, or a recording with heavy added noise or an exaggerated chug. Re-source it from a real recording of the car.
+
+## Verifying
+
+Visual QA never plays audio, so verification is on you. Drive the live car in a **platform-hosted
+world that has vehicle audio**. A world with no `@helix/engine-core/audio` entry in its import map
+plays nothing for any car. Listen for:
+
+- ignition;
+- the idle ladder;
+- a smooth rev sweep under load, with no stepping between rungs;
+- shifts;
+- the limiter;
+- the horn;
+- tyre sounds under wheelspin.
+
+A missing asset URL shows up as silence, not as an error.