Chapter 08

Timecode, OSC and Stream Deck

Scenic can take cues from outside: timecode from the sound cart or a playback track, and OSC from a lighting desk, QLab or a Stream Deck. Both go into the Server by the same road as a Controller's cue, so they are checked, logged and reported on each screen in exactly the same way.

#Timecode

The Timecode window (⌘5, or Window ▸ Timecode, ⌥⌘C) holds a timeline of cues that fire at set times: slide changes, blackouts, dims, grades, Snapshots, VFX, triggers and video.

Cues are run by the Server, not by a Controller, so they fire whether or not any Controller is open.

#The clock

Choose the source at the top right:

• LTC: Scenic chases linear timecode coming into an audio input on the Server Mac. Choose the input and channel from the input menu. The first time, macOS asks to let Scenic Server use the microphone; allow it. If it was refused, the window says so and Open Privacy & Security… takes you to the setting.
• Internal: Scenic runs its own clock. Use the transport buttons: return to start (↩), play and pause (Space), and stop, which returns to the last locate point.

Frame rate: 23.976, 24, 25, 29.97 DF, 30 or 60 (60 is internal only). Stop the transport to change it.

The big readout and the state beside it are the first thing to look at: Locked or Chasing while LTC is coming in, Freewheel for a moment after it drops, No Signal, or Running, Paused and Stopped on the internal clock. When LTC drops, nothing fires until it comes back.

#Arming

The Armed button decides whether cues fire at all. Disarmed, the window says "Cues are disarmed. Nothing will fire." Each cue can also be switched off on its own with the checkbox in the cue list.

When the playhead jumps decides what happens when timecode jumps (a locate, a new take): Re-arm only just gets ready for the next cue; Restore screens puts the screens into the state they should be in at the new time.

#Lanes and cues

A cue sits on a lane, and a lane is a target: a group, a Player or a single screen. Add Lane chooses which. A cue always fires at its lane's target, never at whatever happens to be selected in a Controller.

To add a cue, click the timeline where you want it and press Add Cue at Cursor, or press Add Cue under the cue list, or right-click the timeline. Then set:

Give each cue a Name ("Board up", "Pilot call") so the timeline reads like the script.

Snap (Frame, 1 s or Off) lines cues up as you drag them. Follow Playhead keeps the playhead in view. Cue List shows every cue as a table; Firings lists what fired, when, and how it went: Fired, Blocked by lock, Disarmed, or Not sent. The Cues menu exports and imports a cue list.

#Follow Timecode: a video that follows the timecode

Follow Timecode locks the video on one screen to the timecode coming in, so a sound department's Pro Tools can play, stop, jump and scrub a lyric video. It is off for every screen until you switch it on, and it is a switch on the screen's card.

The timecode comes into this Mac (the Controller), the one that runs the Server, not into the Player. Use Timecode ▸ Input Setup to choose the audio device and channel. It shows a level meter for the channel (and small meters for the others), the timecode it reads, its frame rate and one state: Receiving, No signal, Too low, Clipping or Audio but no readable timecode. If it hears timecode on another channel it says "Signal found on Channel 2 — switch?".

1. Send the video to the screen and let it play.
2. On the screen's card, switch Follow Timecode on. This also starts the timecode input.
3. Line the video up: with the timecode parked on a moment you can recognise in the video, open Window ▸ Transport (⌥⌘T), scrub the video to the matching frame with its scrubber and press Sync Here. It sets the line-up from the timecode now and the video's position now, so extra seconds at the start of the video, or of the song, are both handled. The line-up reads as a sentence: "Timecode 01:00:00:00 = video 0:05.00". −1 frame and +1 frame nudge it, and Type the line-up… takes both values.

The card says what the screen is doing:

The card and the Transport window show both where the Server aimed the video and where the Player last reported it, with how old that report is. A frame-rate mismatch between the timecode and the video is shown as a warning; the video still follows by time.

#OSC

OSC (Open Sound Control) lets a lighting console, QLab, Bitfocus Companion, TouchOSC or any other OSC sender cue Scenic over the network. The Server receives it; Controllers and Players never do.

#Turning OSC on

Open Settings ▸ OSC on any Mac Controller.

1. Turn on Enable OSC. The status line reads "Listening on UDP port 8000."
2. Leave Port at 8000 unless your console needs another.
3. Listen on: Show network lets any console on the show network send. This Mac only refuses everyone else.
4. Optional: list Allowed Sources, such as 192.168.1.0/24 or one console's address, to accept only those.

The settings belong to the Server's Mac, not to a Show.

More options in the same pane:

• Send feedback sends status (blackout, slide, dim, each screen's delivery) to a Destination address and port, for a console that shows it.
• OSC over TCP also listens for TCP on the same port, for consoles that prefer it.
• Discoverable (OSCQuery) publishes the whole address space, with the open Show's Player, group and Snapshot names, so an OSCQuery-aware app can browse it (port 8001).
• Duplicate window (0.1 seconds) ignores the same command twice from the same sender within that time, which tames bouncing buttons. A different value or target always goes through.
• Log lists every message with its time, sender, address and outcome: Done, Refused, Locked, Duplicate or Not understood.
• Address Catalog lists every address Scenic understands.

#What a command acts on

/scenic/next with no target acts on the OSC selection: All Players, until a console sends a /scenic/select/.... Add a target to the address to be exact:

Names use underscores for spaces and ignore case. A name that matches nothing, or more than one thing, is refused and logged, never guessed. To copy an exact address, right-click a screen or group in the Player List and choose Copy OSC Address.

Settings ▸ General ▸ OSC follows the Player List selection changes the default: an untargeted command then acts on what is selected in a Controller's Player List. Use it when the console operator and the Scenic operator are working the same screens together.

While the Show's input lock is on, every OSC command is refused and logged. A Controller's Interface Lock does not stop OSC.

#Common cues

#Stream Deck through Companion

Bitfocus Companion turns an Elgato Stream Deck into a button panel. Scenic has a Companion module, StageGlass Scenic.

1. On the Server's Mac, turn on OSC (above). If Companion runs on another computer, leave Listen on at Show network.
2. In Companion, add a StageGlass Scenic connection.
3. Set Server address to the Server Mac's IP address, OSC port to 8000, and Transport to UDP (or TCP if you turned on OSC over TCP).
4. Drag the presets onto buttons: Next (All Players), Previous (All Players), Blackout toggle (All Players), Computer Labels toggle (All Players) and Server status.

Actions include Next slide, Previous slide, Go to slide, Blackout (toggle, on or off), Computer Labels, Recall Snapshot, Select target for OSC and a Custom OSC command. Each can target the OSC selection, All Players, a Player, one screen, a group or an alias. Refresh Player, group and Snapshot names reloads the lists after you change the Show.

Buttons can show what happened: a screen's feedback lights amber when the Server has accepted a cue and green when the Player reports it on screen. Other feedbacks show when blackout is on and whether the Server is answering. Variables carry the slide, slide count, connected Players, blackout, dim and timecode for button labels.

#OSC address reference

This is the Server's own address table.

#Connection

Numeric arguments accept any numeric type or a numeric string: 20, 20.0 and "20" all mean 20. Values outside a range are clamped to it, except slide numbers, which must be 1 or more. Extra trailing arguments are ignored. A command that cannot be understood is rejected and logged in the Network window.

#Address spaces

Every address starts with /scenic. Where a command has a shorter form, both are listed.

Names use underscores for spaces and ignore case: Stage_Left is "Stage Left". A name that matches more than one Player is refused, never guessed. Commands marked show apply to the whole show and take no target prefix. Commands marked Player cannot be sent to a single screen. The same command sent twice within the duplicate window (default 0.1 s) is delivered once; a different value or target is always delivered.

#Replies and updates

These follow QLab's conventions. They describe the conversation with one console and never change what the screens show. Each also works under /scenic (/scenic/thump).

A reply goes back to the sender, the way the message came (UDP or TCP), at /reply followed by the address it answers, for example /reply/scenic/next. Its one argument is a JSON string: {"address": "/scenic/next", "status": "ok", "data": ...}. The status is ok when the Server accepted the command or answered the query, denied when the Show's input lock or a takeover stopped it, and error otherwise; data then holds the reason. A query's data is its answer, and a Snapshot recall or capture's data is its outcome.

A sender the Server has not heard from for 60 seconds is forgotten: it must send /alwaysReply and /updates again. A sender that is not allowed is never answered.

#Slide & Build

#Blackout & Dim

#Video

#Audio

#Color & Grading

#Overlays

#Trigger Overlays

#Test Patterns

#Aspect

#Snapshots

#Timecode Transport

#Selection

#Queries

#Test pattern names

solid_white (Solid White), gray50 (50% Gray), solid_red (Solid Red), solid_green (Solid Green), solid_blue (Solid Blue), simple_bars (Simple Bars), smpte_bars (SMPTE Color Bars), camera_color_card (Camera Color Card), gamma_pattern (Gamma Pattern), ramp (Grayscale Ramp), crosshatch (Crosshatch Grid), full_hdtv (Full HDTV), audio_sync (Audio Sync), led_wall (LED Wall), arib_bars (ARIB Bars), hdr_bars (HDR Bars), sdi_bars (SDI Pathological)

Names ignore case and underscores, so SMPTE_Bars and smptebars also work.

#On the Server

OSC is received by the Scenic Server, not by a Controller or a Player. It is off until you turn it on in Settings, and the setting belongs to the Server Mac, not to a Show. If the port is in use the Network window says so; the Server never moves to another port.

An OSC command goes down the same path as a Controller's: it is accepted or refused by the Server, sent to each screen once, and shown in the operation history as coming from OSC. Once OSC is on, any console on the show network can send; Allowed Sources narrows that, and This Mac only refuses everyone else and names them.

#Feedback

With feedback on, the Server sends status to each destination as UDP OSC under /scenic/status/: blackout, slide (index from 0, count), connected, overlay (active, slot from 1), dim, testpattern, timecode (state, position) and one screen row per screen (Player, screen from 1, delivery, slide from 0, slide count, blackout). A screen's delivery is sent until the Player acknowledges the Server's last command to it, accepted once it has, and observed only when the Player reports the result; offline, differs and failed say what went wrong. A Companion button shows accepted in amber and observed in green. Values are what the Players report: blackout is 1 when every connected screen is black, and dim is the deepest dim. A change goes out at once and then at most every 200 ms per address, ending on the newest value. Every value is sent again when the listener starts, when a destination is added and when another Show opens.

A console's query/players, query/groups, query/selection, query/timecode and query/snapshots are answered on the matching status/ address. A Snapshot recalled or captured from a console is answered on status/snapshot with captured, recalled (with screens reached and total), notfound, nomatch or failed. When names repeat, the newest capture wins.