Live sets — Bitwig Grid Bridge documentation

This guide turns Bitwig Grid into an attended performance system for Techno, Psytrance, Electro, and related live sets. It is an orchestration model, not a preset loader: the bridge plans musical roles, exposes safe control surfaces, and lets you perform host actions that the running Bitwig extension reports. The producer still listens, chooses the final arrangement, and decides when a change is musical.

The live-set model

A strong live set has three layers:

Material: kick, bass, percussion, texture, cues, and returns with clear frequency and rhythmic jobs.
Sections: scenes or phrase blocks with named energy, active roles, and a deliberate transition.
Agency: a small set of bounded gestures that change density, timbre, space, or role presence and can always land on a neutral state.

Start from a brief

Use grid_live_set_plan before building the set. The planner is non-mutating and returns a concrete role list, scene arc, macro contract, modulation routes, and host-action workflow.

{
  "brief": "142 BPM minimal raw techno for a dark room; stable kick and bass, sparse metallic accents, controlled agency",
  "style": "techno",
  "tempo": 142,
  "scene_count": 8,
  "density": 0.28,
  "motion": 0.38,
  "agency": 0.55
}

For Psytrance, use "style": "psytrance". Its default vocabulary is a short kick, rolling bass, scale-aware psychedelic mid layer, subdivision tops, and filtered atmosphere. For broken or syncopated material, use "style": "electro". If style is omitted, the brief is classified conservatively and falls back to Techno.

The output is a plan, not a project patch. It intentionally contains no live instance IDs, package UUIDs, port indexes, clip payloads, or assumed track indexes.

Build the material layer

Open a copy of the Bitwig project and keep the target track and device selected. For each role:

Call get_grid_capabilities and get_selected_device_state.
Call get_grid_graph only when the selected state reports graph_available: true and topology is needed.
Use grid_shape_start and grid_shape_compose for exposed controls, or resolve modules with search_grid_modules and modulators with search_grid_modulators for graph work.
Insert, tune, connect, and verify as separate operations. Read the graph again after each dependent mutation.
Keep the kick and sub path centered and mono. Put width, feedback, and bright nonlinear detail above the useful bass register.

A practical role order:

Order	Role	Musical test
1	Kick	Does the downbeat stay stable at the intended level?
2	Bass	Does the bass interlock without masking the kick?
3	Percussion or tops	Do rests and accents create groove rather than noise?
4	Texture or psychedelic layer	Does motion preserve the pulse and tonal center?
5	Return and cues	Does the effect mark a boundary without smearing it?

The grid_live_set_plan output supplies live-resolvable Grid source names as queries. Resolve each name against the current catalog; never substitute a similar module from an inventory snapshot.

Design agency as a control contract

Agency is not a large collection of free-running random parameters. Each gesture should answer five questions:

Field	Requirement
Destination	One primary musical job, such as bass bite or transition depth.
Safe range	The smallest range that produces a meaningful change without losing the role.
Neutral	A known value that restores the accepted groove.
Time scale	A phrase, bar, or gesture duration chosen for the destination.
Reset	A clear action or return ramp that lands on neutral.

Recommended macro vocabulary:

Scene energy: role mutes and bounded send amounts; not a master-volume replacement.
Bass bite: low-pass cutoff, resonance, or restrained drive; never direct uncontrolled sub widening.
Percussion chance: event probability or a named fill gate; keep the main motif intact.
Psy depth: AM/RM or wavefolder depth above the bass crossover; preserve a stable root and pulse.
Space send: filtered delay or return level that rises before a boundary and releases on the next downbeat.

Use grid_live_set_plan's macros records as the contract. They include a safe_range, neutral, and reset instruction. Its modulation_routes records name a source role, destination, time scale, depth, polarity, and rationale. Treat those values as starting points for a preview, not permission to write the selected device.

Controlled modulation patterns

Musical goal	Source	Destination	Typical time scale	Boundary
Hypnotic bass pressure	Clock or shaped Segments	Filter bite	8–16 bars	Root and kick remain stable
Psychedelic movement	Smoothed S/H LFO	Sideband depth	8 bars	High-pass the effect layer
Fill variation	Chance or Steps	Percussion probability	1 bar	Main kick/bass cell unchanged
Transition	Segments	Delay send or return level	4–8 bars	Release on the downbeat

Avoid independent random modulation on every parameter. It reduces performer agency because the cause of a sonic change becomes unreadable. Prefer one modulation route at a time, preview its full range, and add another only when the first destination remains useful throughout the phrase.

Use Bitwig host actions safely

The extension exposes a dynamic host-action catalog. These actions can be used for transport, clip, scene, or navigation gestures when the running Bitwig instance reports them. Action IDs are live session facts.

Call grid_list_actions with a focused query:
```
{"query": "scene"}
```
Review returned id, name, and menu values. Do not infer an ID from a display label or from another Bitwig version.
Invoke one exact returned ID with grid_invoke_action and explicit confirmation:
```
{"action_id": "<exact returned id>", "confirm": true}
```
Re-read the relevant state and listen. A successful action response proves invocation, not that the resulting phrase sounds correct.

The returned id is the exact wire-safe identifier to pass back. Bitwig action IDs may contain spaces, so the extension percent-escapes non-token characters in the returned ID; display names and menu labels remain unchanged.

Host actions are deliberately not hard-coded as transport_play or launch_scene tools because Bitwig action IDs and availability are dynamic. The action invoker can affect the project or transport, so use it only for an identified live gesture and keep grid_project_undo available for operations that participate in host undo.

Scene arc examples

Minimal Techno

Use 8-bar scene blocks at 142 BPM as a starting grammar:

foundation -> pressure -> friction -> peak
     -> reset -> return -> late pressure -> exit

The peak is temporary. The reset is structural subtraction, not simply a lower master volume. Change one accent, texture gesture, or return behavior when the motif returns; preserve the downbeat and tonal center.

Psytrance

Use 16-bar blocks when the rolling bass needs more time to settle:

ignition -> motion -> mutation -> drop
       -> re-entry -> lift -> dark turn -> landing

The psychedelic layer can evolve through sidebands and filter motion, but the kick/bass lattice must remain legible. Reserve wide atmosphere for material above the low end and reset its depth before the bass re-enters.

What the bridge can and cannot create

The bridge can inspect and mutate supported selected-device controls and Grid graphs, discover installed devices, inspect 16 siblings and insert/replace/remove devices with fresh selection tokens and authorization, navigate all channels, expose host actions, and provide preview/recovery workflows. The song compiler exports full-length type-1 MIDI and supports reviewed native arranger import, one-track clip/source inspection and explicit guarded loop-flag control. That is distinct from arbitrary launcher clip editing, scene naming or direct Bitwig project-file authoring.

Therefore:

use the plan to construct clips and scenes in Bitwig's native interface or through actions the live action catalog actually exposes;
for a deterministic arranger song, use the song workflow, inspect actual clips with grid_inspect_arranger, and disable looping for a linear score through grid_set_clip_loop. Re-inspect flags, counts/spans and geometry; source summaries are not loop-expanded playback or audio proof;
inspect role devices and replace unintended import-created Organ instruments with a fresh expected_selection_token, rather than stacking voices; listen afterward, since a submitted receipt verifies neither instruments nor audio;
set tempo/meter and play/stop through explicit project-token-guarded grid_song_transport operations; the derived import removes tempo/meter metadata, not arbitrary raw MIDI events, and does not start playback;
do not fabricate clip IDs, scene indexes, module topology, or project-file edits;
if graph_available is false, continue with exposed controls when they are sufficient and report that graph construction is unavailable;
if a requested live-set step is not represented by returned capabilities, stop at the boundary instead of pretending it was created.

Recovery and listening

Before a structural or parameter batch, save a parameter snapshot or note the current graph. Match recovery to the change:

grid_shape_undo for the latest applied shaping revision;
apply_parameter_snapshot for exposed controls;
grid_project_undo for the latest Bitwig host mutation;
grid_project_redo only after confirming the undone operation.

After recovery, re-read state. During performance, use the macro neutral values and reset gestures from the plan rather than guessing a landing point.

Finish each pass by asking one focused listening question: “Does the bass still interlock at the peak?”, “Does the psychedelic layer move without masking the kick?”, or “Does the reset leave enough tension for the return?” State read-back cannot answer those questions; the producer listening in Bitwig decides.