Oscilla Documentation

This documentation describes the cue system, animation model, authoring workflow, and internal architecture of Oscilla. All behaviour is authored directly in SVG and executed at runtime in the browser.

New to Oscilla?

If you're looking for a high-level overview of what Oscilla is for, how it fits into contemporary score practice, and what you can actually accomplish with it, start here:

→ What is Oscilla?

Getting Started

What is Oscilla? — conceptual overview and use cases
Screenshots — visual examples
Workflow — SVG authoring and browser execution
Cheatsheet — compact syntax reference
Quickstart — your first Oscilla score
Install — setup and dependencies

Session Layer

The session layer covers everything that happens at runtime in the browser during a performance or rehearsal.

Session Layer Overview — introduction to the session model
The Playhead — playhead behaviour and positioning
Parts & Layers — multi-part score structure
Text/Audio Annotations — performer annotation system
Audio Objects — embedded audio objects
Freehand Annotation — freehand drawing overlay
Drop Marker — runtime markers
Sequence Timers — timer display and control
Draggable Groups — draggable SVG groups
Live Console — live coding console

Cue Reference

Cues are the primary execution units in Oscilla. They control timing, navigation, media playback, interaction, and external communication.

Timing & Navigation

Cue	Description
`stop()`	Halt playback
`pause()`	Pause playback
`speed()`	Playback speed control
`stopwatch()`	Time display and control
`metronome()`	Metronome and beat sync
`page()`	Page-based navigation
`nav()`	Navigation and mode control

Interaction & Structure

Cue	Description
`button()`	Interactive UI buttons
`propagate()`	Propagate cue state
`reuse()`	Reuse cue definitions
`text()`	Timed and sequenced text
`pin()`	Pin elements to viewport

Media & Synthesis

Cue	Description
`audio()`	Audio file playback
`audioPool()`	Audio pool playback
`audioImpulse()`	Audio impulse triggers
`video()`	Video playback
`synth()`	In-browser synthesis

OSC & External Control

Cue	Description
`osc()`	OSC message output
`oscCtrl()`	OSC routing and control

Animation

Oscilla supports continuous and discrete animation tied directly to score timing.

Function	Description
`scale()`	Uniform and non-uniform scaling
`rotate()`	Continuous and stepped rotation
`o2p()`	Object-to-path traversal
`traverse()`	Object traversal across points or paths
`color()`	Color animation
`fade()`	Fade visual or UI elements
`ui()`	UI element animation

Control & Interaction

Control Overview — control plane architecture
Control & Modulation — parameter routing and modulation
controlXY() — XY control surface

Tools

Tools Overview — available tooling
Inkscape Extension — author Oscilla cues directly in Inkscape

Developer

Complete System Overview — full system documentation
Architecture Overview — high-level architecture
Sync Architecture — internal timing and sync model
How to Add a New Cue — cue authoring guide
Control Signal Architecture — control signal internals
Animation Observer — animation lifecycle management
New Project Flow — project creation pipeline
OSC System — OSC implementation details
Preprocessor: drag() — drag preprocessor
Parsing Marker Nav — marker navigation parsing
Freehand Annotation — drawing system internals
Live Console — live console architecture
The Playhead — playhead implementation
The Audio System — audio pipeline
Audio Object Architecture — audio object internals