Workflows

Use the same short loop for every live change:

1. Observe the selected device and current capabilities.
2. Plan one audible or structural result.
3. Preview whenever the tool offers a preview.
4. Apply one confirmed mutation.
5. Verify by reading state and listening in Bitwig.
6. Recover through the narrowest authorized path after observing any ambiguity.

Keep the Bitwig project open, keep the target track and device selected, and avoid changing selection in Bitwig while an operation is in progress. A selected-device name is not a durable identity.

Compose and deliver a complete song

Composition can start without Bitwig. The live bridge is needed only when you observe a project, import notes, assign instruments, or change controls.

1. Normalize the brief. Use grid_track_plan for a stateless preview, or grid_track_start for a reviewed session. Name style, tempo, key/scale, meter, duration, phrase length, density, motion, seed, exclusions, structured intent, optional sections, locks and native-only source_policy.
2. Review and revise. Inspect the returned plan, including resolved constraints, inferences, unresolved_requests, section/phrase identities, role activity, score, synthesis_spec and automation_spec. Use grid_track_revise with exact session_id, revision, a declared scope, an exact role/section/phrase target when applicable, and flat changes. regenerate: true is deliberate; timbre edits cannot regenerate notes. Review the musical/control diff and fresh revision. There is no legacy whole-brief overrides revision path.
3. Export artifacts. grid_track_export writes song.mid and manifest.json in a new private subdirectory of an explicit output_dir (or configured BITWIG_MCP_SONG_OUTPUT_DIR). It never overwrites an existing artifact. Retain the returned source artifact_sha256.
4. Observe the insertion target. In a saved copy or disposable project, read grid_song_state, then list/select the intended track and read again. Review the exact project token, selected track and recording/capacity guards. The all-channel flattened bank includes hidden group children, FX and master; only an observed Group, Instrument, Audio or Hybrid is an import target.
5. Import once. Call grid_track_import with the exact session/revision, exported hash, freshly observed expected_project_token, and authorization. Native insertion creates arranger tracks after the selected track at beat zero, not at the playhead and not in launcher slots. It uses a private notes/markers copy with tempo and time-signature metadata removed; the original full MIDI is unchanged. The receipt reports submitted_sha256 separately.
6. Inspect actual clips and make the score linear. Read import status and fresh song state, resolve each role by bank index, then call grid_inspect_arranger(track_index). Require available, untruncated and complete metadata/count/detail observations before comparing clip bounds and source-note counts/spans with the manifest. Inspect loop_enabled, loop_start_beats and loop_length_beats, not just clip length. For linear scores, call grid_set_clip_loop for each enabled clip with observed native_id as native_clip_id, current expected_loop_enabled, enabled: false, fresh expected_project_token, track_index and authorization. Re-inspect flags, unchanged counts/spans and clip geometry. Bitwig may choose a per-role loop shorter than a full imported clip, causing unintended repetition even when all source notes are present. These native quarter-note summaries are one-track/non-atomic, not loop-expanded playback or audio proof. A receipt alone proves none of this; never replay an ambiguous import or loop edit.
7. Set global timing explicitly. Use separate grid_song_transport operations tempo and meter, each with fresh project token and authorization. Import and composition never change global timing or start playback implicitly. Read state between operations: a tempo/meter change invalidates the previous token.
8. Assign an instrument by role. Re-list the flattened bank and select each imported child by returned index. Navigate first, then inspect grid_list_devices: it is a 16-sibling window, not a recursive inventory; check window_complete. Import can supply default Organ instruments. Replace an unintended Organ rather than stacking another instrument: select it, refresh selection_token, resolve the catalog UUID with search_bitwig_devices, and call grid_insert_device with position: "replace", device_id, required expected_selection_token and authorization. For intentional additions use start/end on empty chains or before/after on a selected device, always with a fresh token. grid_remove_device also requires that token and authorization. Null tokens allow public reads, not native edits. Re-list devices, then read capabilities/graph state and build one role's path before adding more.
9. Resolve units and bound modulation. A role's envelope milliseconds, filter intent and wet/depth ceilings are starting intentions, not applied settings. Use grid_resolve_parameter_value for native scale conversion, and the graph/patch workflow for exact IDs and cables. Each modulation route needs a resolved destination, safe span, neutral value, polarity, rate and reset. Protect the kick/sub from width and uncontrolled feedback.
10. Listen and verify. Disarm tracks before explicitly authorized play. Use grid_set_track_state for token-guarded mute/arm changes, then refresh state. For a linear full-song pass, authorize grid_song_transport operation loop, enabled: false, with the fresh token; re-read arranger_loop_enabled and unchanged start/duration. This is the global arranger loop, independent of each clip's loop flag. Refresh the token. To start at beat zero, explicitly authorize grid_song_transport operation seek with position_beats: 0 and the fresh project token, read back position, then separately authorize play. Seek accepts finite 0–24576 quarter-note beats and refuses recording; it targets the controller-owned project, unlike an application-wide PlayFromStart action. Listen through full sections and the final landing; compare actual timbre, note routing, gain, tails and mix balance with the brief. Native peak meters are observations, not loudness, clipping or mastering certification. Stop playback explicitly.
11. Checkpoint the intentional result. Observe fresh grid_song_state: no recording, capabilities.project_save: true and project_save_pending: false. Authorize grid_song_save with its exact expected_project_token and optional output_dir parent root. Unlike grid_track_export, this saves the current Bitwig project, including its native arrangement/device state, rather than compiling a MIDI/manifest pair. It requires no composition session or artifact hash. The adapter allocates a fresh private bitwig-project-* directory; it must be outside existing Bitwig project folders. Native saving rejects nonempty or noncanonical destinations. The host writer can replace files: this is not a general atomic no-clobber guarantee. Retain output_directory and returned project_file. Ordinary save is not Collect and Save; external assets may remain external. native_save_completed proves only native completion and expected file presence, not full saved-content equivalence or audio acceptance. On requires_observation or transport loss, inspect the known directory and fresh pending/state observation; do not replay or delete output the host may still be writing. See checkpoint recovery.

Refine without replacing the song

• Sound: use grid_track_prepare_role on the explicitly selected empty native instrument Grid, or refine parameters on its exact existing binding. Review and apply the returned patch operations individually; no import, selection, clearing or playback is implicit.
• Notes: inspect the complete supported native source, bind the role with grid_track_bind_notes, then use scoped score revision, grid_track_preview_notes and grid_track_apply_notes. Review the exact identity-preserving diff; never replace a clip to avoid an unsupported edit.
• Voice and curves: use the native voice inspector for allocation/glide, and native automation previews for supported score-time Grid/mix curves. The bound vocal automation helper compiles supported vowel trajectories. A curve preview is not a playback-time stream or permission to start transport.
• After reload: re-observe exact identities. grid_track_reconcile_role can check an existing recipe with a complete explicit module map, without rebuilding it. Notes, automation and audio/listening evidence remain separate.

For a measured audition, explicitly prepare stopped, disarmed, non-recording transport with the engine active and arranger loop off; inspect exact Bitwig outputs, preview the span, then authorize capture and transport separately. Poll grid_audio_status; never resubmit a consumed capture. Measurements and RMS-matched comparisons inform listening but cannot approve the music.

See the Agent workflow playbook for complete sequences, the Tool reference for arguments and support boundaries for limits. Keep generated artifacts and all project/audio/listening records local.

Supported musical brief

Example input to grid_track_start:

{
  "brief": "Minimal techno, 142 BPM, F# minor, 4/4, 4 minutes, 8-bar phrases; no vocals and reverb",
  "density": 0.3,
  "motion": 0.35,
  "seed": 42
}

This is a deterministic bounded musical compiler, not unrestricted natural-language interpretation. Recognized explicit arguments must agree. Review defaults in inferences and unsupported clauses in unresolved_requests. Supported descriptors such as “less click” affect the synthesis specification, not the seed, score or live device.

Constraint	Supported form and limit
Style	techno, psytrance, hardgroove, electro; deep-ambient, weather-texture, distant-events, harmonic-drift, artifact-bed, generative-percussion. Existing aliases are listed by the style tools; ambient and soft-drift select deep-ambient. Unknown explicit styles reject.
Key	Pitch class A–G with optional #, b, ♯ or ♭, optionally a scale: F# minor, key: Bb, in D dorian. No octave in the key field.
Scale	minor, major, dorian, phrygian, mixolydian, harmonic minor, minor pentatonic, major pentatonic; aliases aeolian/natural minor → minor, ionian → major. Unsupported tonal modes reject.
Tempo	Finite 40–220 BPM: 142 BPM, tempo: 142, bpm=142. Written tempo requests without numbers reject.
Meter	Numerator 2–12 over 4 or 8, such as 4/4 or 7/8. This selects bar length, not a culturally specific groove engine for each meter.
Duration	Numeric hours/minutes/seconds (4 minutes 30 seconds, 270 seconds, duration_seconds: 270) or integer 128 bars/bars: 128. Written-number durations such as “four minutes” reject.
Length bounds	At most 1,800 seconds and 2,048 bars; explicit bars 1–2,048. The default six-section form needs six phrases. Explicit custom sections can be shorter and end in partial bars.
Phrases	8-bar phrases, phrase_bars: 8; allowed 2, 4, 8, 16, 32 bars.
Density/motion	Finite 0–1 numbers: density: 0.3, motion=0.35. “Minimal”/“sparse” affect the default density. Zero density does not necessarily remove the role's core pattern.
Seed	Integer 0–4,294,967,295: seed: 42. Otherwise derived from normalized style, key, scale and meter — not unrelated wording.
Resource limits	Brief 1–8,192 characters, at most 32 negative constraints and 200,000 notes; conservative preflight can reject a large duration/meter/role combination.
Intent	Separate rhythm, timbre, articulation, arrangement, mix objects. Bass rhythm and synthesis families are independent. Consult the published tool schema for exact bounded controls.
Form	sections: 1–128 objects with name, exactly one of bars/seconds, optional stable ID, energy, phrase length, active roles and transition. Sections are contiguous; resizing reports downstream timing changes.
Preservation	locks: target IDs (or *) with notes, rhythm, tuning, sound, arrangement aspects. Conflicting edits reject; no silent lock overrides.
Sources	source_policy.mode: native-only; dependencies may only be native oscillator/noise/procedural/effect categories. Samples, plugins, imported wavetables and recorded/model voices reject.

Use separate comma/semicolon-delimited clauses for structured fields. Numeric field: value/field=value syntax accepts decimal or scientific notation for number fields; bars, phrase_bars and seed must be written as integers. Do not use non-finite values, spelled numbers or words in numeric fields. If both bars and seconds are supplied they must agree exactly after conversion to MIDI ticks. See Tool reference for JSON arguments.

Exclusions: use negative_constraints or a no, without, or avoid clause, with and/or between items. Canonical names are kick, bass, drums, percussion, melody, chords, texture, vocals, delay, reverb, distortion, randomness, modulation, swing, samples, vsts, plugins, external sources, imported wavetables, voice models. Unknown exclusions reject rather than silently disappear. For example, no drums removes kick and percussion, no melody removes leads, and no texture also removes pads. no randomness removes stochastic draws but retains fixed motif variation; no modulation requires zero explicit motion. Removing every role rejects. FX exclusions remove recipe intentions, not effects already in a live project. “Synthetic vocal” adds a dedicated procedural role. Single-vowel excitation, noise and formant recipes exist; arbitrary multi-vowel sequencing, trajectories and host allocation still report explicit native capability blockers. These are not recorded vocals, voice models, intelligible speech or listening proof.

Timing: plans use 480 ticks per quarter note. Tempo is represented as integer MIDI microseconds per quarter; seconds are rounded to the nearest tick, not to whole bars or phrases (subject to the 1,800-second cap). The last bar can be partial. The intro/development/break/build/peak/outro sections are contiguous; notes are released and every MIDI track ends at duration_ticks.

Drums: channel 10 (zero-based midi_channel: 9) follows GM note meanings: 36 bass drum, 38 snare, 39 clap, 42 closed hi-hat. Use matching Drum Machine pads, note filters or explicit Grid note routing. A single pitched Grid voice does not become a drum kit merely because it receives channel-10 notes.

Inspect a Grid before editing

Start with get_grid_capabilities, then get_selected_device_state.

Check these fields before planning work:

• graph_available: whether the selected device exposes supported Grid graph operations.
• Selected-device name and type: whether the bridge is pointed at the intended device.
• Exposed controls and current values: the safe surface for parameter-only edits.
• Current graph revision and modules: the source of instance IDs, ports, and coordinates.

If graph_available is false, use exposed-control workflows only. Do not infer modules or cable routes from the Bitwig interface, screenshots, old inventory, or project files.

Make a small parameter change

Use this path for an audible adjustment that does not alter the Grid graph.

1. Call get_selected_device_state.
2. Identify the exposed control by its returned index and current value.
3. Save a recovery point with save_parameter_snapshot.
4. Change one or more values with set_selected_device_parameters.
5. Read the selected-device state again and listen.
6. If necessary, restore the named snapshot with apply_parameter_snapshot.

For A/B work, save two snapshots and use compare_parameter_snapshots before deciding which state to keep. Snapshots are process-local: restarting the MCP adapter clears them.

Shape exposed controls from a brief

Shaping is the safest creative workflow because it separates preview from mutation.

1. Call grid_list_style_presets for authored profiles, or grid_list_soundscape_styles for broader vocabulary.
2. Start a session with grid_shape_start, supplying a concrete brief and optional style.
3. Review the returned proposed controls, values, explanation, session_id, and revision.
4. Refine with grid_shape_compose when the preview misses the brief. Each compose creates a new revision.
5. Apply only the latest reviewed revision with grid_shape_apply, passing explicit confirmation.
6. Call grid_shape_status and listen in Bitwig.
7. Use grid_shape_undo with the same session ID to restore the pre-apply values.

A useful brief describes audible intent rather than implementation: “slower motion, fewer bright transients, preserve the bass weight.” The bridge chooses only from controls actually exposed by the selected device.

Never apply an earlier revision after composing a newer one. If Bitwig selection or parameters changed outside the session, re-read state and start or compose a fresh revision.

Insert and connect a Grid module

Graph edits require a supported selected Grid and live graph state.

1. Call get_grid_graph and note the graph revision, existing instance IDs, coordinates, ports, and connections.
2. Search the installed catalog with search_grid_modules.
3. Choose the exact returned package ID; names are not insertion identifiers.
4. Pick free coordinates from the current graph.
5. Call grid_insert_module with the package ID, coordinates, reviewed expected_revision, and explicit confirmation.
6. Read get_grid_graph again. Find the new instance ID and its live input/output port indexes.
7. Call grid_connect_modules using those returned IDs/indexes and the newly reviewed expected_revision.
8. Re-read the graph and verify that the expected module and connection exist.
9. Listen before making another structural change.

Do not chain insertion, parameter changes, and cabling from one old graph snapshot. Each mutation can change instance IDs, coordinates, connections, or revision.

For a multi-step additive recipe, prefer grid_analyze → grid_patch_start → review next_action → grid_patch_step → fresh status/graph. Each step requires the exact session revision and applies at most one insertion, native parameter write or connection, with read-back verification. Existing routes are preserved unless an exact replacement is authorized. Protected routes and feedback review belong in the recipe; unresolved or collateral changes freeze the session. It is not a bulk graph replacement or automatic rollback tool.

Add modulation

Use search_grid_modulators for host modulators and get_grid_host_modulators to inspect the modulators available on the selected Grid.

A safe sequence:

1. Read the graph and host-modulator state.
2. Resolve the exact modulator package or live instance.
3. Insert with grid_insert_modulator when needed.
4. Re-read the graph to obtain the new instance and parameter IDs.
5. Set one modulator control with grid_set_modulator_parameter.
6. Connect it with grid_connect_modulator using live port indexes.
7. Re-read and listen for range, polarity, and rate problems.

Prefer one modulation route at a time. Confirm that the destination remains musically useful at the full modulation range before adding a second route.

Use the current reviewed expected_revision on each direct write and re-read between dependent changes. Cataloged Grid modulators and host-level modulation sources are different surfaces; do not substitute IDs or invent mappings.

Plan a live set

Use grid_live_set_plan before building a Techno, Psytrance, Electro, or similar live set. It is non-mutating and returns:

• role-based tracks for kick, bass, percussion, texture, cues, and returns;
• a named scene arc with phrase length, energy, active roles, and transitions;
• performance macros with bounded safe ranges, neutral values, and reset rules;
• controlled modulation routes with a source, destination, time scale, depth, polarity, and musical rationale.

Example:

{
  "brief": "Dark 142 BPM minimal raw techno with controlled live agency",
  "style": "techno",
  "tempo": 142,
  "scene_count": 8,
  "density": 0.28,
  "motion": 0.38,
  "agency": 0.55
}

Build one role at a time using the existing shaping or graph workflow. Treat the plan as musical guidance, not as a preset or authorization to invent modules, tracks, or clip data. Keep each macro tied to one primary destination, preview its full safe range, and provide a neutral landing gesture. Use slow clocks or shaped segments for timbral movement; use probability for fills and events.

The bridge exposes dynamic Bitwig host actions for live gestures:

1. call grid_list_actions with a focused query such as scene, clip, play, or stop;
2. review the returned exact id, name, and menu;
3. call grid_invoke_action with that exact ID and explicit confirmation;
4. re-read state and listen through the phrase boundary.

Action availability and IDs are live facts, not stable tool names. The public extension does not provide a general clip-authoring or scene-naming API. If graph_available is false, use exposed controls only and report that the Grid topology cannot be constructed through the returned capabilities.

Replace a parameterized graph detail

For a known module parameter:

1. Read get_grid_graph.
2. Resolve the module instance and native parameter ID from that response.
3. Check editable, type, native range and discrete options. Operation-mapped controls such as TIMEBASE are supported when the live record permits it.
4. For musical units, call grid_resolve_parameter_value with exact module_id, parameter_id and display_value, such as "65 ms". Review value, current_value, current_display, display_unit and returned graph revision; do not treat an envelope's numeric native range as seconds.
5. Call grid_set_module_parameter with the native value, reviewed expected_revision, and confirmation.
6. Read the graph again and compare the actual value/display.

Discrete choices use the live options[].value, not the option's ordinal or display label. Booleans, integers and floats have different contracts.

Disconnect or remove a route safely

grid_disconnect_module disconnects the target input identified by a live target module ID and target port index.

Before disconnecting:

1. Read the graph and identify the exact connection.
2. Note the source and target so the route can be reconstructed.
3. Disconnect with the reviewed expected_revision and explicit confirmation.
4. Re-read the graph and verify only the intended connection disappeared.
5. Use grid_project_undo only after confirming the latest global host operation is the one to recover.

Navigate tracks and devices

Selection-changing tools are useful, but selection is shared with the Bitwig interface.

1. Call grid_list_tracks and use its zero-based bank indexes. This is a flattened 64-slot all-channel bank including hidden children of collapsed groups, FX and master, not a list of top-level or visible tracks only. In grid_song_state, tracks[].index is the selector; position is the native position and must not replace it.
2. Select with grid_select_track.
3. Call get_selected_device_state to establish the new context.
4. Move with grid_navigate_device using first, next, previous, or parent.
5. Re-read selected-device state after every navigation.

Do not cache track or device positions across project edits. Track banks, nesting, and selection can change.

Draft a soundscape before touching the project

grid_soundscape_plan is non-mutating. Give it a brief to obtain a staged recipe, then inspect current capabilities before translating any step into live operations.

Use this for exploratory prompts such as:

• “A restrained metallic pulse with movement every eight bars.”
• “A distant granular bed that leaves the center clear for vocals.”
• “A low, unstable drone with no abrupt level changes.”

The plan is guidance, not proof that packages or graph operations are available. Resolve every package through the live catalogs and every instance through the current graph.

Recovery order

Use the narrowest recovery mechanism that matches the change:

1. grid_shape_undo for the latest applied shaping revision.
2. apply_parameter_snapshot for a named exposed-control state.
3. grid_project_undo for the latest Bitwig host mutation.
4. grid_project_redo only after confirming the undone operation was the intended one.

After any recovery call, read state again. Never assume that undo restored the selection or graph context expected by an earlier snapshot.

Stop conditions

Stop instead of retrying when:

• a tool result starts with Error:;
• a JSON result reports ok: false, a frozen patch, or a rejected import;
• the selected device changed;
• the graph revision is stale;
• a package ID, instance ID, parameter ID, or port index is missing;
• graph_available is false for a graph operation;
• Bitwig or the bridge extension restarted;
• the requested change cannot be expressed through returned capabilities.

Re-establish capabilities and live state before continuing. Repeating a stale mutation is more dangerous than leaving a partial edit visible and recoverable.