175 lines
10 KiB
Markdown
175 lines
10 KiB
Markdown
# FL Studio plugins
|
|
|
|
Two Rust CLAP plugins: **Motif Storyboard**, a melodic composition companion,
|
|
and **[Resonance Compressor](docs/resonance-compressor.md)**, a mixing effect
|
|
with spectral resonance control and a full native engineer panel.
|
|
|
|
GitLab CI builds a Windows x86-64 ZIP containing both plugins, setup guides,
|
|
licenses, and checksums. Download it from the **windows** job artifacts.
|
|
|
|
## Motif Storyboard
|
|
|
|
A Rust composition companion for an experienced producer developing their own
|
|
melodic ideas. Version 0.3 explores rhythm, space, contour, harmonic arrivals, and
|
|
returns, with reusable gestures, branching ideas, and two sound roles.
|
|
|
|
|
|
|
|
## Write with it
|
|
|
|
1. Import a monophonic MIDI motif of up to two bars in 4/4, or load the demo.
|
|
2. Choose a task: **Develop the motif**, **Write an answer**, **Make room**, or
|
|
**Find a return**. Choose a settled or open ending and a four/eight-bar length.
|
|
3. Decide what defines the idea. **Keep groove** fixes note positions and lengths;
|
|
**Keep contour** protects the direction of movement, allowing flattened steps
|
|
at register limits. Click source notes to lock the whole note, pitch only, or
|
|
rhythm only. Clicking uses the currently selected lock mode. Locks
|
|
and identity constraints take precedence over the proposed transformations.
|
|
4. Optionally open **Harmony** and import a chord/bass MIDI track (up to eight
|
|
bars), or create and edit a four-chord progression. Imported overlapping notes
|
|
become pitch-class regions with the actual lowest held pitch; the tool does
|
|
not guess chord roots or chord names. Empty regions remain gaps, and short
|
|
contexts repeat. Harmony guides strong notes and arrivals; the preview plays
|
|
the melody only. Supplied chord tones may extend beyond the selected scale.
|
|
5. Explore alternatives. A deterministic pool of eight transformation families
|
|
supplies up to three distinct proposals, selected for the task and differences
|
|
in rhythm, density, duration, and pitch. Fully constrained motifs may yield
|
|
fewer than three; cosmetic velocity differences do not count as new ideas.
|
|
6. Select a proposal and pin its two-bar sections. Select another to fill the
|
|
remaining sections, or explore another take. Preview and export the combined
|
|
phrase from the fixed bottom toolbar. Keep a combined result to retain it
|
|
independently of new proposals; undo/redo switches the kept result and its
|
|
previous value. Individual proposals and kept results can also be exported.
|
|
|
|
The opening quotation stays intact. Later sections use displaced entries,
|
|
repeated pickups, fragments, subtraction, short/long answers, changed endings,
|
|
register contrast, and returns. These are compositional suggestions, not promises
|
|
of an emotion or of commercial originality. Different seeds choose structured
|
|
alternatives; they do not independently randomize every pitch.
|
|
|
|
Pins survive task/seed/harmony changes and regeneration. Changing the motif,
|
|
its locks, or the phrase length clears pins. Pinned sections override newly
|
|
proposed material. Unsafe boundaries in legacy candidates are rejected instead
|
|
of truncating sustained notes. Changing generation inputs clears current
|
|
proposals while retaining kept work.
|
|
|
|
## Audition and commit
|
|
|
|
**Internal voice** provides two simple reference voices. **MIDI output** sends
|
|
notes and optional CC curves on the configured channels to routed external synths
|
|
and mutes the internal voice. Solo defaults to channel 1.
|
|
Looping is optional and enabled for new sessions. When audition is already
|
|
running, another selection waits until the next two-bar boundary or current
|
|
phrase end. Note-offs precede repeated same-pitch note-ons; stop, replacement,
|
|
loop boundaries, reset, restoration, and mode changes release active output notes
|
|
on the processing thread. Queued auditions are canceled by Stop.
|
|
|
|
**Host tempo** follows tempo, with the local BPM as fallback. It does not align
|
|
the initial audition to the DAW's song position: start it at the desired point
|
|
in the project loop. Host start never initiates audition; host stop silences it.
|
|
Exported MIDI is in musical ticks and carries the local BPM as its tempo event.
|
|
Native OS MIDI drag-out is not implemented; export files to commit a phrase.
|
|
See [FL Studio setup and acceptance checks](docs/fl-studio.md).
|
|
|
|
Open **Gestures, moves, and branches** to save a source or selected two-bar
|
|
section with its performance choices. Export/import a gesture library between
|
|
projects. Save a branch before experimenting; restore any branch and make a new
|
|
child with subtraction, a delayed entry, longer gates, or transposition.
|
|
Moves respect pins and locks, reject unsafe overlaps, and report when constraints
|
|
leave nothing to change. Libraries and histories each hold up to 16 entries;
|
|
remove a gesture or a leaf branch to make room.
|
|
|
|
Open **Sound roles and expressive gestures** to pass existing notes between two
|
|
patches: alternate events, alternate question/answer bars, or divide strong beats
|
|
from replies. These modes distribute a monophonic phrase rather than generate
|
|
a second independent melody. Assign separate MIDI channels and explicitly map
|
|
each optional CC lane to a synth macro. Curves are normalized over the whole
|
|
phrase, with editable points and rise/fall/arch/pulse starting shapes.
|
|
Names describe your intent; the plugin does not infer feelings.
|
|
|
|
Patch profiles set register offset, gate, velocity, and estimated attack/release.
|
|
MIDI audition uses a short warmup for early triggers. Re-audition after a tempo
|
|
change to recompile millisecond offsets. Compensation estimates trigger timing;
|
|
it does not measure patch latency or model its sound. Default export retains
|
|
musical positions; compensated export adds one bar of lead-in. Role tracks carry
|
|
names, channels, and CC curves. Stop resets mapped controllers to their chosen
|
|
stop values. Internal audition does not reproduce mapped timbre.
|
|
See [the theory and producer workflow](docs/theory/README.md).
|
|
|
|
Sessions save inside the host project and can be saved/loaded as JSON. Version-1/2
|
|
sessions and the original host field identifier remain supported; older sessions
|
|
retain one-shot audition. New sessions persist harmony, task, lock modes on notes,
|
|
pins, proposals, kept history, gestures, branches, patch profiles, CC curves, and
|
|
audition settings. JSON state is bounded at 16 MiB; gesture libraries at 2 MiB. File export/save refuses to
|
|
silently overwrite an existing file.
|
|
|
|
## Build and verify
|
|
|
|
The plugin is CLAP-only, using NIH-plug pinned to
|
|
`de421011f41a6d10fc8c7a6084e4f4dee0143683` with egui 0.31. VST3 is disabled.
|
|
The independent plugin workspace keeps Git/GUI downloads separate from engine
|
|
and MIDI tests. Stable Rust and Python are required for packaging.
|
|
|
|
```sh
|
|
cargo test --workspace --offline
|
|
cargo clippy --workspace --all-targets --offline -- -D warnings
|
|
cargo run -p story-preview --offline -- demo /tmp/motif-demo
|
|
```
|
|
|
|
The headless demo writes source/candidate MIDI, a session JSON, and a WAV using
|
|
the same engine and voice as the plugin. To use existing MIDI, note-track indices
|
|
exclude conductor-only tracks and start at zero. Optional harmony arguments
|
|
accept a separate polyphonic MIDI file and track index.
|
|
|
|
```sh
|
|
cargo run -p story-preview -- develop motif.mid 0 /tmp/phrase
|
|
cargo run -p story-preview -- develop motif.mid 0 /tmp/phrase-with-chords chords.mid 0
|
|
cargo run -p story-preview -- session saved-session.json /tmp/rendered-session
|
|
```
|
|
|
|
Windows needs the Rust MSVC build tools; Linux needs X11/OpenGL development
|
|
headers, plus ALSA/JACK headers for standalone. The GitLab pipeline installs its build dependencies. A MinGW cross-build needs the `x86_64-pc-windows-gnu` Rust target and
|
|
`x86_64-w64-mingw32-gcc`.
|
|
|
|
```sh
|
|
python scripts/build-plugin.py # native CLAP
|
|
python3 scripts/build-plugin.py --standalone # Linux CLAP + app
|
|
python3 scripts/build-plugin.py --target x86_64-pc-windows-gnu
|
|
cargo test --manifest-path plugins/motif-storyboard/Cargo.toml --offline
|
|
cargo clippy --manifest-path plugins/motif-storyboard/Cargo.toml --all-targets --offline -- -D warnings
|
|
cargo run --manifest-path tools/editor-check/Cargo.toml --offline -- /tmp/editor.png
|
|
```
|
|
|
|
Packages are written to `dist/<target>/Motif Storyboard.clap`; builds do not
|
|
install into a DAW. The visual QA harness compiles the shared editor against the
|
|
same egui version and software-renders it without a display. Interactive window
|
|
embedding, FL Studio MIDI routing, and audible artistic evaluation still need
|
|
manual testing. The native Linux window cannot access X11 in this environment.
|
|
The root GitLab pipeline checks both plugins and cross-builds Windows CLAPs.
|
|
Linux is used for CI execution and local development, with no Linux release
|
|
artifact. A live GitLab run still needs verification on the configured runner.
|
|
|
|
## Design and references
|
|
|
|
[Theory findings and implemented design](docs/theory/README.md) connect the research
|
|
to practical controls. [Implementation plan](docs/variation-plan.md) records the musical and technical
|
|
choices. [Devath reference measurements](docs/devath-reference-notes.md) document
|
|
analysis of the seven supplied FLACs, with reproducible plots and explicit limits.
|
|
Original reference audio is excluded from source distribution.
|
|
|
|
- `story-core`: musical model, harmonic context, structured proposals, section
|
|
composition, session migration, and bounded playback clips.
|
|
- `story-midi`: bounded SMF 0/1 import/export. Rejects SMPTE, unsupported meters,
|
|
incomplete notes, and timing not exactly representable at 960 PPQ. Reports
|
|
ignored controllers/pitch bends. Polyphonic tracks work as harmonic context;
|
|
motif import requires monophony.
|
|
- `story-app`: worker jobs, revision handling, bounded queues, sample-accurate
|
|
preview/MIDI scheduling, and Windows/Zenity dialogs.
|
|
- `motif-storyboard`: CLAP wrapper, host persistence, editor, and standalone.
|
|
|
|
Tests cover musical constraints/diversity, harmony, legacy state, section seams,
|
|
MIDI round trips, sample timing, looping, queued switches, note releases, and
|
|
zero allocation/deallocation during rendering and queued clip replacement. The
|
|
CLAP ABI test verifies discovery, note-output port exposure, state restoration,
|
|
and silent startup at several sample rates and buffer sizes.
|