S4 Tier 0: the bank plays — VST3 marshals MIDI to the S3 core, reads the live bank + resolves WAV the M4 way, mono downmix, lock-free load handoff, LICE sample-pick

2026-07-26 16:43:04 -04:00
parent b0fc052113
commit 0cde457224
24 changed files with 1239 additions and 302 deletions
@@ -0,0 +1,110 @@
+#pragma once
+// sample_map — PURE mapping logic for the S4 Tier-0 instrument: turn the live
+// "reasampler" bank ext-state + a decoded WAV into the plain data the sampler core
+// plays, and (de)serialize the instance's selected-sample choice for VST3 component
+// state. NO VST3, NO REAPER, NO SWELL, NO vendor/ includes at the boundary — the
+// mirror of capture_paths / wav_trim / bridge_marshal splitting the fiddly, testable
+// arithmetic out of a host-facing shell.
+//
+// WHY IT EXISTS (S4 seams). The instrument reads the bank over the live-state seam
+// (the "banks" ext-state blob) and the audio over the file seam (the on-disk WAV).
+// Both of those raw inputs cross the bridge/file boundary in the shell; everything
+// after — parse the bank with the SHARED bank_model/bank_book JSON path (NOT a second
+// parser; the S1 spike's string-scan reader is retired), pick the selected sample,
+// downmix its decoded PCM to the core's mono contract, and build the Tier-0 chromatic
+// Keymap — is pure and unit-tested here.
+//
+// It links bank_book (the shared BankBook::deserialize) and wav_trim (the shared
+// 32-bit-float WAV parse — no third WAV reader) and sampler_core (the Keymap /
+// SampleData it produces). All three are pure; this stays pure.
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "bank_book.h"       // BankBook::deserialize (shared bank JSON parse)
+#include "sampler_core.h"    // Keymap, SampleData, SampleLoop
+#include "wav_trim.h"        // parseWavLayout, extractFloatFrames (shared WAV parse)
+
+namespace reasampler {
+
+// The bank sample this instance is bound to, distilled from the live "banks" blob:
+// the project-relative WAV path the file seam must resolve+decode, plus the S2 bank
+// intrinsics the core repitches / loops by. A pure value — no host, no PCM yet.
+struct SelectedSample {
+    std::string relativePath;   // project-relative; the shell resolves it (M4 convention)
+    int rootNote = 60;          // S2 intrinsic; defaults to middle C when the bank left it empty
+    SampleLoop loop;            // S2 intrinsic; hasLoop=false when the bank left it empty
+};
+
+// Resolve the bound sample from the live bank blob. `banksJson` is the raw "banks"
+// ext-state value the bridge read (may be empty / malformed — an unsaved or pre-bank
+// project). `sampleId` is this instance's stored selection.
+//
+// Precedence, all pure:
+//   * empty / malformed banksJson            -> nullopt (nothing to play)
+//   * sampleId names a sample in ANY bank    -> that sample (searched pool + named)
+//   * sampleId empty or not found, bank has   -> the FIRST sample in ordinal order
+//     >= 1 sample                                (a sensible default so a fresh
+//                                                 instance plays SOMETHING; the UI can
+//                                                 then pick a specific one)
+//   * bank has zero samples                  -> nullopt
+//
+// The "first sample" fallback is deliberate: Tier 0 is "the bank plays", and a brand-
+// new instance with no stored selection should map the bank's first sample rather than
+// stay silent until the user opens the editor.
+std::optional<SelectedSample> selectSample(const std::string& banksJson,
+                                           const std::string& sampleId);
+
+// All (id, displayName) pairs across every bank in ordinal order (pool first), for the
+// selection UI to list. Empty for an empty / malformed blob. Pure projection over the
+// shared parse — the UI never parses JSON itself.
+struct SampleChoice {
+    std::string id;
+    std::string displayName;
+};
+std::vector<SampleChoice> listSamples(const std::string& banksJson);
+
+// Downmix interleaved float frames (the shape wav_trim::extractFloatFrames yields:
+// [f0c0,f0c1,...,f1c0,...]) to the core's MONO contract by AVERAGING channels per
+// frame. `channelCount` is the interleave stride (>= 1). CHANNEL POLICY (Tier 0,
+// documented + surfaced): the S3 core is mono-per-sample by design; bank WAVs preserve
+// their source channel count, so a stereo (or N-channel) capture is folded to a single
+// mono stream here by an equal-weight average. Averaging (not "take L", not summing) is
+// the least-surprising, no-clip default — a centered mono source stays unity, and a
+// hard-panned source is attenuated rather than silenced or doubled. Empty / zero-stride
+// in -> empty out. Pure.
+std::vector<AudioSample> downmixToMono(const std::vector<AudioSample>& interleaved,
+                                       int channelCount);
+
+// Build the Tier-0 chromatic keymap for one decoded, mono sample: one zone spanning
+// the whole keyboard, repitched from `rootNote`, looped per `loop`. This is the
+// single-sample degenerate case (Keymap::singleSampleChromatic) with the S2 intrinsics
+// threaded in. `monoFrames` is the downmixed PCM; `sampleRate` is the WAV's rate.
+Keymap buildTier0Keymap(std::vector<AudioSample> monoFrames, int sampleRate,
+                        int rootNote, const SampleLoop& loop);
+
+// --- Instance state (VST3 setState/getState) --------------------------------
+//
+// The instrument's OWN state is which bank sample it plays (D-B: the selection is a
+// performance choice, held by the instrument, never written back to the bank). It is a
+// single string id. serialize/deserialize keep the on-the-wire form explicit and
+// versioned so a future Tier can extend it without breaking already-saved instances.
+//
+// Format (v1): a 4-byte little-endian version tag (== 1) followed by the id bytes. No
+// length prefix is needed — the id runs to the end of the stream (the host tells us the
+// byte count). deserializeSelection tolerates a truncated / wrong-version / empty blob
+// by returning "" (no selection — the instrument falls back to the bank's first sample),
+// never throwing across the host boundary.
+
+inline constexpr std::uint32_t kSelectionStateVersion = 1;
+
+// The selected-sample id serialized to bytes for IBStream (getState).
+std::vector<std::uint8_t> serializeSelection(const std::string& sampleId);
+
+// The selected-sample id parsed back from IBStream bytes (setState). Unknown version,
+// too-short, or empty -> "" (graceful no-selection).
+std::string deserializeSelection(const std::vector<std::uint8_t>& bytes);
+
+}  // namespace reasampler