daniel/reasampler
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Retire the zone system: one capture = one parameter set, and re-seam the engine and Sample face into bands

Browse Source
This commit is contained in:
Daniel Harvey
2026-07-30 07:15:54 -04:00
parent a689fb75eb
commit 8d4ccbf841
61 changed files with 5416 additions and 8008 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tests/test_component_state_io.cpp
+612 -214
View File
@@ -1,14 +1,16 @@
// component_state_io unit tests (Q-W2v). The HISTORICAL codec suite — the full
// envelope/payload version ladder, every legacy lift, the golden byte fixtures —
// lives in test_sample_map.cpp and runs unmodified against the split module; this
// target exists as the module's OWN executable (house rule: every pure module has
// one) and as the STRUCTURAL PROOF the codec links WITHOUT the voice engine
// (T2-07): it links component_state_io + velocity_curve + master_gain only — a
// sampler_core/pitch_shift symbol reaching this link is a regression.
// component_state_io unit tests — the codec's whole suite: the current envelope + params
// payload round-trip, the frozen prefix bytes, the ENVELOPE ladder (v1..v11) with each
// version's documented lift, and the RETIRED-ZONE-PAYLOAD migration ladder (payload v1..v7
// -> the one parameter set, adopting zone one). The codec's own executable is also the
// STRUCTURAL PROOF it links WITHOUT the voice engine: it links component_state_io +
// velocity_curve + master_gain only, so a sampler_core/pitch_shift symbol reaching this
// link is a regression.
#include "../src/core/instrument/map/component_state_io.h"
#include "../src/core/instrument/engine/master_gain.h" // masterGainMaxLinear (the v8 wire cap)
#include <cstdio>
#include <cstring>
#include <string>
#include <vector>
@@ -25,7 +27,166 @@ static int failures = 0;
} \
} while (0)
// A full round-trip through the CURRENT envelope (v11): every field survives.
// --- A writer for the RETIRED zone-list payloads -----------------------------
//
// The shipping codec no longer EMITS a zone list, so the migration ladder can only be
// tested against bytes this suite lays out itself. These helpers mirror the frozen v1..v7
// record shapes documented in component_state_io.h; if they and the reader ever disagree,
// the migration tests below fail — which is the point.
namespace legacy {
static void u8v(std::vector<std::uint8_t>& out, std::uint8_t v) { out.push_back(v); }
static void u32v(std::vector<std::uint8_t>& out, std::uint32_t v) {
for (int i = 0; i < 4; ++i) out.push_back(static_cast<std::uint8_t>((v >> (8 * i)) & 0xFF));
}
static void i64v(std::vector<std::uint8_t>& out, std::int64_t v) {
const auto u = static_cast<std::uint64_t>(v);
for (int i = 0; i < 8; ++i) out.push_back(static_cast<std::uint8_t>((u >> (8 * i)) & 0xFF));
}
static void f64v(std::vector<std::uint8_t>& out, double v) {
std::uint64_t bits = 0;
std::memcpy(&bits, &v, sizeof(bits));
for (int i = 0; i < 8; ++i) out.push_back(static_cast<std::uint8_t>((bits >> (8 * i)) & 0xFF));
}
static void strv(std::vector<std::uint8_t>& out, const std::string& s) {
u32v(out, static_cast<std::uint32_t>(s.size()));
out.insert(out.end(), s.begin(), s.end());
}
// One zone's worth of the retired per-zone record, in the v7 (fullest) shape.
struct Zone {
std::string sampleId;
int lowNote = 0;
int highNote = 127;
int rootOverride = -1; // < 0 = absent
bool hasLoopOverride = false;
std::int64_t loopStart = 0;
std::int64_t loopEnd = 0;
std::int64_t startPoint = -1; // < 0 = absent
bool trigger = false;
double holdSeconds = 0.0;
double lengthFraction = 1.0;
std::int64_t fadeIn = 0;
std::int64_t fadeOut = 0;
bool preserve = false;
bool pitchEnvEnabled = false;
double pitchAttack = 0.0;
double pitchDecay = 0.0;
double peakSemis = 0.0;
double attackSeconds = 0.003;
double decaySeconds = 0.0;
double sustainLevel = 1.0;
double releaseSeconds = 0.060;
double keyTrack = 1.0;
std::vector<VelocityPoint> curve; // empty -> the flat endpoints
};
static void putZone(std::vector<std::uint8_t>& out, const Zone& z, std::uint32_t pv) {
strv(out, z.sampleId);
u32v(out, static_cast<std::uint32_t>(z.lowNote));
u32v(out, static_cast<std::uint32_t>(z.highNote));
u8v(out, z.rootOverride >= 0 ? 1 : 0);
if (z.rootOverride >= 0) u32v(out, static_cast<std::uint32_t>(z.rootOverride));
if (pv >= 2) {
u8v(out, z.hasLoopOverride ? 1 : 0);
if (z.hasLoopOverride) {
u8v(out, 1);
i64v(out, z.loopStart);
i64v(out, z.loopEnd);
}
u8v(out, z.startPoint >= 0 ? 1 : 0);
if (z.startPoint >= 0) i64v(out, z.startPoint);
}
if (pv >= 5) {
u8v(out, z.trigger ? 1 : 0);
f64v(out, z.holdSeconds);
f64v(out, z.lengthFraction);
i64v(out, z.fadeIn);
i64v(out, z.fadeOut);
u8v(out, z.preserve ? 1 : 0);
u8v(out, z.pitchEnvEnabled ? 1 : 0);
f64v(out, z.pitchAttack);
f64v(out, z.pitchDecay);
f64v(out, z.peakSemis);
f64v(out, z.attackSeconds);
f64v(out, z.decaySeconds);
f64v(out, z.sustainLevel);
f64v(out, z.releaseSeconds);
}
if (pv >= 6) f64v(out, z.keyTrack);
if (pv >= 7) {
const std::vector<VelocityPoint> pts =
z.curve.empty() ? std::vector<VelocityPoint>{{0.0, 1.0}, {127.0, 1.0}} : z.curve;
u32v(out, static_cast<std::uint32_t>(pts.size()));
for (const VelocityPoint& p : pts) { f64v(out, p.velocity); f64v(out, p.amp); }
}
}
// The envelope fields, in wire order. A builder at version N emits only the prefix fields
// version N carried, so each lift can be asserted against a blob shaped exactly as that
// version's writer produced.
struct Envelope {
std::uint32_t version = kComponentStateVersion;
std::uint8_t modeByte = 0; // v4+ 0 mono / 1 stereo
std::int64_t assignGeneration = 0; // v5+
std::uint8_t previewVelocity = kPreviewVelocityDefault; // v6+
std::uint8_t voiceCount = static_cast<std::uint8_t>(kDefaultVoiceCount); // v7+
std::uint8_t voiceMode = 0; // v7+ 0 poly / 1 mono
std::uint8_t monoTrigger = 0; // v7+ 0 retrigger / 1 legato
double masterGain = 1.0; // v8+
std::uint8_t channelModeExplicit = 0; // v9+
std::string instanceGuid; // v11+
std::string selectionId; // v3+
};
// A complete envelope at `env.version` whose tail is a RETIRED zone-list payload at version
// `pv`. `env.selectionId` is the envelope's own stored pick — which the adoption rule
// overrides when the payload carries a zone. The sample-refs table (v10+) is always empty:
// its own shape is covered by the round-trip test.
static std::vector<std::uint8_t> envelopeWithZones(const Envelope& env,
const std::vector<Zone>& zones,
std::uint32_t pv) {
std::vector<std::uint8_t> out;
const std::uint32_t v = env.version;
u32v(out, v);
if (v >= 4) u8v(out, env.modeByte);
if (v >= 5) i64v(out, env.assignGeneration);
if (v >= 6) u8v(out, env.previewVelocity);
if (v >= 7) { u8v(out, env.voiceCount); u8v(out, env.voiceMode); u8v(out, env.monoTrigger); }
if (v >= 8) f64v(out, env.masterGain);
if (v >= 9) u8v(out, env.channelModeExplicit);
if (v >= 10) u32v(out, 0); // sample-refs: empty table
if (v >= 11) strv(out, env.instanceGuid);
if (v >= 3) strv(out, env.selectionId); // v2 was zones-only, no selection
if (pv >= 2) {
u32v(out, kParamsFormatMarker);
u32v(out, pv);
}
u32v(out, static_cast<std::uint32_t>(zones.size()));
for (const Zone& z : zones) putZone(out, z, pv);
return out;
}
// Shorthand for the common case: the CURRENT envelope version carrying a zone payload.
static std::vector<std::uint8_t> envelopeWithZones(const std::string& selectionId,
const std::vector<Zone>& zones,
std::uint32_t pv) {
Envelope env;
env.selectionId = selectionId;
return envelopeWithZones(env, zones, pv);
}
} // namespace legacy
// --- The current format -------------------------------------------------------
// A full round-trip through the CURRENT envelope (v11) + params payload (v8): every field
// survives. This is the "one parameter set round-trips save/reload intact" contract.
static void testComponentStateRoundTrip() {
ComponentState in;
in.selectionId = "smp-1";
@@ -48,18 +209,30 @@ static void testComponentStateRoundTrip() {
e.ref.channelCount = 2;
e.displayName = "My Capture";
in.sampleRefs.push_back(e);
PerformanceZone z;
z.sampleId = "smp-1";
z.lowNote = 30;
z.highNote = 90;
z.rootOverride = 61;
z.startPoint = 5;
z.keyTrack = 1.5;
z.play.playMode = PlayMode::Trigger;
z.play.trigger.lengthFraction = 0.75;
z.play.trigger.fadeInFrames = 441;
z.play.trigger.fadeOutFrames = 882;
in.map.zones.push_back(z);
in.params.rootOverride = 61;
SampleLoop lp;
lp.hasLoop = true;
lp.start = 7;
lp.end = 900;
in.params.loopOverride = lp;
in.params.startPoint = 5;
in.params.keyTrack = 1.5;
in.params.velocityCurve = reasampler::instrument::engine::VelocityCurve::fromPoints(
{VelocityPoint{0.0, 0.2}, VelocityPoint{64.0, 0.6}, VelocityPoint{127.0, 1.0}});
in.params.play.playMode = PlayMode::Trigger;
in.params.play.adsr.attackSeconds = 0.01;
in.params.play.adsr.holdSeconds = 0.05;
in.params.play.adsr.decaySeconds = 0.02;
in.params.play.adsr.sustainLevel = 0.8;
in.params.play.adsr.releaseSeconds = 0.15;
in.params.play.trigger.lengthFraction = 0.75;
in.params.play.trigger.fadeInFrames = 441;
in.params.play.trigger.fadeOutFrames = 882;
in.params.play.pitchEngine = PitchEngine::Preserve;
in.params.play.pitchEnv.enabled = true;
in.params.play.pitchEnv.attackSeconds = 0.02;
in.params.play.pitchEnv.decaySeconds = 0.03;
in.params.play.pitchEnv.peakSemitones = 5.0;
const std::vector<std::uint8_t> bytes = serializeComponentState(in);
const ComponentState out = deserializeComponentState(bytes, 48000.0);
@@ -85,168 +258,52 @@ static void testComponentStateRoundTrip() {
CHECK(out.sampleRefs[0].ref.channelCount == 2);
CHECK(out.sampleRefs[0].displayName == "My Capture");
}
CHECK(out.map.zones.size() == 1);
if (out.map.zones.size() == 1) {
const PerformanceZone& oz = out.map.zones[0];
CHECK(oz.sampleId == "smp-1");
CHECK(oz.lowNote == 30);
CHECK(oz.highNote == 90);
CHECK(oz.rootOverride && *oz.rootOverride == 61);
CHECK(oz.startPoint && *oz.startPoint == 5);
CHECK(oz.keyTrack == 1.5);
CHECK(oz.play.playMode == PlayMode::Trigger);
CHECK(oz.play.trigger.lengthFraction == 0.75);
CHECK(oz.play.trigger.fadeInFrames == 441);
CHECK(oz.play.trigger.fadeOutFrames == 882);
}
const InstrumentParams& p = out.params;
CHECK(p.rootOverride && *p.rootOverride == 61);
CHECK(p.loopOverride && p.loopOverride->hasLoop);
CHECK(p.loopOverride && p.loopOverride->start == 7 && p.loopOverride->end == 900);
CHECK(p.startPoint && *p.startPoint == 5);
CHECK(p.keyTrack == 1.5);
CHECK(p.velocityCurve.points().size() == 3);
CHECK(p.play.playMode == PlayMode::Trigger);
CHECK(p.play.adsr.attackSeconds == 0.01);
CHECK(p.play.adsr.holdSeconds == 0.05);
CHECK(p.play.adsr.decaySeconds == 0.02);
CHECK(p.play.adsr.sustainLevel == 0.8);
CHECK(p.play.adsr.releaseSeconds == 0.15);
CHECK(p.play.trigger.lengthFraction == 0.75);
CHECK(p.play.trigger.fadeInFrames == 441);
CHECK(p.play.trigger.fadeOutFrames == 882);
CHECK(p.play.pitchEngine == PitchEngine::Preserve);
CHECK(p.play.pitchEnv.enabled);
CHECK(p.play.pitchEnv.attackSeconds == 0.02);
CHECK(p.play.pitchEnv.decaySeconds == 0.03);
CHECK(p.play.pitchEnv.peakSemitones == 5.0);
}
// GOLDEN FULL-BLOB FIXTURE (reviewer follow-up, Q-W2v). testEnvelopePrefixBytesFrozen below
// only pins the first 5 bytes of a near-EMPTY blob; it cannot catch a drift anywhere past the
// mode byte (a field re-ordered or dropped inside the voice/gain/refs/guid/zone tail would
// still pass it). This test builds a canonical v11 ComponentState that exercises EVERY field
// family at once (two zones — one Trigger with every optional override set, one Gate with all
// optionals absent — a two-entry sample-refs table, non-default voice/gain/channel-mode
// fields, and a non-flat velocity curve) and asserts the encoded bytes equal an EXACT expected
// vector. The vector below is the current writer's PROVABLY-CORRECT output (proven by the
// round-trip test above) captured as the golden — so the byte layout itself becomes
// un-driftable, not just its first 5 bytes.
static void testGoldenFullBlobFixture() {
ComponentState in;
in.selectionId = "kick";
in.channelMode = ChannelMode::Stereo;
in.channelModeExplicit = true;
in.lastConsumedAssignGeneration = 12345;
in.previewVelocity = 100;
in.voiceCount = 24;
in.voiceMode = VoiceMode::Mono;
in.monoTrigger = MonoTrigger::Legato;
in.masterGainLinear = 2.0;
in.instanceGuid = "guid-1234-5678-abcd";
SampleRefEntry kickRef;
kickRef.sampleId = "kick";
kickRef.ref.relativePath = "bank/kick.wav";
kickRef.ref.rootNote = 36;
kickRef.ref.loop.hasLoop = true;
kickRef.ref.loop.start = 1000;
kickRef.ref.loop.end = 5000;
kickRef.ref.channelCount = 2;
kickRef.displayName = "Kick Drum";
in.sampleRefs.push_back(kickRef);
SampleRefEntry snareRef;
snareRef.sampleId = "snare";
snareRef.ref.relativePath = "bank/snare.wav";
snareRef.ref.rootNote = 38;
snareRef.ref.loop.hasLoop = false;
snareRef.ref.loop.start = 0;
snareRef.ref.loop.end = 0;
snareRef.ref.channelCount = 1;
snareRef.displayName = "Snare";
in.sampleRefs.push_back(snareRef);
// Zone A: every optional field present, Trigger mode, non-flat velocity curve.
PerformanceZone zoneA;
zoneA.sampleId = "kick";
zoneA.lowNote = 24;
zoneA.highNote = 60;
zoneA.rootOverride = 36;
SampleLoop loopA;
loopA.hasLoop = true;
loopA.start = 1000;
loopA.end = 5000;
zoneA.loopOverride = loopA;
zoneA.startPoint = 250;
zoneA.keyTrack = 0.5;
zoneA.velocityCurve = reasampler::instrument::engine::VelocityCurve::fromPoints(
{VelocityPoint{0.0, 0.2}, VelocityPoint{64.0, 0.6}, VelocityPoint{127.0, 1.0}});
zoneA.play.playMode = PlayMode::Trigger;
zoneA.play.adsr.attackSeconds = 0.01;
zoneA.play.adsr.holdSeconds = 0.05;
zoneA.play.adsr.decaySeconds = 0.02;
zoneA.play.adsr.sustainLevel = 0.8;
zoneA.play.adsr.releaseSeconds = 0.15;
zoneA.play.trigger.lengthFraction = 0.75;
zoneA.play.trigger.fadeInFrames = 100;
zoneA.play.trigger.fadeOutFrames = 200;
zoneA.play.pitchEngine = PitchEngine::Preserve;
zoneA.play.pitchEnv.enabled = true;
zoneA.play.pitchEnv.attackSeconds = 0.02;
zoneA.play.pitchEnv.decaySeconds = 0.03;
zoneA.play.pitchEnv.peakSemitones = 5.0;
in.map.zones.push_back(zoneA);
// Zone B: every optional field absent, Gate mode, default flat velocity curve.
PerformanceZone zoneB;
zoneB.sampleId = "snare";
zoneB.lowNote = 61;
zoneB.highNote = 90;
zoneB.keyTrack = 2.0;
zoneB.play.playMode = PlayMode::Gate;
zoneB.play.adsr.attackSeconds = 0.005;
zoneB.play.adsr.holdSeconds = 0.0;
zoneB.play.adsr.decaySeconds = 0.1;
zoneB.play.adsr.sustainLevel = 0.5;
zoneB.play.adsr.releaseSeconds = 0.2;
zoneB.play.pitchEngine = PitchEngine::Varispeed;
in.map.zones.push_back(zoneB);
const std::vector<std::uint8_t> bytes = serializeComponentState(in);
// clang-format off
static const std::uint8_t kGolden[] = {
0x0b,0x00,0x00,0x00,0x01,0x39,0x30,0x00,0x00,0x00,0x00,0x00,0x00,0x64,0x18,0x01,
0x01,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x40,0x01,0x02,0x00,0x00,0x00,0x04,0x00,
0x00,0x00,0x6b,0x69,0x63,0x6b,0x0d,0x00,0x00,0x00,0x62,0x61,0x6e,0x6b,0x2f,0x6b,
0x69,0x63,0x6b,0x2e,0x77,0x61,0x76,0x24,0x00,0x00,0x00,0x01,0xe8,0x03,0x00,0x00,
0x00,0x00,0x00,0x00,0x88,0x13,0x00,0x00,0x00,0x00,0x00,0x00,0x02,0x00,0x00,0x00,
0x09,0x00,0x00,0x00,0x4b,0x69,0x63,0x6b,0x20,0x44,0x72,0x75,0x6d,0x05,0x00,0x00,
0x00,0x73,0x6e,0x61,0x72,0x65,0x0e,0x00,0x00,0x00,0x62,0x61,0x6e,0x6b,0x2f,0x73,
0x6e,0x61,0x72,0x65,0x2e,0x77,0x61,0x76,0x26,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x00,0x00,
0x00,0x05,0x00,0x00,0x00,0x53,0x6e,0x61,0x72,0x65,0x13,0x00,0x00,0x00,0x67,0x75,
0x69,0x64,0x2d,0x31,0x32,0x33,0x34,0x2d,0x35,0x36,0x37,0x38,0x2d,0x61,0x62,0x63,
0x64,0x04,0x00,0x00,0x00,0x6b,0x69,0x63,0x6b,0x00,0xff,0xff,0xff,0x07,0x00,0x00,
0x00,0x02,0x00,0x00,0x00,0x04,0x00,0x00,0x00,0x6b,0x69,0x63,0x6b,0x18,0x00,0x00,
0x00,0x3c,0x00,0x00,0x00,0x01,0x24,0x00,0x00,0x00,0x01,0x01,0xe8,0x03,0x00,0x00,
0x00,0x00,0x00,0x00,0x88,0x13,0x00,0x00,0x00,0x00,0x00,0x00,0x01,0xfa,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x01,0x9a,0x99,0x99,0x99,0x99,0x99,0xa9,0x3f,0x00,0x00,
0x00,0x00,0x00,0x00,0xe8,0x3f,0x64,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xc8,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x01,0x01,0x7b,0x14,0xae,0x47,0xe1,0x7a,0x94,0x3f,
0xb8,0x1e,0x85,0xeb,0x51,0xb8,0x9e,0x3f,0x00,0x00,0x00,0x00,0x00,0x00,0x14,0x40,
0x7b,0x14,0xae,0x47,0xe1,0x7a,0x84,0x3f,0x7b,0x14,0xae,0x47,0xe1,0x7a,0x94,0x3f,
0x9a,0x99,0x99,0x99,0x99,0x99,0xe9,0x3f,0x33,0x33,0x33,0x33,0x33,0x33,0xc3,0x3f,
0x00,0x00,0x00,0x00,0x00,0x00,0xe0,0x3f,0x03,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x9a,0x99,0x99,0x99,0x99,0x99,0xc9,0x3f,0x00,0x00,0x00,0x00,
0x00,0x00,0x50,0x40,0x33,0x33,0x33,0x33,0x33,0x33,0xe3,0x3f,0x00,0x00,0x00,0x00,
0x00,0xc0,0x5f,0x40,0x00,0x00,0x00,0x00,0x00,0x00,0xf0,0x3f,0x05,0x00,0x00,0x00,
0x73,0x6e,0x61,0x72,0x65,0x3d,0x00,0x00,0x00,0x5a,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0xf0,
0x3f,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x7b,0x14,0xae,0x47,0xe1,
0x7a,0x74,0x3f,0x9a,0x99,0x99,0x99,0x99,0x99,0xb9,0x3f,0x00,0x00,0x00,0x00,0x00,
0x00,0xe0,0x3f,0x9a,0x99,0x99,0x99,0x99,0x99,0xc9,0x3f,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x40,0x02,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
0x00,0x00,0x00,0x00,0x00,0xf0,0x3f,0x00,0x00,0x00,0x00,0x00,0xc0,0x5f,0x40,0x00,
0x00,0x00,0x00,0x00,0x00,0xf0,0x3f,
};
// clang-format on
CHECK(bytes.size() == sizeof(kGolden));
if (bytes.size() == sizeof(kGolden)) {
bool same = true;
for (std::size_t i = 0; i < bytes.size(); ++i) {
if (bytes[i] != kGolden[i]) { same = false; break; }
}
CHECK(same);
}
// A DEFAULT parameter set must round-trip to defaults — the "no pick, nothing configured"
// blob restores as the silent empty state, not as a set of accidental values.
static void testDefaultStateRoundTripsToDefaults() {
const ComponentState out =
deserializeComponentState(serializeComponentState(ComponentState{}), 48000.0);
CHECK(out.selectionId.empty());
CHECK(!out.params.rootOverride);
CHECK(!out.params.loopOverride);
CHECK(!out.params.startPoint);
CHECK(out.params.keyTrack == 1.0);
CHECK(out.params.play.playMode == PlayMode::Gate);
CHECK(out.params.play.pitchEngine == kDefaultPitchEngine);
CHECK(!out.params.play.pitchEnv.enabled);
CHECK(out.params.play.adsr.attackSeconds == AdsrSeconds{}.attackSeconds);
CHECK(out.params.play.adsr.releaseSeconds == AdsrSeconds{}.releaseSeconds);
}
// The FROZEN envelope prefix: version tag v11 LE, then the mode byte — a drift in
// either is a byte-format break the round-trip alone can't prove (both sides could
// drift together). Pins the writer's absolute bytes.
// The FROZEN envelope prefix: version tag v11 LE, then the mode byte — a drift in either is
// a byte-format break the round-trip alone can't prove (both sides could drift together).
// Also pins the payload version + marker as SEMANTIC constants, so a bump has to be
// deliberate rather than incidental.
static void testEnvelopePrefixBytesFrozen() {
ComponentState in; // defaults: mono, implicit, no refs, no selection, no zones
ComponentState in; // defaults: mono, implicit, no refs, no selection, default params
const std::vector<std::uint8_t> bytes = serializeComponentState(in);
CHECK(bytes.size() > 5);
if (bytes.size() > 5) {
@@ -254,64 +311,405 @@ static void testEnvelopePrefixBytesFrozen() {
CHECK(bytes[4] == 0); // ChannelMode::Mono
}
CHECK(kComponentStateVersion == 11);
CHECK(kZonesPayloadVersion == 7);
CHECK(kZonesFormatMarker == 0xFFFFFF00u);
CHECK(kParamsPayloadVersion == 8);
CHECK(kParamsFormatMarker == 0xFFFFFF00u);
}
// A v1 selection blob lifts to {id, one full-keyboard zone} — the oldest live lift.
// The WRITER emits the CURRENT payload version, and the marker + version sit at the head of
// the payload — the self-describing property every legacy branch depends on. Asserted
// against the semantic constants, not literals.
static void testWriterEmitsCurrentPayloadVersion() {
ComponentState in;
in.selectionId = "id";
const std::vector<std::uint8_t> bytes = serializeComponentState(in);
// Scan for the marker; the four bytes after it are the payload version.
bool found = false;
for (std::size_t i = 0; i + 8 <= bytes.size(); ++i) {
const std::uint32_t m = static_cast<std::uint32_t>(bytes[i]) |
(static_cast<std::uint32_t>(bytes[i + 1]) << 8) |
(static_cast<std::uint32_t>(bytes[i + 2]) << 16) |
(static_cast<std::uint32_t>(bytes[i + 3]) << 24);
if (m != kParamsFormatMarker) continue;
const std::uint32_t v = static_cast<std::uint32_t>(bytes[i + 4]) |
(static_cast<std::uint32_t>(bytes[i + 5]) << 8) |
(static_cast<std::uint32_t>(bytes[i + 6]) << 16) |
(static_cast<std::uint32_t>(bytes[i + 7]) << 24);
CHECK(v == kParamsPayloadVersion);
found = true;
break;
}
CHECK(found);
}
// --- The retired-zone-payload migration ladder --------------------------------
// SINGLE-ZONE LIFT IS LOSSLESS: a single-capture instance saved under the zone model
// restores with the same capture, the same root, and the same parameters.
static void testSingleZoneMigrationIsLossless() {
legacy::Zone z;
z.sampleId = "kick";
z.lowNote = 0;
z.highNote = 127;
z.rootOverride = 36;
z.hasLoopOverride = true;
z.loopStart = 1000;
z.loopEnd = 5000;
z.startPoint = 250;
z.trigger = true;
z.holdSeconds = 0.05;
z.lengthFraction = 0.75;
z.fadeIn = 100;
z.fadeOut = 200;
z.preserve = true;
z.pitchEnvEnabled = true;
z.pitchAttack = 0.02;
z.pitchDecay = 0.03;
z.peakSemis = 5.0;
z.attackSeconds = 0.01;
z.decaySeconds = 0.02;
z.sustainLevel = 0.8;
z.releaseSeconds = 0.15;
z.keyTrack = 0.5;
z.curve = {VelocityPoint{0.0, 0.2}, VelocityPoint{64.0, 0.6}, VelocityPoint{127.0, 1.0}};
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones("kick", {z}, 7), 48000.0);
CHECK(out.selectionId == "kick"); // same capture
const InstrumentParams& p = out.params;
CHECK(p.rootOverride && *p.rootOverride == 36); // same root
CHECK(p.loopOverride && p.loopOverride->start == 1000 && p.loopOverride->end == 5000);
CHECK(p.startPoint && *p.startPoint == 250);
CHECK(p.keyTrack == 0.5);
CHECK(p.velocityCurve.points().size() == 3);
CHECK(p.play.playMode == PlayMode::Trigger);
CHECK(p.play.adsr.attackSeconds == 0.01);
CHECK(p.play.adsr.holdSeconds == 0.05);
CHECK(p.play.adsr.decaySeconds == 0.02);
CHECK(p.play.adsr.sustainLevel == 0.8);
CHECK(p.play.adsr.releaseSeconds == 0.15);
CHECK(p.play.trigger.lengthFraction == 0.75);
CHECK(p.play.trigger.fadeInFrames == 100);
CHECK(p.play.trigger.fadeOutFrames == 200);
CHECK(p.play.pitchEngine == PitchEngine::Preserve);
CHECK(p.play.pitchEnv.enabled);
CHECK(p.play.pitchEnv.attackSeconds == 0.02);
CHECK(p.play.pitchEnv.decaySeconds == 0.03);
CHECK(p.play.pitchEnv.peakSemitones == 5.0);
}
// A lifted single-zone instance RE-SAVES in the current format and survives a second
// round-trip unchanged — the lift is a one-way door, not a per-open re-derivation.
static void testLiftedStateReSavesInCurrentFormat() {
legacy::Zone z;
z.sampleId = "kick";
z.rootOverride = 36;
z.keyTrack = 0.5;
z.releaseSeconds = 0.4;
const ComponentState lifted =
deserializeComponentState(legacy::envelopeWithZones("kick", {z}, 7), 48000.0);
const ComponentState again =
deserializeComponentState(serializeComponentState(lifted), 48000.0);
CHECK(again.selectionId == "kick");
CHECK(again.params.rootOverride && *again.params.rootOverride == 36);
CHECK(again.params.keyTrack == 0.5);
CHECK(again.params.play.adsr.releaseSeconds == 0.4);
}
// MULTI-ZONE LIFT ADOPTS ZONE ONE: its capture AND its parameters win; every later zone
// drops. No error, no empty state.
static void testMultiZoneMigrationAdoptsFirstZone() {
legacy::Zone first;
first.sampleId = "kick";
first.lowNote = 0;
first.highNote = 59;
first.rootOverride = 36;
first.keyTrack = 0.5;
first.releaseSeconds = 0.4;
legacy::Zone second;
second.sampleId = "snare";
second.lowNote = 60;
second.highNote = 127;
second.rootOverride = 38;
second.keyTrack = 2.0;
second.releaseSeconds = 0.9;
legacy::Zone third;
third.sampleId = "hat";
third.rootOverride = 42;
const ComponentState out = deserializeComponentState(
legacy::envelopeWithZones("", {first, second, third}, 7), 48000.0);
CHECK(out.selectionId == "kick"); // zone one's capture
CHECK(out.params.rootOverride && *out.params.rootOverride == 36);
CHECK(out.params.keyTrack == 0.5); // zone one's parameters
CHECK(out.params.play.adsr.releaseSeconds == 0.4);
// Zones two and three left no trace anywhere.
CHECK(out.selectionId != "snare" && out.selectionId != "hat");
CHECK(out.params.keyTrack != 2.0);
}
// The FIRST zone supersedes the envelope's own stored selection — that zone is what
// first-match resolve actually played, so adopting it is what keeps the sound identical.
static void testFirstZoneSupersedesStoredSelection() {
legacy::Zone z;
z.sampleId = "actually-playing";
const ComponentState out = deserializeComponentState(
legacy::envelopeWithZones("stale-selection", {z}, 7), 48000.0);
CHECK(out.selectionId == "actually-playing");
}
// An EMPTY zone list leaves the envelope's selection alone (a picked-but-never-edited
// instance) and yields default parameters.
static void testEmptyZoneListKeepsTheStoredSelection() {
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones("picked", {}, 7), 48000.0);
CHECK(out.selectionId == "picked");
CHECK(!out.params.rootOverride);
CHECK(out.params.keyTrack == 1.0);
}
// EVERY older payload version takes the migration path, and each lifts the fields its own
// shape carries while defaulting the ones it predates.
static void testEveryOlderPayloadVersionMigrates() {
for (std::uint32_t pv : {1u, 2u, 5u, 6u, 7u}) {
legacy::Zone z;
z.sampleId = "kick";
z.rootOverride = 36;
z.keyTrack = 0.5;
z.releaseSeconds = 0.4;
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones("", {z}, pv), 48000.0);
CHECK(out.selectionId == "kick"); // every version
CHECK(out.params.rootOverride && *out.params.rootOverride == 36); // v1 onward
// keyTrack arrived at v6; older payloads lift to 100% ET (bit-identical repitch).
CHECK(out.params.keyTrack == (pv >= 6 ? 0.5 : 1.0));
// The full A/D/S/R tail arrived at v5; older payloads keep the tier-0 defaults.
CHECK(out.params.play.adsr.releaseSeconds ==
(pv >= 5 ? 0.4 : AdsrSeconds{}.releaseSeconds));
}
// And the CURRENT version does NOT take the migration path: it reads its own record.
CHECK(kParamsPayloadVersion == 8);
}
// The LEGACY v3 payload's wall-clock frame counts convert to seconds at the READ boundary
// using the project rate threaded in — no baked constant.
static void testLegacyV3FramesConvertAtTheProjectRate() {
// v3's own tail shape differs from v5's, so lay it out directly here.
std::vector<std::uint8_t> out;
legacy::u32v(out, kComponentStateVersion);
legacy::u8v(out, 0);
legacy::i64v(out, 0);
legacy::u8v(out, kPreviewVelocityDefault);
legacy::u8v(out, static_cast<std::uint8_t>(kDefaultVoiceCount));
legacy::u8v(out, 0);
legacy::u8v(out, 0);
legacy::f64v(out, 1.0);
legacy::u8v(out, 0);
legacy::u32v(out, 0);
legacy::strv(out, "");
legacy::strv(out, "");
legacy::u32v(out, kParamsFormatMarker);
legacy::u32v(out, 3);
legacy::u32v(out, 1); // one zone
legacy::strv(out, "kick");
legacy::u32v(out, 0); // lowNote
legacy::u32v(out, 127); // highNote
legacy::u8v(out, 0); // no root override
legacy::u8v(out, 0); // no loop override
legacy::u8v(out, 0); // no start point
legacy::u8v(out, 0); // playMode: Gate
legacy::i64v(out, 2400); // holdFrames -> 0.05 s at 48 kHz
legacy::f64v(out, 1.0); // lengthFraction
legacy::i64v(out, 0); // fadeIn
legacy::i64v(out, 0); // fadeOut
legacy::u8v(out, 1); // pitchEngine: Preserve
legacy::u8v(out, 1); // pitchEnv enabled
legacy::i64v(out, 960); // pitchEnv attackFrames -> 0.02 s
legacy::i64v(out, 1440); // pitchEnv decayFrames -> 0.03 s
legacy::f64v(out, 5.0); // peakSemitones
const ComponentState st = deserializeComponentState(out, 48000.0);
CHECK(st.selectionId == "kick");
CHECK(st.params.play.adsr.holdSeconds == 0.05);
CHECK(st.params.play.pitchEnv.attackSeconds == 0.02);
CHECK(st.params.play.pitchEnv.decaySeconds == 0.03);
CHECK(st.params.play.pitchEnv.peakSemitones == 5.0);
// A/D/S/R are absent in v3 -> the tier-0 seconds defaults hold.
CHECK(st.params.play.adsr.attackSeconds == AdsrSeconds{}.attackSeconds);
CHECK(st.params.play.adsr.releaseSeconds == AdsrSeconds{}.releaseSeconds);
// The SAME bytes at a different project rate convert to different seconds — proof the
// rate is a read-time parameter, not a baked constant.
const ComponentState at96k = deserializeComponentState(out, 96000.0);
CHECK(at96k.params.play.adsr.holdSeconds == 0.025);
}
// --- The ENVELOPE ladder (v2..v11) -------------------------------------------
// EVERY envelope version restores the fields it carried and lifts the ones it predates to
// their documented defaults. One table over the whole ladder, so a new envelope field
// cannot be added without deciding what each older version lifts it to.
static void testEnvelopeLadderLiftsEachVersion() {
for (std::uint32_t v : {3u, 4u, 5u, 6u, 7u, 8u, 9u, 10u, 11u}) {
legacy::Envelope env;
env.version = v;
env.selectionId = "kick";
env.modeByte = 1; // stereo
env.assignGeneration = 4242;
env.previewVelocity = 99;
env.voiceCount = 7;
env.voiceMode = 1; // mono
env.monoTrigger = 1; // legato
env.masterGain = 0.5;
env.channelModeExplicit = 1;
env.instanceGuid = "guid-abc";
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones(env, {}, 7), 48000.0);
CHECK(out.selectionId == "kick"); // v3 onward all carry the selection
// v4 added the channel mode; older blobs lift to MONO.
CHECK(out.channelMode == (v >= 4 ? ChannelMode::Stereo : ChannelMode::Mono));
// v5 added the consumed-assignment marker; older blobs lift to 0, so a genuinely
// new first assign (generation >= 1) still applies to a pre-marker instance.
CHECK(out.lastConsumedAssignGeneration == (v >= 5 ? 4242 : 0));
// v6 added the preview velocity; older blobs lift to the mid default.
CHECK(out.previewVelocity == (v >= 6 ? 99 : kPreviewVelocityDefault));
// v7 added the voice system; older blobs lift to {16, Poly, Retrigger} — the
// pre-voice-system behavior, byte-identically.
CHECK(out.voiceCount == (v >= 7 ? 7 : kDefaultVoiceCount));
CHECK(out.voiceMode == (v >= 7 ? VoiceMode::Mono : VoiceMode::Poly));
CHECK(out.monoTrigger == (v >= 7 ? MonoTrigger::Legato : MonoTrigger::Retrigger));
// v8 added the master gain; older blobs lift to unity.
CHECK(out.masterGainLinear == (v >= 8 ? 0.5 : 1.0));
// v9 added the channel-mode EXPLICIT flag; older blobs lift to implicit, so the
// auto-default may follow the loaded capture.
CHECK(out.channelModeExplicit == (v >= 9 ? true : false));
// v10 added the refs table (always empty here), v11 the instance guid; a pre-v11
// blob lifts to an empty guid, which the processor mints on first publish.
CHECK(out.instanceGuid == (v >= 11 ? "guid-abc" : ""));
CHECK(out.sampleRefs.empty());
}
}
// A v2 blob is ZONES-ONLY — no stored selection at all — so the adopted first zone supplies
// BOTH the capture and the parameters.
static void testV2ZonesOnlyBlobAdoptsBothFromZoneOne() {
legacy::Zone z;
z.sampleId = "kick";
z.rootOverride = 36;
std::vector<std::uint8_t> out;
legacy::u32v(out, kPerformanceStateVersion); // == 2, the zones-only envelope
legacy::u32v(out, kParamsFormatMarker);
legacy::u32v(out, 7);
legacy::u32v(out, 1);
legacy::putZone(out, z, 7);
const ComponentState st = deserializeComponentState(out, 48000.0);
CHECK(st.selectionId == "kick");
CHECK(st.params.rootOverride && *st.params.rootOverride == 36);
CHECK(st.channelMode == ChannelMode::Mono); // a v2 blob predates the mode byte
}
// A CORRUPT field falls back to its own DEFAULT rather than clamping to an edge the user
// never chose (or, for the gain, silencing/blasting the instance).
static void testCorruptFieldsFallBackToDefaults() {
legacy::Envelope env;
env.selectionId = "kick";
env.previewVelocity = 0; // 0 is a note-off by convention — out of the 1..127 spec
env.voiceCount = 200; // past kMaxVoiceCount
env.masterGain = 1e9; // far past the +24 dB cap
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones(env, {}, 7), 48000.0);
CHECK(out.previewVelocity == kPreviewVelocityDefault);
CHECK(out.voiceCount == kDefaultVoiceCount);
CHECK(out.masterGainLinear == 1.0);
}
// The WRITER never emits an out-of-range voice count or master gain, so a blob this codec
// produced always re-reads as itself.
static void testWriterClampsOutOfRangeFields() {
ComponentState in;
in.voiceCount = 999;
in.masterGainLinear = 1e9;
const ComponentState out =
deserializeComponentState(serializeComponentState(in), 48000.0);
CHECK(out.voiceCount >= kMinVoiceCount && out.voiceCount <= kMaxVoiceCount);
CHECK(out.masterGainLinear <=
reasampler::instrument::engine::masterGainMaxLinear() * (1.0 + 1e-9));
// Zero gain is TRUE silence and a legal stored value — it must not be "corrected".
ComponentState silent;
silent.masterGainLinear = 0.0;
CHECK(deserializeComponentState(serializeComponentState(silent), 48000.0)
.masterGainLinear == 0.0);
}
// An UNKNOWN envelope version yields the empty state rather than a misparse.
static void testUnknownEnvelopeVersionIsEmpty() {
legacy::Envelope env;
env.version = 99;
env.selectionId = "kick";
const ComponentState out =
deserializeComponentState(legacy::envelopeWithZones(env, {}, 7), 48000.0);
CHECK(out.selectionId.empty());
CHECK(!out.params.rootOverride);
}
// A v1 selection blob lifts to {id, default params} — the oldest live lift.
static void testV1SelectionLift() {
const std::vector<std::uint8_t> v1 = serializeSelection("old-pick");
const ComponentState out = deserializeComponentState(v1, 48000.0);
CHECK(out.selectionId == "old-pick");
CHECK(out.map.zones.size() == 1);
if (out.map.zones.size() == 1) {
CHECK(out.map.zones[0].sampleId == "old-pick");
CHECK(out.map.zones[0].lowNote == 0);
CHECK(out.map.zones[0].highNote == 127);
}
CHECK(!out.params.rootOverride);
CHECK(out.params.keyTrack == 1.0);
}
// Truncation degrades to a partial/empty parse — never out-of-bounds, never throws.
// Truncation degrades to a partial/empty parse — never out-of-bounds, never throws. Run
// over BOTH the current format and a retired zone-list blob, since the migration path has
// its own bounded-read walk.
static void testTruncationDegradesCleanly() {
ComponentState in;
in.selectionId = "smp-2";
PerformanceZone z;
in.params.rootOverride = 61;
const std::vector<std::uint8_t> current = serializeComponentState(in);
legacy::Zone z;
z.sampleId = "smp-2";
in.map.zones.push_back(z);
const std::vector<std::uint8_t> bytes = serializeComponentState(in);
for (std::size_t cut = 0; cut < bytes.size(); ++cut) {
const std::vector<std::uint8_t> part(bytes.begin(),
bytes.begin() + static_cast<long>(cut));
const ComponentState out = deserializeComponentState(part, 48000.0);
(void)out; // reaching here without UB/throw is the contract under test
const std::vector<std::uint8_t> retired = legacy::envelopeWithZones("smp-2", {z, z}, 7);
for (const std::vector<std::uint8_t>* blob : {&current, &retired}) {
for (std::size_t cut = 0; cut < blob->size(); ++cut) {
const std::vector<std::uint8_t> part(blob->begin(),
blob->begin() + static_cast<long>(cut));
const ComponentState out = deserializeComponentState(part, 48000.0);
(void)out; // reaching here without UB/throw is the contract under test
}
}
CHECK(true);
}
// serializePerformance/deserializePerformance round-trip through the v2 envelope.
static void testPerformanceRoundTrip() {
PerformanceMap in;
PerformanceZone z;
z.sampleId = "zone-a";
z.lowNote = 10;
z.highNote = 20;
in.zones.push_back(z);
const PerformanceMap out = deserializePerformance(serializePerformance(in), 48000.0);
CHECK(out.zones.size() == 1);
if (out.zones.size() == 1) {
CHECK(out.zones[0].sampleId == "zone-a");
CHECK(out.zones[0].lowNote == 10);
CHECK(out.zones[0].highNote == 20);
}
}
int main() {
testComponentStateRoundTrip();
testGoldenFullBlobFixture();
testDefaultStateRoundTripsToDefaults();
testEnvelopePrefixBytesFrozen();
testWriterEmitsCurrentPayloadVersion();
testSingleZoneMigrationIsLossless();
testLiftedStateReSavesInCurrentFormat();
testMultiZoneMigrationAdoptsFirstZone();
testFirstZoneSupersedesStoredSelection();
testEmptyZoneListKeepsTheStoredSelection();
testEveryOlderPayloadVersionMigrates();
testLegacyV3FramesConvertAtTheProjectRate();
testEnvelopeLadderLiftsEachVersion();
testV2ZonesOnlyBlobAdoptsBothFromZoneOne();
testCorruptFieldsFallBackToDefaults();
testWriterClampsOutOfRangeFields();
testUnknownEnvelopeVersionIsEmpty();
testV1SelectionLift();
testTruncationDegradesCleanly();
testPerformanceRoundTrip();
if (failures == 0) {
std::printf("component_state_io_tests: all tests passed\n");
return 0;