Add harmonic bank DSL surface

This commit is contained in:
Meta Vens 2026-05-14 20:36:06 +01:00
commit 9714913407
11 changed files with 187 additions and 23 deletions

View file

@ -120,9 +120,10 @@ First deliverable:
effects.
- Rebuild one additive lead, one PAD texture, and one formant/vocal patch. The
first rebuild catalog entries now parse/export and record the first Zyn
missing abstractions: additive harmonic-bank syntax, PAD-style spectral
source generation, free envelopes for normal voices, named kit/layer routing,
and richer formant/vowel morphing.
missing abstractions. Named layers and additive harmonic-bank syntax now
exist; PAD-style spectral source generation, free envelopes for normal
voices, fuller kit/effect routing, and richer formant/vowel morphing remain
pressure.
Do not vendor the upstream Zyn instrument-bank submodule until its preset
license/provenance is explicit enough for this repo. Use project-authored
@ -140,6 +141,13 @@ label while lowering to ordinary Aquarium voices. It is intentionally only an
ownership/routing scaffold for now; it does not add PAD synthesis, free
envelopes, or effect buses by stealth.
The second response is `harmonics`: additive layers can declare ratio/gain
partial banks such as `harmonics layer=body root=220
partials=1:.16,2:.075`. The parser preserves the bank as authored structure
and lowers it to ordinary voices. This gives additive lead, drawbar, and future
partial-bank targets a reusable surface without pretending to implement Zyn
ADDsynth phase, bandwidth, or free-envelope details.
Sources:
- [ZynAddSubFX](https://github.com/zynaddsubfx/zynaddsubfx)

View file

@ -62,7 +62,7 @@ engines. A named layer surface would give additive banks, PAD sources, free
envelopes, and formant motion somewhere coherent to live later. Without it, the
next abstractions risk becoming loose fields on anonymous voices.
## First Response
## First Responses
Aquarium now has a minimal `layer` command:
@ -74,3 +74,15 @@ voice layer=pad_low freq=130.8128
The layer owns source identity and metadata while current lowering still emits
ordinary voices. This is the scaffold needed before promoting PAD sources,
additive harmonic banks, free envelopes, or richer formant motion.
Additive layers now also have a `harmonics` command:
```text
layer name=body engine=add gain=.16
harmonics layer=body root=220 partials=1:.16,2:.075,3:.045
```
The harmonic bank records authored additive partial intent under a named layer,
then lowers to ordinary sine voices. It does not claim Zyn ADDsynth's full
oscillator table: phase, bandwidth, oscillator shaping, and exact free-envelope
behavior remain separate pressure.

View file

@ -793,10 +793,8 @@ public static class BuiltInScripts
layer name=body engine=add min_key=36 max_key=96 gain=0.16
layer name=shine engine=add min_key=48 max_key=108 gain=0.045
voice layer=body freq=220
voice layer=body freq=440 gain=0.075
voice layer=shine freq=660
voice layer=shine freq=880 gain=0.025
harmonics layer=body root=220 partials=1:0.16,2:0.075
harmonics layer=shine root=220 partials=3:0.045,4:0.025
""";
public const string ZynStylePadTexture = """

View file

@ -194,6 +194,13 @@ public sealed record PatchLayer(
float Gain = 1,
string EffectSend = "");
public sealed record HarmonicPartial(float Ratio, float Gain);
public sealed record HarmonicBank(
string LayerName,
float RootFrequencyHz,
IReadOnlyList<HarmonicPartial> Partials);
public sealed record ReferencePatch(
string Id,
string Family,
@ -227,6 +234,7 @@ public sealed record SynthPatch
{
public IReadOnlyList<Voice> Voices { get; init; } = Array.Empty<Voice>();
public IReadOnlyList<PatchLayer> Layers { get; init; } = Array.Empty<PatchLayer>();
public IReadOnlyList<HarmonicBank> HarmonicBanks { get; init; } = Array.Empty<HarmonicBank>();
public IReadOnlyList<OperatorGraph> OperatorGraphs { get; init; } = Array.Empty<OperatorGraph>();
public IReadOnlyList<ControlLane> Controls { get; init; } = Array.Empty<ControlLane>();
public IReadOnlyList<PatchParameter> Parameters { get; init; } = Array.Empty<PatchParameter>();

View file

@ -35,6 +35,7 @@ public static class PatchScript
private readonly List<PatchParameter> _parameters = [];
private readonly List<ParameterBinding> _parameterBindings = [];
private readonly List<PatchLayer> _layers = [];
private readonly List<HarmonicBank> _harmonicBanks = [];
private readonly Dictionary<string, string> _defaults = new(StringComparer.OrdinalIgnoreCase);
private readonly Dictionary<string, Dictionary<string, string>> _layerDefaults = new(StringComparer.OrdinalIgnoreCase);
private PendingOperatorGraph? _pendingOperatorGraph;
@ -54,6 +55,7 @@ public static class PatchScript
{
Voices = Voices,
Layers = _layers,
HarmonicBanks = _harmonicBanks,
OperatorGraphs = _operatorGraphs,
Controls = _controls,
Parameters = _parameters,
@ -97,6 +99,10 @@ public static class PatchScript
FlushPendingOperatorGraph();
AddLayer(fields, line);
break;
case "harmonics":
FlushPendingOperatorGraph();
AddHarmonicBank(fields, line);
break;
case "voice":
FlushPendingOperatorGraph();
Voices.Add(ParseVoice(ExpandVoiceFields(fields, line), Voices.Count, line));
@ -134,6 +140,54 @@ public static class PatchScript
}
}
private void AddHarmonicBank(IReadOnlyDictionary<string, string> fields, int line)
{
var layerName = Required(fields, "layer", line);
if (!_layerDefaults.ContainsKey(layerName))
{
throw new PatchScriptException(line, $"unknown layer `{layerName}`");
}
var rootFrequency = GetBoundFloat(fields, line, 440, $"/harmonics/{_harmonicBanks.Count}/root", "root", "base", "freq", "frequency");
if (rootFrequency <= 0)
{
throw new PatchScriptException(line, "harmonic root frequency must be greater than zero");
}
var partials = ParseHarmonicPartials(
GetAny(fields, ["partials", "bank", "tones", "drawbars"], ""),
line);
if (partials.Count == 0)
{
throw new PatchScriptException(line, "harmonics needs at least one partial");
}
_harmonicBanks.Add(new HarmonicBank(layerName, rootFrequency, partials));
var sharedFields = Without(fields,
"layer",
"root",
"base",
"freq",
"frequency",
"partials",
"bank",
"tones",
"drawbars",
"gain",
"g");
foreach (var partial in partials)
{
var voiceFields = new Dictionary<string, string>(sharedFields, StringComparer.OrdinalIgnoreCase)
{
["layer"] = layerName,
["freq"] = F(rootFrequency * partial.Ratio),
["gain"] = F(partial.Gain)
};
Voices.Add(ParseVoice(ExpandVoiceFields(voiceFields, line), Voices.Count, line));
}
}
private Dictionary<string, string> ExpandVoiceFields(Dictionary<string, string> fields, int line)
{
var expanded = new Dictionary<string, string>(_defaults, StringComparer.OrdinalIgnoreCase);
@ -674,6 +728,24 @@ public static class PatchScript
private static ParsedEnvelope AdEnvelope(float attackSeconds, float decaySeconds) =>
new(new Envelope(attackSeconds, decaySeconds, 0, 0), attackSeconds + decaySeconds);
private static IReadOnlyList<HarmonicPartial> ParseHarmonicPartials(string value, int line)
{
if (string.IsNullOrWhiteSpace(value)) return [];
return value.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
.Select(part =>
{
var pieces = part.Split(':', 2);
if (pieces.Length != 2) throw new PatchScriptException(line, $"bad harmonic partial `{part}`");
var ratio = ParseFloat(pieces[0], line);
var gain = ParseFloat(pieces[1], line);
if (ratio <= 0) throw new PatchScriptException(line, "harmonic partial ratio must be greater than zero");
if (gain < 0) throw new PatchScriptException(line, "harmonic partial gain must be zero or greater");
return new HarmonicPartial(ratio, gain);
})
.ToArray();
}
private ParsedEnvelope ParseRateLevelEnvelope(IReadOnlyDictionary<string, string> fields, int line, string fieldPath)
{
var rates = ParseFloatList(Required(fields, "rates", line), line, "rates");
@ -901,6 +973,7 @@ public static class PatchScript
"d" or "default" or "defaults" => "defaults",
"def" or "t" or "template" => "template",
"layer" or "kit" => "layer",
"harmonics" or "partials" or "drawbars" => "harmonics",
"v" or "voice" => "voice",
"opgraph" or "ops" or "operators" => "opgraph",
"operator" or "op" => "operator",

View file

@ -21,17 +21,18 @@ public static class ReferenceRebuildCatalog
"zyn/project/additive-lead",
BuiltInScripts.ZynStyleAdditiveLead,
[
new("engine_add", "1", "Represented as explicit additive sine partial voices."),
new("engine_add", "1", "Represented as additive sine partials under named layer authority."),
new("named_layers", "body,shine", "Layer declarations group partial voices under reusable ADD engine intent."),
new("partial_voice_count", "4", "The additive shape is represented as four explicit Aquarium partial voices."),
new("additive_harmonic_bank", "2 banks / 4 partials", "Harmonic-bank syntax records authored ADD partial sets before lowering to ordinary voices."),
new("partial_voice_count", "4", "The additive shape lowers to four Aquarium partial voices."),
new("envelope_count", "2", "Amplitude and pitch contour pressure maps to ADSR plus vibrato in the current patch surface."),
new("lfo_count", "1", "The fixture's amplitude/frequency motion is represented as patch-level vibrato/macro motion.")
],
[
new("additive_harmonic_bank", "Zyn ADDsynth harmonic table", "Aquarium currently writes each partial as a voice; it lacks a terse harmonic-bank source."),
new("zyn_addsynth_oscillator_detail", "Zyn ADDsynth harmonic phase/bandwidth details", "Aquarium records harmonic ratios and gains, but not Zyn's full ADDsynth oscillator table semantics."),
new("zyn_free_envelope_exactness", "Zyn envelope parameter semantics", "The rebuild uses Aquarium ADSR/motion controls rather than Zyn's exact envelope timing model.")
],
"This is the easy Zyn pressure case: Aquarium can say the sound as layered partials, but the syntax is already showing the need for a compact additive harmonic-bank abstraction."),
"This is the easy Zyn pressure case: Aquarium can now say the sound as named harmonic banks while keeping the emitted voice graph plain enough to inspect."),
new(
"zyn/project-pad-texture/aquarium",
"zynaddsubfx",

View file

@ -61,3 +61,4 @@
{"kind":"zyn_reference_rebuilds","lesson":"The first Zyn-style Aquarium rebuilds can sketch additive lead, PAD texture, and vocal/formant layer fixtures with existing voices, macros, formants, filters, noise, and modulation, but the missing abstractions are now concrete: additive harmonic-bank syntax, PAD/spectral source generation, free envelopes for normal voices, named kit/layer routing with per-layer effect sends, and richer formant/vowel morphing. Keep these as named pressure before adding new DSL surface.","source":"ZynAddSubFX rebuild catalog slice on 2026-05-14"}
{"kind":"zyn_worst_case_survey","lesson":"Scanning the upstream ZynAddSubFX instrument bank at commit e9f64a9 found 1358 .xiz files and the hardened reader now parses all of them. The nastiest target is `olivers-100/0032-Drum Kit.xiz`: 16 enabled kit items, mixed ADD/SUB/PAD engines, 106 envelopes, 25 free envelopes, 73 LFOs, 37 filters, and 3 formant filters. The broader top list says named kit/layer routing should come before syntax golf for additive banks, PAD sources, or formant motion; otherwise new abstractions will have no coherent owner.","source":"ZynAddSubFX pressure survey on 2026-05-14"}
{"kind":"layer_language_golf","lesson":"The first Zyn-driven language-golf abstraction is `layer`: named layer declarations own engine tags, optional MIDI key range metadata, default gain, and effect-send labels, while lowering to ordinary Aquarium voices for now. The abstraction generalizes across additive, PAD-texture, and vocal/formant rebuilds and gives future additive-bank, PAD-source, free-envelope, and formant-motion syntax a coherent owner. It deliberately does not implement those later features yet.","source":"Zyn named layer DSL slice on 2026-05-14"}
{"kind":"harmonic_bank_language_golf","lesson":"Additive `harmonics` syntax now records authored ratio/gain partial banks under named layers and lowers them to ordinary Aquarium voices. This generalizes additive lead and future drawbar/partial-bank targets without hiding Zyn ADDsynth phase, bandwidth, oscillator shaping, or free-envelope semantics behind a fake parity claim.","source":"Zyn harmonic-bank DSL slice on 2026-05-14"}

View file

@ -20,6 +20,7 @@
"ignored listening WAV parity artifacts",
"structured development .aqua patch library",
"ZynAddSubFX .xiz feature extraction with project-authored fixtures",
"Zyn additive harmonic-bank DSL surface",
"thresholded DX7 rendered parity test",
"reference rebuild catalog",
"DX7 SysEx structural parsing",
@ -81,9 +82,9 @@
"next": "Use the now-validated algorithm-8 route scale, transpose lowering, and fixed-frequency lowering as fixed inputs while isolating remaining community-voice timbre mismatch, then expand to broader public-domain banks."
},
"zyn_reference_path": {
"status": "Initial ZynInstrumentReader parses plain XML and gzip-compressed .xiz-shaped XML from project-authored fixtures into ZynInstrument records and ReferencePatch features. First Zyn-style Aquarium rebuilds exist for additive lead, PAD texture, and vocal/formant layer. `ZynInstrumentSurvey` can rank .xiz directories by feature pressure. Named `layer` declarations now provide the first Zyn-driven DSL abstraction.",
"lesson": "Start Zyn as structural classification, not translation. Upstream Zyn presets live in a separate bank submodule and should not be vendored until license/provenance is explicit. The hardened reader now parses the observed upstream instrument bank at commit e9f64a9: 1358/1358 .xiz files. The worst target is `olivers-100/0032-Drum Kit.xiz`, with 16 enabled kit items, mixed ADD/SUB/PAD engines, 106 envelopes, 25 free envelopes, 73 LFOs, 37 filters, and 3 formant filters. The first rebuilds show Aquarium can sketch small Zyn fixtures with existing voices/macros/formants/noise, and the upstream survey correctly pushed named kit/layer routing first. `layer` now owns name, engine tag, optional key range metadata, default gain, and effect-send labels while lowering to ordinary voices. It gives future additive-bank, PAD-source, free-envelope, and formant-motion syntax a coherent owner.",
"next": "Choose the next syntax that attaches to named layers: additive harmonic bank, PAD spectral source, free envelope, or richer formant morphing. Prove one across more than one target."
"status": "Initial ZynInstrumentReader parses plain XML and gzip-compressed .xiz-shaped XML from project-authored fixtures into ZynInstrument records and ReferencePatch features. First Zyn-style Aquarium rebuilds exist for additive lead, PAD texture, and vocal/formant layer. `ZynInstrumentSurvey` can rank .xiz directories by feature pressure. Named `layer` declarations provide the first Zyn-driven DSL abstraction, and additive `harmonics` banks now attach to those layers.",
"lesson": "Start Zyn as structural classification, not translation. Upstream Zyn presets live in a separate bank submodule and should not be vendored until license/provenance is explicit. The hardened reader now parses the observed upstream instrument bank at commit e9f64a9: 1358/1358 .xiz files. The worst target is `olivers-100/0032-Drum Kit.xiz`, with 16 enabled kit items, mixed ADD/SUB/PAD engines, 106 envelopes, 25 free envelopes, 73 LFOs, 37 filters, and 3 formant filters. The first rebuilds show Aquarium can sketch small Zyn fixtures with existing voices/macros/formants/noise, and the upstream survey correctly pushed named kit/layer routing first. `layer` owns name, engine tag, optional key range metadata, default gain, and effect-send labels while lowering to ordinary voices. `harmonics` owns authored ratio/gain partial banks under those layers and lowers them to voices for inspectable Faust output. It does not claim Zyn ADDsynth phase, bandwidth, oscillator shaping, or free-envelope semantics.",
"next": "Choose the next syntax that attaches to named layers: PAD spectral source, free envelope, or richer formant morphing. Prove one across more than one target."
},
"note_and_envelope_model": {
"rule": "Notes own frequency, gate duration, and host/MIDI source. Envelopes own ADSR level shape.",
@ -98,7 +99,7 @@
},
"last_verified": {
"command": "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore",
"result": "88 passed; named layer DSL added without regressing DX7 parity",
"commit": "pending Zyn named layers"
"result": "90 passed; additive harmonic-bank DSL added without regressing DX7 parity",
"commit": "pending Zyn harmonic banks"
}
}

View file

@ -15,6 +15,21 @@ Doctrine update:
Completed this slice:
- Added additive harmonic-bank syntax attached to named layers:
`harmonics layer=body root=220 partials=1:.16,2:.075`.
- The parser preserves each bank as `HarmonicBank`/`HarmonicPartial` model
data, then lowers the partials into ordinary voices so Faust output remains
inspectable.
- Converted the Zyn additive lead rebuild from repeated partial voices to two
named banks under `body` and `shine`.
- This is not Zyn ADDsynth parity theater. Phase, bandwidth, oscillator
shaping, and exact free-envelope behavior remain explicit pressure.
- Verified with bundled Python/dexed-py still wired:
`AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore`:
90 passed.
Previous slice:
- Added Zyn-driven language golf through `layer` declarations. A layer owns
name, engine tag, optional MIDI key range metadata, default gain, and an
effect-send label, then lowers to ordinary voices for now.

View file

@ -1,6 +1,6 @@
project: AquariumSynthCSharp
spine_version: 1
updated: 2026-05-14T19:45:00+01:00
updated: 2026-05-14T20:15:00+01:00
prime_directive: >
Build coherent synth machinery. References exist to reveal missing structure,
@ -74,6 +74,7 @@ live_invariants:
- Public-domain reference fixtures and dexed-py helpers are test/development material only; the NuGet package must ship only AquariumSynth.Dsl.
- ZynAddSubFX import starts as feature extraction, not translation. Use project-authored `.xiz` fixtures until external preset-bank license/provenance is explicit.
- Named `layer` declarations own Zyn-style kit/layer identity: engine tag, optional key range metadata, default gain, and effect-send labels. They lower to ordinary voices for now; do not smuggle PAD/free-envelope/effect behavior into them.
- Additive `harmonics` declarations own authored ratio/gain partial banks under named layers. They lower to ordinary voices for now; do not pretend this covers Zyn ADDsynth phase, bandwidth, oscillator shaping, or free-envelope semantics.
- Structured `.aqua` stock lives under `patches/` as development source material. Every library patch must parse/export, and the patch library must stay out of the NuGet package unless intentionally promoted.
- Project-authored Dexed patches may be generated inside tests for calibration; do not ship them in the NuGet package or treat them as runtime dependencies.
- Harsh calibration probes belong in tests and ignored artifacts, not in the patch library unless they are musically useful stock.
@ -95,10 +96,11 @@ reference_targets:
priority: 2
purpose: "Additive, subtractive, PAD, formant, kit, and layered-instrument pressure test."
source: "https://github.com/zynaddsubfx/zynaddsubfx"
status: "Initial ZynInstrumentReader reads plain or gzip-compressed .xiz XML from project-authored fixtures and classifies active ADD/SUB/PAD engines, enabled kit items, layering, envelopes, free envelopes, LFOs, filters, formants, and effects as ReferencePatch features. First Aquarium rebuilds exist for additive lead, PAD texture, and vocal/formant layer and now use named `layer` declarations. A non-vendored upstream bank survey parsed 1358/1358 .xiz files and identified named kit/layer routing as the next likely owner abstraction."
status: "Initial ZynInstrumentReader reads plain or gzip-compressed .xiz XML from project-authored fixtures and classifies active ADD/SUB/PAD engines, enabled kit items, layering, envelopes, free envelopes, LFOs, filters, formants, and effects as ReferencePatch features. First Aquarium rebuilds exist for additive lead, PAD texture, and vocal/formant layer and now use named `layer` declarations. Additive rebuilds can now use `harmonics` banks attached to layers. A non-vendored upstream bank survey parsed 1358/1358 .xiz files and identified named kit/layer routing as the first owner abstraction."
first_slice:
- "Use named layers as the owner before promoting additive harmonic bank, PAD spectral source, free envelope, or richer formant morphing syntax."
- "Do not add all of them at once."
- "Use named layers as the owner before promoting PAD spectral source, free envelope, or richer formant morphing syntax."
- "Additive harmonic banks now exist; prove any next syntax across more than one target."
- "Do not add all remaining pressures at once."
faust:
priority: 3
purpose: "General DSP graph topology pressure test."
@ -128,8 +130,9 @@ next_agent_start_here:
Continue the ZynAddSubFX phase. The first parser/classifier slice exists in
`src/AquariumSynth.Dsl/ZynInstrument.cs` with project-authored fixtures
under `tests/AquariumSynth.Dsl.Tests/Fixtures/ZynAddSubFX/ProjectAuthored`.
Next pressure is to choose the next syntax that attaches to named layers:
additive harmonic bank, PAD spectral source, free envelope, or richer
Named `layer` declarations own source identity, and additive `harmonics`
banks now attach to those layers. Next pressure is to choose the next syntax
that attaches to named layers: PAD spectral source, free envelope, or richer
formant morphing. Do one, prove it across more than one target, and leave
DX7 alone unless a regression test fails.
must_read:
@ -144,6 +147,16 @@ next_agent_start_here:
- "dotnet test AquariumSynthCSharp.slnx --no-restore"
completed_slices:
- date: 2026-05-14
summary: >
Added additive harmonic-bank syntax for named layers. `harmonics
layer=body root=220 partials=1:.16,2:.075` records authored ratio/gain
partial banks in the model, then lowers them to ordinary voices for
inspectable Faust output. The Zyn additive lead rebuild now uses two
banks under `body` and `shine`, while the catalog marks harmonic-bank
support as matched and keeps Zyn ADDsynth phase/bandwidth/oscillator
detail as missing pressure.
verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore: 90 passed"
- date: 2026-05-14
summary: >
Added the first Zyn-driven language-golf abstraction: `layer`.

View file

@ -323,6 +323,40 @@ public sealed class PatchScriptTests
Assert.Throws<PatchScriptException>(() => PatchScript.Parse("voice layer=missing"));
}
[Fact]
public void HarmonicBankSyntaxExpandsNamedLayerPartials()
{
var patch = PatchScript.Parse("""
layer name=drawbar engine=add gain=.2 wave=sine attack=.01
harmonics layer=drawbar root=110 partials=1:.5,2:.25,3:.125
""");
var export = FaustEmitter.Emit(patch);
var bank = Assert.Single(patch.HarmonicBanks);
Assert.Equal("drawbar", bank.LayerName);
Assert.Equal(110, bank.RootFrequencyHz);
Assert.Equal(3, bank.Partials.Count);
Assert.Equal(3, patch.Voices.Count);
Assert.All(patch.Voices, voice => Assert.Equal("drawbar", voice.Layer?.Name));
Assert.Equal([110, 220, 330], patch.Voices.Select(voice => voice.Oscillator.FrequencyHz).ToArray());
Assert.Equal(.5f, patch.Voices[0].Gain, 5);
Assert.Equal(.25f, patch.Voices[1].Gain, 5);
Assert.Equal(.125f, patch.Voices[2].Gain, 5);
Assert.Contains("process =", export.Source);
}
[Fact]
public void HarmonicBankSyntaxRejectsUnknownLayerOrBadPartials()
{
Assert.Throws<PatchScriptException>(() =>
PatchScript.Parse("harmonics layer=missing root=110 partials=1:.5"));
Assert.Throws<PatchScriptException>(() => PatchScript.Parse("""
layer name=drawbar
harmonics layer=drawbar root=110 partials=1
"""));
}
[Fact]
public void Dx7Algorithm32RebuildMatchesAdditiveCarrierShape()
{