Workflow

This page describes the current OscillaScore workflow, including creating, loading, saving, and sharing projects. It reflects the newer project lifecycle tools available from the UI (New Project, Save As, Import / Export).

The core idea remains the same: draw in Inkscape, perform in the browser, but project management is now handled explicitly by Oscilla.

1. Projects and Project Structure

Your projects live in a dedicated folder outside the Oscilla installation:

~/oscilla-projects/

(override the location with the OSCILLA_PROJECTS_DIR environment variable — the default is cross-platform: C:\Users\you\oscilla-projects on Windows, /Users/you/oscilla-projects on macOS). Nothing is created behind your back: the first time the server starts, the server console asks where your projects should live — point it at a folder of Oscilla projects you already have, choose a place for new ones, or accept the default with one click. The choice is remembered and can be changed in the console any time.

The shipped demos live inside the app itself (public/scores/) and are read-only in spirit — your own work never mixes with the software tree, so upgrading or version-controlling Oscilla can't touch your scores.

The server serves both locations transparently: any folder you drop into ~/oscilla-projects/ is immediately a first-class project — it appears in the menus, loads by name, and every connected client can open it, which is what makes multi-client performance work.

Each project is a self-contained folder. At minimum, a project contains:

myProject/
└── score.svg

This is enough for a project to load and run.

A typical project created by Oscilla looks like:

myProject/
├── score.svg                # main scrolling or hybrid score
├── preferences.json         # project preferences (auto-generated)
├── pages/                   # optional page-mode SVGs
├── audio/                   # optional local audio files
├── text/                    # optional external text cues
└── video/                   # optional local video files

You normally do not create this structure by hand anymore — Oscilla does it for you.

2. Creating a New Project

Recommended method (UI)

1. Open Oscilla in your browser:

http://localhost:8001

2. Open the hamburger menu (top-right)
3. Choose:

File → New Project…

4. Enter a project name

Oscilla will:

• create a new project folder inside ~/oscilla-projects/
• copy the project template (including score.svg and helper files)
• load the project automatically

After creation, Oscilla shows a short hint explaining where the score file lives on disk and that it should be edited in Inkscape.

3. Editing the Score in Inkscape

Oscilla does not provide a built-in score editor. Inkscape is the primary authoring tool.

1. Open Inkscape
2. Open:

~/oscilla-projects/myProject/score.svg

3. Draw shapes, text, paths, and layout the score visually
4. Save the file

Refresh the browser and the changes appear immediately.

Page size conventions

Oscilla expects specific page dimensions depending on score type:

Set this in Inkscape via:

File → Document Properties → Page Size

Notes:

• 1024px height is optimized for tablet landscape display
• For scrolling scores, width directly affects playback duration
• Playback speed can be adjusted in preferences.json

4. Adding Behaviour (CueDSL)

Behaviour is encoded as CueDSL — a compact expression syntax stored in SVG element attributes. For example:

• rotate(dur:2, uid:myShape, trig:auto) — continuous rotation
• audio(src:audio/intro.flac, uid:theme, trig:auto) — triggered audio
• pause(dur:12, count:true) — score pause with countdown
• scale(values:[0.5,1.5], dur:1, uid:s1) — scale animation

There are two ways to author cues:

Method 1: DSL Inspector (recommended — no Inkscape required)

The DSL Inspector is a built-in browser tool. Enable it with the pencil icon (✏) in the top bar.

• Hover over any SVG element to see its current cue
• Click a cue element to open the parameter editor — fill in form fields, see a live DSL preview, and click Save to SVG
• Click any plain element (no cue) to open the Add Cue panel — pick a cue type and fill in the form
• + Add cue adds a second (or third) cue to an element — each cue gets its own wrapper <g> so animations do not conflict

Touch gestures

On a touchscreen the score itself is the transport. Double-tap (double-click with a mouse) by screen region — the same map on every device:

Drag left or right to scrub, with momentum. Pinch to zoom in on your part and drag with two fingers to move it up or down the screen — both are local to your device and never reach the other players, because zoom is a view setting, not a transport one. With Single-finger pan when zoomed on in the preferences, a single finger dragged up or down also pans once the score is zoomed past fit; it is off by default so it can never compete with a fader or a drag object.

With a mouse or touchpad: the wheel scrubs; Ctrl/⌘ + wheel — or a touchpad pinch — zooms the score about the cursor; shift + wheel pans; and the middle button drags the score up or down. Panning works at any zoom and goes past the edges of the window on purpose — a quarter of the score always stays on screen, the rest may be pushed off — so the top of a score can be brought down clear of the overview strip, or the bottom up clear of the transport, with no margin drawn into the score. All of it is local to your device, like the touch gestures.

Press Z to draw the zones over the score with labels; the Transport demo opens with them showing (the showGestureZones project preference), and its gesture zones button is authored in the score itself:

button(label:"gesture zones", trigger:ui(target:"#gesture-zones-overlay", action:toggle), uid:gzBtn, style(size:"160x34", color:"#3a5570", textcolor:"#ffffff", fontsize:14))

ui(target:…, action:toggle) shows or hides any element the selector matches — score or interface — so a score can carry its own controls for the app.

Changes are written directly to score.svg and take effect immediately. No Inkscape round-trip needed.

See the full DSL Inspector documentation.

Method 2: Inkscape XML Editor

For fine-grained SVG control or when the inspector is not available:

1. Open score.svg in Inkscape
2. Select an element and open the XML editor: Ctrl + Shift + X
3. Set the data-oscilla attribute to a cue expression
4. Save and refresh the browser

The Inkscape extension provides a structured form interface inside Inkscape as an alternative to typing DSL by hand. See Inkscape extension.

You can also type a cue expression straight into the element's id field (the object properties dialog — no XML editor needed). This is the quickest route in Inkscape, but ids with spaces and parentheses are not valid SVG. Oscilla reads them fine, and when it finds them in one of your projects it offers a one-click Normalize (a notice appears after loading): each cue's DSL moves into data-oscilla and the element gets a plain id (its uid:). Behaviour is identical before and after; a version snapshot is saved first, and if the score is open in Inkscape at the time, do File → Revert there afterwards.

You can mix both approaches freely — the inspector and Inkscape edit the same score.svg file.

5. Opening and Switching Projects

Everything opens by name — Oscilla finds the project whether it lives in ~/oscilla-projects/ or is a shipped demo.

From the splash screen

Visit http://localhost:8001 and use the four buttons:

• New — create a project
• Open — your projects (most recently used first)
• Demos — the shipped demo scores
• Help — this documentation

From the menu (while a project is loaded)

• File → Open… — the same Projects dialog
• Projects submenu — recently worked-on projects first
• Demos submenu — all shipped demos

Direct URL

http://localhost:8001/?project=myProject

Useful for bookmarks, tablets, and connecting performers straight to a score.

6. Saving and Duplicating Projects

Save As

Use:

File → Save Project As…

This:

• duplicates the current project
• assigns a new project name
• preserves all SVGs, media, and preferences

The new project is loaded automatically.

This is the recommended way to create variations or rehearsal versions.

7. Exporting and Importing Projects (.oscilla)

Oscilla supports bundling a complete project into a single file for sharing.

Export

File → Export Project (.oscilla)

This creates a .oscilla file containing:

• score.svg
• preferences.json
• pages, audio, texts, and videos (if present)

You can send this file to collaborators or archive it.

Import

File → Import Project (.oscilla)

When importing:

• you choose a new project name
• the project is unpacked into ~/oscilla-projects/
• the project is loaded automatically

This allows projects to be shared without manually copying folders.

8. Iteration Loop (Typical Use)

With the DSL Inspector (fast):

1. Enable the inspector (✏ in the top bar)
2. Click an element to edit or add cues
3. Adjust parameters in the panel — the preview updates live
4. Click Save to SVG — the animation restarts immediately

No Inkscape, no page reload.

With Inkscape (for layout and drawing):

1. Edit score.svg in Inkscape (shapes, layout, paths)
2. Save
3. The browser reloads automatically (file watcher)
4. Switch back to the inspector to wire up cues

Both loops can run in parallel — use Inkscape for visual design, the inspector for cue logic.

Oscilla never locks files — the filesystem is always the source of truth.

9. Rehearsal and Performance

For rehearsal and performance:

• open the same project on all devices (by name or direct URL)
• use cues for timing and navigation
• optionally synchronize multiple clients

Each performer reads from the same authored score, rendered locally in their browser. Because the server serves ~/oscilla-projects/ directly, a score you edit on the host machine — in Inkscape or the DSL editor — is what every connected client sees, with no publish or copy step.

Summary

• Projects are folders in ~/oscilla-projects/, not opaque files — outside the app, easy to back up and version
• The DSL Inspector (browser, ✏) is the fastest way to add and edit cue behaviour
• Inkscape handles visual layout and drawing; cues can be set there too
• Oscilla handles loading, duplication, import/export, and playback
• .oscilla files are for sharing and archiving, not daily editing

This separation keeps the system transparent, hackable, and robust.

Zooming the score

] makes the score bigger, [ smaller, \ puts it back to fit. The same three are in the top bar as a magnifier pair with the current percentage between them; clicking the percentage goes back to fit. Only the score scales — the top bar, panels and dialogs stay the size they were, which is the difference from the browser's own zoom.

Zoom is local to one machine and one project. It is not sent to the server and it does not disturb the ensemble: the playhead, the drift correction and every cue trigger work in the score's own coordinates, so a tablet at 200% and a laptop at 100% stay sample-accurate with each other. Each performer sets the size they can read from where they sit. The setting is remembered per project, so a score you always want large stays large.

Zoomed past the fit size the score is taller than the screen (or wider, in a vertical score). It is centred, and Shift + scroll wheel moves it up and down to reach the top or bottom staves. Plain scrolling still seeks the playhead.

Behind other windows

Oscilla keeps time when its window is hidden. Browsers stop drawing and slow their timers to once a second for a page that is minimised, behind another tab, or — on Windows and macOS — fully covered by another window; Oscilla then drives its playhead, animations, cue triggers and OSC/MIDI from a background worker clock instead, so a Max, Pd or Reaper window on top of the score costs nothing. The desktop app additionally opts its windows out of that throttling altogether. Video playback and the follow:1 overlay are the exceptions: they resume when the window is visible again.

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