bass-foundry/docs/rivet/theory/README.md

# Theory: perceptual identity as a compositional resource

The research and local reference work are consolidated in
[psychoacoustics and creative direction](../research/psychoacoustics.md)
and [Devath measurements](../research/devath.md). This document connects
those findings to implementation choices and their practical limits.

## Findings and their interpretation

- Expectation is contextual. Recognition and deviation can both be rewarding;
  a mathematically novel note sequence is not automatically useful music.
- Groove depends on how a pattern is heard against an orienting frame. Intermediate
  syncopation was preferred in particular experiments, not established as a
  universal genre-independent optimum.
- Timbre can carry motion and contribute tension independently of MIDI pitch.
  Brightness, roughness, noisiness, loudness, and harmonic stability are distinct.
- Relative timing helps determine which events form one perceived stream. Passing
  a gesture between sound roles should preserve chosen connections.
- Preference depends on experience and culture as well as sensory mechanisms.
  Musical rules should inform experiments rather than rank artistic worth.

Primary research: [Cheung et al.](https://cms.mus.cam.ac.uk/publications/cheung-uncertainty-surprise/),
[Witek et al.](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0094446),
[Farbood and Price](https://bpb-us-e1.wpmucdn.com/wp.nyu.edu/dist/f/11865/files/2020/08/Farbood_Price_2017.pdf),
[Elhilali et al.](https://pmc.ncbi.nlm.nih.gov/articles/PMC2673083/), and
[McDermott et al.](https://www.nature.com/articles/nature18635).
The genre-specific design connections are hypotheses, not reported findings from
those studies or claims about Devath's intent.

## What the references establish

The seven local FLACs have measured differences in level, attacks, and broad
spectral texture. HENKA and Phantasy contain substantial reductions followed by
returns; Petals retains more consistent activity through much of its early span.
These observations motivate exploring both contrast and continuous development.
They do not identify exact notes, chords, emotional meaning, or melodic roles.

## Implemented creative model (0.3)

- A reusable gesture stores a short musical phrase and its explicit performance
  choices. A name records the producer's interpretation; it is not inferred emotion.
- A bounded branching history stores working ideas, ancestry, context, and pinned
  decisions. Composable moves create children rather than overwrite their parent.
- Two sound roles can share or answer a motif through explicit routing. Each role
  has a separate MIDI channel, gate, velocity response, octave offset, and patch
  timing profile. The roles are user-assigned, not separated from mixed audio.
- Each role can carry an optional, explicitly mapped MIDI CC trajectory. The tool
  sends controller data; the producer binds it to a synth macro. An internal voice
  does not simulate an arbitrary synth's timbre.
- Patch attack compensation is scheduled using a short lead-in, and estimated
  release is accounted for when setting note-off times. These are editable timing
  estimates, not an automatic model of the target patch. Re-audition after tempo
  changes because millisecond offsets are compiled at the audition tempo.
- Musical export stays on its original grid by default. Optional compensated export
  adds one bar of lead-in so early triggers have valid nonnegative MIDI times.

## Producer workflow and evaluation

Import or recall a gesture -> choose context and what to preserve -> explore a
proposal -> save a branch -> apply a move -> distribute sound roles -> map an
expressive controller -> audition through real patches -> keep or branch again.
Compare alternatives against the same surrounding loop and listening level.
The useful outcome is a section the producer can own and develop further.

All mappings and compensation are explicit. Original reference audio remains
local. The model does not claim source separation, automatic emotion recognition,
universal quality scoring, or a verified melodic transcription of Devath's tracks.

## Concrete limits and implementation

A gesture is at most two bars; a working phrase is four or eight bars.
Libraries and branch histories each retain up to sixteen entries. A branch
stores musical settings, source, harmony, the composed phrase, pinned sections,
and performance choices without recursively copying the history. Importing a
library merges validated entries with new identifiers. State versions 1 and 2
migrate to version 3; controller output is disabled by default.

Role assignment partitions existing notes, so it preserves a readable motif
before sound design. It is not source separation or independent counterpoint.
Controller curves span the phrase, interpolate at 32nd-note intervals and exact
control points, and reset to explicit stop values. Their effect depends entirely
on the synth mapping. Gates are capped at subsequent triggers in the same role;
estimated release cannot guarantee that a patch becomes silent at that point.
Negative attack triggers receive a warmup and a separate repeated-loop schedule.

Composition and performance compilation run away from the audio callback.
The callback uses fixed event storage and bounded control queues. Regression
checks cover history forks, migration, locks, two-role event identity, MIDI
channels/controller export, warmup/loop timing, mapping resets, and allocation-free
rendering. Actual patch perception, FL Studio routing, and producer usefulness
still require listening in the target workflow.

For implementation, see [creative history](../../../plugins/rivet/core/src/creative.rs),
[performance scheduling](../../../plugins/rivet/core/src/performance.rs), and
[FL Studio acceptance checks](../fl-studio.md).