Scroll Mode & Direction
Oscilla supports four scroll configurations that control how a score moves past the playhead during playback. The mode (horizontal or vertical) and the direction (left-to-right, right-to-left, top-to-bottom, bottom-to-top) are independent settings and can be combined freely.
Scroll Modes
Horizontal (default)
The score is laid out on a wide horizontal canvas — typically 40,000 px or more — and scrolls leftward past a fixed vertical playhead line. This is the standard Western notation reading direction and the default for any score whose SVG width is greater than its height.
Vertical
The score is laid out on a tall portrait canvas and scrolls upward past a
fixed horizontal playhead line — like a teleprompter or autocue. This is
activated automatically when the SVG viewBox is taller than it is wide
(portrait aspect ratio).
Vertical mode is well suited to:
- iPad performance — a 1024 × 30 000 canvas fills the screen naturally in portrait orientation
- Dense text-based scores — single-column notation reads comfortably top-to-bottom
- Projected scores — a tall narrow format works well on portrait displays or screens in vertical rig positions
The playhead becomes a horizontal line fixed at 50 % of the viewport height by default. The score ascends past it as time advances.
Starting a vertical score
Use the built-in template at demo-vertical-scroll as a starting point. It
provides a 1024 × 30 000 canvas with a time grid at 50 px/sec (10 minutes
total). Open it in Inkscape, delete the grid guides you don't need, and draw
your score content above y = 0 (beginning) down to y = 30 000 (end).
The grid lines in the template are:
| Spacing | At 50 px/sec |
|---|---|
| 50 px | 1 second |
| 500 px | 10 seconds |
| 3 000 px | 1 minute |
Scroll Direction
Left → Right (ltr) — default horizontal
Standard Western reading direction. The score begins at the left (SVG x = 0) and the playhead sweeps rightward.
Right → Left (rtl)
The score begins at the right edge (SVG x = scoreWidth) and the playhead sweeps leftward. Suited to scores for performers reading in right-to-left scripts (Arabic, Hebrew, Persian, Urdu, etc.), or as a compositional choice where the visual flow of notation follows a RTL grammar.
The SVG coordinate system is unchanged — x = 0 is still the bottom-left of the canvas in Inkscape — but playback starts from the far right and counts down. Cues are triggered as the playhead crosses their right edge.
Top → Bottom (ttb) — default vertical
The score begins at the top (SVG y = 0). This is the default for portrait scores.
Bottom → Top (btu)
The score begins at the bottom (SVG y = scoreHeight) and scrolls downward. Suitable for scores intended for cultures or compositional contexts where vertical text or notation flows upward, or as an explicit artistic direction.
Setting Scroll Direction
There are two ways to configure scroll mode and direction:
1. Preferences dialog (recommended)
Open the project preferences dialog (hamburger menu → Settings tab) and find Scroll Direction. Choose from:
| Option | Behaviour |
|---|---|
auto |
Detect from SVG aspect ratio and data-scroll-dir attribute (default) |
ltr |
Force horizontal, left → right |
rtl |
Force horizontal, right → left |
ttb |
Force vertical, top → bottom |
btu |
Force vertical, bottom → top |
The setting is saved to preferences.json and takes effect the next time the
score is loaded. It overrides the SVG auto-detection below.
2. SVG attribute
Add data-scroll-dir directly to the <svg> root element:
<svg xmlns="http://www.w3.org/2000/svg"
viewBox="0 0 40000 1080"
data-scroll-dir="rtl">
Valid values are ltr, rtl, ttb, btu. Omitting the attribute lets
Oscilla detect the mode from the aspect ratio (portrait = ttb, landscape =
ltr).
The preferences dialog value takes precedence over the SVG attribute when set
to anything other than auto.
Playhead Appearance by Mode
The playhead adapts automatically to the scroll mode:
| Mode | Playhead shape | Default position |
|---|---|---|
| Horizontal (ltr / rtl) | Vertical line, full viewport height | 50 % from left |
| Vertical (ttb / btu) | Horizontal line, full viewport width | 50 % from top |
Colour, width, and visibility are configured the same way in all modes — see The Playhead for details.
The playhead position % preference and drag handle are active in horizontal mode. In vertical mode the playhead is fixed at 50 % of the viewport height (drag repositioning in vertical mode is planned for a future release).
Cue Triggering in Each Mode
Cues fire when the playhead crosses their leading edge — the edge that arrives at the playhead first as time advances:
| Mode | Leading edge |
|---|---|
| ltr | Left edge of the cue element |
| rtl | Right edge of the cue element |
| ttb | Top edge of the cue element |
| btu | Bottom edge of the cue element |
The isInside region (used by continuous cues such as audio(), synth(),
and osc()) spans the full bounding box of the element in all modes, so
region-lifetime behaviour is preserved regardless of direction.
Duration and Pixel Density
Scroll speed is determined by the ratio of score length to duration:
px/sec = scoreLength / durationInSeconds
where scoreLength is the width (horizontal modes) or height (vertical
modes) of the SVG viewBox.
Set Duration (min) in the preferences dialog to control playback speed. The Target px/sec field shows the resulting density as a reference.
For the vertical template at its defaults: 30 000 px ÷ 600 s = 50 px/sec.
Tip: use ← → or ↑ ↓ to navigate the docs