Skip to content

Getting started ​

Start ​

You do not clone Single Studio, and you do not need a copy of this repository. A studio is your own repository with @single-studio/core as a dependency.

Press Use this template on Single-Studio-Template, name your repository, and clone it.

With gh instead, the same two steps also switch Pages on, which is the one thing you would otherwise have to do by hand before the first deploy:

bash
gh repo create my-studio --template FourCourtJester/Single-Studio-Template --public --clone
gh api -X POST repos/<you>/my-studio/pages -f build_type=workflow

Then, in the repository:

bash
npm install
npm run dev

npm, pnpm or yarn — the template ships with npm because it comes with Node, and nothing the framework does needs a particular package manager.

Open the printed URL. That is the control surface. The header's menu holds the setup a board needs and a show does not: Browser sources lists every graphic's URL with a copy button, alongside the image store and the collaboration settings.

Start over is the last item, under a rule of its own, and holds the three ways to undo:

  • Reset the show — every name, score, timer and toggle back to its default, on every machine in the room. The image library is kept: the show is what happened tonight, the library is what somebody spent an afternoon filing, and one button that loses both is one nobody dares press.
  • Disconnect from collaboration — leave the room and drive the show from this machine alone. Nothing is deleted and the graphics do not miss a frame; the invite link still works if you want to come back.
  • Shut somebody out — a brand new key, which is a brand new room. Offered only on an encrypted show, because that is the only kind with a key to rotate.
  • Reset this machine — the show, the images, the room, your name, everything this browser has stored, and then a reload. It leaves the room before it wipes anything, so the other machines keep the show. This is the one to reach for after a rebuild.

Emptying the image library is not in there. It lives in the image store beside the images, because it is the only one of these whose blast radius is a thing you are looking at.

Each asks twice: one click arms the button, it says Click to confirm, a second does it, and a few seconds of silence disarms it. Deliberately not window.confirm — the board's main home is an OBS custom browser dock, where a native dialog may never be drawn, and a guard that silently reads as "they said no" is a guard that quietly stops the button working.

Each copied URL carries ?layer-name=SS - <studio> - <Source>, which is the name OBS gives the browser source. The display name is title-cased from the source's key, so a key written for a URL (lower-third) reads as English in a scene list (Lower Third) without anybody maintaining a second copy of it.

Wire a studio into OBS ​

  1. Control surface — Docks → Custom Browser Docks, pointed at the app root (.../#/).

    Run it as a dock, not in a separate browser. The dock and your graphics share one show because they are in the same place. A separate browser window is a separate place, with a separate copy of everything.

  2. Each graphic — one Browser source per URL from the control page. Set the resolution to your canvas (usually 1920x1080).

    Shutdown source when not visible is safe to enable if you want the memory back. The graphic is rebuilt from scratch each time its scene returns, and nothing is painted until the store has answered — see Loading and reload.

    Use Copy rather than retyping what is on screen. What it puts on the clipboard carries an OBS parameter the displayed URL leaves off:

    http://localhost:4173/?layer-name=Demo%20scoreboard#/source/scoreboard

    layer-name is what OBS names the source from. Routing is hash-based, so every source on a studio shares one origin and one path — without the parameter OBS sees a dozen copies of the same page, which is how a scene ends up full of localhost, localhost (2), localhost (3). It sits ahead of the hash because that is where OBS looks, and it is plain text: edit it if you want the source called something else.

What the template gives you ​

Pressing Use this template leaves you with a working studio, not a skeleton — a control surface, a graphic, and a Pages deploy already wired. npm install pulls @single-studio/core from npm like any other dependency.

Two folders are the ones you will live in:

FolderHolds
src/control/The operator's board — Control.jsx composes panels/
src/sources/One file per graphic — each becomes a browser source

Then, as you need them:

src/mutations/How your show's data changes — see Your own data
src/studio/The studio itself: what it is called, what it registers, and the worker that holds the show
src/css/Tailwind, and anywhere you want your own CSS

Name it ​

src/studio/config.js is the one file worth editing before anything else:

js
export const STUDIO_NAME = 'My Studio'
export const STUDIO_ID = 'my-studio'

STUDIO_NAME is the label — it titles the board, and OBS shows it in front of every browser source (SS - My Studio - Lower Thirds / Single). Change it whenever you like.

STUDIO_ID is where the show is filed. It names the databases and the shared worker that the board, the previews and every browser source find each other through, so changing it after you have built something starts you on an empty show. Pick it once.

The rest is wiring that already works. Have a look around the template repository if you want the full tour.

Add a graphic ​

Create src/sources/MyGraphic.jsx, default-exporting a component. That is the whole step. It appears in the control surface's Browser sources list with a copy button and the name OBS should give it — no list to add it to, nothing to register.

The filename decides the address, and folders group:

FileURL
src/sources/Scoreboard.jsx#/source/scoreboard
src/sources/LowerThird.jsx#/source/lower-third
src/sources/lower-thirds/Single.jsx#/source/lower-thirds/single
src/sources/game/Scoreboard.jsx#/source/game/scoreboard

The group carries through to what OBS calls the source — SS - My Studio - Lower Thirds / Single — so a scene list sorts the way your folders do.

Rename the file and the URL changes with it. That is the point: the folder is the only place a graphic is named, so there is nothing to keep in step and nothing to forget to update.

src/sources/ is only for graphics. Everything in it becomes a browser source, so a shared plate, a hook or a helper belongs somewhere else — src/components/ is the obvious home. A file left in sources/ by mistake turns up in the operator's list and in OBS, which is a confusing way to find out.

Add state ​

Nothing to declare. Write to any path and read it back:

jsx
<Field name="home.name" label="Home" />        {/* writes variables.home.name */}
<Variable name="home.name" fallback="Home" />  {/* reads it */}

Namespaces (variables, toggles, timers) are fixed per component: Variable reads variables, Toggle reads toggles, Timer reads timers. You never pass one -- the name you give a component is the part after it.

Use a counter ​

Stepper and the increment/decrement mutations store values so that concurrent edits add up rather than overwrite each other. Use them for anything numeric an operator adjusts — scores especially.

step sizes the buttons, so a sport scoring in threes is <Stepper step={3} …/> and nothing else changes.

Typing a number into the field sets it rather than adding, and that is the point — going from 3 to 10 by pressing + seven times is not a control. It is a different intention, so it gets a different write: an absolute value lands on top of whatever anybody else was adding at that instant, because that is what correcting a value means.

Add a mutation ​

js
// src/mutations/index.js
export const mutations = {
  'my:new-period'(ctx) {
    ctx.write([['variables.period', String(Number(ctx.read('variables.period') || 0) + 1)]])
    ctx.add('variables.home.fouls', 0)
  },
}
jsx
const mutate = useVelcroMutate()
<button onClick={() => mutate('my:new-period')}>New period</button>

A mutation is one transaction, so however many paths it touches, the graphics see one change rather than a sequence of them. Your own data covers the rest: what ctx gives you, how to store a list that two operators can both add to without one of them losing an entry, and how to pull data in from a scoring API or a socket rather than a person.

Component reference ​

Two entry points, because a graphic and the operator's board are separate worlds and nothing needs both in one file:

js
import { Scene, Toggle, Variable } from '@single-studio/core/source' // in src/sources/
import { Field, Panel, Toggle } from '@single-studio/core/control' // in src/control/

That separation is what lets each side use the right name — Toggle is a button on the board and the thing being toggled on air. Hooks, mutations and toolkits are on the root @single-studio/core, since those genuinely are shared.

The full generated reference, with every prop, is api.md.

Source — what goes on air:

ComponentReadsNotes
Scene—Root of a graphic. vars maps CSS custom properties to paths.
Variablevariables.<name>Text. fit shrinks it to fit its box, on one line or on up to lines of them.
Imagevariables.<name>A bundled path, a URL, or a library entry. Preloads and decodes before swapping.
Toggletoggles.<name>Shows or hides its children.
Timertimers.<name>Any of the three clocks; reads the stored shape. Clears itself when done. limit marks a count-up that overran.
ImageListvariables.<name>A row of images from a multi-valued path. Same loading rules as Image.
Slideshowthe image libraryA folder of pictures, playing. Picks the one on screen off the time in the room, so every output agrees.
Sequencetoggles.<toggle>, optionalSlides of anything, each on screen for its own duration. Plays when its Scene mounts, or when a toggle goes on.
Tallyvariables.<name>A count said in icons — three demolitions is three marks. of fills a race instead. Only the change animates.
Clock— (local)Wall clock. Never replicates.
Tickervariables.<name>Crawl at a constant px/sec, swaps text between passes.

fit shrinks a name until it fits its box, keeping it on one line. Add lines to let it wrap first: <Variable name="home.name" fit lines={2} /> takes up to two lines and shrinks only as far as that needs, so a long team name stays large across two lines rather than going small on one. A single word wider than the box still shrinks, and the box's height is not consulted, so size the box for the lines you allow. <Fit lines={2}> from @single-studio/core does the same for text of your own.

Variable, Timer and Clock render a <span>, so a value can sit inside a sentence without breaking the line it is on. Pass as for anything else — as="div" if you want it to fill its own row. Every other component is a container and renders a <div>.

Every one of these except Clock, Ticker and Slideshow takes a transition prop — see Transitions. On a Sequence it is the default for its items, fade unless you say, and each SequenceItem can have its own. Slideshow cross-fades between pictures instead, over --ss-fade; anything beyond that is a rule of your own on .ss-slide[data-on].

Control — the operator's board:

ComponentWritesNotes
Fieldvariables.<name>One line of text. Staged until saved.
TextAreavariables.<name>Several lines. Enter makes a line break; the save shortcut saves.
ImagePickervariables.<name>Preview, dropdown of library entries and a magnifier, on one line.
ImageSelectvariables.<name>Pick by picture. multiple + max for a composition.
ImageToggletoggles.<name>Toggle with a picture. from reads the face off a path.
AssetLibrary—Manage images: add by URL or file, rename, delete.
Selectvariables.<name>options of strings or { label, value }. Staged until saved.
ColorPickervariables.<name>Swatch, hex field and optional presets. Staged until saved.
Steppervariables.<name>Numeric −/+, sized by step. Type in it to set a value outright.
Cyclevariables.<name>Steps through options, wrapping to unset.
Toggletoggles.<name>group names a radio group; buttons sharing one are exclusive.
SwapButtonany pathsTrades values pairwise, outermost first. Asks first; confirm={false} opts out.
ResetButtonany pathsUnsets them. Reads "Reset label". Asks first; confirm={false} opts out.
Confirm—A destructive button that arms on the first click and acts on the second.
Countdowntimers.<name>Counts down a duration. Typed unless duration presets it.
CountdownTotimers.<name>Counts down to a wall-clock time, not a duration.
Stopwatchtimers.<name>Counts up. Start, pause, reset.
Leaderboardvariables.<name>One delimited string; paste view and table view. Staged.
SaveButton—Commits every staged edit. Hosts the save and discard shortcuts.
Panel—Titled group, one row per child. actions on the title line; collapsible.
BoardBar—A bar of your own under the board's top bar. Empty, it is not there.
PanelJump—Lists the board's panels; choosing one folds the rest and scrolls it into view.
Row—Side by side when there is room, stacked in a dock. Widths in twelfths.
Break—Deprecated: draws nothing. Use Row.

A Panel's actions go at the right of its title, and work while it is folded: anything at all, or a function given { open } that returns it. collapsible makes the title fold the panel away. A collapsible panel starts folded on every load, so a fresh board is a short list of headers; defaultOpen starts one open. The fold is that page's alone, never the show's, so folding a panel on your board folds nobody else's. A button in the header takes size="sm" — Confirm, ResetButton, SwapButton and Toggle all have it — and useCollapsed and Chevron fold anything else, such as a card inside a panel, the same way.

Every other panel is a shade lighter, so a long board reads as blocks. The stripes count sibling panels, so render panels directly or in a fragment rather than each inside a <div> of its own.

jsx
<Panel title="Slate" collapsible actions={<ResetButton label="slate" names={['slate.title']} size="sm" />}>
  <Field name="slate.title" label="Title" />
</Panel>

A bar of your own ​

BoardBar puts whatever you give it in a second bar under the board's top bar, which stays put as the board scrolls. Write it anywhere in your control view, beside the panels its controls belong to; a board without one has no second bar at all. It is yours to shape: it grows with what you put in it, onto as many rows as that takes, and className and style go on its box. Several BoardBars share the one bar, in the order they mount. It is a dark blue, apart from the top bar and the panels; set --ss-board-bar-bg on .ss-control for another.

PanelJump is the one the framework provides. It lists every titled panel, in board order; choosing one folds every other collapsible panel, opens that one — and the panel it is inside, if any — and scrolls it to just under the bar. "Minimize all" at the head of the list folds everything and goes back to the top.

jsx
<BoardBar>
  <PanelJump />
</BoardBar>

Working with other people ​

A studio is one operator by default and needs nothing. To bring in others, press Collaborate on the board: it wants a free Supabase project's URL and public key, and gives you a link to send each operator, which they paste into an OBS dock.

That is the whole setup, and working with other people walks through it — including why Supabase, what it costs, and what it gives up.

Clocks ​

Three of them, because a broadcast asks three different questions:

ControlQuestion
Countdown"five more minutes"
CountdownTo"we go live at 19:00"
Stopwatch"how long have we been on?"
jsx
<Countdown name="round" label="Round" />                 {/* operator types it */}
<Countdown name="break" label="break" duration="5:00" /> {/* a fixed preset */}
<CountdownTo name="showtime" label="Doors open" />
<Stopwatch name="match" label="Show elapsed" />

Countdown grows an input unless you hand it a duration, because a fixed five minutes is a guess about somebody else's show. The input takes whatever an operator would naturally type — 90, 1:30, 1:02:03 — rather than insisting on a format. Give it a duration when the length never varies and one press should start it.

All three are read by the same component, whichever kind you used:

jsx
<Timer name="round" fallback="--:--" />

Every machine shows the same number. A second operator's clock agrees with the one running OBS, down to the second, without either of them having to be in sync with the other. A graphic that OBS destroys and rebuilds comes back showing the right time rather than starting over, and pausing then resuming picks up exactly where it stopped.

A countdown shows 00:00 for a second, then takes itself off air. The number the whole thing exists to reach gets its full second on screen, and then the graphic leaves on its own — nobody has to remember to dismiss it mid-show. It goes at the same moment on every machine.

Images ​

Four ways in, all handled by the same component.

Templated from a value — "Single Studio" resolves logos/single-studio.svg:

jsx
<Image name="home.name" src="/logos/:value:.svg" slug fallback="/logos/placeholder.svg" />

Images you ship with the studio live in public/ — public/logos/acme.svg is /logos/acme.svg on air. Drop them in, commit them, and they deploy with everything else.

The value is the URL — paste a link into a Field and it is on air:

jsx
<Image name="sponsor.url" fallback="/logos/placeholder.svg" />

An operator's upload, stored locally and referenced by content hash:

jsx
<Image name="guest.photo" />

paired with a picker on the board:

jsx
<ImagePicker name="guest.photo" label="Headshot" />

Image does not care which of the four it is given — a bundled path, a URL and a library entry are all treated the same.

What separates this from an <img> tag is what happens between images. A new URL is loaded and decoded off-screen first, and only swapped in once it can paint. The previous image stays up meanwhile. Setting src directly leaves a hole on air for however long the network takes — fine in a web page, not over a live scene.

The rest is failure handling that a broadcast needs and a web page does not:

BehaviourWhy
Falls back to fallback when a load failsA missing image should read as "no image", not as a broken-image glyph
Keeps the previous image while a new one loadsNever blank a working graphic to wait for the network
referrerpolicy="no-referrer"Many hosts block hotlinking by Referer
Warns loudly on http:// from an https:// pageMixed content is blocked silently and is the most common way this fails

Use https:// URLs. A studio deployed to GitHub Pages is served over https, so an http:// image is blocked as mixed content. The console says so explicitly.

The image library ​

Framing and logos belong in the repo — they do not change between shows. A guest headshot that lands five minutes before air does not: there is no time to patch a repo, and it usually arrives as a file.

The library is where those live. Two ways in, and both produce a named entry:

  • Paste a URL — the bytes stay wherever they are.
  • Drop or choose files, or a whole folder — the bytes are stored locally, content-addressed.

A graphic points at the entry by name — "ada-okafor" — rather than at a link or a file path. That is the name an operator recognises under pressure, and it means repointing a slot is a rename in the library rather than an edit everywhere it is used.

jsx
<AssetLibrary />                                 {/* the manager, as a panel */}
<ImagePicker name="guest.photo" label="Headshot" />  {/* choose one */}
<Image name="guest.photo" />                     {/* on air */}

Groups ​

A key can be a path, and the slash is the whole organisation scheme:

players/ada-okafor
players/kim-nakamura
logos/acme

The part before the last slash becomes a group — a heading in the library, and a heading in every picker's dropdown. A hundred images in one flat list is a scroll an operator has to read; the same hundred under a handful of prefixes is a menu they can aim at.

In the image store, loose images come first and every group starts folded, showing only its name and how many images it holds; press a group to open it. A filter opens every group it finds something in, a folder you have just uploaded opens so you can see what arrived, and the store opened from a picker opens on the group its current image is in.

Groups are deliberately not a second concept with their own storage and their own editing screen. The key already existed, renaming it already worked, and a graphic still points at one string — so re-filing an image is renaming it, and nothing downstream knows the difference.

Three ways to file something:

You do thisYou get
Type players/ada as the nameThat exact key
Type players and add several filesplayers/<each filename>
Drop or choose a folder<folder>/<each filename>, nesting preserved

The name field means "name" for one file and "group" for several, which is the same field meaning the same thing at two scales.

Sharing a library ​

When collaboration is on, the library's index replicates and its bytes do not. Every machine sees every entry by name; one that does not hold the file marks it elsewhere and greys it.

The rule that makes that safe rather than a trap: files are added on the machine running OBS, and URLs by anybody. A file's bytes exist only where they were dropped, and the machine that has to draw a graphic is the machine going to air — so the one place a file can usefully be added is the one place it can be drawn. A URL is a reference rather than bytes, so it works from anywhere and replicates for free.

That means an entry marked elsewhere on a remote operator's board is not a warning. It lives on the studio machine, it will go to air, and the only thing missing is their own preview. The board says so in those words.

Adding from code ​

A plugin handler or a mutation has the show but not a page's library. A URL entry needs nothing but its index entry to draw everywhere, so urlAssets writes exactly that:

js
import { urlAssets } from '@single-studio/core/worker'

this.mutate('set', urlAssets([{ key: 'logos/acme', url: 'https://example.com/acme.png', name: 'Acme' }]))

It appears in every picker and draws on every graphic, on every machine, the same as one pasted on the board. Files cannot be added this way: their bytes have to be stored on the machine that draws them.

How many images can it hold? ​

There is no limit in the framework. The practical ones:

  • Browser storage. The browser gives a studio a large share of free disk, so hundreds of megabytes of photos is not a problem. A show's worth of headshots is nowhere near it.
  • Duplicates are free. The same photo filed under two names is stored once. Re-adding a folder you already have costs nothing but entries.
  • Adds are sequential, one file read at a time, so a folder of a hundred does not spike memory the way reading all hundred at once would. There is a progress readout above four files, and one unreadable file is reported rather than losing the rest of the batch.

ImagePicker gives a preview, a dropdown of the library's keys for a fast swap between segments, and a magnifier joined onto the dropdown that opens the library as a modal for adding, renaming and deleting. The same AssetLibrary component serves both.

Playing a folder ​

Slideshow points at a group rather than a list, so loading the show is dropping a folder on the board:

jsx
<Slideshow group="slides" every={9} order="shuffle" />

Two things worth knowing before you put one on air:

An empty group renders nothing at all — no element, not an empty one, and no timer running behind it. That means there is nothing to style for the empty case: if you want a holding card while the folder fills up, put it in the studio as a sibling, where it can say what this show is waiting for.

It follows the library while it plays. Pictures added to the group during a programme join the deck without a reload, and removing one takes it out. Loading the show and running it are the same act, which is the point of pointing at a group instead of writing a list.

It only plays what the machine it is running on can actually paint. A file lives in the browser that added it, so a picture dropped on a producer's laptop shows up in everyone's library but only plays where its bytes are — see the box above. Images added by URL have no bytes to be missing and play everywhere.

Slides of anything ​

Sequence is a slideshow whose slides are whatever you put in them — a sponsor line, a logo beside a clock, a countdown — each on screen for its own duration:

jsx
<Sequence transition="slide-up">
  <SequenceItem duration={12}>
    <Variable name="sponsor.line" />
  </SequenceItem>
  <SequenceItem duration={8}>
    <div className="flex gap-2">
      <Image name="logo" alt="" />
      <Clock />
    </div>
  </SequenceItem>
  <SequenceItem duration={15} transition="wipe">
    <Timer name="break" />
  </SequenceItem>
</Sequence>

A duration is the time an item is the current one, its entrance included. Its exit is not counted: it plays while the next item is already coming in, so the default is a cross-fade. For one to leave before the next arrives, delay the entrance — .ss-sequence-item.ss-active { transition-delay: 300ms }.

Without a toggle it plays from the first item when its Scene mounts, and goes round and round. Tick Refresh browser when scene becomes active on the browser source in OBS and it starts from the top every time the scene is taken. With toggle="intro" it follows toggles.intro: playing from the first item when the toggle goes on, and leaving when it goes off. loop={false} holds the last item instead of going round.

Each output keeps its own time, from its own mount or from when it saw the toggle change. A browser source reloaded mid-sequence starts again from the top, and two outputs mounted at different moments are on different items. If every output must show the same picture at the same moment, that is what Slideshow is for.

Durations are in seconds. The sequence's own duration is the default for its items, 8 unless you say, and transition likewise, fade unless you say; an item with neither of its own takes both. Items must be direct children, because the sequence reads duration off them, and a child that is not a SequenceItem is one with the defaults. A duration of 0 takes an item out of the rotation.

Picking by picture ​

When the choice is a picture — a faction crest, a commander portrait, a map — reading nine words is slower than recognising nine images, and a draft does not wait. ImageSelect is Select laid out as a grid of tiles, and ImageToggle is Toggle with a picture on it.

jsx
<ImageSelect name="home.faction" label="Faction" options={FACTIONS} />
<ImageSelect name="home.army" label="Army" options={UNITS} multiple max={5} />
<ImageToggle name="sponsor" label="Sponsor" image="./logos/acme.svg" />
<ImageToggle name="sponsor" label="Sponsor" from="variables.sponsor.url" image="./logos/placeholder.svg" />

ImageToggle's from points its face at a path rather than a fixed file, which is what a switch for something the operator also chooses wants: the sponsor toggle should wear the sponsor they picked. image stays as the fallback for before anything is chosen.

Each ImageSelect option is { value, label, image }. The stored value is the plain one — a source reading variables.home.faction cannot tell which control wrote it — so the usual templating still applies:

jsx
<Image name="home.faction" src="./factions/:value:.svg" />
<ImageList name="home.army" src="./units/:value:.svg" limit={5} />

multiple stores an array in the order the picks were made, which is what an army composition or a ban list is, and max stops the grid rather than silently dropping the overflow. ImageList puts that array on air, giving each entry the full Image treatment.

These are buttons, so they act immediately. Pass staged to an ImageSelect that should wait for a save with the text fields — a draft assembled off-air and revealed on the cut.

Two properties worth knowing:

  • Adding and going to air are separate. Bytes land in the library immediately, because a file arriving is not a broadcast change. The selection is staged like any other field, so nothing appears until save — an operator can line up the next guest mid-segment and commit on the cut.
  • Bytes deduplicate, keys do not. The same photo filed under two names stores its bytes once, and deleting one key leaves the other working.

Images are stored on the machine, separately from the show itself — the show carries the name of the picture, not the picture.

Bytes stay on the machine that holds them. A file added on the OBS machine does not travel to a remote operator's board, and deliberately so: moving it would buy a preview, not correctness, because the machine that has to draw it is the one that already has it. That is why files are the OBS machine's to add — see the rule that removes most of the problem. URL entries replicate fine, since they are just strings.

Driving anything else from a value ​

Scene maps CSS custom properties to paths, which covers everything the framework does not have a component for — colours, offsets, widths, radii:

jsx
<Scene vars={{ '--accent': 'variables.sponsor.color' }}>
  <div style={{ borderLeft: '6px solid var(--accent, #0ea5e9)' }} />
</Scene>

A path holding nothing is left unset rather than blanked, so the var() fallback still applies.

On the board, ColorPicker is what fills that path. A swatch to pick from, a hex field to paste a brand colour into, and an optional row of presets — because most shows have four colours, and nobody should have to know that amber is #f59e0b:

jsx
<ColorPicker name="sponsor.color" label="Accent" fallback="#f59e0b" presets={['#f59e0b', '#0ea5e9', '#e11d48']} />

Both halves write the same path and stay in step, and it stages like any other field — typing #f5 mid-hex would otherwise put a half-parsed colour on air.

Transitions ​

Broadcast graphics do not snap between values; they animate out, swap, and animate back in. Every source component does that already — the interesting part is how.

jsx
<Toggle name="lowerthird" transition="slide-right ease-back opaque" />
<Variable name="home.name" transition="flip ease-sharp" />
<Image name="home.faction" transition="wipe" />
<Toggle name="showtime" transition="bounce" />

The prop is a space-separated list of variant names, and what each one looks like is CSS — so a new motion costs a rule rather than a code path.

cut is the one that does nothing:

jsx
<Variable name="clock" transition="cut" />

A clock that fades every second is a clock drawing attention to itself once a second. Leaving the prop off is not the same thing — the default is fade.

Every transitioning element is in exactly one of four phases:

PhaseMeaning
inactiveOff. Not showing, not moving
enteringOn its way in
activeOn air, at rest
exitingOn its way out

The phase is on the element as data-state and as an ss- class, so you can style or inspect any of them.

MotionWhat it does
fadeThe default. Opacity only.
cutNo animation at all. Swaps, the way a mixer cuts
slide-upArrives travelling upward (starts below its place)
slide-downArrives travelling downward
slide-leftArrives travelling leftward (starts to the right)
slide-rightArrives travelling rightward
zoomScales up into place
flipRotates in about its top edge
wipeReveals left to right, clipped rather than faded
bounceDrops in and settles twice; dips and lifts out (keyframes)
numberCounts from the old number to the new one. Variable only
ModifierWhat it does
opaqueMove without also fading — a pure slide
ease-outFast then settling. The safe default for a reveal
ease-backOvershoots and comes back. Reads as a bounce
ease-inSlow then fast. For exits
ease-sharpHard in, hard out. Mechanical, good for a wipe
ease-linearNo easing

Two custom properties tune the rest:

jsx
<Toggle name="sponsor" transition="slide-up ease-out opaque" style={{ '--ss-shift': '14rem', '--ss-duration': '480ms' }} />
  • --ss-shift — how far a slide travels (default 1.5rem)
  • --ss-duration — how long a phase takes (default 300ms); --ss-drop for bounce

Use a length for --ss-shift, not a percentage. A percentage transform resolves against the element's own size, and a hidden Toggle has no content in it — so 150% of a collapsed box is zero and the graphic sits parked exactly where it will land. It still animates correctly on the way in and out, when content is present, which is what makes the mistake so easy to miss.

Two more things worth knowing before you build a scene around this:

  • Pin blocks that reveal independently. If two graphics share a flex row, one sliding in shoves the other sideways to make room. On air that reads as a bug rather than as a transition. The demo's Match scene positions each bottom block absolutely for exactly this reason.
  • Do not centre a transitioning element with a transform. -translate-x-1/2 and a variant that animates transform will fight, and the variant wins. Centre with a wrapper.
  • A keyframe variant needs keyframes in both directions. An entrance animation ends with both, so the animation itself is holding the final transform; take it away on the way out and the element drops straight to the off-phase value with nothing to interpolate from. It teleports and then fades in place. bounce has an ss-bounce-out for this reason, and a custom keyframe variant needs one too.

Writing your own ​

A variant is a class name and nothing else. transition="stinger" puts ss-stinger on the element; the state machine adds ss-inactive, ss-exiting, ss-entering or ss-active beside it, and never touches a transform itself. So a new motion is a rule in your own stylesheet:

css
@layer components {
  /* Off, and on the way out or in: where the element sits when not showing. */
  .ss-stinger.ss-inactive,
  .ss-stinger.ss-exiting,
  .ss-stinger.ss-entering {
    opacity: 0;
    transform: translateX(-100%) skewX(-12deg);
  }

  /* On air: no transform, which is what everything animates towards. */
  .ss-stinger.ss-active {
    opacity: 1;
    transform: none;
  }
}
jsx
<Toggle name="stinger" transition="stinger ease-sharp">
  <StingerCard />
</Toggle>

Three things make that work, and each is a mistake worth making once:

  • Wrap it in @layer components, matching the framework's own rules — see Styling for why the layer matters.
  • The same declarations for inactive, exiting and entering. Those three are one visual state — "not showing" — reached from three different directions. Giving entering its own values makes the element jump at the moment it starts arriving.
  • Only active is the resting state. Set the transform to none there rather than restating it, so the variant composes with --ss-shift and with whatever a studio's own rule does.

A variant is ordinary CSS, so Tailwind can supply the values — see Styling.

Easing and duration come from the modifiers and custom properties above, so a variant only has to describe where the element is — not how long it takes to get there. That split is why stinger ease-back works without you writing an easing.

Pick per element rather than per scene. In the demo's scoreboard a name flips over, a score slides up and overshoots, and the badge plainly fades — because a logo swapping with a flourish reads as a mistake.

Counting ​

number is for totals that change by a lot at once — money raised, points, a viewer count. Instead of swapping, the value counts to the new one:

jsx
<Variable name="donations.total" fallback="0" transition="number" />
<Variable name="raised" transition="number ease-back" style={{ '--ss-count-duration': '2s' }} />
  • Only changes count. The first value after a source loads is shown as it is, so a scene switch or a reload does not count up from zero on air.
  • It counts in the value's own shape. $1,000 raised counts to $1,500 raised through $1,237 raised: the same words either side, the same decimals, commas if the value has them. A change that alters the words (1st to 2nd), or a value that is not a number, is shown straight away instead.
  • A change mid-count carries on from what is on screen, rather than jumping back.
  • Easings apply. The default slows as it lands; ease-back overshoots and settles back onto the number; ease-linear counts evenly.
  • It replaces the motion variants. There is no swap for a slide or a flip to animate, so number slide-up counts and ignores the slide.
  • --ss-count-duration sets how long a count takes (default 1.2s). The figures are tabular, so the number does not shimmer sideways as its digits change.

A step of one looks like any other change — a score going from 3 to 4 has nothing in between to show.

Sizing for the dock ​

An OBS dock is either a narrow column pinned down one side or most of a monitor, and the same board has to work at both. It does it by going row by row:

  • A Panel is one row per child, top to bottom, at every width.
  • A Row puts controls side by side from 768px up, and stacks them below that. Left alone, the controls share the line equally.

A Row is sized the way Bootstrap sizes one, with Tailwind's breakpoints:

ClassOnDoes
row-cols-*RowHow many controls to a line. sm:row-cols-2 lg:row-cols-4 is two, then four
col-span-*controlIts width out of twelve. md:col-span-8 is two thirds
col-autocontrolIts own width; the controls beside it share what is left
col-span-fullcontrolThe whole line
jsx
<Panel title="Teams">
  {/* One to a line in a dock, two from 640px, four from 1024px, where the
      score keeps its own width and the other three share the rest. */}
  <Row className="sm:row-cols-2 lg:row-cols-4">
    <Field name="home.name" label="Home" />
    <ImagePicker name="home.logo" label="Logo" />
    <Stepper name="home.score" label="Score" className="lg:col-auto" />
    <ColorPicker name="home.color" label="Colour" />
  </Row>
  <Leaderboard name="standings" /> {/* on its own row */}
</Panel>

With a breakpoint a class holds from there up; without one, at every width, so row-cols-2 keeps buttons in pairs even in a slim dock. A line that does not fill has no hole at the end: the last control on it takes the room.

Every control fills the cell it is given, a Stepper and a Stopwatch included: the number field and the readout grow between their buttons. To keep one at its own width and give the rest of the line to its neighbours, that is what col-auto is for — a stepper is 160px.

Side by side, controls line up along their inputs. Every control is a label, then one input line of the same height, then anything extra — colour presets, a warning — below, where it cannot push its neighbours out of line. A switch or button beside a labelled control drops by a label's height to sit level with the inputs. Give a button of your own the ss-unlabelled class for the same treatment. The input line is --ss-input-h tall (default 2.5rem):

css
.ss-control {
  --ss-input-h: 2.25rem;
} /* a tighter board */

The board's own spacing is set the same way. Each steps up at 640px by default, as it always has; set one on .ss-control and it holds at every width.

PropertySpacesBelow 640pxFrom 640px
--ss-panel-padinside every Panel0.75rem1rem
--ss-board-padaround the board (.ss-board)0.75rem1rem
--ss-board-gapbetween the panels0.75rem1rem
--ss-bar-pad-xthe top bar, either side0.75rem1rem
--ss-bar-pad-ythe top bar, above and below0.625rem0.75rem
--ss-picker-maxthe widest a col-auto ImagePicker9.25rem9.25rem
css
.ss-control {
  --ss-panel-pad: 1rem;
  --ss-board-pad: 1rem;
  --ss-board-gap: 1rem;
} /* one size at every width, in a dock you resize mid-show */

--ss-picker-max exists because an ImagePicker is as wide as the longest name in the library, which the operator chooses: given col-auto, a picker with a long logo name took the line from the field beside it. It stops there now.

Reading an --ss-* property, give it a fallback — var(--ss-basis, 0%), not var(--ss-basis). A property that is misspelt, or renamed in a later release, makes the whole declaration invalid, and the browser treats that as if the rule were not there at all: no error, just nothing. A fallback turns that into a default.

Two rules keep a wide control from breaking a narrow dock, and are worth knowing if you write your own layout: min-width: 0 is what lets a flex or grid item shrink below its content at all, and max-width: 100% is what stops a wide control from forcing a horizontal scrollbar across the whole board. A control with a hard min-w-* will escape a narrow dock — that is the one thing to avoid.

The smoke test asserts a 260px dock has no horizontal scroll and that no control escapes it, and measures that a row's inputs line up.

Saving ​

Free-text controls stage their edits and commit on save. Typing does not reach air: an operator revises mid-word, and every intermediate state of that would otherwise be on screen.

ActionEffect
Ctrl/Cmd + SCommit every staged edit
Enter (in a field)Commit every staged edit
Escape (in a field)Abandon that field's edit
Discard (red ✕)Abandon all staged edits

Ctrl/Cmd+S is only the default. If it collides with something else you use, or your keyboard makes it awkward, change it: menu → Keyboard shortcuts, press the key you want, done. You can also put discard on a key, which ships unbound.

Shortcuts are yours rather than the show's, so rebinding one does not move anybody else's. They are stored with the studio, which means they come along if you move it to another machine. A choice with no modifier, like F2, works fine; a plain letter also works, but only while no text field has focus, since otherwise you would be typing it. The dialog says so when you pick one, and warns you if the browser would take the combination before the board ever sees it.

Buttons — Stepper's −/+, Toggle, ImageToggle, ImageSelect, Countdown, CountdownTo, Stopwatch, Cycle — act immediately. Each is a single deliberate press with no half-finished state to protect, and all of them are undone by pressing again.

ResetButton and SwapButton ask first, because those two are not. A reset unsets values with no undo, and a swap puts both team names and both scores on the wrong side of a live scoreboard. One press arms the button and it says so, a second does it, and a few seconds of silence disarms it — so a board left alone never sits with a live "wipe the show" under the cursor. Pass confirm={false} to either one for the single press, where the worst outcome is small and speed matters more.

Stepper's field is the exception among them, and stages like the text ones do: typing "10" passes through "1", and a board that wrote every keystroke would put a 1 on air on the way to a 10. Enter or clicking away commits it; Escape abandons it.

A save is one mutation, so every staged path lands in a single transaction and the whole board changes on air together.

Save and Discard are icons — an amber floppy disk and a red ✕ — sized to match, and Discard only appears when there is something to discard. There is no count of pending changes: the dirty dot on each edited control says which, which is the half worth knowing.

ControlPage renders a SaveButton in its header automatically. To put one somewhere else, or to read the pending count yourself:

jsx
import { SaveButton, useDraft, useDraftCount } from '@single-studio/core'

const pending = useDraftCount()
const { save, revert } = useDraft()

Browser requirements ​

A studio needs a reasonably current browser:

BrowserMinimum
Chrome / Edge83
Firefox114
Safari16
OBS28

Every one of those shipped by mid-2023, so in practice anything current works. The OBS dock is Chromium, and remote operators on the collaboration path can use whatever they already have.

If a browser is too old, the board says so plainly instead of loading a page where nothing updates — it names what is missing and the version needed. You can replace that screen with onUnsupported, or ask first:

jsx
import { getSupport } from '@single-studio/core'

const { ok, missing, persistent } = getSupport()

persistent: false means the browser will not keep anything after a reload — private windows and some locked-down profiles. It is not a failure: the show runs normally for the session, it just starts fresh next time.

Phones and tablets are not supported yet. A studio needs a browser feature that mobile Safari and Chrome for Android do not provide, so the board will refuse to load rather than half-work. See the note below.

A hand-held control surface ​

Running the operator's board from a phone is a reasonable thing to want, and it is on the list. It is not a small change: the store is shared between the board and every graphic by a mechanism phones do not implement, so supporting them means a second way of sharing it. Until then, a remote operator needs a laptop.

Styling ​

Tailwind v4. A studio's CSS entry needs three lines:

css
@import 'tailwindcss';
@import '@single-studio/core/styles.css';
@source '../../node_modules/@single-studio/core/dist';

If your editor underlines @source as an unknown rule, it is wrong — Tailwind v4 adds at-rules the built-in CSS checker has not been taught. The template ships a .vscode/settings.json that silences it, and recommends the Tailwind IntelliSense extension, which understands them properly.

Fonts ​

The board ships its own font, Inter, so it looks and measures the same on every machine: the Windows PC running OBS, a Mac, a tablet. Without it the board borrowed each machine's own — Segoe UI on Windows, San Francisco on a Mac — and the same dock wrapped and cut off text at different widths on each. It comes with the framework and is served by your own build, so a dock with no internet still has it; a browser fetches only the alphabets on the page, 48 kB for Latin. To use another, set it on the board:

css
.ss-control {
  --ss-font: 'Atkinson Hyperlegible', sans-serif;
}

The board's scrollbars are thin and dark. Their colours are properties on the page's root, since the page's own scrollbar belongs to it:

css
:root {
  --ss-scrollbar-thumb: #475569;
  --ss-scrollbar-track: transparent;
}

Graphics keep whatever font you give them, and with none, the machine's own — the framework does not choose a font for anything that goes to air. A graphic designed on a Mac and shown on the Windows PC will draw in a different font unless it names one, so load the one you design with and set it on the graphic. A font from npm is the simplest, since your build then serves it like the board's:

css
/* src/css/index.css, after the framework's import */
@import '@fontsource-variable/oswald';

.scoreboard {
  font-family: 'Oswald Variable', sans-serif;
}

Splitting it up ​

Two ways, and they are not equivalent — one of them keeps a graphic's CSS out of every other graphic.

Import it from the graphic, and it becomes that graphic's own stylesheet:

jsx
// src/sources/Podium.jsx
import './podium.css'

Vite gives each graphic its own chunk, and CSS imported this way rides along with it: a browser source pointed at the scoreboard never downloads the podium's rules. Measured on the demo, a one-rule file came out as its own 0.05 kB asset.

It needs no boilerplate. Do not import Tailwind or the framework's styles at the top — plain rules are all it takes, and the utility classes in your JSX already come from index.css, which every page loads.

The exception is @apply and theme(), which need to know your theme. Point them at it with @reference, which reads it without emitting anything:

css
/* src/sources/podium.css */
@reference '../css/index.css';

.podium-plate {
  @apply rounded-lg bg-sky-600;
}

Forgetting it fails the build rather than silently dropping the rule, and the error names @reference — so this is a thing you meet once.

@import 'tailwindcss' is the wrong fix, and it is the one that looks right. It works, and it copies the whole utility layer into that graphic's stylesheet: the same file went from 0.22 kB to 17.84 kB. @reference gives the same result at the smaller size.

Import it from index.css, and it is part of the one stylesheet every page loads:

css
@import 'tailwindcss';
@import '@single-studio/core/styles.css';
@import './game.css';
@source '../../node_modules/@single-studio/core/dist';

Right for anything shared — brand colours, a plate every graphic uses, @theme tokens. CSS requires @import to come before any other rule, so these stay at the top, above @source.

The rule of thumb: if only one graphic uses it, import it from that graphic. Otherwise index.css.

That @source line is required. Tailwind scans your files for utility classes, and the framework's components live in node_modules — without it their classes get stripped from your build.

@single-studio/core/styles.css carries only behaviour-critical rules: transparent backgrounds for sources, the Transition state classes, their timing and motion variants, and the ticker keyframes.

CSS owns the timing. Transition reads the duration back off computed style, so there is no duration prop to keep in sync — retune it any of three ways:

jsx
<Variable name="home.name" className="duration-500" />   {/* Tailwind utility */}
css
.scoreboard .ss-transition {
  transition-duration: 700ms;
} /* your own rule */
.scoreboard {
  --ss-duration: 900ms;
} /* custom property */

Tailwind, and the @layer rule ​

The template ships with Tailwind, and every framework component takes a className, so utilities work on anything:

jsx
<Variable name="home.name" className="text-6xl font-bold tracking-tight" />

Write your own rules inside @layer components, the same layer the framework uses:

css
@layer components {
  .ss-stinger.ss-inactive {
    @apply opacity-0 -translate-x-full;
  }
}

That is load-bearing rather than tidy. Unlayered CSS beats layered CSS whatever the specificity, so a rule written outside a layer outranks every Tailwind utility on the same element — and duration-500 would quietly do nothing. Both the framework's rules and yours sit in the layer, so ordinary specificity decides, and the last one written wins.

Tailwind is not required. It is what the template happens to use, and nothing in the framework depends on it.

Reduced motion applies to your control surface, not to graphics. On a browser source, animation is broadcast content, and the preference being read belongs to the operator's machine — nobody watching the stream has a say in it. Honouring it there would let one person's OS setting strip the animation from everyone's screen.

Deploy ​

The template ships a Pages workflow, so there is nothing to run. Switch Settings → Pages → Source to GitHub Actions, push to main, and the board lands at https://<you>.github.io/<your-repo>/#/ — the URL you paste into an OBS custom browser dock, and the one every invite link is built from.

That switch is the one manual step, and the workflow cannot make it for you: enabling Pages from inside an action needs a personal access token with repo scope, which is a worse thing to keep around than one click. If you would rather not click, gh is already signed in as you and the call is idempotent — a repository that already has Pages on answers 409:

bash
gh api -X POST repos/<you>/<your-repo>/pages -f build_type=workflow

To build it yourself:

bash
npm run build      # dist/

Asset paths are relative (base: './'), so a build works at a Pages repo subpath, on a custom domain, or opened off disk — which matters because OBS loads these URLs directly.

Troubleshooting ​

My graphics show fallback text and never update ​

The board and the graphics have to be in the same place. Check both:

  • The control surface is an OBS custom browser dock, not a separate browser window.
  • STUDIO_ID in src/studio/config.js matches the one the worker is given. A mismatch logs a warning in the browser console.

A source is blank in OBS but works in a browser ​

The browser source URL is missing its #/source/... part. Copy it again from the board's Browser sources menu — the copy button includes everything needed.

I renamed my studio and the show emptied ​

STUDIO_ID is the name your show is filed under, so renaming it starts a fresh one. Nothing is lost: put the old STUDIO_ID back and the show returns.

If you only meant to retitle it, change STUDIO_NAME instead — that one is a label and nothing reads it back.

Do graphics survive being hidden in OBS? ​

Yes, and it is tested. A graphic is destroyed and rebuilt every time its scene comes back, and nothing paints until the real values have arrived — no flash of fallback text over the programme.

Keep the dock open, though. It is what holds the show while the graphics are unloaded. If the dock is closed and every graphic is hidden at once, the next one to appear reloads the show from disk — slower, but nothing is lost.

A CSS change has no effect, or the board comes up unstyled, in npm run dev ​

Run npm run build and look at the CSS it writes to dist. If that is right, your code is right and the dev server is not: restart it — a reload does not help.

Two ways it goes wrong, both seen in a real studio. A hot update can apply one of two quick edits to the same file, so a rule arrives but the custom property it reads does not, and the rule silently does nothing. And when the dev server restarts itself — a branch checkout touching vite.config.js is enough — it can come back serving Tailwind's colours but none of its utility classes, so the board is serif text and bare buttons. To tell which you have, read the page's own <style> in the browser's dev tools rather than your file.

The board will not load on my phone ​

Not supported yet — see browser requirements.

MIT licensed