ui()

ui() applies performer-facing UI changes during playback — most commonly to hide or reveal interface elements such as the playhead, play zone, overlays, or control panels.

It can target:

The UI cue system was primarily designed to manage visibility of the playhead and play zone, allowing scores to shift between guided, open, or reduced-UI performance states.

Syntax

Selector mode (HTML elements)

ui("<css selector>", opacity:<number>, scale:<number>, x:<px>, y:<px>, rotate:<deg>, visible:<bool>, color:<css>, bg:<css>, z:<number>, dur:<seconds>)

UID mode (SVG animations + overlays)

ui(uid:<animation-uid>, visible:<bool>, action:toggle, dur:<seconds>, click:1)

What it affects

Selector mode

UID mode

UID Mode — Targeting SVG Animations

The uid parameter targets SVG animation elements by their unique identifier. This is especially useful for:

Syntax

ui(uid:<animation-uid>, visible:true|false, dur:<seconds>)
ui(uid:<animation-uid>, action:toggle, dur:<seconds>)

What gets hidden/shown

When targeting by uid, the following are affected:

  1. SVG element — The animated element itself
  2. HTML overlays — Hit labels, OSC controls, waveforms associated with that uid
  3. O2P overlays — Object-to-path animation overlays

Example: Hide a polygon

ui(uid:rot_triangle, visible:false, dur:0.3)

Example: Toggle visibility

ui(uid:rot_triangle, action:toggle)

Creating Clickable Toggle Buttons

Combine ui() with click:1 to create native SVG toggle buttons:

<g id="ui(uid:rot_triangle, action:toggle, click:1)">
  <rect x="0" y="0" width="50" height="30" rx="4" fill="#d4af37"/>
  <text x="25" y="20" text-anchor="middle" fill="#000">TRI</text>
</g>

When clicked, this toggles visibility of the element with uid:rot_triangle and all its associated overlays.

See button() documentation for more on click:1.

Initial Visibility State

When using click:1 with a ui() cue, you can set the initial visibility state of the target element using the visible parameter:

<!-- Target starts HIDDEN - click to show -->
<g id="ui(uid:rot_triangle, action:toggle, visible:false, click:1)">
  <path d="M 20,-18 L 38,18 L 2,18 Z" style="fill:#d4af37"/>
  <text x="20" y="38">TRI</text>
</g>

<!-- Target starts VISIBLE (default) - click to hide -->
<g id="ui(uid:rot_pentagon, action:toggle, click:1)">
  <path d="M 15,-10 L 25,-3 L 21,9 L 9,9 L 5,-3 Z" style="fill:#9370db"/>
  <text x="15" y="22">PENT</text>
</g>

This is useful for scores where certain animated elements should be revealed during performance rather than shown from the start.

Toggle State Indicator

When using click:1 or drag-click:1 with action:toggle, the clickable overlay displays a visual indicator showing the current state of the target element:

This helps performers quickly identify which elements are toggled on or off without needing to search the score.

The indicator updates automatically when:

State Persistence

Visibility state is automatically saved to JSON and restored when the score reloads. The indicator reflects the correct state on load by checking (in priority order):

  1. Saved JSON state — Previously persisted visibility
  2. visible: parameter — Initial state defined in the cue
  3. Default — Visible (true)

Multiple Buttons for Same Target

If multiple toggle buttons target the same uid, all their indicators stay synchronized. Clicking any one of them updates all indicators for that target:

<!-- Both buttons toggle the same element and stay in sync -->
<g id="ui(uid:rot_triangle, action:toggle, click:1)">
  <rect x="0" y="0" width="45" height="24" fill="#d4af37"/>
  <text x="22.5" y="16">TRI</text>
</g>

<g id="ui(uid:rot_triangle, action:toggle, click:1)">
  <rect x="100" y="0" width="45" height="24" fill="#d4af37"/>
  <text x="122.5" y="16">TRI 2</text>
</g>

Preset Integration

Visibility state is included when saving and recalling presets. This allows presets to capture both fader positions AND which UI elements are visible or hidden, restoring the complete performance state.

Built-in UI toggle button

Oscilla includes a GUI button in the bottom-right corner that toggles:

on and off.

This button uses the same internal UI logic as the ui() cue and exists to allow fast switching between visible guidance and reduced interface modes during performance.

Parameters

Common

Selector mode only

Transforms are stateful and combined.

UID mode only

Examples

Selector mode (HTML elements)

// Fade out playhead
ui("#playhead", opacity:0, dur:0.3)

// Hide playhead
ui("#playhead", visible:false, dur:0.3)

// Hide multiple elements
ui("#playhead, #playzone", visible:false, dur:0.25)

// Show multiple elements
ui("#playhead, #playzone", visible:true, dur:0.25)

UID mode (SVG animations)

// Hide a polygon animation and its overlays
ui(uid:rot_triangle, visible:false, dur:0.5)

// Show it again
ui(uid:rot_triangle, visible:true, dur:0.5)

// Toggle visibility
ui(uid:rot_pentagon, action:toggle)

Clickable toggle buttons (click:1)

<!-- Create a clickable SVG button that toggles the triangle -->
<g id="ui(uid:rot_triangle, action:toggle, click:1)">
  <rect x="0" y="0" width="45" height="24" rx="4" fill="#d4af37"/>
  <text x="22.5" y="16" font-size="10" text-anchor="middle">TRI</text>
</g>

<!-- Toggle the pentagon -->
<g id="ui(uid:rot_pentagon, action:toggle, click:1)">
  <rect x="55" y="0" width="45" height="24" rx="4" fill="#9370db"/>
  <text x="77.5" y="16" font-size="10" text-anchor="middle">PENT</text>
</g>

Draggable + clickable toggle buttons (drag-click:1)

Use drag-click:1 when you want the toggle button to be repositionable:

<!-- Draggable toggle button - drag to move, click to toggle -->
<g id="ui(uid:synthLevels, action:toggle, drag-click:1, visible:false)">
  <rect x="0" y="0" width="50" height="48" rx="4" fill="#f0f0f0" stroke="#999"/>
  <!-- Drag handle lines at top -->
  <line x1="15" y1="6" x2="35" y2="6" stroke="#888" stroke-width="1.5"/>
  <line x1="15" y1="10" x2="35" y2="10" stroke="#888" stroke-width="1.5"/>
  <!-- Icon -->
  <text x="25" y="38" text-anchor="middle" font-size="18">🎚</text>
</g>

Design notes

Tip: use ← → or ↑ ↓ to navigate the docs