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)

A double-clickable application for Linux, macOS and Windows.

No Node.js, npm, or Git required.

Download

https://oscilla.cc/

• macOS — .zip containing Oscilla.app (macOS 12 or newer; Intel, and Apple Silicon via Rosetta)
• macOS, older systems — a second -legacy build for macOS 11 Big Sur. Electron follows Chromium's macOS floor, so the current build cannot run there. The legacy build is the same app on the last Electron that supported Big Sur; that release no longer gets security updates, so use it only if the main download will not open.
• Windows — .zip containing Oscilla.exe (Windows 10 or newer)
• Linux — .deb for Debian/Ubuntu, .AppImage for everything else

A separate Linux server binary is also published, for machines with no screen, for several instances at once, or for running Oscilla as a background service. It has no window of its own and takes command-line flags.

Run

The applications are not code-signed, so each system asks once:

• macOS — unzip, drag Oscilla.app into Applications, then right-click it and choose Open. Opening it by double-click the first time is refused; after the first time it opens normally.

• Windows — unzip the folder anywhere and run Oscilla.exe. If SmartScreen warns, choose More info → Run anyway.

• Linux, Debian or Ubuntu — install the .deb:

  sudo apt install ./oscilla_*_amd64.deb
  

  Oscilla then appears in the applications menu; sudo apt remove oscilla uninstalls it.

• Linux, other distributions — make the AppImage executable and run it:

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

  AppImages are type 2 and need FUSE. Ubuntu has not shipped libfuse2 by default since 22.04, so on a stock system this fails with dlopen(): error loading libfuse.so.2. Either sudo apt install libfuse2t64, or use the .deb, which has no FUSE dependency — that is why it is published.

Open Oscilla

A small window titled Oscilla Server appears. That is the control panel, not the score. Click Open Oscilla on this computer to open the score itself.

Performers on the same network join by entering the address shown in that window, or by scanning its QR code. If you need it directly, the score is at:

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 run electron

This opens the Oscilla server console — a desktop window showing server status, the addresses performers connect to (with scannable QR codes), settings, and the live log. Click Open Oscilla on this computer to open the score. See Server Console for everything it does.

To run the server without the console window instead:

npm start

then open http://localhost:8001 in a browser.

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 run electron

This opens the Oscilla server console (see the Windows section above). npm start runs the plain server instead — open http://localhost:8001 in a browser.

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 run electron

This opens the Oscilla server console (see the Windows section above). npm start runs the plain server instead — open http://localhost:8001 in a browser.

One-Click Launcher (No Terminal)

The first time you open the server console (npm run electron), it offers an Install launcher button — click it and Oscilla appears in your application menu / Start Menu / ~/Applications. From then on, start Oscilla with one click, no terminal.

(Equivalent manual command, from the repo folder: ./build/launcher/install-launcher.sh on Linux/macOS, or powershell -ExecutionPolicy Bypass -File build\launcher\install-launcher.ps1 on Windows.)

Where Projects Live

Your score projects are stored outside the Oscilla folder, in:

~/oscilla-projects/

The folder is created automatically on first start (override the location in the server console's Projects folder setting, or with the OSCILLA_PROJECTS_DIR environment variable). The shipped demos live inside the app itself. If you're upgrading from an older version that kept projects inside public/scores/, Oscilla shows a one-time notice offering to move them for you.

Updating

With a git installation, the server console has a Check & update button (runs git pull; restart Oscilla to apply). Equivalent terminal command:

git pull && npm install

Test the Demo Project

Once Oscilla is running:

http://localhost:8001/?project=demo-trans

You should see the demo score demo-trans, with objects travelling between waypoints. Every distribution ships the full set of demo-* projects — open them from Demos in the menu.

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

Building the apps (maintainers)

npm run build # standalone server binaries (pkg) -> dist/ npm run dist:mac # macOS app, Intel x64 (Apple Silicon via Rosetta) npm run dist:desktop # Windows .zip + Linux AppImage and .deb ./build/build-mac.sh arm64 # Apple Silicon native (must then be signed on a Mac)

Run npm run build first — it wipes dist/, which is the staging directory the website publishes from; the app builds then add themselves to it. Publish with cd public/docs && ./build_kompot.sh --deploy.

All three apps share electron/builder-app.json. Windows uses the zip target rather than an installer: NSIS and rcedit both need wine to run on Linux, so signAndEditExecutable is off and the .exe keeps Electron's default icon and metadata.

Output: dist-mac/Oscilla-<version>-macOS-x64.zip, containing Oscilla.app plus a "READ ME FIRST" note for the recipient.

Two things this build handles that npm run dist does not:

• Old macOS support. Electron follows Chromium's macOS floor, and Chromium 140 (Electron 38+) requires macOS 12. electron/builder-mac.json therefore pins Electron 37 — the last release whose LSMinimumSystemVersion is 11.0 — so the app runs on Big Sur.
• Symlinks. electron-builder's macOS zip, when produced on Linux, flattens the .app's framework symlinks into copies. macOS then refuses to launch the bundle, and the download doubles in size. The script repacks with zip -y, then verifies symlinks, the executable bit, VERSION and the bundled MIDI prebuild before reporting success.

The native MIDI module ships N-API prebuilds for darwin, so no cross-compiler is needed; npmRebuild is off because rebuilding on Linux would target Linux.

The app is unsigned (signing requires a Mac). The recipient opens it the first time with right-click → Open; after that it opens normally.

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