Imports
Import shared instrument collections from external .ins files so songs stay short and libraries stay reusable.
Syntax
| Form | Environments |
|---|---|
import "local:path/to/file.ins" | CLI / Desktop only |
import "github:user/repo/branch/file.ins" | CLI, Desktop, browser |
import "https://example.com/path/file.ins" | CLI, Desktop, browser |
import "local:lib/common.ins"
import "github:user/repo/main/drums.ins"
import "https://example.com/instruments/kit.ins"
| Rule | Behaviour |
|---|---|
| Prefix required | Bare paths like "lib/x.ins" are rejected |
local: paths | Relative to the song file (fallback: cwd) |
| Recursion | Allowed; cycles are detected |
| Merge | Last-wins — song-local inst overrides imported names |
Platform matrix
| Prefix | CLI | Desktop | Browser / web-lite |
|---|---|---|---|
local: | Yes | Yes | Blocked |
github: / https: | Yes | Yes | Yes |
See CLI, Desktop, and Web client.
Security constraints
| Rule | Detail |
|---|---|
| Explicit prefix | Every import must use local:, github:, or https:// |
| Browser | Local filesystem imports are blocked |
| Path traversal | .. segments and absolute paths are rejected for local: |
| Allowed roots | Local resolution stays under the song directory / configured roots |
Authoring example
import "github:user/repo/main/drums.ins"
chip gameboy
bpm 140
# Local override wins over an imported name
inst hat type=noise gb:width=15 env=gb:5,down,1 uge_note=C-8 note=C6
pat drums = kick . hat . snare . hat hat
channel 4 => inst snare seq drums
play
The docs player cannot load arbitrary local: files. The kit below shows the result of a shared drum library with instruments inlined:
Shared kit result (inline)
Interactive playback loads in the browser.
…# Shared kit (same idea as importing a .ins file)inst kick type=noise gb:width=7 uge_note=C-6 length=16 pitch_env=[0,-2,-4,-6] vol_env=[15,12,8,4]inst snare type=noise gb:width=7 env=gb:13,down,1 length=16 uge_note=C-7 note=C6 pitch_env=[0,7,0] vol_env=[13,10,6,2]inst hat type=noise gb:width=15 env=gb:5,down,1 uge_note=C-8 note=C6
pat drums = kick . hat . snare . hat hat # instrument names as tokens…