Seed music knowledge manuals

docs/music-production-knowledge/aqua-dsp-usage-manual.md

@@ -0,0 +1,112 @@
+# AquaSynth DSP Usage Manual For Music Agents
+
+kind: manual
+tier: core-doctrine
+topic: AquaSynth DSP usage for composition and production
+
+## Owner
+
+This manual owns the minimum practical DSP and DSL knowledge a musician agent
+needs before writing a song candidate, so retrieval starts from usable
+AquaSynth technique instead of copying weak prior patches.
+
+## Transfer Rules
+
+- Start with form, not timbre. Declare `meter`, harmonic center or progression,
+  lane gates, section-level mix motion, and target duration before building
+  voices.
+- Treat every sound as a role owner. Leads, bass, drums, pads, and texture need
+  separate control surfaces so the next agent can adjust them without surgery.
+- Use reference analysis as constraints: tempo/autocorrelation for gates,
+  register/root/scale for pitch lanes, band stats for filtering, and RMS/motion
+  coverage for arrangement density.
+- Write the simplest patch that makes ownership inspectable. Do not hide a song
+  in one giant voice or one full-duration noise bed.
+
+## Current AquaSynth Authoring Surface
+
+Composition sugar:
+
+```aqua
+meter bpm=128 beats=4
+sequence name=kick pattern=x...x...x...x... step=.125 high=.9 low=0
+scale name=hook path=/seq/lead/freq root=220 scale=minor degrees=0,2,3,5,3,2 step=.25
+chords name=pad root=220 scale=minor progression=0,5,3,4 voicing=0,2,4 paths=/chords/pad/root,/chords/pad/third,/chords/pad/fifth step=bar
+mix name=pad points=0:.10,4:.22,8:.15,12:.30,16:.12
+```
+
+The sugar lowers into visible `param` and `curve` owners. Bind those paths from
+voices with `gain=@/seq/kick`, `freq=@/seq/lead/freq`, or
+`gain=@/mix/pad/gain`.
+
+Voice-like leads:
+
+```aqua
+source_port name=lead_src kind=syrinx pressure=.75 opening=.42
+acoustic_network name=lead_body source=lead_src radiation=beak
+acoustic_voice name=lead network=lead_body freq=@/seq/lead/freq gain=@/mix/lead/gain
+```
+
+Use syrinx/acoustic ownership when the reference has singing, vocal chops,
+creature calls, reed-like lead, or expressive vowel motion. Move pressure,
+opening, filter/formant color, and pitch. A static syrinx badge is not a vocal
+line.
+
+Subtractive drums:
+
+```aqua
+sequence name=kick pattern=x...x...x...x... step=.125 high=1 low=0
+voice name=kick_body wave=sine freq=54 gain=@/seq/kick env=ad attack=.002 decay=.14
+voice name=kick_click wave=noise gain=@/seq/kick hpf=2500 lpf=7000 env=ad attack=.001 decay=.035
+```
+
+Drums need body plus skin. Use sine/triangle bodies for kick/snare weight,
+filtered noise only for click, skin, dust, or air, and gates from target tempo.
+Noise alone is a placeholder unless it has band limits, a gate, and a musical
+job.
+
+Additive/PAD beds:
+
+```aqua
+layer name=pad engine=pad freq=@/chords/pad/root gain=@/mix/pad/gain
+harmonics name=pad_bank source=pad partials=1:.7,2:.25,3:.18,5:.08
+spectrum name=pad_air source=pad_bank centroid=1800 bandwidth=.35
+```
+
+Pads own harmonic field and emotional bed. Use harmonic banks and slow
+brightness/gain motion. Do not let a pad occupy every band for the full target
+unless the reference really does.
+
+Texture and recording color:
+
+```aqua
+texture name=dust_hat role=dust pattern=x..x..x. step=.125 gain=.08 sustain=30
+texture name=air_wash role=air gain=.035 sustain=30
+texture name=codec_bed role=codec gain=.04 sustain=30
+```
+
+Texture owns band-limited color, not arrangement. It should support a scene with
+motion, gates, or slow modulation. A static broadband noise voice is failure
+pressure.
+
+## Production Checklist
+
+- Producer brief: target feel, energy contour, meter, tonal center, section map,
+  role map, and mix priority.
+- First attempt: prove parsing, duration coverage, and audible lane ownership.
+- Later attempts: change one hypothesis at a time: timing, register, role
+  assignment, filter band, envelope, or section/mix motion.
+- Listening journal: write what sounded alive, fake, static, missing, or too
+  generic after every render.
+- Gap ledger: name missing AquaSynth primitives or sugar only when a concrete
+  production problem forced the workaround.
+
+## Failure Modes
+
+- Naming `kick`, `hat`, `pad`, or `syrinx` without audible role behavior.
+- Copying one stock drum grid across unrelated targets.
+- Letting texture keep the tail non-silent while composition dies.
+- Hand-writing isolated frequencies when the reference suggests a tonal center
+  or progression.
+- Treating a metric bump as a lesson without a reusable owner sentence.
+

docs/music-production-knowledge/open-music-theory-production-distill.md

@@ -0,0 +1,108 @@
+# Open Music Theory And Production Textbook Distill
+
+kind: source-distillation
+tier: core-doctrine
+topic: open music theory and digital production lessons for AquaSynth
+
+## Sources
+
+- Open Music Theory, https://viva.pressbooks.pub/openmusictheory/
+- Music Theory for the 21st-Century Classroom, https://musictheory.pugetsound.edu/mt21c/
+- Miller Puckette, The Theory and Technique of Electronic Music, https://msp.ucsd.edu/techniques.htm
+- Hack Audio, https://www.hackaudio.com/
+
+## Owner
+
+This distillation owns source-grounded general music and production knowledge
+for AquaSynth agents, so the music generator can reason from composition and
+signal-production fundamentals instead of imitating previous weak candidates.
+
+## Transfer Rules
+
+- Meter is a promise about expectation. Use it to place accents, repetition,
+  syncopation, fills, and section boundaries, not just to calculate step
+  seconds.
+- Melody needs contour, register, motive, and variation. A lead line should have
+  a recognizable shape, then repeat, answer, invert, truncate, sequence, or
+  intensify.
+- Harmony is motion plus gravity. Even simple progressions should imply
+  departure and return. Use roots, chord tones, pedal tones, and bass movement
+  deliberately.
+- Rhythm works through pattern, contrast, and hierarchy. Kick/snare/hat lanes
+  should form a groove with strong and weak positions, not independent blinking
+  lights.
+- Timbre is spectrum over time. Envelopes, filters, modulation, and saturation
+  should move the sound from attack to body to tail.
+- Mixing is arrangement made audible. Gain lanes, frequency separation, and
+  automation decide which role owns attention at each section.
+
+## AquaSynth Patterns
+
+Melodic motive:
+
+```aqua
+meter bpm=132 beats=4
+scale name=lead path=/seq/lead/freq root=220 scale=minor degrees=0,2,3,5,3,2,0,-2 step=.25
+sequence name=lead_gate pattern=x.x.xx.. step=.25 high=.75 low=0
+mix name=lead points=0:.00,2:.25,6:.18,10:.32,14:.12
+```
+
+Harmonic field:
+
+```aqua
+chords name=prog root=110 scale=minor progression=0,6,3,5 voicing=0,2,4 paths=/chords/prog/root,/chords/prog/third,/chords/prog/fifth step=bar
+mix name=pad points=0:.08,4:.18,8:.11,12:.24,16:.08
+```
+
+Groove hierarchy:
+
+```aqua
+sequence name=kick pattern=x...x..x....x... step=.125 high=1 low=0
+sequence name=snare pattern=....x.......x... step=.125 high=.8 low=0
+sequence name=hat pattern=x.x.x.xx.x.x.xxx step=.125 high=.18 low=.03
+```
+
+Production automation:
+
+```aqua
+mix name=bass points=0:.20,4:.26,8:.14,12:.31,16:.18
+mix name=air points=0:.02,4:.05,8:.03,12:.07,16:.02
+```
+
+## Composition Moves
+
+- Repeat with change: keep one parameter stable while another evolves. Examples:
+  same rhythm with different degrees, same degrees with a denser gate, same pad
+  chord with brighter filter motion.
+- Call and response: a lead phrase should leave space for bass, percussion,
+  chord stab, or texture answer.
+- Register contrast: keep bass low, lead in a bounded melodic register, and pads
+  wide but not louder than the role carrying attention.
+- Section contrast: intro, main groove, break, rise, drop, and outro can be
+  represented by lane gain curves before timbre gets fancy.
+- Energy contour: density, brightness, loudness, and rhythmic subdivision are
+  separate levers. Move one or two deliberately.
+
+## Digital Production Moves
+
+- Attack/body/tail: split percussive sounds into transient click/skin and tonal
+  body; filter each component differently.
+- Subtractive shaping: start rich or noisy, then use filters/envelopes to carve
+  the useful band. Do not confuse raw oscillator choice with final timbre.
+- Additive shaping: build sustained tones from harmonic relationships, then
+  automate gain/brightness slowly.
+- Modulation: use LFO/tremolo/FM/AM for motion, but keep rate and depth tied to
+  the song grid or expressive gesture.
+- Space and air: model ambience as low-gain shaped texture or delayed motion,
+  not as a full-band noise floor.
+
+## Failure Modes
+
+- A loop with no phrase contour is not melody.
+- A progression with no role using its chord tones is metadata, not harmony.
+- A drum grid with no body/skin separation becomes weak noisy ticking.
+- A pad with no entrance, exit, or brightness motion becomes wallpaper.
+- A mix with every lane always on has no foreground.
+- A source citation is not a lesson unless it lowers to a current AquaSynth
+  action.
+