---
name: orchestron-performance-creator
description: Create, edit, import, validate, save, and live-test Orchestron performances through orchestron_cli, including musical structure, mixer and Master routing, shared effects, MIDI automation, per-note timing, melodic chord strumming, drummer ratchets with velocity ramps, and per-instance perf_controller settings.
---

# Orchestron Performance Creator

Use this skill to create or edit Orchestron performances through the skill-local `orchestron_cli` command. The CLI talks only to the running FastAPI backend; never edit SQLite directly.

## CLI Entry Point

Resolve this skill's directory from the location of this `SKILL.md`, whether it is
in a plugin installation, a standalone installation, or a repository checkout.
Python 3.13 and `uv` are required; first use installs the locked dependencies.
From that directory:

```bash
uv run --locked orchestron_cli --api-url http://localhost:8000/api -h
```

From another working directory, add `--project "/absolute/path/to/this-skill"`
to `uv run --locked`. Prefer running from the user's music working directory:
the CLI stores edit sessions in `.orchestron/` relative to the working directory.
When running from the installed skill directory, pass
`--session-file /absolute/path/to/work/edit-session.json` on every edit command.
Keep authored scores outside the installed skill and use absolute score paths.

Repository development example, from the repository root:

```bash
uv run --locked --project integrations/skills/orchestron-performance-creator orchestron_cli --json health
```

or use the thin wrapper:

```bash
uv run --locked --project integrations/skills/orchestron-performance-creator \
  python integrations/skills/orchestron-performance-creator/scripts/orchestron_cli.py --json health
```

Use `--json` for agent-readable output (`{"ok":true,"result":...}`) and structured `error.retry` hints:

```bash
uv run --locked orchestron_cli --json health
```

If the backend is not running, ask for the correct `--api-url` or whether to start it with `make run` from an available Orchestron repository checkout. The plugin contains the client tools, not the backend application.

## Workflow

1. Check backend health.
2. List/import patches as needed.
3. If composing new material, choose the musical brief before writing notes: ambient state, techno process, trance wave, or Goa/psy rise. For interactive melodic exploration, use `orchestron-composition-creator` first. When realising its accepted score, preserve the supplied notes and arrangement and use its channel-to-part mapping to choose instruments.
4. Start an edit session from an existing performance or a new draft.
5. Add instruments first, then run `edit instruments list` to discover their stable binding IDs and audio ports.
   For per-performance sound customization, read `references/performance_controllers.md`, discover the patch's controller node IDs, and stage overrides using `edit performance-controllers set`.
6. Read `references/effect_routing.md` and `references/mixer.md` to connect main outputs and sends and set strip/return/Master levels. The built-in `$master` needs no patch or rack instance. Use the optional `edit add-standard-effects --send-gain-db -12` only when the user wants dry instruments and reverb feeding a compressor into Master; read `references/standard_effect_patching.md` first. Effects are not mandatory.
7. Add sequencers/controllers/arpeggiators with explicit flags or a YAML/JSON score spec.
   Read [score specs](references/score_spec.md) for composition handoffs: `edit apply-score` accepts v1/v2, per-event velocity and local track timing. V2 checks explicit event boundaries and overlaps. Independent voices use separate melodic tracks on the same instrument channel, preserving GUI-compatible note/chord cells. Apply a whole-song score once to a fresh staged draft; the command appends tracks.
   For selected early/late notes or syncopated patterns, read [per-note timing](references/step_timing.md). Use `edit sequencers list` to discover tracks, then `edit step-timing list|set|reset` to inspect or adjust individual melodic steps and drum hits.
   For drum rolls, read [drummer ratchets](references/step_ratchets.md). Use `edit ratchets list|set|reset` or score `step_ratchets` to set 1–8 hits with optional final velocity. These edits preserve cell activation.
   For strummed chords, read [melodic strumming](references/step_strum.md). Use `edit strum list|set|reset` or score `step_strum` / inline event and progression fields. Direction is off/up/down; spread is 0–100% of one local step, with each note retaining its duration.
8. Run `edit validate`; this asks the backend to resolve every source outlet to its target inlet and rejects missing ports, invalid targets, and feedback loops.
9. Commit only after validation succeeds.
10. For live testing, use `edit create-runtime --start`. After rack, patch-definition, or route changes, use `edit rebuild-runtime`; use `edit push-runtime` when only sequencer, mixer, or performance-controller values changed. Always-on instruments need a rack restart to adopt controller changes.

## Core Commands

```bash
uv run --locked orchestron_cli --json patches list
uv run --locked orchestron_cli --json patches formulas set "Lead Patch" --target filter.xcf --expression "0.1 * in1"
uv run --locked orchestron_cli --json performances list
uv run --locked orchestron_cli --json edit begin --new --name "Agent Sketch"
uv run --locked orchestron_cli --json edit add-instrument --patch "TB303" --channel 2 --binding-id bass
uv run --locked orchestron_cli --json edit instruments list
uv run --locked orchestron_cli --json edit performance-controllers list --binding bass
# Use an actual node ID reported by the preceding command:
uv run --locked orchestron_cli --json edit performance-controllers set --binding bass --node attack --value 0.04
uv run --locked orchestron_cli --json edit performance-controllers reset --binding bass --node attack
# Optional preset, after confirming the reverb/compressor patches exist:
uv run --locked orchestron_cli --json edit add-standard-effects --send-gain-db -12
uv run --locked orchestron_cli --json edit routes list
uv run --locked orchestron_cli --json edit mixer list
uv run --locked orchestron_cli --json edit mixer strip set --binding bass --gain-db -6
uv run --locked orchestron_cli --json edit mixer strip set --binding '$master' --gain-db -3
uv run --locked orchestron_cli --json edit add-melodic --channel 2 --steps "s0=C3:min7/4s s4=F3:dom7/4s"
uv run --locked orchestron_cli --json edit sequencers list
# Replace voice-1 with the melodic track ID reported above:
uv run --locked orchestron_cli --json edit strum set --track voice-1 --pad 1 --step 0 --step 4 --direction up --spread 40
uv run --locked orchestron_cli --json edit add-melodic --channel 2 --grid-pattern "C3 . . ." --pad-grid-pattern "2=F3 . . ." --pad-loop "A P4 A" --pad-loop-group "A=1 2"
uv run --locked orchestron_cli --json edit add-drummer --channel 10 --groove backbeat
uv run --locked orchestron_cli --json edit validate
uv run --locked orchestron_cli --json edit commit
uv run --locked orchestron_cli --json edit create-runtime --start
```

Pattern-pad and pad-loop CLI syntax:

- `--pad 1..8` assigns the primary `--steps`, `--grid-pattern`, `--groove`, or `--curve` to that pad.
- Repeat `--pad-steps`, `--pad-grid-pattern`, `--pad-groove`, or `--pad-curve` as `PAD=VALUE` to define additional pads.
- Use `--pad-loop "1 2 P4 1"` for root pad-loop sequences. Pad tokens are `1..8`; pause tokens are `P1`, `P2`, `P4`, `P8`, and `P16`.
- Use repeated `--pad-loop-group "A=1 2"` and `--pad-loop-super-group "I=A A"` for nested sequences.

## References

CLI and data formats:

- For melodic step/chord syntax, read `references/chord_syntax.md`.
- For YAML/JSON score specs, read `references/score_spec.md`.
- For early/late notes, syncopated patterns, CLI timing inspection/editing, and score timing fields, read [per-note timing](references/step_timing.md).
- For drummer rolls, velocity ramps, `edit ratchets` commands and score `step_ratchets`, read [drummer ratchets](references/step_ratchets.md).
- For melodic chords played low-to-high or high-to-low, tempo-synced spread, `edit strum` commands and score fields, read [melodic strumming](references/step_strum.md).
- For `perf_controller` discovery, per-instance overrides, reset, persistence, exports, and live updates, read `references/performance_controllers.md`. These I-rate instrument settings are separate from MIDI CC controllers and controller sequencers.
- For patch graph input formulas such as `0.1 * in1`, read `references/patch_formulas.md`.
- For main/send routing, port discovery, Master, direct output, validation, and runtime replacement, read `references/effect_routing.md`.
- For strip/return/Master gain, balance, mute/solo, stereo send updates, and the TB303 Demo walkthrough, read `references/mixer.md`.
- For the optional reverb/compressor preset through Master, read `references/standard_effect_patching.md`.

Composition and genre guidance:

- For the end-to-end pattern-based writing process, read `references/composition_workflow.md`.
- For groove, syncopation, phrase lengths, pad-loop hierarchy, and layer roles, read `references/rhythm_layering.md`.
- For chord color, voicing, bass relationships, and arpeggiator use, read `references/harmony_arpeggiation.md`.
- For ambient, techno, trance, Goa trance, and psytrance blueprints, read `references/genre_blueprints.md`.

## Error Handling

When a command fails, read the structured `error.retry` field and adjust the next command. Do not commit after a failed validation. Use `--debug` only when backend response details are needed.