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

All Oscilla projects live inside:

public/scores/

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 public/scores/
• 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:

public/scores/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

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 mix both approaches freely — the inspector and Inkscape edit the same score.svg file.

5. Opening and Switching Projects

You can open projects in several ways.

From the loader

1. Visit:

http://localhost:8001

2. Select a project from the loader dialog

Direct URL

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

From the menu

Use:

File → Projects

to switch between existing projects without restarting the server.

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 public/scores/
• 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
• use cues for timing and navigation
• optionally synchronize multiple clients

Each performer reads from the same authored score, rendered locally in their browser.

Summary

• Projects are folders, not opaque files
• 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.

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