Oscilla — Installation Guide

Oscilla is a browser‑based system for creating and performing synchronized graphic scores. It can be run either as a standalone desktop application (recommended for most users) or via Node.js for development and advanced workflows.

Option 1 — Standalone Application (Recommended)

Standalone builds are available for Linux, macOS (Intel & Apple Silicon), and Windows.

No Node.js, npm, or Git required.

Download

Download the latest release from:

https://oscilla.cc/builds/

Choose the build for your operating system:

• Linux — AppImage
• macOS — .app (Intel or Apple Silicon)
• Windows — .exe

Run

• Linux: Make the AppImage executable and run it

  chmod +x Oscilla-*.AppImage
  ./Oscilla-*.AppImage
  

• macOS: Open the .app

  • You may need to right‑click → Open the first time

• Windows: Double‑click the .exe

Oscilla will start its local server automatically and open in your browser.

Open Oscilla

If it does not open automatically, visit:

http://localhost:8001

Requirements for Standalone Use

Option 2 — Node.js / npm Installation (Advanced / Development)

This option is intended for:

• contributors and developers
• users modifying Oscilla source code
• custom server integrations

Requirements

Windows (Node.js Route)

1. Install Inkscape

https://inkscape.org/release/windows/

2. Install Node.js (18 or later required)

https://nodejs.org/en/download

Choose the Windows Installer (.msi) — pick the LTS version (18 or 20). Ensure Add to PATH is enabled during installation.

Verify:

node -v
npm -v

Node 12 or 14 will fail with a syntax error on startup — upgrade if needed.

3. Get Oscilla

Option A — Git

git clone https://git.kompot.si/rob/oscilla.git
cd oscilla

Option B — ZIP

1. Download from https://git.kompot.si/rob/oscilla/releases
2. Extract the ZIP
3. Open PowerShell in the extracted folder

4. Install & Run

Note — PowerShell users: Windows may block npm with "running scripts is disabled on this system". The quickest fix is to use Command Prompt (cmd.exe) instead of PowerShell — the restriction does not apply there.

Alternatively, if you want to keep using PowerShell, open it as Administrator (right-click the Start menu → Windows PowerShell (Admin)) and run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

You only need to do this once.

npm install
npm start

Open:

http://localhost:8001

Linux (Node.js Route)

1. Install Inkscape

sudo apt update
sudo apt install inkscape

2. Install Node.js (18 or later required)

Note: apt install nodejs on Ubuntu 22 installs Node 12, which is too old. Use the NodeSource script instead:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Verify:

node -v   # should show v20.x.x
npm -v

3. Get Oscilla

git clone https://git.kompot.si/rob/oscilla.git
cd oscilla

Or download and extract the ZIP from the releases page.

4. Install & Run

npm install
npm start

Open:

http://localhost:8001

macOS (Node.js Route)

1. Install Inkscape

https://inkscape.org/release/macos/

2. Install Node.js (18 or later required)

https://nodejs.org/en/download

Pick the LTS version (18 or 20). Verify:

node -v
npm -v

3. Get Oscilla

git clone https://git.kompot.si/rob/oscilla.git
cd oscilla

Or download and extract the ZIP from the releases page.

4. Install & Run

npm install
npm start

Open:

http://localhost:8001

Test the Demo Project

Once Oscilla is running:

http://localhost:8001/?project=helper-score

You should see the demo score helper‑score.

Inkscape Extension (Optional)

Oscilla includes an optional Inkscape extension to assist with:

• creating score templates
• inserting cue elements
• managing IDs and layers

See the documentation for installation and usage details.

Troubleshooting

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