Oscilla — Complete System Documentation

Version: 0.4.2
Purpose: Browser-based framework for animated, cue-driven graphic scores
Technologies: SVG, JavaScript (ES Modules), Node.js, WebSockets, OSC

Table of Contents

1. System Overview
2. Architecture
3. Server Components
4. Client Components
5. Cue System
6. Transport & Synchronization
7. OSC Integration
8. Project Structure
9. File Reference

System Overview

Oscilla is a browser-based platform for real-time animated graphic scores. It enables:

• Animated and spatial graphic notation — SVG-based scores with cue-driven animations
• Networked performances — Multiple clients synchronized via WebSocket
• Cue-driven timing, navigation, and media — DSL for defining behaviors via SVG element IDs
• OSC integration — Bidirectional communication with external audio/media engines
• Hybrid fixed-form and open-form works — Support for linear playback and interactive navigation

What Oscilla Is NOT

• A DAW (Digital Audio Workstation)
• A notation engraver (like Sibelius/MuseScore)
• A collaborative score editor

Architecture

High-Level Data Flow

┌─────────────────────────────────────────────────────────────────┐
│                         INKSCAPE                                │
│  (Score Authoring - SVG with cue IDs in element names)          │
└──────────────────────────┬──────────────────────────────────────┘
                           │ score.svg
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      NODE.JS SERVER                             │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐     │
│  │   Express   │  │  WebSocket   │  │    OSC Bridge       │     │
│  │  (HTTP/API) │  │   Server     │  │  (UDP In/Out)       │     │
│  └─────────────┘  └──────────────┘  └─────────────────────┘     │
│         │                │                    │                 │
│         │     Shared State (playhead, time, speed)              │
│         │                │                    │                 │
└─────────┼────────────────┼────────────────────┼─────────────────┘
          │                │                    │
          ▼                ▼                    ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐
│  Browser Client │ │  Browser Client │ │  External Audio Engine  │
│  (Performer 1)  │ │  (Performer 2)  │ │  (SuperCollider, etc.)  │
└─────────────────┘ └─────────────────┘ └─────────────────────────┘

Key Concepts

Server Components

server.js (Main Server — ~2175 lines)

The central Node.js server providing:

HTTP/Express Endpoints:

• GET / — Serves static files from /public
• GET /scores/:project — Project score files
• GET /api/version — Returns Oscilla version
• GET /api/projects — Lists available projects
• GET /api/audio-tree/:project — Audio file browser
• POST /api/upload-audio/:project — Audio file upload
• POST /api/project/new — Create new project
• POST /api/project/save-as — Duplicate project
• GET /api/project/export/:name — Export as .oscilla
• POST /api/project/import — Import .oscilla file
• POST /save-preferences/:project — Save project preferences
• GET /config — WebSocket configuration for clients

WebSocket Message Types (Inbound from Clients):

WebSocket Message Types (Outbound to Clients):

Shared State Object:

sharedState = {
  elapsedTime: 0,           // ms
  isPlaying: false,
  playheadX: 0,             // world units
  duration: null,           // ms (from project)
  speedMultiplier: 1.0,
  startTimestamp: null,     // performance.now() anchor
  scoreWidth: null,
  canonicalRenderedWidth: null,
  countdown: null           // server-owned countdown state
}

serverUtils.js

Project management utilities:

• createNewProject(name) — Copy template to new project
• saveProjectAs(source, name) — Duplicate existing project
• exportProject(name, res, version) — Create .oscilla ZIP archive
• importProject(buffer, name) — Extract and validate .oscilla file

server-gui.js

Electron wrapper for standalone builds:

• Spawns server.js as child process
• Displays server status in GUI window
• Shows connected clients and log output

Client Components

public/js/app.js (Entry Point)

Orchestrates client initialization:

• Imports and wires all major subsystems
• Establishes global window bindings for cross-module access
• Detects platform (desktop/mobile) and loads appropriate CSS
• Initializes WebSocket connection
• Sets up UI controls and event handlers

Key Global Bindings:

window.playheadX          // Current position
window.elapsedTime        // Current time
window.speedMultiplier    // Playback speed
window.duration           // Score duration
window.scoreWidth         // Score width in world units
window.isPlaying          // Playback state
window.triggeredCues      // Set of triggered cue IDs
window.socket             // WebSocket connection

public/js/system/ (System Modules)

public/js/oscillaTransport.js (~2225 lines)

Transport control and synchronization:

• Play/pause/stop controls
• Speed adjustment (0.1x - 4.0x)
• Seek bar and keyboard navigation (←/→ arrows)
• Rehearsal mark navigation
• Visual scroll synchronization
• Dark mode toggle

Synchronization Model:

All clients use identical scale: canonicalScale = canonicalRenderedWidth / scoreWidth

Visual positioning via CSS transform (GPU-accelerated):
  screenX = playheadX * canonicalScale
  translateX = (viewportWidth / 2) - screenX
  scrollStage.style.transform = translateX(${translateX}px)

public/js/projectLoader.js

Loads projects from /scores/:project/:

• Fetches and parses score.svg
• Loads preferences.json
• Initializes score dimensions
• Reports metadata to server

public/js/projectScoreSetup.js

Score DOM setup:

• Extracts score elements
• Auto-injects scroll groups
• Processes SVG layers
• Applies transformations

Cue System

Overview

Cues are behaviors defined by SVG element ID attributes. When the playhead crosses an element, its ID is parsed and the corresponding handler executes.

Parser (public/js/parser/parser.js — ~2681 lines)

Chevrotain-based DSL parser supporting:

Cue Syntax Examples:

pause(5)                    // Pause for 5 seconds
speed(0.5)                  // Set speed to 0.5x
speed(2 dur:4)              // Ramp to 2x over 4 seconds
nav(A)                      // Jump to rehearsal mark A
page(intro dur:3)           // Show page "intro" for 3 seconds
audio(file.mp3 vol:0.8)     // Play audio at 80% volume
rotate(360 dur:2 ease:inOut) // Rotate 360° over 2 seconds
scale(2 dur:1)              // Scale to 2x over 1 second
osc(/addr 0.5)              // Send OSC message
synth(freq:440 amp:0.5)     // Trigger synthesizer
text("Hello" dur:3)         // Display text for 3 seconds

Cue Dispatcher (public/js/cues/cueDispatcher.js)

Routes parsed AST to appropriate handlers:

switch (ast.type) {
  case "cuePause":    return handlePauseCue(ast);
  case "cueSpeed":    return handleSpeedCue(ast);
  case "cuePage":     return handlePageCue(ast);
  case "cueNav":      return handleNavCue(ast);
  case "cueAudio":    return handleAudioCue(ast);
  case "cueRotate":   return handleRotateCue(ast);
  case "cueScale":    return handleScaleCue(ast);
  case "cueO2P":      return handleO2PCue(ast);
  case "cueColor":    return handleColorCue(ast);
  case "cueOsc":      return handleOscCue(ast);
  case "cueSynth":    return handleSynthCue(ast);
  case "cueText":     return handleTextCue(ast);
  // ... etc
}

Cue Handlers (public/js/cues/)

Animation Shared (public/js/cues/animShared.js)

Common animation utilities:

• Easing functions
• Duration parsing
• Loop handling
• Prestate management (ghostClickable, fadein)

Transport & Synchronization

Clock Model

The server maintains an authoritative transport clock:

// Server calculates elapsed time from wall clock
const wallSeconds = (performance.now() - startTimestamp) / 1000;
const elapsedMs = wallSeconds * speedMultiplier * 1000;

// Playhead position derived from elapsed time
playheadX = (elapsedTime / duration) * scoreWidth;

Sync Broadcast (4Hz)

Server broadcasts state every 250ms:

{
  type: 'sync',
  state: {
    elapsedTime,
    isPlaying,
    scoreWidth,
    playheadX,
    speedMultiplier,
    startTimestamp,
    canonicalRenderedWidth,
    duration,
    countdown
  },
  serverTime: Date.now()
}

Client Sync Handling

Clients apply server state with drift protection:

• Small drift (<2% of score): Gradual correction
• Medium drift (2-5%): Immediate position update
• Large drift (>5%): Teleport mode (suppress cue triggers)

// Teleport mode prevents cue cascade during large jumps
window._isTeleporting = true;
window.suppressCueTriggers = true;
window._skipTriggerFrame = 5;

OSC Integration

Configuration

oscConfig = {
  localAddress: "0.0.0.0",      // Listen address
  localPort: 57121,             // OSC input port
  remoteAddress: "127.0.0.1",   // Destination address
  remotePort: 57120             // OSC output port
}

Outbound OSC Messages

OSC-In Support

Server can receive OSC and route to clients via WebSocket:

case "osc_in":
case "osc_control":
  handleOSCIn(address, args);

Project Structure

Score Project Layout

public/scores/{project}/
├── score.svg           # Main score file (required)
├── preferences.json    # Project settings
├── audio/              # Audio files
│   ├── samples/
│   └── recordings/
├── video/              # Video files
├── pages/              # SVG page overlays
└── oscilla.manifest.json  # Export manifest (in .oscilla archives)

preferences.json

{
  "projectName": "my-score",
  "duration": 300,
  "scoreWidth": 40960,
  "enableOSC": true,
  "oscAddress": "/oscilla",
  "theme": "dark"
}

Score SVG Structure

<svg viewBox="0 0 40960 1080">
  <!-- Main scrolling content -->
  <g id="scroll-content">
    <!-- Notation elements -->
    <rect id="pause(5)" .../>
    <circle id="rotate(360 dur:2)" .../>
    <path id="audio(click.mp3)" .../>
  </g>
  
  <!-- Rehearsal marks -->
  <g id="rehearsal-marks">
    <text id="mark-A">A</text>
    <text id="mark-B">B</text>
  </g>
  
  <!-- Reusable blocks -->
  <defs>
    <g id="reuse-pattern1">...</g>
  </defs>
</svg>

File Reference

Server Files

Client Core Files

Parser Files

Cue Handler Files

System Module Files

Interaction Files

Control Module Files

Inkscape Extension Files

Build/Deploy Scripts

Dependencies

Server (package.json)

{
  "dependencies": {
    "archiver": "^7.0.1",      // ZIP creation
    "chevrotain": "^11.0.3",   // Parser generator
    "express": "^4.21.2",      // HTTP server
    "multer": "^2.0.2",        // File upload
    "osc": "^2.4.5",           // OSC protocol
    "unzipper": "^0.12.3",     // ZIP extraction
    "ws": "^8.18.0",           // WebSocket
    "yargs": "^17.7.2"         // CLI arguments
  },
  "devDependencies": {
    "@11ty/eleventy": "^2.0.1", // Docs generator
    "@yao-pkg/pkg": "^6.12.0",  // Binary packaging
    "esbuild": "^0.25.0"        // Bundler
  }
}

Client (Vendor Libraries)

• anime.min.js — Animation library
• svg-path-commander.js — SVG path manipulation
• wavesurfer.min.js — Audio waveform display

Quick Reference: Adding a New Cue Type

1. Add token to parser.js token definitions
2. Add grammar rule to parser class
3. Add CST-to-AST conversion in cstToAst()
4. Create handler in public/js/cues/newcue.js
5. Add case to cueDispatcher.js switch statement
6. Add OSC handler (if needed) in server.js
7. Update Inkscape extension presets (optional)

Document generated from Oscilla v0.4.2 source code

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