Choroboros Documentation

Version target: 2.04-beta

This document explains how Choroboros is organized today: the front panel workflow, the Dev Panel architecture, the modular core assignment system, the tutorial flow, and the full interactive console command surface.

It is written as one continuous learning path so you can read top-to-bottom without jumping around.

1.1 Preset Browser & Top Header Bar

The top header bar contains the Kaizen DSP logo, a preset browser, the engine color selector, and an animated drawer with quick-access buttons.

Preset Browser

• Navigate presets: Use the ‹ and › arrows to cycle through factory and user presets, or click the preset name to open a dropdown menu.
• Save a user preset: Click the + button, type a name, and confirm. Your current parameter state and engine selection are stored as an XML file.
• Delete a user preset: Select it, then click the − button. Factory presets cannot be deleted.
• No preset active: If you tweak any parameter after loading a preset, the preset name clears to indicate you have moved away from a stored state.

Factory Presets (7)

Animated Drawer

Click the arrow icon at the top right of the header bar to expand the drawer. It reveals four icon buttons:

• DEV — Opens the Dev Panel window.
• About — Version, company, and JUCE info.
• Help — Links to documentation and known issues.
• Feedback — Opens the feedback dialog, which pre-fills your email client with usage stats (DAW, format, sample rate, buffer size, CPU, RAM) and the last 64 session log events.

2. Quick Start

1. Load Choroboros on a track in your DAW.
2. Choose an engine color and HQ mode.
3. Set rate, depth, offset, width, color, mix.
4. Open Dev Panel for deep tuning and diagnostics.
5. In Dev Panel, use this loop:
   1. Set target: Profile + Core + HQ.
   2. Shape movement in Modulation.
   3. Shape frequency and response in Tone.
   4. Validate telemetry and trace matrix.
   5. Persist with JSON/script/defaults only after validation.

3. Main Plugin Controls

The front panel is the fast performance surface: six knobs and sliders (Rate, Depth, Offset, Width, Color, Mix), plus the engine selector and HQ toggle — eight host-visible parameters total. It is intentionally compact so host automation stays stable while deeper DSP tuning lives in Dev Panel.

3.1 Primary Automation Surface

These are the host-visible control IDs exposed by the processor:

3.2 What the Color Macro Means Per Engine

3.3 Direct Value Editing and Units

Each value readout under a control is editable. Double-click a value text field, type a value, and commit.

• Rate: accepts Hz values (example: 0.35, 2.5 Hz).
• Depth/Width/Color/Mix: accepts either normalized values (0.0..1.0 or 0.0..2.0 for Width) or percentages (example: 65%).
• Offset: accepts degrees (example: 120, 120 deg, 120°).
• Invalid input is rejected and the previous value is restored.

3.4 Fast Gestures and Defaults

• Double-click any slider to return it to that parameter's default value.
• Right-click the Rate slider to open the host-BPM sync menu with straight, triplet, and dotted subdivisions.
• Rate sync menu only enables entries inside valid mapped range and writes back to the real underlying raw parameter.

3.5 Engine and HQ Visual Behavior

• Changing Engine updates the front-panel theme colors, background art set, and value text accent color.
• HQ switch animates and also drives the lit overlay layer on the panel background.
• Value text color follows engine accent unless a custom override mode is enabled in layout tuning.

3.6 Utility Buttons (Top Bar)

3.7 Front Panel Workflow (Practical)

1. Choose Engine + HQ first, because Color meaning depends on target engine/mode.
2. Set mix to 40% to 60% as a starting point.
3. Use Rate/Depth to set movement amount and speed.
4. Set Offset/Width for stereo behavior.
5. Use Color last for engine character shaping.
6. If needed, open Dev Panel and continue with engine internals and validation.

3.8 Tooltips and Discoverability

The front panel ships with contextual hover help for all major controls:

• Each macro control has a behavior-focused tooltip.
• Engine selector and HQ toggle explain quality/algorithm intent and trade-offs.
• Top utility buttons (DEV/About/Help/Feedback) describe what opens and why to use it.

3.9 Main Window Behavior

• Main plugin editor is fixed-size by design to preserve visual alignment.
• Default editor size is 700 x 363 (then UI scale is applied).
• The Dev Panel window is where deep, resizable editing and diagnostics happen.

4. Dev Panel Manual

4.1 Open and Window Behavior

• Open the panel from the plugin editor DEV entry.
• Panel is resizable and always-on-top.
• Minimum size is 1028 x 525.

4.2 Mental Model

The Dev Panel is split into two columns:

• Left Inspector: readouts and controls for the currently selected tab/subtab.
• Right Visual Deck: cards, visualizers, workbenches, and action rows.

The top row of controls defines the active editing target, then each tab changes what you can inspect and edit for that target.

4.3 Top Target Controls

At the top of the right column, these controls are always visible:

4.4 Overview Tab

Subtabs

• Signal Flow
• Delay Visual

What you see

• Left inspector sections: Active Parameters (start here), Derived State.
• Right cards: signal chain view and delay trajectory view.

How to use it

1. Confirm target (Profile/Core/HQ).
2. Read raw to mapped values in inspector.
3. Use Delay Visual to confirm smooth movement before deep tuning.

4.5 Modulation Tab

Modulation is unified (no second row subtabs).

What you see

• Left inspector: LFO Readouts (passive monitor).
• Right cards in one stack:
  • LFO Left
  • LFO Right
  • Delay Trajectory
  • LFO Control Workbench

LFO Control Workbench controls

• LFO Rate (Hz)
• LFO Depth (%)
• Stereo Offset (deg)
• Stereo Width (x)

4.6 Tone Tab

Subtabs

• Spectrum
• Engine Response

Spectrum subtab

• Left inspector sections: Analyzer Controls (for cards above), Tone Readouts (passive monitor).
• Right card: spectrum and HP/LP overlay.

Engine Response subtab

Cards are engine and HQ specific. The panel chooses cards based on active Profile and HQ mode.

4.7 Engine Tab

Subtabs

• Signal Flow
• Engine Identity
• Dynamic macro label from selected core (for example Bloom Macros, Tape Macros, Orbit Macros, Ensemble Macros)

Signal Flow subtab

• Shows engine signal flow card.
• Core row uses active core descriptor label (not fixed per color anymore in modular mode).

Engine Identity subtab

• Engine Identity Guide card.
• Core Assignment card:
  • Enable Modular Cores (DevPanel)
  • NQ Core chooser
  • HQ Core chooser
• Core Assignment Warnings card (duplicates are allowed, but listed).
• Engine Macro Workbench for main macros (Rate/Depth/Offset/Width/Color/Mix).

Third Engine subtab (dynamic label)

• Contains engine-specific macro controls tied to active core package.
• Cards are filtered by engine and HQ mode where needed (for example BBD only for Red NQ, Tape only for Red HQ).

Internals panels below Engine visual deck

In Engine tab, active internals panels are laid out below the deck on the right side. These include the active per-engine internals panel and conditional Red BBD/Tape sections when visible.

Core tokens

lagrange3, lagrange5, cubic, thiran, bbd, tape, phase_warp, orbit, linear, ensemble.

Legacy assignment map (when modular cores disabled)

4.8 Look and Feel Tab

Subtabs

• Mapping
• UI Feel
• Engine Layout
• Global Layout
• Text Animations

Engine Layout propagation menu

Many Engine Layout numeric controls support right-click propagation with two actions:

• Apply to all engine colours
• Apply to all HQ profiles or Apply to all NQ profiles (label adapts to current HQ state)

4.9 Validation Tab

Subtabs

• Telemetry
• Trace Matrix
• Console

Telemetry

Telemetry readouts include:

• Audio thread process time (last and peak)
• Input and output peak hold
• Callbacks and parameter write counters
• Engine/HQ switch counters
• Host sample rate and block size
• Analyzer frame and delay probe data

Trace Matrix

Shows control flow from UI to runtime using rows like Rate/Depth/Offset/Width/Color/Mix with columns for raw, mapped, snapshot, and effective.

Console

Interactive command console with watch HUD, history, and direct state editing. Full command guide is in section 6 below.

4.10 Settings Tab

Top action rows (right side)

• FX presets: FX Off, FX Subtle, FX Medium
• Actions: Lock Controls, Reset to Factory, Set Current as Defaults, Copy JSON

Inspector sections in Settings tab

5. Interactive Tutorials

Tutorials are available from Settings and from console commands.

How to launch

• Settings -> Tutorial -> choose topic -> Run
• Console command: tutorial or tutorial <topic>

Available topics

core, overview, modulation, tone, engine, validation, bbd, tape, phase, bimodulation, saturation, envelope

Controls while tutorial is active

• Overlay buttons: Next, Next Section, Skip Tutorial
• Console: tutorial next, tutorial next section, tutorial skip, tutorial exit

6. Interactive Console Manual

6.1 Syntax and Input Rules

• Commands are space-separated tokens.
• Use help any time for in-console command list.
• Many commands return ERROR: messages when usage is wrong.
• Alias support exists via alias <name> <command>.

6.2 Engine and State Commands

engine <green|blue|red|purple|black>
hq <on|off>
view <overview|modulation|tone|engine|layout|validation|settings>
bypass <on|off>
solo <node>
unsolo

Notes

• view accepts aliases: internals, bbd, tape, look, lookfeel.
• bypass on forces wet mix to 0 and remembers previous mix for restore on bypass off.

6.3 Parameter Tuning Commands

set <target> <value>
add <target> <delta>
sub <target> <delta>
get <target>
reset <target>
reset all
lock <target>
unlock <target>
toggle <target>
macro <rate|depth|offset|width|color|mix> <0..100>
sweep <target> <start> <end> <time_ms>

Usage tips

• get prints current value and previous value when available.
• sweep creates a timed parameter ramp.
• lock and unlock affect panel interaction lock state for target controls.

6.4 History and Undo

undo [n]
redo [n]
history

Use these while listening to quickly A/B sequences of changes.

6.5 Introspection and Utilities

watch <target>
unwatch <target>
dump <color>
diff factory
search <term>
stats
list <color> [all] [full]
list globals [full]
fx <0|1|2>
clear

How list works

• Default output is deduped and capped for speed/readability.
• full shows all variant slugs.
• all (with color) includes globals plus engine-scoped entries.

6.6 Core and Slot Commands

core list
core show <id>
slot show
slot set <green|blue|red|purple|black> <nq|hq> <core_id>

Behavior details

• core list: prints all core IDs with token and display name.
• core show: accepts token or numeric index.
• slot show: prints slot assignment table and duplicate warning count.
• slot set: applies assignment immediately; duplicates return warning but still apply.

6.7 Import Export and Defaults

export script
import script [file_path]
cp json
save defaults
alias <name> <command>
help

I/O behavior

• export script: copies generated set ... command list to clipboard.
• import script: reads clipboard by default; if file path provided, reads that file.
• cp json: copies full state JSON to clipboard.
• save defaults: writes current state to user defaults file.

6.8 Practical Command Examples

Example A: Switch profile and tweak movement

engine purple
hq off
set rate 0.75
set depth 0.42
set width 1.40
stats

Example B: Core routing test

slot show
slot set red nq bbd
slot set red hq tape
slot show

Example C: Safe tune workflow with rollback

search bloom
watch green_bloom_gain
set green_bloom_gain 0.42
diff factory
undo
redo
export script

7. File Locations and Persistence

State and recovery files are stored in the user application data directory under Choroboros/.

• defaults_user.json
• defaults_factory.json
• defaults_user_recovery_last_attempt.json
• defaults_user_recovery_failed_<timestamp>.json
• defaults_save_failures.log
• devpanel_recent_touches.log

8. Performance and Troubleshooting

Performance checklist

1. Enable Lazy UI Refresh in Settings -> Performance for lower UI overhead.
2. Use Validation -> Telemetry to watch process time and write activity.
3. Keep Console output line cap reasonable (300 or 600) during long sessions.
4. Use list ... in deduped mode unless you specifically need full.

Common issues and fixes

9. Glossary

• LFO: Low Frequency Oscillator used to modulate delay motion.
• Trajectory: time path of moving delay target values.
• Zipper noise: audible stepping from abrupt parameter jumps.
• HPF / LPF: high-pass filter / low-pass filter.
• Raw: normalized control value from host/UI layer.
• Mapped: engineering-unit value after mapping/scaling.
• Snapshot: stored profile value in state.
• Effective: live runtime value currently used by DSP.
• NQ / HQ: Normal Quality / High Quality mode per slot.
• Core package: selected algorithm identity token for a slot/mode.
• Macro: high-level control that steers multiple lower-level behaviors.

10. Licenses and Attribution

This section documents what third-party frameworks and SDKs are used, where their licenses live in this repository, and what should ship with binaries for transparency.

10.1 Project Ownership and Primary License Files

10.2 Frameworks and SDKs Used in Build

10.3 Fonts, Branding, and UI Assets

10.4 Third-Party Notice Bundles in Repository

Additional vendor notices are archived under Licenses/, including:

• Licenses/Avid/
• Licenses/Third Party/

These folders contain notices from SDK/toolchain bundles and historical packaging work. Not every file in those folders is necessarily linked into the current shipping binary.

10.5 Public Project Links

• Kaizen Strategic AI
• Choroboros Beta Site
• info@kaizenstrategic.ai
• info@kaizenstrategic.ai

End of manual.