GrandMA3

What it's for — CueSync drives a grandMA3 console over OSC. It fires executors, sequences, macros and Looks from your cues, pads, AutoPilot and Theatre cue lists, writes a Theatre cue list into a desk sequence and reads it back, and gives the desk timecode files it can import. This page covers the whole workflow, from the desk's OSC settings to show day.

CueSync does three different jobs with a grandMA3. Each has its own section below.

What has been checked, and on what. The command grammar, the sync pushes and the file imports were graded against grandMA3 onPC 2.4.2.2 and 2.5.0.3 by reading the console's own Command Line History and its own exported XML. onPC is console software, not a physical desk driving fixtures. Several commands have only been checked by reading MA's documentation. The list is at the end of this page. Before you rely on any lane in a show, do one dry run on your own desk and software version.

1 · Connect the console

On the desk — Menu → In & Out → OSC

CueSync talks to the desk through one OSC line in, and optionally hears back through one line out. Most mistakes on this page fail silently. CueSync reports the send as successful and the desk does nothing, because UDP cannot tell whether anything arrived. So check these settings once when you rig, not when a cue misses.

onPC and network changes. On onPC, the OSC input does not follow the computer to a new network. If the laptop moves from one Wi-Fi to another, or from Wi-Fi to a rig switch, MA-Net comes up on the new address and the OSC input stays on the old one. That survives a restart of the console software. When commands stop arriving after a move, open the OSC page, select the current interface and re-enable the input line.

In CueSync

1. Network → Outputs → Add Output, then choose GrandMA3 (UDP). It is the default for a new output, and the dialog marks it UDP OSC (recommended).
2. Enter the console's IP address. The port fills in as 8000.
3. Save. The output connects immediately.

What "connected" means for UDP. A UDP output shows green when the console's computer answers a network ping. That does not prove the OSC input is on or that the desk accepts commands. The only proof is the desk's Command Line History: every CueSync command appears there as it lands.

GrandMA3 (TCP) is for older consoles only (2.3.x). grandMA3 2.4 and 2.5 open no TCP OSC listener, so a TCP output to a current desk may never connect. TCP has only been exercised against a stand-in console, never a real one. Use UDP.

Do not add both transports for one desk. CueSync fires every grandMA3 action down every transport it has, so one desk with a UDP and a TCP output receives each command twice. A Go+ advances two cues. The Add Output dialog warns you with "Every cue would reach this device twice". A Tour Pack import or a venue profile can add outputs without that warning, so check the output list after applying one.

Network scan will not find a grandMA3. The desk opens OSC on UDP only and does not advertise itself. A scan result on TCP port 8000 is a low-confidence guess, and that port is very often a development server rather than a console. Add the desk by hand.

More than one desk (main + backup). An action with no output chosen goes to the first connected grandMA3 output. To reach a specific desk, pick that output in the action. To reach every desk, set the action to broadcast. A Theatre cue goes where its Part's or lane's routing sends it, and Flight Check grades each routed desk separately.

Schedule on the console's clock. The output editor offers OSC timetags for grandMA3. MA documents support for them, but this has not been checked on a desk. Leave it off unless you have tested it on your console.

2 · What a grandMA3 action can do

Add an action to a cue or a Cue Pad and pick one of three grandMA3 action types:

• GrandMA3 — the general action, with a verb picker.
• GrandMA3 Sequence cue — drives a sequence directly: Goto a cue (with an optional fade), Go+, or Off.
• GrandMA3 Sequence level — a sequence's master level, or Go+ / Go−.

The GrandMA3 verb picker

Pick what the action does. Only that verb's fields appear, and the Sends: strip above the form shows the exact line the desk will receive. Read it before you save. An action does exactly one thing, so any field left over from another verb is discarded.

Executors are addressed as page.executor, and CueSync writes that as Page p.e, the form grandMA3 accepts. (Exec 1.201 is not the same thing on MA3. It addresses executor 1201 on the current page.)

✔ means the console accepted the line in a verification session. Not checked and parsed only are known gaps. — means no desk session has recorded it either way.

Relative verbs do their thing again every time they are sent. Go+, Go−, Tap and Macro don't describe a state. Fired twice, they act twice. Anything that can be re-sent — a Theatre Back or Goto (see §4), a second transport, a retried pad — should use an absolute verb instead: Goto cue, a GrandMA3 Sequence cue with a cue number, a fader level, Off.

Blackout is a level, not a toggle. Blackout sets the Grand Master to 0, and sending it again changes nothing. Blackout off sets the Grand Master to 100, not back to the level the LD had it at.

Flash presses key number 100 + executor on the page, so executor 201's flash goes out as Key301. That mapping has not been checked on a desk. Test it on your console before you build a show on it.

Store cue and Clear programmer change the desk's show file or wipe the programmer, and they fire from any trigger that reaches them. Keep them on pads you press deliberately, not on beat or AutoPilot cues.

Effect needs one of Level, Speed or Size filled in. With all three empty the action is refused by name when it fires, and the Sends: strip says so. The same goes for a Speed master with no BPM, a Group with no level and a Preset with no number. None of them falls back to a Go+.

GrandMA3 Sequence level does one thing: a level, Go+ or Go−. Typing a level turns Go+ and Go− off, and ticking either clears the level. The same applies to a Look whose target is Sequence level. An action saved by an earlier version with both Go+ and a level sends Go+, and its row says Seq N Go+. Retype the level to send the level.

Decimal cue numbers. grandMA3 cues can be 1.5 or 12.25, and the cue boxes take them as you type.

Ranges. Pages 1–999, executors and sequences 1–9999, macros, groups, effects and presets 1–9999, cues 0–99,999 (decimals allowed), speed masters 1–16, timecode slots 1–8, levels 0–100 %. Those are CueSync's default ceilings, not the console's, and every one except the level is editable in Settings → Advanced → grandMA3 Address Limits. Raise one if your rig numbers past it.

Fixture selections are the ones you would type on the desk: 5, 1 Thru 10, 1 + 3 + 5, 1.1. Anything outside digits, spaces, + - ., Thru and And is refused before it leaves the app, so a stray quote or a console verb can never reach the command line. That check is not adjustable.

Default addresses. Built-in pads, starter Looks and AutoPilot's default moves (set a look, master level, strobe) address Page 1, executor 1 and Effect 1. Repoint them at the executors your show actually uses before you rely on them. AutoPilot's "master level" moves that executor's fader, not the Grand Master.

3 · Looks on a grandMA3

A Look is a named, reusable target. Cues and AutoPilot fire the Look, and you can repoint the Look without touching any cue. On the Looks screen, create a Look, choose grandMA3 as the target, then pick what it drives:

A Preset or Raw Look can't be turned off by panic or a track change. Clear it at the desk, or use one of the first three kinds if it must be released automatically.

Release groups keep one Look of a group live at a time. Firing a member sends the previous member's release first, then the new fire. Members on the same grandMA3 sequence or executor are the exception. For example, Verse = cue 1 and Chorus = cue 2 of sequence 3. The new fire replaces the old look in place, with no Off first, so the desk crossfades between them instead of dipping.

Tile state. An Executor Look turns LIVE while the desk reports that executor active (fader up or key down), once the desk's OSC output reaches CueSync (§8). It returns to idle when the desk reports it off. Every other grandMA3 Look reads SENT: the desk's feedback describes executors, not sequences, presets or command lines. Treat SENT as "CueSync sent it", and check the stage or the desk to confirm.

Shows made before Looks moved into the Scene library still carry GrandMA3 Look (legacy) actions. They keep firing through the Palette.

4 · Firing a show

DJ edition — beat cues, pads and AutoPilot

Beat, phrase and hot-cue triggers fire their grandMA3 actions the moment the music reaches them. With Pre-fire or Latency comp set on the output, they are sent early by that amount. A pad fires its action on press and its release action (if you set one) on release.

AutoPilot picks a Look for each moment of the track. With a CUT transition that has blackout beats, it sends Master "Grand" At 0 for the gap and Master "Grand" At 100 after it. That 100 is fixed. It is not the level the LD had set. The Grand Master also comes back if a track load, a resume or another transition cuts the gap short. A panic during the gap keeps it at 0.

Theatre edition — cue lists

A Theatre cue sends its actions to the outputs its Part (or its lane) is routed to. So a main and a backup desk can run different Parts, and Flight Check tells you before doors if a routed desk is down.

• GO fires the next armed cue.
• Timecode-triggered cues fire as the show clock reaches them. After a jump in the incoming timecode, CueSync replays the cues it skipped, in show order, so the desk ends on the right look.
• Goto, Back and locating the playhead don't fire the target cue on its own. For each lane, CueSync re-sends the cue that should be in charge at that point, so the desk shows what it would show there. A relative step — Go+, Go−, Tap, Flash, Macro, Store — would move the desk on from wherever it is, so the re-send leaves it out and the run log says which cue it skipped. The Theatre cue editor warns when a cue carries one. Use absolute actions on cues a jump should restore: a GrandMA3 Sequence cue with a cue number, or Goto cue.
• Spans (a cue with an automatic Off at its end) send Off Page p.e or Off Sequence N when the span ends. If a later cue on the same lane has driven that executor or sequence since, the Off is handed over to it, so the later cue's look stays up.

Choose one clock owner. If the desk plays a Timecode object imported from CueSync (§5), let the desk fire those cues, and don't also route the same cues to the desk from CueSync. If CueSync fires the cues, don't import a Timecode object for them. Leave Push follow times off on a sequence the desk runs from timecode.

Panic and blackout

Panic (the blackout shortcut, the menu, the Stream Deck key) sends Master "Grand" At 0 straight to every connected grandMA3, and pauses AutoPilot.

Releasing the blackout brings each grandMA3's Grand Master back to 100. That applies to Release and Resume alike. It's 100, not the level the LD had before the panic, which CueSync can't read back. If the LD runs the Grand Master lower, set it again on the desk. If a desk refuses the restore, CueSync names it on screen.

When the desk drops out. An action aimed at a desk that is not connected fails and is not queued. Nothing is replayed when the connection comes back. On UDP, a desk that is powered but not listening still reads as sent. Fire a Goto to the current cue after a reconnect.

5 · Preparing the show on the desk

This is Theatre and Production work, done before the show with the show stopped. The dialog is File → Sync, Import & Export → Sync to GrandMA3… (also ⌘K → Sync to GrandMA3). Every region, button and message in it is described on the GrandMA3 Session Sync page. This section is the order to do things in, and the rules that protect the LD's work.

The recommended order

1. Build the cue list in CueSync — one Theatre Part per desk sequence, cues in show order, with names and fade times.
2. Clear the desk's programmer. A first push stores each cue with Store … /Overwrite, and a Store captures whatever is in the programmer.
3. Connect a GrandMA3 (UDP) output to the desk (§1).
4. Pick a sequence. Your own work goes in the scratch range: 900–999 out of the box, changeable in Settings → Advanced → grandMA3 Sync. A sequence the LD already programmed needs the bridge and Adopt console as baseline first (step 8).
5. Read the preview. First push on a new sequence, Merge sync on one you have pushed before. Every command is listed.
6. Send to GrandMA3…, read the confirmation, Confirm send.
7. Check the desk. Open the sequence and read the cue list. Over UDP, "sent" means the commands left this computer and nothing more. If the bridge is running, CueSync checks its read-back once the plugin has had time to see the push, and names any cue the desk doesn't hold. Without the bridge, an "already in sync" verdict over UDP says it is CueSync's record, not the desk's.
8. Hand the sequence to the LD. They program looks into the cues. From now on, every push is a merge: new cues are stored, and existing ones are only relabelled or retimed, never re-stored, so the looks survive.
9. Re-sync after each edit in CueSync. The preview shows only what changed.
10. Export the Timecode XML after you sync, not before, if the desk will run the show from its own timecode (§6).

The rules that protect the LD's programming

• What CueSync may write to. The scratch range always. Any sequence CueSync holds a baseline for (one it pushed, or one you adopted), by merge only. Nothing else, unless you turn on Allow writing to ANY sequence, which should stay off.
• Cues keep their desk numbers. A cue added between 2 and 3 becomes 2.5 on the desk. It does not renumber. Where the desk number differs from yours, the desk label starts with yours, like Q2.1 - Storm, so the LD can find the cue the stage manager calls.
• Deletes are off by default. A cue you delete in CueSync stays on the desk until you tick Delete removed cues on console, and its number stays reserved.
• Moving a cue past its neighbour would put the desk's numbers out of show order, so the sync refuses. Renumbering means re-storing every cue, which overwrites the looks in them.

Things to watch

• Run the bridge, and adopt when it says the sequence differs. With the bridge running, CueSync never gives a new cue a number the desk already uses, so a cue the LD stored on the desk (say cue 4) is not overwritten. Your new cue becomes 3.5 instead. Without the bridge, CueSync can't see cues added on the desk, and its next new cue could land on one of them. When the dialog says "console sequence N differs from the last sync", click Adopt console as baseline so CueSync's record matches the desk before you send.
• Adopt with the Theatre track you'll sync selected. When that track has as many desk cues as the desk's sequence, CueSync pairs them there and then, and you can add or remove cues right away. The new ones slot in between the desk's. If the counts differ, the sync refuses and says how to fix it: make the counts match (Import as Theatre track and build on that), then adopt again, or sync to a fresh scratch sequence.
• Push everything (overwrites) appears when the show was last synced to a different console. It re-stores every cue. It asks for confirmation first, but there is no preview of that full push. Use it only when that sequence on this desk is empty or yours to overwrite.
• "Different console" is decided by IP address. A touring show that meets a different desk on the same static IP will read as the same console. At a new venue, open the sequence on the desk before trusting "already in sync".
• After a USB macro, answer the Sync dialog's question. A macro runs on the desk out of CueSync's sight. So when you export one for a sequence CueSync has no record of, the next Sync asks whether it was run. Yes: CueSync takes what the macro wrote as its record, and the push merges. No: the push is a First push that re-stores every cue.
• Push follow times gives a Time trigger to the cues that advance by themselves: timecode, follow and auto-continue cues. It uses the gap to the previous cue. GO and standby cues keep their Go trigger, so the desk waits for the operator. A desk pushed by an earlier version, where GO cues got a Time trigger too, is repaired on the next sync.
• Assign to executor puts the sequence on the executor you name (default 1.201), replacing whatever the LD had on that executor. That command has not been checked on a desk.
• Two Parts with the same name end up on the desk as CueSync Live and CueSync Live#2, because MA renames the second. CueSync keeps calling it by the name it pushed.

Whole setlists

With two or more Theatre tracks, the dialog offers Sync scope → Whole setlist. Each song gets the lowest free scratch sequence, saved with the show. Then:

• Push whole setlist… pushes every song and stops at the first failure.
• Export Setlist Timecode XML (USB)… writes one Timecode file per song, timed from the song's own start.
• Export as ONE object (every part, one clock)… writes a single Timecode object covering every Part, on the house clock.
• Auto-arm song timecode on Pioneer track load sends Off Timecode <previous> and Go+ Timecode <song> when a known track loads on a CDJ, or when the incoming timecode enters a song. The desk accepts both commands, but nobody has yet watched them start and stop timecode objects. The setlist exports save their song assignments the same way a setlist push does, so an export-only workflow arms too. Rehearse one song change before relying on it.
• When auto-arm starts a song's clock. A Go+-started object counts from 0 at the moment it is armed, and its events are timed from the song's own start: the Part's window or audio placement, or its first cue if it has neither. From timecode, a song is armed as the clock reaches that start, and a locate back into the song arms it again. If a song is armed partway through (the show started mid-song, say), CueSync says how many seconds behind its events will run. From a CDJ, the song is armed when the track loads, so its clock starts then, not when the DJ presses play. Loading the same track again does not re-arm it, because a repeated load event could restart the object mid-song.

6 · Timecode

There are three separate things here. Use one clock owner per show (§4).

Stream CueSync's clock to a desk timecode slot. In Timecode → Output Routing, enable the grandMA3 row and pick the desk's slot. CueSync then keeps sending Goto TimecodeSlot <slot> Time "hh:mm:ss:ff" while the clock runs. A cue can also start or stop a slot with a timecode action (Go TimecodeSlot n / Off TimecodeSlot n). How the desk chases a stream of Goto lines at the full frame rate has not been measured on a desk.

Give the desk a Timecode object. Export Timecode XML (USB)… in the Sync dialog writes a native MA3 Timecode object:

1. Copy CueSync Timecode.xml to the USB stick under gma3_library/datapools/timecodes/.
2. On the desk: Import Timecode <slot> "CueSync Timecode" /NC.
3. Assign it to a timecode slot and slave it to the show's timecode.

Only cues CueSync fires from timecode get an event. GO, standby and follow cues get none, so the desk can't fire them early. Event times are on the house clock: show position plus the venue origin in Settings → Timecode. The event numbers are the ones CueSync's last sync put on the desk, which is why you export after syncing.

Bring a desk timecode show into CueSync. On the desk, Export Timecode <n>. In CueSync, Import Timecode XML… creates a Theatre track from the Goto events.

23.976 and 29.97 fps. At these two rates a timecode label runs 3.6 s an hour behind real time. CueSync writes real seconds. Whether grandMA3 reads them the same way has not been checked. Check one event late in the show against the desk.

7 · The bridge plugin (read-back)

The bridge is a small read-only Lua plugin that runs on the desk and reports its sequences to CueSync. It never stores, deletes, labels or fires anything. You need it for Browse console, Adopt console as baseline, Import as Theatre track and the differs warning. Pushing works without it.

1. Turn on CueSync's OSC input first. In Settings → Advanced → OSC Input Listener, set Listen Port (9001 is the usual choice). It ships at 0, which means off. If the desk is another machine, turn on Allow other devices on the network. Leave Require signed messages off, because a console cannot sign its messages and every bridge message would be refused.
2. In the Sync dialog, click Install bridge… and choose a folder. You get cuesync_bridge.lua, cuesync_bridge.xml and INSTALL.txt, which has the exact console steps.
3. Copy the files to a USB stick under gma3_library/datapools/plugins/. On the desk, set up an OSC line whose destination is the CueSync machine and that port, with Enable Output and Send on. The plugin sends on OSC line 1. If the line you set up is a different row on the OSC page, change OSC_LINE at the top of cuesync_bridge.lua before importing it.
4. Import the plugin into a Plugin pool slot (Import Plugin <slot> "cuesync_bridge" /NC) and tap it to start. Tap again to stop.
5. The bridge row in the Sync dialog turns green with the plugin version, the console and its software version.

Keep these in mind:

• The row is live only while messages keep coming. It goes amber ("silent for N s") when the plugin stops or the desk goes away, after three scan intervals or 10 s, whichever is longer. If CueSync restarts while the plugin runs, the row sees its heartbeat but asks you to restart the plugin: the plugin only re-sends a sequence when it changes, so CueSync has nothing to read until then. An older plugin is flagged "outdated — re-export and re-import". A read-back interrupted mid-dump is marked out of date and can't be adopted or imported until a full dump arrives.
• Settings are baked in when you click Install bridge… — the scratch range, Bridge watches the whole sequence pool and Bridge scan interval. After changing any of them, re-export and re-import the plugin.
• Whole-pool reading has not been checked on a desk. Plugin 1.2.0 and later ask the desk for every sequence it holds instead of probing a fixed range. If that fails, it says so on the console's feedback line and falls back to watching the scratch range. The first time you use it, compare Browse console against the desk's sequence pool. The numbers must match.
• Messages carry a per-machine token. Plugin messages from a copy exported on another computer are refused. Re-export from the machine you sync from.

8 · Feedback from the desk

The desk's OSC output is a second, optional line. It reports executor fader and key movements back to CueSync. Set it up like this:

That feedback turns Executor Look tiles LIVE (§3). It also shows in Diagnostics → GrandMA3 Feedback (turn the Diagnostics screen on in Settings → Advanced): the last reported executor and how long ago it arrived. The feedback never gates or delays a cue. If an Executor Look fires and no feedback arrives within 30 s, CueSync says so. The message names both halves: the desk's OSC output, and CueSync's own OSC Input Listener.

9 · Show-day checklist

1. Desk OSC page: Enable Input + Receive Command on, prefix empty, port 8000, interface = today's network.
2. One CueSync output per desk, UDP. No second transport to the same desk.
3. Fire one harmless action (a Goto to the current cue) and see it in the desk's Command Line History as OK:.
4. Theatre: run Flight Check and read the per-desk lines.
5. Theatre cues use absolute actions (Sequence cue with a cue number, or Goto cue), not Go+.
6. The sequence on the desk matches CueSync: re-open the Sync dialog and look for "Already in sync — nothing to send" and no differs warning.
7. You know what the LD runs the Grand Master at. Releasing panic brings it back to 100.
8. Built-in pads and AutoPilot moves point at your executors, not Page 1.1.
9. If timecode drives the desk, only one side fires each cue.

Troubleshooting

What has been checked on a desk, and what has not

The full list, with how to check each item in one session at a desk, is on Desk Verification.

Related

• GrandMA3 Session Sync — Every region and button of the Sync to GrandMA3 dialog
• Network Outputs — Adding, testing and monitoring outputs
• Looks — Building Looks, grandMA3 targets included
• Cues — Adding actions to cues
• Timecode — The show clock, output routing and venue origin
• Desk Verification — What still needs a console, and how to check it
• GrandMA2 — The grandMA2 equivalent, over Telnet