diff --git a/README.md b/README.md index 129d185..8608f00 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,186 @@ -# Rivet & Patina +# FL Studio Suite -Six Rust CLAP plugins for writing, designing and mixing bass music. +**Rust CLAP plugins for writing, designing and mixing bass music in FL Studio.** -| Plugin | Purpose | Guide | -| --- | --- | --- | -| **Rivet** | Tell a MIDI motif as a story on a storyboard of roles, with joined seams | [Rivet](docs/rivet/README.md) | -| **Patina** | Smooth harsh resonances while retaining tone and transient character | [Patina](docs/patina/README.md) | -| **Anvil** | Give every bass note the same clean sub: one level, one start phase | [Anvil](docs/anvil/README.md) | -| **Crucible** | Capture the last bars, slice them and export clean, key-labelled samples | [Crucible](docs/crucible/README.md) | -| **Lathe** | EQ the harmonics of the played note: a cut on harmonic 3 stays on harmonic 3 | [Lathe](docs/lathe/README.md) | -| **Temper** | Distort every note the same: level and tone filters follow the note | [Temper](docs/temper/README.md) | +![CLAP](https://img.shields.io/badge/format-CLAP-6c5ce7) +![FL Studio 2024.1+](https://img.shields.io/badge/FL%20Studio-2024.1%2B-ff8a00) +![Windows x64](https://img.shields.io/badge/platform-Windows%20x64-0078d4) +![Rust stable](https://img.shields.io/badge/Rust-stable-b7410e) +![License ISC](https://img.shields.io/badge/license-ISC-2ea44f) + +Riddim and dubstep basses change patch on every switch-up. Fixed-frequency tools +then act differently on every note: the sub jumps, an EQ cut lands on another +harmonic, the distortion gets fizzy on one note and dull on the next. Most plugins +in this suite follow the played note, so a setting means the same thing on every +note. Each plugin is a separate product with its own version, guide and release. + +## Plugins + +| Plugin | What it does | Load it on | Latency | Docs | +| --- | --- | --- | --- | --- | +| **[Rivet](docs/rivet/README.md)** | Tells a MIDI motif as a story on a storyboard of roles and joins the seams into one phrase | Channel Rack | none | [Guide](docs/rivet/README.md) · [Changes](docs/rivet/CHANGELOG.md) | +| **[Patina](docs/patina/README.md)** | Smooths harsh, ringing resonances while plain harmonic tone and transients pass | Any mixer track | one analysis frame | [Guide](docs/patina/README.md) · [Changes](docs/patina/CHANGELOG.md) | +| **[Anvil](docs/anvil/README.md)** | Replaces the sub with a clean mono sine: one level and one start phase on every note | Bass bus | 80 ms | [Guide](docs/anvil/README.md) · [Changes](docs/anvil/CHANGELOG.md) | +| **[Crucible](docs/crucible/README.md)** | Records the last bars all the time, then slices, cleans and exports key-labelled samples with one button | End of the chain to resample | none | [Guide](docs/crucible/README.md) · [Changes](docs/crucible/CHANGELOG.md) | +| **[Lathe](docs/lathe/README.md)** | EQ with one band on each harmonic of the played note: a cut on harmonic 3 stays on harmonic 3 | Bass, after the synth | ≈ 67 ms | [Guide](docs/lathe/README.md) · [Changes](docs/lathe/CHANGELOG.md) | +| **[Temper](docs/temper/README.md)** | Distortion that drives every note the same: level and tone filters follow the note | Bass | ≈ 67 ms + oversampling | [Guide](docs/temper/README.md) · [Changes](docs/temper/CHANGELOG.md) | +| **[Weld](docs/weld/README.md)** *(in development)* | Phase-aligns one bass layer to another layer through the sidechain, so the layers sum in the mids instead of cancelling | One layer's track | none | [Guide](docs/weld/README.md) · [Changes](docs/weld/CHANGELOG.md) | + +Plugins with latency report it to the host, so FL Studio compensates the delay. +Anvil, Lathe and Temper detect pitch from the audio. They can also take the +pitch from MIDI. Weld is a sidechain test build at the moment; the phase +alignment comes next. The names come from metalwork: a **rivet** joins pieces; **patina** changes a -surface while leaving its character; an **anvil** is the solid base everything is -struck on; a **crucible** melts material down to be cast again; a **lathe** turns -a piece so each cut lands the same all the way round; **tempering** sets how hard -and how tough a metal ends up. They share a Rust foundation and keep their own -musical purpose, code, documentation, and version. Ideas for further plugins are -collected in [docs/ideas.md](docs/ideas.md). +surface and keeps its character; an **anvil** is the solid base that everything +is struck on; a **crucible** melts material down to be cast again; a **lathe** +turns a piece so each cut lands the same all the way round; **tempering** sets +how hard and how tough a metal ends up; a **weld** fuses two pieces into one. + +## Editors + + + + + + + + + + + + + + +
Rivet editor
Rivet: storyboard composition		Patina editor
Patina: resonance smoothing
Anvil editor
Anvil: sub anchor		Crucible editor
Crucible: resampler
Lathe editor
Lathe: harmonic EQ		Temper editor
Temper: tracked distortion
+ +The previews are rendered headless from the real editor code by +`tools/editor-check`, so they match what the plugin draws. ## Install -Download the desired plugin's Windows ZIP from its Gitea release. Extract it -and copy its `.clap` file (`Rivet.clap`, `Patina.clap`, `Anvil.clap`, -`Crucible.clap`, `Lathe.clap` or `Temper.clap`) into: +1. Open the plugin's release on Gitea. Every plugin has its own release tag, + for example `lathe-v0.1.0`. +2. Download `-windows-x86_64-.zip`. You can check it against + the `.zip.sha256` file next to it. +3. Extract the ZIP and copy the `.clap` file into: -```text -C:\Program Files\Common Files\CLAP\ + ```text + C:\Program Files\Common Files\CLAP\ + ``` + +4. In FL Studio 2024.1 or newer, open **Options → Manage plugins**, enable + **Verify plugins**, and click **Find installed plugins**. +5. Load Rivet in the Channel Rack. Load the other plugins in mixer effect slots. + +Keep the font license (`licenses/`) with redistributed packages. + +Every branch and pull-request pipeline also builds a combined Windows preview +ZIP in its **windows** job. Use it to test unreleased changes. + +> **Upgrading from Motif Storyboard or Resonance Compressor?** These are now +> Rivet and Patina. The CLAP IDs and saved state are unchanged, so projects +> still load. Delete the old `.clap` files and rescan. + +## Build from source + +You need: + +- Rust stable and Python 3.11 or newer. +- For the Windows target on Linux: the `x86_64-pc-windows-gnu` Rust target and + MinGW (`x86_64-w64-mingw32-gcc`). +- For the native wrapper tests on Linux: pkg-config and the X11/XCB and OpenGL + development headers. Rivet's optional standalone also needs ALSA/JACK headers. + +```sh +# Tests for all engines, editors and tools +cargo test --workspace --locked + +# Formatting, tests and lints for one product, including its CLAP wrapper +python3 scripts/check-plugin.py --plugin lathe + +# Windows build, then the ZIPs (all plugins, or --plugin ) +python3 scripts/build-plugin.py --plugin lathe --target x86_64-pc-windows-gnu +python3 scripts/package-windows.py + +# Headless editor preview +cargo run --manifest-path tools/editor-check/Cargo.toml -- target/editor/lathe.png --plugin lathe ``` -In FL Studio 2024.1 or newer, open **Options → Manage plugins**, enable -**Verify plugins**, and **Find installed plugins**. Load Rivet in the Channel Rack; -load the others in mixer effect slots. +Plugin names for the scripts are `rivet`, `patina`, `anvil`, `crucible`, +`lathe`, `temper` and `weld`. Builds go to `dist//.clap`. No +script installs anything into a DAW. [Development and testing](docs/development.md) +has the full command list. -Normal branch/PR pipelines also provide a combined Windows preview ZIP in the -**windows** job. Releases are separate: tags such as `rivet-v0.4.0`, -`patina-v0.2.0`, `anvil-v0.1.0`, `crucible-v0.1.0`, `lathe-v0.1.0` and -`temper-v0.1.0` publish independently. See [release workflow](docs/releases.md). +## Quality checks -These names replace Motif Storyboard and Resonance Compressor. Their CLAP IDs -and saved-state identifiers are preserved; replace old scanned copies and rescan. +Every push and pull request runs these checks in CI +(`.gitea/workflows/check.yml`): + +- **Engine tests.** Every engine has tests for its signal behaviour and latency + against measured targets. +- **Realtime safety.** Patina, Anvil, Crucible, Lathe and Temper have a test + that fails if the audio thread allocates memory. +- **Host tests.** Each wrapper is loaded through the exported CLAP ABI, without + a DAW. The tests check the ports, the reported latency, state save and load, + and processing at 44.1, 48 and 96 kHz. +- **Lints.** `rustfmt` and `clippy -D warnings` for every package and wrapper. +- **Editor previews.** All editors are rendered headless and kept as CI + artifacts. +- **Windows builds.** Every `.clap` is cross-compiled and packaged. + +Release ZIPs are deterministic and contain checksums for every file. Things CI +cannot check stay manual: FL Studio routing, native window behaviour, and +listening. ## Repository ```text plugins/ - catalog.json Product metadata used by build and release tools - rivet/ - core/ Motifs, harmony, variation, history, performance - midi/ Standard MIDI import/export - app/ Worker jobs and real-time audition control - preview/ Offline MIDI/WAV development tool - plugin/ CLAP wrapper, editor, optional standalone - patina/ - core/ Spectral detector and attenuation engine - ui/ Patina's native editor - render/ Offline WAV evaluation - plugin/ CLAP audio-effect wrapper - anvil/ - core/ Pitch tracking, crossover and sub oscillator - ui/ Anvil's native editor - plugin/ CLAP audio-effect wrapper with MIDI input - crucible/ - core/ Input history, capture, slicing, cleanup and export - ui/ Crucible's native editor - plugin/ CLAP audio-effect wrapper - lathe/ - core/ Harmonic band bank tuned to the tracked note - ui/ Lathe's native editor - plugin/ CLAP audio-effect wrapper with MIDI input - temper/ - core/ Note-tracked filters, level normalising, oversampled shaper - ui/ Temper's native editor - plugin/ CLAP audio-effect wrapper with MIDI input + catalog.json Product metadata for the build, check and release tools + rivet/ core · midi · app · preview · plugin + patina/ core · ui · render · plugin + anvil/ core · ui · plugin + crucible/ core · ui · plugin + lathe/ core · ui · plugin + temper/ core · ui · plugin + weld/ core · ui · plugin common/ - ui/ Shared look: palette, embedded fonts, knobs and panels - dsp/ Shared filters, note tracking, oversampling, meters, WAV files -tools/editor-check/ Headless visual QA for all editors -scripts/ Shared build, packaging, release, and analysis tools -docs// Guide, changelog and editor preview per plugin -references/ Local reference audio; excluded from distribution + ui/ Shared look: palette, embedded fonts, knobs, panels, meters + dsp/ Shared filters, pitch tracking, oversampling, meters, WAV files +tools/editor-check/ Headless editor renderer for visual QA +scripts/ Build, check, packaging, release and analysis tools +docs// Guide, changelog and editor preview for each plugin +docs/ideas.md Problems in bass-music production and the plugin ideas for them +references/ Local reference audio; never distributed ``` -The root Cargo workspace contains the engines and supporting tools. Each CLAP -wrapper has an independent workspace and lockfile so SDK dependencies stay -separate. [Development and testing](docs/development.md) covers the commands. +Each product follows the same split: -```sh -cargo test --workspace --locked -python scripts/build-plugin.py --plugin rivet --target x86_64-pc-windows-gnu -python scripts/build-plugin.py --plugin patina --target x86_64-pc-windows-gnu -python scripts/build-plugin.py --plugin anvil --target x86_64-pc-windows-gnu -python scripts/build-plugin.py --plugin crucible --target x86_64-pc-windows-gnu -python scripts/build-plugin.py --plugin lathe --target x86_64-pc-windows-gnu -python scripts/build-plugin.py --plugin temper --target x86_64-pc-windows-gnu -python scripts/package-windows.py -``` +- `core` is the engine. It is plain Rust, does not depend on a plugin SDK, and + is tested on its own. +- `ui` is the egui editor, built on `common-ui`. +- `plugin` is the CLAP wrapper on a pinned NIH-plug revision. -Windows is the release target. Linux remains useful for tests, cross-compilation, -and headless editor previews. FL Studio routing, native window behavior, and -artistic listening still require manual checks in the target setup. +The root Cargo workspace holds the engines, editors and tools. Each wrapper is +its own workspace with its own lockfile, so SDK dependencies stay separate. +`plugins/catalog.json` is the single list of products. The scripts and CI read +it, so adding a plugin starts there. + +## Releases + +Each plugin is versioned and released on its own. Its version is the `version` +in `plugins//plugin/Cargo.toml`. A tag `-v`, for example +`temper-v0.1.0`, starts the release workflow. The workflow builds, checks and +publishes that plugin's Windows ZIP to a Gitea release. See +[docs/releases.md](docs/releases.md). + +## Roadmap + +[docs/ideas.md](docs/ideas.md) lists the production problems the suite targets, +the released plugins and the ideas for the next ones. + +## License + +ISC, see [LICENSE](LICENSE). The embedded Roboto Condensed fonts are under the +SIL Open Font License ([OFL.txt](plugins/common/ui/assets/OFL.txt)).