Unreal Engine

What it's for — CueSync drives an Unreal Engine world the way it drives a lighting desk. The free CueSync for Unreal plugin receives the CueSync Bus over OSC, so the level moves with the music — beat, energy, key and phrase arriving as normalized 0→1 values, with anticipation ahead of the drop — and, optionally, follows your cue stack and timecode over a second, reliable link.

There are two connections, and the second one is optional:

The reactive link is what most projects need. Add the show link when the world has to follow the show — cues that release cleanly, and scrubbing that doesn't leave anything stuck on.

---

Requirements

• Unreal Engine 5.8, macOS or Windows.
• CueSync for Unreal 1.8 or later; install the latest release to get every feature on this page. An older plugin can silently ignore commands it does not know, and the output card flags the gaps it can detect (blackout, level cues, band split).
• CueSync itself is macOS on Apple Silicon. A Windows Unreal machine is fine — it just needs a Mac running CueSync on the same network to drive it.

Install the plugin

1. Get the free plugin from its Fab listing, or through cuesync.live/unreal; install it from Fab, or copy CueSyncForUnreal/ into your project's Plugins/ folder.
2. Enable CueSync for Unreal in Edit → Plugins. It auto-enables the stock OSC and Niagara plugins.
3. Restart the editor.

Connect the reactive link

In Unreal:

1. Drag a CueSync Bus Manager actor into your level — or add a CueSync Bus Receiver component to an actor you already have.
2. Leave Bus Collection empty to use the bundled MPC_CueSyncBus, or point it at your own Material Parameter Collection.
3. Press Play.

In CueSync:

1. Open Network → Outputs → Add Output and choose Unreal Engine 5.
2. Set the host to the Unreal machine's IP and the port to 8001.
3. Connect it. See Network Outputs for the connection states and what each one means.

That is the whole reactive setup. Read the collection in any material or Niagara system; bind the accent events in Blueprint.

What arrives on the bus

The plugin writes these thirteen values into the Material Parameter Collection:

Anticipation is the one to build against. The bus carries how many beats remain until the next drop, and the plugin turns that into a smooth ramp that peaks on the downbeat and falls away. A world driven by Energy alone reacts after the moment; a world driven by Anticipation arrives with it.

The band split is the one that makes a rig look programmed. Energy is one number for the whole mix, so everything bound to it swells and falls together — a stage that reads as a level meter. Bass, Mid and High let the kick drive the floor pods while the hats drive the strobes. From a prepared track they follow the track's beat; switch on Settings → Audio → Booth Input and they come live from the room with real transients, which is how a live band, a guest's laptop or a CD drives the world at all.

Every single-signal driver has a Drive Source dropdown — Energy (the default), Bass, Mid, High or Anticipation. The Niagara and Material drivers instead gain three extra named parameters, because a material is a fan-out and not a single intensity: bass in the displacement and highs in the sparkle, at the same time.

Accent events

These fire as Blueprint events on the bus component. Bind your own art to them.

Two of them also act on their own, because a show-safety command must not depend on a project having wired a Blueprint: Blackout fades the player camera and holds until CueSync releases it, and LoadLevel / UnloadLevel perform the matching streaming call. Both can be turned off per actor (bApplyDefaultBlackoutFade, bApplyDefaultLevelStreaming) when the project owns that flow itself.

An Unreal Look, and its preset

An Unreal Look (Palette → new Look → Unreal) calls one function on one Remote Control preset. Its Preset field says which:

• CueSyncBus, the default, is the plugin's own. The function has to be one of the table above, and Save says so if it is not: the plugin ignores any other name, so a Look that looked fine would do nothing on the stage.
• Any other name is a stock Remote Control preset of your own, such as a Show preset exposing Look1…Look10 as Blueprint functions. The function is whatever that preset exposes. CueSync calls /RemoteControl/<preset>/<function> once per fire, carrying only the function's own arguments (numbers as numbers, anything else as text). A Look, a pad and an Unreal action in a cue all do this. The plugin is not involved, so nothing checks the function name: a wrong one fails on the Unreal side. (A function named like one of the plugin's, such as Blackout, is the plugin's whatever the preset.) The tile shows the preset (Show · Look1) when it is not the default.

Looks saved by earlier versions stay on CueSyncBus.

Drop-on drivers

Add a driver component to any actor and it follows the bus with no Blueprint graph. Each one finds the bus itself and stays inert when there isn't one.

Fixture groups. Each group has its own Drive Source, which is the fastest way to make a truss look authored: put one group on Bass and another on High and they alternate with the music instead of flashing in unison. Tag your lights CueSyncGroup:<GroupName>. Tagged actors are ordered by actor label, so Truss_01…Truss_12 chase in the order you named them and a re-run cannot reshuffle a look you rehearsed. That order is saved with the level, because a packaged build has no actor labels: open each level that uses a tagged group (or a Camera Director) and save it once, and after you add, remove or relabel a fixture. Map Check tells you when a group's saved order is missing or out of date. Leave BaseIntensityOverride at 0 and each lamp keeps its authored intensity as its own base, so a hand-lit stage gains movement instead of being flattened to one number.

Show modes

Place a CueSync Show Mode actor in the persistent level to run one map three ways — Live, Capture and Demo. Each mode applies its own console variables, loads or unloads its streaming levels, and sets the camera director's blend time.

Demo drives itself: the plugin runs its own clock, an energy swell, a band pattern, a hue drift and a scripted accent timeline, with no desktop, deck or operator attached. It yields the moment a real CueSync stream arrives and hands back if that stream stops, so plugging in mid-demo is a silent handover rather than two shows fighting over one bus.

When the plugin reports its mode, CueSync shows it in the output's configuration panel. It is worth reading before a show: Capture removes the framerate cap that holds a live show at a locked 60, and Demo means the level is driving itself.

Switching the mode from a cue

An Unreal action of kind Show Mode — Live, Capture or Demo — switches it from the desk: Capture before a take, Live before doors. The pad library's Capture Take is a toggle that switches to Capture and back to Live on release, and Show Live switches to Live.

It travels the paired show link (below), so it needs the pairing and a current plugin, and it is the one Unreal action that waits for an answer: the cue succeeds only when Unreal confirms the switch. Otherwise it fails and says why —

• the level has no CueSync Show Mode actor, so nothing could switch and no take is rolling;
• Unreal did not answer in time (a busy editor, or a plugin too old to take it from the desk) — treat the take as not rolling; if the answer turns up later, CueSync tells you it applied after all;
• the output is not the one holding the show link (the message names the one that is), has no pairing token, or the link is down. A Show Mode switch is never queued to be sent on reconnect: a take that starts late is a different take.

Like every send on the show link, it sends nothing in Rehearsal / DRY RUN or without an active licence.

Authoritative show output (the show link)

Pair once, and CueSync mirrors its authoritative cue and timecode state to Unreal over a reliable link, so nothing is left orphaned: rewinding a Theatre show reverts the world cleanly instead of leaving values stuck on, and stopping it releases what its cues owned. A Cue Stack cue has no stop of its own, so the channels it set are released with everything else CueSync releases — on panic, on a track change, and when you open another show.

Every way of firing reaches it. A channel set from a Cue Stack cue, a pad, a scene, an AutoPilot moment or a triggered cue all travel the show link on the output that holds the pairing. On that output CueSync also refuses a Blueprint function the plugin does not offer, naming the address, rather than reporting it sent; an output that is not paired is left alone, because it may be stock Remote Control. If the link is down when a channel is set, the value is held and applied the moment it reconnects, and the event log says so.

The show link obeys the same two switches as every other output: it sends nothing without an active licence, and nothing in Rehearsal / DRY RUN — when the rehearsal ends, Unreal is handed the show's real state at once, and a look that was only rehearsed never reaches the stage.

1. In Unreal, open Window → CueSync Monitor and click Open pairing page (or browse to http://<unreal-machine-ip>:8090/). The page shows a pairing token. It survives editor restarts, so you pair once. The Monitor shows the token masked — press Show to read it — and New token replaces it and unpairs every device at once (use it if a device you do not recognise has paired). Optionally click Require PIN in the Monitor to add a PIN; setting or changing a PIN also unpairs every device, so CueSync must connect again with it.
2. In CueSync, edit the Unreal Engine 5 output and open Authoritative Show Output (optional).
3. Paste the pairing token, and the PIN if you set one. Leave the control port blank to use the plugin's default (8091, the plugin's HTTP port + 1). If you moved the plugin's HTTP port from 8090, tick Use a different port under Liveness Check and enter it in REST/health port; the control port follows it.
4. Connect. A wrong token or PIN reports a clear error rather than failing quietly — and so does one changed in Unreal after pairing: the output shows Token/PIN refused until you re-enter it. If a second desktop takes the link over, the first one shows Another desk took over and stops; switch its output off and on to take the link back.

A pairing token belongs to the address you typed it for. One saved before that, or typed for another address and then re-pointed, is not sent to the new address until you agree: the output connects without it and a notice asks Send the pairing token to <address>? with a Send pairing token button. Your answer is remembered for that address.

Once paired, the panel also lists the channel names Unreal has bound, so you can see from CueSync what the world is actually listening for.

A Theatre cue that loads or unloads a level follows the show state while the link is up — the level is part of the show there, so scrubbing back unloads it — and loads directly while the link is down, so it still loads on time.

Two Unreal outputs

One output holds the show link at a time — the first paired output to connect. The others still get the reactive link, accents and levels, and their card says Plane-B: link owned by another output (the card's name for the show link). What that means for a cue:

• An Unreal action that names an output (a target) belongs to that output. A channel aimed by name at the second machine is never set in the first machine's world.
• A show-link channel or a Show Mode switch aimed at a second output that is paired but does not hold the link fails and says so — it cannot reach that machine.
• If the output holding the link drops, the link passes to the next connected output with a pairing token, which is handed the whole show state at once. Channels a Cue Stack cue had aimed at the machine that dropped do not follow the link; untargeted and broadcast ones do, so a main-plus-backup pair keeps its look. (A pad's channel cannot say which machine it was meant for, so it follows the link.) The machine that dropped does not take the link back when it returns.

A cue reaches a second machine's show link only by holding the link there — the desk drives one paired Unreal's authoritative state at a time. A Theatre track's or lane's output list does not apply to the show link: name the output on the action itself.

Timecode genlock

Once paired, the plugin becomes the engine's timecode provider when locked timecode arrives from CueSync, carrying the show playhead — including a deck on its pitch fader. Pairing alone leaves whatever the engine was using (an AJA card, an LTC reader) in place, and the engine's previous provider is handed back when the last desktop disconnects or is unpaired. A second desktop that pairs replaces the first: the first is told and disconnected.

To make a Level Sequence follow it, put a Sequence Director in the level, assign the sequence to its Timecode Sequence and tick Chase Timecode. That sequence follows jumps, scrubs otherwise, and rides over momentary gaps. It is one sequence and it is opt-in — it needs the pairing above. Unreal's Map Check reports a chase armed with nothing behind it.

A scrubbed playhead follows everything Sequencer evaluates continuously — transforms, cameras, curves, material parameters — but does not fire the sequence's own event track, play its audio, or respawn spawnables. Drive one-shots from CueSync cues instead. See Timecode for the CueSync side.

Bringing a Level Sequence's markers in

An artist who blocks a piece in Sequencer has already decided where things happen — the markers say so. File → Sync, Import & Export → Import Unreal Sequencer Markers… reads them in as a new Theatre track, so the desk follows what was laid out instead of the two departments keeping separate lists. It is also in ⌘K under the same name.

The file it reads is the one the plugin's Content/Python/cuesync_tools/export_sequence_markers.py writes (run it headless against your project; the script's own header has the command line) — a small CSV with a Frame, a Function and an Arg per marker, plus one CutToCamera row for each section of a camera-cut track.

• A marker named after an accent becomes a cue that fires it. TriggerDrop, CutToCamera(2), StopSequence(Intro) — anything in the accent table above — arrives as an Unreal Engine action on the cue, argument included.
• Any other marker becomes a labelled position that fires nothing. Chorus is a note to a person, and CueSync keeps it as one: the cue is there, named, at the right time, with a note saying why it is empty. It is never dropped, and never turned into a cue that sends something the plugin would not receive.
• CueSync judges each marker by what it can actually fire, so a file exported by an older or newer plugin still imports correctly.
• The track is named after the file and lands on the output lane you are looking at. One undo removes it.

The frame rate is asked for, never assumed

A marker is a frame number, so where it lands depends on the sequence's frame rate — and that is often not the show's. A 24 fps cinematic cut read at a 25 fps show's rate puts every cue 4% early: more than a second and a half by the end of a 40-second shot.

If the file has an Fps column, CueSync uses it and says so. If it does not, you are asked for the sequence's display rate — the one in Sequencer's toolbar — from a list, with 30 preselected because that is what the plugin's own bake tool defaults to. The two NTSC rates are offered as their exact fractions. Closing that dialog imports nothing; CueSync will not fall back to the show's frame rate, because that is a guess that leaves no trace. The confirmation tells you which rate was used and whether the file or you supplied it.

Rows that cannot be read — a frame that is not a number, a marker before frame 0, a blank label — are skipped and counted in the confirmation, with the first reason spelled out.

Baking a track into a Level Sequence

A live show is a live show: the bus arrives over the network and the world reacts a frame or two later. For a render you want the opposite — every value keyed on the frame it belongs to, so the film can be path-traced offline. That is what the bake is.

File → Sync, Import & Export → Export Unreal Bake Curve… (also in ⌘K) writes a CSV with one row per display frame for the local track currently loaded in the queue: the thirteen values the plugin's bus component would have written to MPC_CueSyncBus had the track played live — beat and bar phase, energy, hue, tempo, trend, phrase, the drop anticipation ramp, bars-in-phrase and the three bands. It asks for the sequence's display rate first, because a row is a frame and a frame is only a time at some rate — and it writes that rate into the file as an Fps column (24, or the exact 30000/1001, never 29.97), so the rate is never retyped.

• It needs a working licence. On an install that is in read-only mode the command answers Subscribe to export the Unreal bake curve — you're in read-only mode with a Subscribe button, and nothing is written.
• What a bake moves is the material parameter collection. The curve keys MPC_CueSyncBus, so every material bound to it renders exactly as it played. The driver components do not read the collection — a Light, Fixture Group, Transform, Post Process, Niagara or Camera Shake driver reads the live bus component — and a marked frame fires nothing under Movie Render Queue, so in a render those drivers hold still and the accents are positions, not events. Dress a shot you intend to bake from the collection (materials, or Sequencer tracks keyed off it).
• It is a replay of your track. The curve matches what the plugin would have played live, including the corrections and marker edits your playback uses. Smoothing in the plugin is reproduced at its default settings. A project that changed those settings renders differently, as it would live.
• Only a local track in the queue can be baked. A Pioneer deck's track cannot be replayed from a file the desk does not have, and a Theatre part's audio is not analysed by the queue. The command says so rather than writing a silent curve.
• The accents are AutoPilot's plan. Beside the curve, …-accents.csv lists the fires AutoPilot has planned for this track that reach an Unreal function, on the frame of their beat, in the same file shape the plugin's own marker export writes. Planned, not performed: fires decided live against the room are not written, and the confirmation counts the planned fires that carry no Unreal accent. Pass the file to build_show_sequence.py --accents and each becomes a marked frame. The file opens safely in a spreadsheet: a function name or argument that starts with =, +, @, a tab, or a minus sign that is not a plain number is written with a leading apostrophe so the spreadsheet shows it as text, and a line break inside a name stays inside its cell instead of splitting the row.

Then, in the plugin: Content/Python/cuesync_tools/build_show_sequence.py --curve <the file> --accents <the accents file> --into /Game/Shows/LS_MyShow --fps <rate> builds the sequence headlessly, and verify_show_sequence.py beside it reads it back against the curve.

Rendering a track: the render kit

File → Sync, Import & Export → Export Unreal Render Kit… (also in ⌘K) writes everything a render needs into one folder, so you can run it without typing a command line. It asks for the film's frame rate and for a folder. If the folder is empty, the kit goes straight into it. Otherwise CueSync makes a new <track>-render-kit folder inside it, so nothing already there is overwritten.

On the machine that has Unreal Engine and the current plugin installed in your project, double-click render.command, drag your project's .uproject into the window, and type the level to render in (for example /Game/Maps/MyStage). On Windows, drag the .uproject onto render.bat and answer the same question. A render plays the take inside a level, so the scripts ask for one before Unreal starts. To skip the question, add "level" to take.json. The camera cuts follow that level's Camera Director; a level without one still renders, with no cuts. In that level, CueSync Show Mode must not be set to Demo: Demo drives the bus itself and overwrites the baked values. The script finds the engine (in UE_ROOT, or else the Epic Games Launcher's default install folder) and the plugin (in the project's Plugins folder or the engine's Fab folder). It builds /Game/CueSync/Takes/LS_<track> and its Show Take TK_<track>, then renders with Movie Render Queue at final quality as 1920×1080 PNG frames by default. With ffmpeg installed, it also makes an mp4 with the track's audio, in the kit's render folder. Logs go to logs. When something is missing, the script says what.

• Spaces in any path are fine. The level is the only argument you type, and an Unreal level path cannot contain a space.
• The audio is the track, not the analysis. It is decoded at full fidelity. If CueSync cannot do that for a file, the original goes into the kit as audio-source.<ext> and the confirmation says why. The script then rebuilds audio.wav from it with ffmpeg, if you have ffmpeg.
• It needs an active licence, the same as a live Unreal connection. Export Unreal Bake Curve and Export Unreal Render Kit are in the File menu on DJ and Production, the editions with Local Audio; a paid Theatre edition does not list them.
• The accents are still a plan. They are what AutoPilot planned for the track when you exported it. Fires decided live against the room are not in the kit. The README and the confirmation both say so.
• CueSync does not start Unreal itself. The render runs wherever the engine and the project are, which is often not the desk. The kit is how the show gets there.

The tablet remote

The plugin serves a LAN-local control surface on port 8090 — open it on a tablet and drive the world from the floor. It uses the same pairing token as the show link, and it lists whatever the level has registered: cameras, camera moves, screens, clips and Level Sequences — each sequence with a stop beside it, which is the control a drop fired early otherwise has nowhere.

Ports, and exactly when they are open

A game you ship to end users should not open listening sockets because a plugin is enabled, so the web remote is editor-only unless you opt in. A stage build that needs the tablet or show-link control turns it on in the project's Config/DefaultEngine.ini:

[CueSync.WebRemote]
bEnable=True

or with -CueSyncWebRemote=1 on the command line. The OSC bus on 8001 is a separate listener and works in cooked builds either way — a packaged world still reacts to the music with the remote off.

A packaged build with the remote off answers nothing on 8090, and CueSync cannot tell that from a closed editor — so by default it judges the output dead and keeps reconnecting it, and the music bus stops each time. Tell it which it is: in the output's Liveness Check, tick Packaged build without the web remote (music bus only). CueSync then checks only that the machine answers, and the bus streams steadily. The price is said on the box: CueSync can no longer see whether Unreal itself is running, and pairing, Show Mode and the plugin's health line need the remote on.

The plugin serves a read-only status page without the pairing token: CueSync uses it to check that Unreal is alive before pairing, and it shows status only — nothing that can change the show. Everything else on the web remote requires the token. The OSC link on UDP 8001 does not use it: switch on Restrict Senders on the plugin to accept it only from listed and paired addresses, and keep both on a network you control.

The plugin makes no outbound connections, collects no telemetry and requires no account. Keep 8090 and 8091 on your show LAN — never expose them on a routable interface.

Emergency blackout

CueSync's blackout reaches Unreal like any other output. The plugin fades the player camera itself, whatever drivers you wired, gates every driver, holds the Material Parameter Collection's continuous values at 0, and stays dark until CueSync sends the release. A bus that begins play while a blackout is engaged comes up dark, and only a release clears it. If Unreal restarts during a blackout, CueSync re-sends it with a warning. The Monitor shows a Release button while it is engaged, and CueSync.Blackout 0 lifts it from a console. Bpm and PhraseId keep reporting live values, because a readout claiming 0 BPM during a blackout is a lie about the music rather than a safety measure.

Troubleshooting

Where to look first. Build → Map Check lists the setup mistakes that make a correct build look broken, each with a link to the actor, and runs when a level opens and when Play starts (switch it off in Project Settings → Plugins → CueSync). The CueSync Monitor's top row says whether beats are arriving, and where to point CueSync (with Copy IP). In a packaged build with no Monitor, the console command CueSync.Status says the same in words, and the tablet page reports whether a bus is present and listening.

A driver set to Bass, Mid or High does nothing. Update the plugin to the latest release, and make sure the desktop is publishing the split. The output card names the gap: "Plugin x.y.z · update for the band split (Bass / Mid / High)". On a current plugin, check the Monitor's Bass/Mid/High meters — if they move, the bus has the signal and the driver is where to look.

Nothing moves. Check the output shows connected in Network Outputs, then confirm a bus actor or receiver component is actually in the level being played. The plugin logs the addresses it receives — the reactive link is one-way UDP, so the Unreal log is the only place the truth exists.

Lights ignore everything. A light placed in Unreal is Static by default, and a static light refuses intensity changes at runtime. Set the ones you want driven to Movable.

The whole rig flashes together. That is the Auto Reactor driving every light identically. Tag the fixtures into a group and use the Fixture Group driver.

A packaged build's output keeps dropping and reconnecting, and the world stutters with it. The build does not serve the web remote, so the health check finds nothing — see Ports above: switch serving on, or tick Packaged build without the web remote on the output.

The tablet can't reach the page. Confirm you browsed to the machine's LAN address rather than localhost, that the editor is running, and that macOS or Windows firewall is allowing Unreal. In a packaged build, check the bEnable=True opt-in above.

Pairing says denied. Repeated wrong tokens or PINs from one address pause that address for a short while; wait, then retype rather than restarting the editor. To rotate the token entirely, press New token in the CueSync Monitor.

A media clip doesn't appear. Check the screen id first: it must match the Media Driver's Screen Id (0 by default; −1 on a driver means "every screen"). Then the clip id, which compares case-sensitively — an unknown id logs a warning naming both it and every registered id.

A level won't stream. The name must be a streaming level of the persistent level. An unknown name logs a warning naming the world rather than failing silently.

---

See also: The CueSync Bus — the same vocabulary as plain OSC, for every other engine · Network Outputs · Timecode · Diagnostics · Protocols