QTracksQTracks
← Docs

grandMA3 macro reference.

grandMA3 Macro XML Reference

A reference for how grandMA3 macros work when exported as XML, based on the GMA3 DataVersion 1.4.0.0 format.

XML Structure

<?xml version="1.0" encoding="UTF-8"?>
<GMA3 DataVersion="1.4.0.0">
  <Macro Name="MyMacro">
    <MacroLine Command="..." Wait="0.01"/>
  </Macro>
</GMA3>
  • <GMA3> — Root element. DataVersion specifies the grandMA3 software version format.
  • <Macro> — A named macro. The Name attribute is the macro's identifier.
  • <MacroLine> — A single command in the macro. Executed sequentially from top to bottom.
    • Command — The console command to execute.
    • Wait (optional) — Delay in seconds before executing the next line. Used to let the console process heavy operations before continuing.

Quotes inside XML attribute values are escaped as &quot;.

Navigation: cd (Change Directory)

grandMA3 uses a hierarchical object tree. You navigate it with cd, similar to a filesystem.

| Command | Description | | --------------------------------- | ------------------------------------------------------------ | | cd root | Return to the top of the object tree | | cd DataPool "Name" | Enter a named DataPool | | cd DataPool "Name" Timecode 10 | Enter Timecode slot 10 inside the DataPool | | cd DataPool "Name" Sequence 240 | Enter a specific Sequence | | cd "Timecodes" | Enter the Timecodes container (from within a DataPool) | | cd 1 | Enter child object at index 1 (relative to current location) |

You must cd into an object before you can Store, Set, or modify its children. Always cd root when done to reset your position.

DataPool Operations

A DataPool is a named container that holds Sequences, Timecodes, and other show data. It acts as an isolated namespace.

Create and Delete

Delete DataPool "MyPool" /NC          -- Delete if exists (No Confirm)
Store DataPool "MyPool" /NC           -- Create new DataPool (No Confirm)
Delete DataPool "MyPool" /NoConfirm   -- Full flag spelling also works

Storing Sequences and Cues

Store DataPool "MyPool" Sequence 240 Cue 1 /Merge
Store DataPool "MyPool" Sequence 240 Cue 2 /Merge
Store DataPool "MyPool" Sequence 241 Cue 1 /Merge
Store DataPool "MyPool" Sequence 241 Cue 2
  • Sequence number (e.g., 240) — The sequence slot in the DataPool.
  • Cue number (e.g., Cue 1) — A cue within that sequence.
  • /Merge — Merges into an existing cue instead of overwriting.

Cue Properties

DataPool "MyPool" Sequence 240 Cue 1 CueFade 0
DataPool "MyPool" Sequence 241 Cue 2 CueFade 0.5
  • CueFade — Fade time in seconds. 0 = instant snap, 0.5 = half-second fade.

Labeling

Label DataPool "MyPool" Sequence 240 "Base 0"
Label DataPool "MyPool" Sequence 241 "Strobe 0"
Label DataPool "MyPool" Sequence 242 "Hit 0"
Label DataPool "MyPool" Sequence 240 Cue 1 ""
Label DataPool "MyPool" Timecode 10 "Song Name"

Empty string "" clears the label.

Sequence Configuration

Cue Trigger Types

Set DataPool "MyPool" Sequence 241 Cue 2 Property "TrigType" "Time"
Set DataPool "MyPool" Sequence 241 Cue 2 Property "TrigTime" "0.1"
Set DataPool "MyPool" Sequence 242.OffCue Property "TrigType" "Follow"

| TrigType | Behavior | | -------- | ----------------------------------------------------------- | | Go | Manual trigger (default) — operator presses Go | | Time | Auto-fires after the time specified in TrigTime (seconds) | | Follow | Fires immediately after the previous cue completes its fade |

  • TrigTime — Delay in seconds before auto-triggering (used with TrigType "Time").
  • .OffCue — Refers to the sequence's release/off cue. Setting its TrigType to Follow makes the sequence auto-release.

Assert

Set DataPool "MyPool" Sequence 241 Cue 1 Property "Assert" "Yes"

Assert forces the cue to re-assert its values even if the sequence is already at that cue. Useful for timecode-triggered cues that must fire reliably every time.

Timecode Shows

Timecode shows allow sequences to be triggered automatically at specific times, synchronized to an incoming timecode signal or internal clock.

Create a Timecode Show

Store DataPool "MyPool" Timecode 10

Configure Timecode Properties

After navigating to the Timecodes container:

cd DataPool "MyPool"
cd "Timecodes"
set 10 Property FRAMEREADOUT "25 fps"
set 10 Property OFFSETTCSLOT "3600"
set 10 Property DURATION "236.031"
set 10 Property IGNOREFOLLOW "1"
set 10 Property PLAYBACKANDRECORD "Manual Events"

| Property | Description | | ------------------- | ---------------------------------------------------------------------------- | | FRAMEREADOUT | Frame rate display format. Common values: "24 fps", "25 fps", "30 fps" | | OFFSETTCSLOT | Timecode offset in seconds. 3600 = 1 hour offset (01:00:00:00) | | DURATION | Total duration of the timecode show in seconds | | IGNOREFOLLOW | "1" = ignore follow triggers during timecode playback | | PLAYBACKANDRECORD | Playback mode. "Manual Events" = events placed manually, not recorded live |

Timecode Tracks

Each timecode show contains numbered tracks. Each track is linked to a sequence.

cd DataPool "MyPool" Timecode 10
cd 1                                          -- Enter timecode show's track container
Store 1 "CuePoints"                           -- Create track 1
cd 1
Assign DataPool "MyPool" Sequence 240 At 1    -- Link Sequence 240 to Track 1

To add more tracks:

Store 2
Assign DataPool "MyPool" Sequence 241 At 2    -- Link Sequence 241 to Track 2

Store 3
Assign DataPool "MyPool" Sequence 242 At 3    -- Link Sequence 242 to Track 3

Command Sub-Tracks and Events

Each track has sub-tracks for timecode events. The CmdSubTrack type holds command-based events (Go, Top, etc.).

cd 1                      -- Inside a track
cd 1                      -- Enter the track's sub-track container
Store Type "CmdSubTrack" 1
cd 1                      -- Enter the CmdSubTrack

Placing Events

Events are stored with a time (seconds from timecode start) and a token (the action to perform):

Store 1
Set 1 "TIME" "8.12"
Set 1 "TOKEN" "Goto"

Store 2
Set 2 "TIME" "36.32"
Set 2 "TOKEN" "Goto"

| Token | Action | | ------- | -------------------------------------------------------------- | | Goto | Fires a Go on the assigned sequence, advancing to the next cue | | Top | Jumps to the top (first cue) of the assigned sequence | | Off | Turns off the assigned sequence | | Flash | Flashes the assigned sequence |

Assigning Cues to Events

After creating events, you can link specific cues to specific timecode events:

Assign DataPool "MyPool" Sequence 240 Cue 1 At Timecode 10.1.1.1.1.1
Assign DataPool "MyPool" Sequence 240 Cue 2 At Timecode 10.1.1.1.1.2

The address format is: Timecode {show}.{track}.{subtrack container}.{subtrack}.{event container}.{event index}

Page and Executor Assignment

Pages hold executor buttons that operators use to control sequences.

Store Page 0
Assign DataPool "MyPool" Sequence 240 At Page 0.101    -- Executor 101 on Page 0
Assign DataPool "MyPool" Sequence 241 At Page 0.102    -- Executor 102 on Page 0
Assign DataPool "MyPool" Sequence 242 At Page 0.103    -- Executor 103 on Page 0
Assign Top Page 0.102                                   -- Set executor 102 default action to Top
Assign Top Page 0.103                                   -- Set executor 103 default action to Top
Label Page 0 "Song Name"
  • Page 0.101 — Executor 101 on Page 0.
  • Assign Top Page 0.102 — Changes the executor's default button action to "Top" (jump to first cue) instead of the default "Go".

Moving and Renumbering

After building everything at temporary high slot numbers (240+), you can renumber them down to final positions:

Move DataPool "MyPool" Sequence 1 Thru At Sequence 240
Move DataPool "MyPool" Timecode 1 Thru At Timecode 10

This moves objects from the high temporary slots to their final slot numbers. The Thru keyword addresses a range.

Cleanup

Delete DataPool "MyPool" /NoConfirm

Deletes the temporary DataPool after all objects have been moved to their final locations.

Flags Reference

| Flag | Description | | --------------------- | ------------------------------------------------- | | /NC or /NoConfirm | Suppress confirmation dialogs | | /Merge | Merge into existing object instead of overwriting |

Typical Macro Workflow

  1. Setup — cd root, delete old DataPool, create fresh one
  2. Create sequences — Store sequences and cues with fade times
  3. Create timecode show — Store timecode, configure frame rate, offset, duration
  4. Build tracks — Create tracks, link sequences, add CmdSubTracks with timed events
  5. Assign cues to events — Link specific cues to specific timecode event slots
  6. Page layout — Assign sequences to executor buttons on a page
  7. Label everything — Name sequences, cues, timecodes, and pages
  8. Configure triggers — Set TrigType, TrigTime, Assert on cues
  9. Renumber — Move objects from temporary slots to final positions
  10. Cleanup — Delete the temporary DataPool

Token Syntax Variants

grandMA3 accepts two syntax forms for setting tokens:

Set 1 "TOKEN" "Goto"       -- Quoted key and value
Set 1 TOKEN="Top"           -- Key=Value format

Both are equivalent. The same applies to other properties.