Add to / extend a user-profile-specific variable (AddUserVar).

Numeric values are summed; text values are concatenated.

Args:
    var_name: Variable name (should start with $)
    value: Value to add (numeric) or append (text)

Returns:
    str: Operation result message

Add to / extend a global show variable (AddVar).

Numeric values are summed; text values are concatenated.

Args:
    var_name: Variable name (should start with $)
    value: Value to add (numeric) or append (text)

Returns:
    str: Operation result message

Set appearance (color) on a cue across a range of sequences.

Iterates over every sequence in the range and applies the color to the
specified cue. Supports RGB values (0-100) or hex color codes.

Args:
    cue_id: Cue number (e.g., 1, 0.5)
    sequence_start: First sequence number in the range
    sequence_end: Last sequence number in the range (inclusive)
    red: (Optional) Red component (0-100)
    green: (Optional) Green component (0-100)
    blue: (Optional) Blue component (0-100)
    color: (Optional) Hex color code (e.g., "FF0000")

Returns:
    dict: Result with commands_sent, count, and summary

Examples:
    - Set cue 0.5 to black across sequences 101-125 (red=0, green=0, blue=0)
    - Set cue 1 to red across sequences 101-103 (color="FF0000")

Apply a predefined effect from the effect pool to the current fixture selection.

Fixtures must be selected first using set_fixture_value or create_fixture_group.

Args:
    effect_id: Effect number from the effect pool

Returns:
    str: Operation result message

Examples:
    - Apply effect 5 to selected fixtures

Apply an existing preset to the current selection.

Args:
    preset_type: Preset type (dimmer, position, gobo, color, beam, focus, control, shapers, video)
    preset_id: Preset number

Returns:
    str: Operation result message

Examples:
    - Apply color preset 3
    - Apply position preset 1

Assign an appearance (frame/background color) to a grandMA2 pool object or cue.

Colors can be specified via RGB (0-100), HSB (hue 0-360, sat/bright 0-100),
hex color string, or by copying from a source object. Use reset to clear.

Args:
    object_type: Object type (e.g., "group", "cue", "preset", "macro")
    object_id: Object number or compound ID (e.g., 1 or "0.1")
    end: (Optional) End ID for applying to a range of objects
    source_type: (Optional) Source object type to copy appearance from
    source_id: (Optional) Source object ID to copy appearance from
    reset: Reset appearance to default
    color: Hex color code (e.g., "FF0000") or gel name
    red: Red component (0-100)
    green: Green component (0-100)
    blue: Blue component (0-100)
    hue: Hue (0-360)
    saturation: Saturation (0-100)
    brightness: Brightness (0-100)

Returns:
    str: Operation result message

Examples:
    - Set group 1 to red: object_type="group", object_id=1, red=100, green=0, blue=0
    - Set preset 0.1 to hex color: object_type="preset", object_id="0.1", color="FF0000"
    - Copy appearance from macro 13 to macro 2: object_type="macro", object_id=2, source_type="macro", source_id=13
    - Reset group 1 appearance: object_type="group", object_id=1, reset=True

Assign a timecode show to a timecode slot for cue triggering.

Args:
    tc_id: Timecode show ID
    slot: Timecode slot number

Returns:
    str: Operation result message

Assign a sequence to an executor.

Args:
    sequence_id: Sequence number to assign
    executor_id: Target executor number

Returns:
    str: Operation result message

Examples:
    - Assign sequence 1 to executor 6

Build (or extend) a color preset palette for a fixture selection in one call.

For each color: selects ``target``, sets R/G/B/W, stores the preset (Global by
default), labels it, and sets its pool appearance swatch.

To extend an existing palette to a new fixture group without disturbing
already-stored values, pass that group as ``target`` and ``merge=True``.

Args:
    target: A grandMA2 selection command (e.g. "Group 3", "Group 1 Thru 5").
    colors: List of {id, name?, r, g, b, w?} with r/g/b/w in 0-100.
    scope: "global" (default), "selective", or "universal".
    merge: Merge into existing presets (non-destructive extend).
    label: Apply each color's name as the preset label.
    appearance: Set each preset's pool swatch from its color.

Returns:
    str: Operation result message

Examples:
    - Build a palette on LED Par: target="Group 3", colors=[{"id":7,"name":"Red","r":100,"g":0,"b":0}]
    - Extend it to Wash: target="Group 4", merge=True, same colors

Build a preset palette of any type from per-fixture-type value sets.

Generalizes color/beam/focus palette building: each preset carries one or
more targets (fixture selections), each with its own attribute values. The
first target uses ``scope``; subsequent targets of the same preset merge
(per-fixture-type accumulation into one preset).

Args:
    preset_type: "color", "beam", "focus", "dimmer", "position", ...
    presets: list of {id, name?, by_target: [{target, attrs}]} where target
        is a selection command (e.g. "Fixture 101 Thru 128") and attrs is a
        list of [attribute, value] pairs.
    scope: "global" (default), "selective", or "universal".
    merge: if True the first target also merges (extend an existing preset).
    label: apply each preset's name as its label.

Returns:
    str: Operation result message

Examples:
    - Beam strobe across types: preset_type="beam", presets=[{"id":3,"name":"Strobe","by_target":[{"target":"Fixture 401 Thru 428","attrs":[["SHUTTER",50]]},{"target":"Fixture 201 Thru 215","attrs":[["MASTERSHUTTERSTROBE",21]]}]}]

Create a set-list sequence with cue-to-macro links.

Stores a sequence, then for each song creates a cue and assigns a
macro trigger to its CMD field. Each song dict must contain:
    cue_id (int): Cue number in the set-list sequence
    macro_id (int): Macro to trigger via cue CMD
    name (str): Name for the cue

Args:
    sequence_id: Sequence number for the set list
    sequence_name: Label for the set-list sequence
    songs: List of song definition dicts

Returns:
    str: Operation result message

Examples:
    - Build a set list with 3 songs linking cues to macros

Machine-readable contract surface for the gma2-workflow startup self-check
(issue #85). Pure metadata: it does NOT open a console connection, so it is
intentionally not wrapped with ``@handle_connection_error``.

Returns:
    dict: ``{version, tools (sorted), tool_count, profile_schema_version}``.

Clear the programmer.

Args:
    mode: Clear mode - "all" (clear everything), "selection" (clear selection only),
          "active" (clear active values only), or "default" (standard clear)

Returns:
    str: Operation result message

Examples:
    - Clear all programmer data
    - Clear selection only

Clone all programming from source fixture(s) to target fixture(s).

WARNING: mode="overwrite" replaces existing target programming.

Args:
    source_fixture: Source fixture number (or start of range)
    target_fixture: Target fixture number (or start of range)
    source_end: Optional end of source range
    target_end: Optional end of target range
    mode: "default", "overwrite", or "merge"

Returns:
    str: Operation result message

Control an executor (on, off, go, kill, toggle).

Args:
    executor_id: Executor number
    action: Action to perform: "on", "off", "go", "kill", or "toggle"

Returns:
    str: Operation result message

Examples:
    - Turn on executor 1
    - Kill executor 3
    - Go on executor 2

Control timecode playback/recording.

Args:
    tc_id: Timecode show ID
    action: One of "go" (play), "pause", "off" (stop), "top" (rewind),
            or "record" (arm real-time event recording)

Returns:
    str: Operation result message

Examples:
    - Start timecode 1: action="go"
    - Record events into timecode 1: action="record"

Copy an object (or range) to a new location.

``source`` and ``target`` accept grandMA2 selection expressions: a single ID
or a range/list using thru / + / - (e.g. "1 thru 10", "1 + 3 + 5"), so a
whole range copies in one call.

Args:
    object_type: Object type ("cue", "preset", "group", "sequence", "macro", ...)
    source: Source selection expression
    target: Target selection expression
    mode: "default", "overwrite", or "merge"

Returns:
    str: Operation result message

Examples:
    - Copy cue 1 to cue 10: object_type="cue", source="1", target="10"
    - Copy groups 1 thru 5 to 11: object_type="group", source="1 thru 5", target="11"

Create a group containing a specified range of fixtures.

This tool selects the specified range of fixtures and saves them as a group.
Optionally, a name can be assigned to the group.

Args:
    start_fixture: Starting fixture number
    end_fixture: Ending fixture number
    group_id: Group number to save
    group_name: (Optional) Group name, e.g., "Front Wash"

Returns:
    str: Operation result message

Examples:
    - Save fixtures 1 to 10 as group 1
    - Save fixtures 1 to 10 as group 1 with name "Front Wash"

Create a macro with command lines.

Stores an empty macro, then assigns each command to sequential lines.
Optionally labels the macro.

Args:
    macro_id: Macro number to create
    commands: List of command strings for each macro line
    name: Optional label for the macro
    pool: Macro pool number (default: 1)

Returns:
    str: Operation result message

Examples:
    - Create macro 10 with commands ["Go Sequence 1", "Go Sequence 2"]
    - Create macro 10 named "Start Show" with one command

Create and label a Sequence + Page pair for a song.

Stores a sequence and a page with the same ID and name, which is the
standard pattern for per-song programming in music show workflows.

Args:
    song_id: ID for both the sequence and page
    song_name: Name to assign to both objects

Returns:
    str: Operation result message

Examples:
    - Create sequence 101 and page 101 named "Opening+Childhood"

Create a timecode show, optionally naming it and assigning a slot.

Standard SMPTE setup: store the timecode pool object, label it, and bind it
to a timecode slot for cue triggering. Timecode events themselves are
recorded in real time via control_timecode(action="record").

Args:
    tc_id: Timecode show ID
    name: Optional display name
    slot: Optional timecode slot to assign

Returns:
    str: Operation result message

Examples:
    - Create timecode 1 named "Act 1" on slot 1

Delete a cue from the current sequence.

Args:
    cue_id: Cue number to delete

Returns:
    str: Operation result message

Examples:
    - Delete cue 3

Delete a macro from the macro pool.

WARNING: This is a destructive operation that permanently removes the macro.

Args:
    macro_id: Macro number to delete
    pool: Macro pool number (default: 1)

Returns:
    str: Operation result message with warnings

Execute sequence-related operations.

Args:
    sequence_id: Sequence number
    action: Operation type: "go" (execute), "pause" (pause), or "goto" (jump to cue)
    cue_id: (Required for goto) Target cue number

Returns:
    str: Operation result message

Examples:
    - Execute sequence 1
    - Pause sequence 2
    - Jump to cue 5 of sequence 1

Flash an executor (momentary intensity bump) — a live busking control.

Args:
    executor_id: Executor number
    page: Optional page number for page-qualified addressing
    mode: "flash" (momentary), "flash_on" (latching), or "flash_go" (flash and go)

Returns:
    str: Operation result message

read the user-added annotation text on a cue.

in grandMA2, the Info keyword reads or writes user-added descriptive text
annotations on objects. this tool reads the annotation. if no annotation has
been set on the cue, the response will be empty.

note: this does NOT return cue properties (fade time, values, etc.).
to see cue properties, use list_cues with a specific cue_id instead.

Args:
    cue_id: cue ID to read annotation from
    sequence_id: sequence containing the cue (optional)

Returns:
    str: the user annotation text, or empty response message if none set

read the user-added annotation text on a group.

in grandMA2, the Info keyword reads or writes user-added descriptive text
annotations on objects. this tool reads the annotation. if no annotation has
been set on the group, the response will be empty.

note: this does NOT return group composition or fixture details.
to see group details, use list_groups with a specific group_id instead.

Args:
    group_id: group ID to read annotation from

Returns:
    str: the user annotation text, or empty response message if none set

Jump to a specific cue.

Targets either an executor or a sequence. If neither is specified,
the command applies to the selected executor.

Args:
    cue_id: Target cue number
    executor: (Optional) Executor number
    sequence: (Optional) Sequence number

Returns:
    str: Operation result message

Examples:
    - Goto cue 5 on executor 4
    - Goto cue 3 in sequence 1

Label a cue across a range of sequences.

Iterates over every sequence in the range and labels the specified cue.

Args:
    cue_id: Cue number to label (e.g., 1, 0.5)
    sequence_start: First sequence number in the range
    sequence_end: Last sequence number in the range (inclusive)
    label: Label text to assign

Returns:
    dict: Result with commands_sent, count, and summary

Examples:
    - Label cue 0.5 across sequences 101-125 as "((LOADING SONG))"

Label a macro in the macro pool.

Args:
    macro_id: Macro number to label
    name: Label text for the macro

Returns:
    str: Operation result message

Examples:
    - Label macro 5 as "Blackout All"

Assign a name label to a grandMA2 object.

Args:
    object_type: Object type (e.g., "group", "cue", "sequence", "macro", "preset")
    object_id: Object number
    name: Name to assign

Returns:
    str: Operation result message

Examples:
    - Label group 1 as "Front Wash"
    - Label cue 5 as "Intro"

Label a cue within a specific sequence.

This tool addresses cues through the sequence context, which is required
for labeling cues inside named sequences.

Args:
    sequence: Sequence ID or name (e.g., "100" or "Set List")
    cue_id: Cue number within the sequence
    name: Label to assign
    end_cue: (Optional) End cue for range labeling

Returns:
    str: Operation result message

Examples:
    - Label cue 1 in "Set List" as "Opening+Childhood"
    - Label cue 1 in sequence 100 as "Opening+Childhood"
    - Label cues 1 thru 5 in "Set List" as "Act 1"

list cues on the grandMA2 console.

lists cues of the selected executor, or a specific sequence if sequence_id is provided.

Args:
    cue_id: specific cue ID or start of range (optional)
    end_cue_id: end cue ID for range query (optional)
    sequence_id: sequence to list cues from (optional)

Returns:
    str: raw console response with cue listing

list all defined groups on the grandMA2 console.

returns raw console output from the List Group command.

Args:
    group_id: specific group ID or start of range (optional)
    end_group_id: end group ID for range query (optional, requires group_id)

Returns:
    str: raw console response with group listing

List macros in the macro pool.

Returns raw console output from the List Macro command.

Returns:
    str: Raw console response with macro listing

list presets of a given type on the grandMA2 console.

valid preset types: dimmer, position, gobo, color, beam, focus, control, shapers, video.

Args:
    preset_type: type of preset (e.g. "color", "position", "dimmer")
    preset_id: specific preset ID (optional)

Returns:
    str: raw console response with preset listing

list available show files on the grandMA2 console.

Args:
    filter: optional filter pattern (e.g. "Mac*" to list shows starting with Mac)

Returns:
    str: raw console response with show file listing

list show variables or user variables on the grandMA2 console.

Args:
    variable_type: "show" for show variables (ListVar), "user" for user variables (ListUserVar)
    filter: optional filter pattern (e.g. "f*" to list variables starting with f)

Returns:
    str: raw console response with variable listing

load a show file on the grandMA2 console.

WARNING: this is a DESTRUCTIVE operation. any unsaved changes to the current
show will be lost. set save_first=True to save the current show before loading.

Args:
    show_name: name of the show file to load
    save_first: if True, saves the current show before loading the new one

Returns:
    str: confirmation message with warning about unsaved changes

Move an object (or range) to a new location. WARNING: removes from source.

``source`` and ``target`` accept selection expressions (thru / + / -), so a
whole range moves in one call (e.g. move groups 1 thru 10 to 21).

Args:
    object_type: Object type ("cue", "preset", "group", "sequence", "macro", ...)
    source: Source selection expression
    target: Target selection expression

Returns:
    str: Operation result message

create a new empty show on the grandMA2 console.

WARNING: this is a DESTRUCTIVE operation. any unsaved changes to the current
show will be lost. set save_first=True to save the current show before creating a new one.

note: per the grandMA2 manual, NewShow requires a show name. omitting the
name may work on some console versions but this behavior is undocumented.
providing a name is recommended.

Args:
    show_name: name for the new show (recommended — required per official manual)
    save_first: if True, saves the current show before creating a new one

Returns:
    str: confirmation message with warning about unsaved changes

Park DMX output (lock a value regardless of playback).

Args:
    target: What to park (e.g. "fixture 1", "channel 5", "fixture 1 attribute dim").
            Omit to park the current selection.
    at_value: Optional value to park at (0-100); omit to park at current value.

Returns:
    str: Operation result message

generic query for any grandMA2 object type.

use this for object types without a dedicated tool (e.g. executors, sequences, effects).
for groups, cues, and presets, prefer the specific tools.

Args:
    object_type: MA2 object type (e.g. "executor", "sequence", "effect", "macro")
    object_id: object ID to query (optional)
    mode: "list" to list objects, "annotation" to read user-added text annotation (default: "list").
          note: "annotation" mode reads user-added descriptive text, NOT object properties.

Returns:
    str: raw console response

Read timecode pool status / configuration.

Args:
    tc_id: Specific timecode ID (optional; lists the whole pool if omitted)

Returns:
    str: raw console response with timecode listing

Retrieves and parses cue data including label, fade time, and CMD field.

Args:
    sequence_id: Sequence ID containing the cue
    cue_id: Cue ID (int or str for decimal cue numbers like "2.5")

Returns:
    dict with parsed cue info and raw response

Retrieves and parses all lines of a macro, returning each line's
number and command string.

Args:
    macro_id: Macro ID to read
    pool: Macro pool number (default 1)

Returns:
    dict with parsed macro lines and raw response

Uses the generic list command to retrieve an object's name field.

Note: For macros, object_id must be pool-qualified (e.g., "1.5" for
Macro 5 in Pool 1) since grandMA2 addresses macros as pool.id.
For most other object types, a plain integer ID is sufficient.

Args:
    object_type: Object type (e.g., "group", "sequence", "macro", "page")
    object_id: Object ID (int for most types, or "pool.id" string for macros)

Returns:
    dict with parsed label and raw response

Release an executor (clean removal from output, respecting tracking).

Args:
    executor_id: Executor number
    page: Optional page for page-qualified addressing

Returns:
    str: Operation result message

Execute a macro by ID.

Starts the specified macro using the Go+ command.

Args:
    macro_id: Macro number to execute
    pool: Macro pool number (default: 1)

Returns:
    str: Operation result message

Examples:
    - Run macro 5 from default pool
    - Run macro 10 from pool 2

save the current show file on the grandMA2 console.

if no name is provided, saves under the current show name.
uses /noconfirm to suppress the overwrite confirmation popup
that would otherwise block Telnet when a show with the same name exists.

Args:
    show_name: name to save the show as (optional)

Returns:
    str: confirmation message

Send a MIDI control-change (CC) message via the MIDI Out port.

Args:
    controller: Controller number (0-127)
    value: Control value (0-127)
    channel: MIDI channel; uses the Setup MSC channel if omitted

Returns:
    str: Operation result message

Send a MIDI note message via the console's MIDI Out port.

Used to trigger external devices (video servers, audio, pyro, fog).

Args:
    note: MIDI note number (0-127)
    velocity: Note velocity (0-127); defaults to full (127) if omitted
    channel: MIDI channel; uses the Setup MSC channel if omitted
    off: If True, send note-off instead of note-on

Returns:
    str: Operation result message

Send a MIDI program-change message via the MIDI Out port.

Args:
    program: Program number (0-127)
    channel: MIDI channel; uses the Setup MSC channel if omitted

Returns:
    str: Operation result message

Send a raw MA command to grandMA2.

This is a low-level tool that allows sending any grandMA2 command-line instruction.
It is recommended to use other high-level tools first; use this tool only when
special commands are needed.

Args:
    command: Raw MA command to send

Returns:
    str: Operation result message

Examples:
    - blackout
    - go+ executor 1.1
    - store sequence 1 cue 1

Assign a command to a cue's CMD field.

When the cue fires, the assigned command will execute automatically.
Common use: trigger a macro when a cue runs.

Args:
    cue_id: Cue number
    sequence_id: Sequence number
    command: Command to execute when cue fires (e.g., "Macro 101")

Returns:
    str: Operation result message

Examples:
    - Set cue 1 in sequence 100 to trigger "Macro 101"
    - Set cue 5 in sequence 200 to run "Go Sequence 10"

Set fade/delay timing on a cue or the current selection.

Provide any subset (at least one required). ``target`` applies the timing to
a specific object (e.g. "cue 5" or "cue 5 sequence 2"); omit to apply to the
current programmer selection.

Args:
    fade: Fade time (seconds)
    delay: Delay time (seconds)
    out_fade: Out-fade time (seconds)
    out_delay: Out-delay time (seconds)
    target: Optional target object string

Returns:
    str: Operation result message

Set effect envelope parameters (attack, decay, delay, fade) on the selection.

Provide any subset (at least one required).

Returns:
    str: Operation result message

Set the effect waveform for the current selection.

Args:
    form: Waveform type — name (e.g., "sin", "ramp", "square") or number

Returns:
    str: Operation result message

Examples:
    - Set effect form to "sin"
    - Set effect form to 6

Set the effect phase offset for the current selection.

Args:
    phase: Phase value in degrees (e.g., 0, 90, 180, 270)

Returns:
    str: Operation result message

Set effect high and/or low values for the current selection.

At least one of high or low must be provided.

Args:
    high: Effect high value (optional)
    low: Effect low value (optional)

Returns:
    str: Operation result message

Examples:
    - Set effect range high=100, low=0
    - Set only effect high to 80

Set the effect speed for the current selection.

Args:
    value: Speed value
    unit: Speed unit — "bpm" (beats per minute) or "hz" (hertz)

Returns:
    str: Operation result message

Examples:
    - Set effect speed to 120 BPM
    - Set effect speed to 2.5 Hz

Set the effect width for the current selection.

Args:
    width: Width value (percentage of cycle)

Returns:
    str: Operation result message

Set an executor's fader level.

Args:
    executor_id: Executor number
    value: Fader value (0-100)

Returns:
    str: Operation result message

Examples:
    - Set executor 1 fader to 75%

Control an executor's playback rate (live tempo matching).

Args:
    executor_id: Executor number
    mode: "set" (rate), "half", "double", or "reset" (1:1)
    page: Optional page for page-qualified addressing

Returns:
    str: Operation result message

Control an executor's playback speed (live tempo matching).

Args:
    executor_id: Executor number
    mode: "set" (speed), "half", or "double"
    page: Optional page for page-qualified addressing

Returns:
    str: Operation result message

Set a specific attribute on fixture(s).

First selects the fixture(s), then applies the attribute value.

Args:
    fixture_id: Fixture number (or start of range)
    attribute: Attribute name (e.g., "Pan", "Tilt", "Dimmer")
    value: Value to set
    end_fixture: (Optional) End fixture for range

Returns:
    str: Operation result message

Examples:
    - Set Pan to 128 on fixture 1
    - Set Tilt to 50 on fixtures 1 thru 10

Set fixture(s) to a dimmer value.

Args:
    fixture_id: Fixture number (or start of range)
    value: Dimmer percentage (0-100)
    end_fixture: (Optional) End fixture for range

Returns:
    str: Operation result message

Examples:
    - Set fixture 1 to 75%
    - Set fixtures 1 thru 10 to 50%

Set the command for a specific line within a macro.

Args:
    macro_id: Macro number
    line: Line number within the macro
    command: The command string for that line (e.g., "SetVar $song='Opening+Childhood'")
    pool: Macro pool number (default: 1)

Returns:
    str: Operation result message

Examples:
    - Set macro 101 line 1 to "SetVar $song='Opening+Childhood'"
    - Set macro 50 line 3 in pool 2 to "Go Sequence 5"

Configure MAtricks for fan effects / selection-pattern manipulation.

Applies to the current fixture selection. Provide any subset of parameters;
they are sent together. At least one parameter is required.

Args:
    blocks: Block size grouping
    wings: Number of wings (symmetry)
    groups: Number of groups
    interleave: Interleave step
    filter: MAtricks filter value

Returns:
    str: Operation result message

Set step/chase timing parameters for the current selection.

Provide any subset (at least one required).

Args:
    snap_percent: Snap percentage (hard-cut portion)
    step_fade: Step fade time
    step_in_fade: Step in-fade time
    step_out_fade: Step out-fade time
    fade_path: Fade path / curve value

Returns:
    str: Operation result message

Create a macro that sets a user variable to the song name.

Stores a macro, labels it with the song name, and assigns a SetVar
command on line 1. This is used to track the current song in
music show workflows.

Args:
    macro_id: Macro number to create
    song_name: Song name used for label and variable value
    var_name: Variable name for the SetVar command (default: "$song")

Returns:
    str: Operation result message

Examples:
    - Create macro 101 that sets $song to "Opening+Childhood"

Set a user-profile-specific variable (SetUserVar).

Args:
    var_name: Variable name (should start with $)
    value: Numeric, text, or None to delete the variable
    input_dialog: If True (string values only), prompt with an input dialog

Returns:
    str: Operation result message

Set a global show variable (SetVar).

Args:
    var_name: Variable name (should start with $, e.g. "$song")
    value: Numeric, text, or None to delete the variable
    input_dialog: If True (string values only), prompt the operator with an
                  input dialog instead of setting a fixed value

Returns:
    str: Operation result message

Examples:
    - Set $count to 5
    - Set $song to "Opening"
    - Delete $count (value=None)

Stomp an executor (assertive playback, overrides lower priorities).

Args:
    executor_id: Executor number
    page: Optional page number for page-qualified addressing

Returns:
    str: Operation result message

Stop all running effects for the current selection.

Removes effect values from the programmer using the Off command.

Returns:
    str: Operation result message

Store the current programmer state as a cue.

Args:
    cue_id: Cue number to store
    name: (Optional) Name for the cue
    merge: Merge new values into existing cue
    overwrite: Overwrite existing cue entirely
    noconfirm: Suppress store confirmation pop-up

Returns:
    str: Operation result message

Examples:
    - Store cue 1
    - Store cue 5 with name "Blackout" and merge enabled

Store a cue across a range of sequences.

Iterates over every sequence in the range and stores the specified cue.
Optionally assigns a name to each stored cue.

Args:
    cue_id: Cue number to store (e.g., 1, 0.5)
    sequence_start: First sequence number in the range
    sequence_end: Last sequence number in the range (inclusive)
    cue_name: (Optional) Name for the cue

Returns:
    dict: Result with commands_sent, count, and summary

Examples:
    - Store cue 0.5 across sequences 101-125 with name "((LOADING SONG))"
    - Store cue 1 in sequence 101

Store current programmer values as a preset.

Use merge to ADD the current selection's values into an existing preset
without disturbing values already stored for other fixture types (the
non-destructive way to extend a global palette to a new fixture group).

Args:
    preset_type: Preset type (dimmer, position, gobo, color, beam, focus, control, shapers, video)
    preset_id: Preset number
    scope: (Optional) Scope: "global", "selective", or "universal"
    merge: Merge into the existing preset (keeps other fixtures' stored values)
    overwrite: Overwrite the existing preset entirely

Returns:
    str: Operation result message

Examples:
    - Store color preset 1
    - Store global dimmer preset 5
    - Extend global color preset 7 to the current selection: merge=True

Swop an executor (solo with blackout on others) — a live busking control.

Args:
    executor_id: Executor number
    page: Optional page number for page-qualified addressing
    mode: "swop" (momentary), "swop_on" (latching), or "swop_go" (swop and go)

Returns:
    str: Operation result message

Synchronize all running effects.

Resets effect timing so all running effects align their phase.

Returns:
    str: Operation result message

Temporarily activate an executor (Temp).

Args:
    executor_id: Executor number
    page: Optional page number for page-qualified addressing

Returns:
    str: Operation result message

Toggle the grand blackout state.

Returns:
    str: Operation result message

Toggle blind editing mode (edit cues without affecting stage output).

Args:
    executor_id: Optional executor to toggle blind for (global if omitted)
    page: Optional page for page-qualified executor addressing
    edit_mode: If True, toggle blind-edit mode (global) instead

Returns:
    str: Operation result message

Toggle highlight mode for fixture programming.

Returns:
    str: Operation result message

Toggle preview mode (visualize output without affecting DMX).

Args:
    executor_id: Optional executor to toggle preview for (global if omitted)
    page: Optional page for page-qualified executor addressing
    edit_mode: If True, toggle preview-edit mode (global) instead

Returns:
    str: Operation result message

Set an executor to top priority (Top).

Args:
    executor_id: Executor number
    page: Optional page for page-qualified addressing

Returns:
    str: Operation result message

Unpark previously parked DMX output.

Args:
    target: What to unpark (e.g. "fixture 1"); omit for the current selection.

Returns:
    str: Operation result message

Update an existing cue with current programmer values (Update).

Unlike store, Update merges programmer changes into an existing cue without
re-storing. WARNING: this modifies existing programming.

Args:
    cue_id: Cue number to update
    sequence_id: Optional sequence the cue belongs to
    merge: Add /merge flag
    cueonly: Add /cueonly flag (do not track changes forward)
    tracking: Add /tracking flag

Returns:
    str: Operation result message