Using Sialk
Sialk plays work made for the web — Three.js, Cables.gl, Spline, a shader, a
canvas, anything that runs in a browser — as layers you mix live, moved by the
music.
This page is the whole instrument. It takes about ten minutes.
**Reading it during the beta:** some of what this page teaches arrives with
v1 rather than in the beta build. The differences are decided in one file and
listed here, generated from it:
<!--sialk:withholds-->
## The idea, in one paragraph
Every sketch you add is a **layer**. Layers stack, and the stack is composited
on the GPU into one picture that goes to the wall. Each layer has **parameters**
— some the sketch declares, some Sialk gives it for free — and every parameter
can be **modulated**: pushed around by the music, or by a shape running in
time. You set where a value rests; something else decides where it goes.
## Layers
The stack reads bottom-up: the layer at the bottom of the list is drawn first,
and everything above it is composited on top.
| | |
| --- | --- |
| **Add** | `+ add layer` at the foot of the stack, or ⌘O. Paste an address, or browse for a folder or the HTML file that starts it. A link or a folder dropped on the window is added too, as is an address on the clipboard with ⌘V. |
| **Opacity** | The amber bar. **Drag it** — a click does nothing, so that selecting a layer can never fade it by accident. |
| **Blend** | The dropdown: normal, add, screen, multiply. |
| **On / off** | The `ON` at the top right of the row. |
| **Order** | `↑` and `↓`, or ⌘↑ and ⌘↓. |
| **Remove** | `✕`, or ⌘⌫. |
The numbers at the bottom right of a layer — `2448/2448` — are frames painted
against frames delivered. They should track each other. If the second number
stops moving, that sketch has stopped.
### A layer with no background is transparent
If your sketch never paints a background, the layer is transparent and whatever
is beneath it shows through. If you want it opaque, paint it: `background:
#000` is enough. This is the same behaviour as a browser source anywhere else.
## Parameters
Selecting a layer lists its parameters in the middle column. There are two
kinds and they are grouped separately.
**LAYER** — four that Sialk gives every layer, whatever the sketch is. They act
on the picture, not on the work inside it, so they are there even for a sketch
that has never heard of Sialk.
| | |
| --- | --- |
| Scale | 0.05 – 4 |
| Position X / Y | −1 – 1, where 1 pushes it a whole frame off the side |
| Rotation | −180° – 180° |
**The sketch's own** — whatever it declared. A number becomes a fader, a switch
becomes a toggle, a menu becomes buttons, a colour becomes a swatch, a trigger
becomes `FIRE`. If a sketch declares nothing, this group is simply absent; see
[for developers](/contract/) for how to declare.
The pills above the list — `all`, `bound`, `moving` — filter it. `moving` is
measured, not assumed: it shows what is actually changing right now.
## Modulation
Select a parameter and the right-hand column shows what is moving it.
**base** is where the value rests when nothing is pushing it. That is the value
you set by hand with the fader.
**reach** appears once something is modulating it, and is the two ends of where
it can be carried. It is in the parameter's own units, so a `reach` of
`14.00 – 34.30 rings` means exactly that.
### Modulators
Add as many as you like. They are summed, and the order does not matter.
**`+ audio`** follows the sound in the room.
- **source** — `level`, `bass`, `mid`, `high`, `onBeat`, `beatPhase`
- **polarity** — `unipolar` pushes from the base upward; `bipolar` pushes either
side of it
- **curve** — `linear`, `exponential`, `logarithmic`. Exponential ignores quiet
passages and reacts to loud ones; logarithmic does the opposite.
- **depth** — how far it carries the value. Negative depth inverts it.
**`+ LFO`** follows a shape in time, with no audio needed.
- **shape** — `sine`, `triangle`, `saw`, `square`, `random`
- **rate** — synced to the tempo Sialk hears: `1/1` down to `1/32`. Until a
tempo has been detected it runs on an assumed one, so it moves from the
first second.
- **retrigger** — `free` runs continuously; `on beat` restarts its cycle on
each beat, so it stays locked to the music.
- **depth** — as above.
### Smoothing
Appears once there is something to smooth. **attack** is how fast the value is
allowed to rise, **release** how fast it may fall, both 0–1000 ms. At 0 it
follows exactly; raise the release and a kick leaves a tail.
### If nothing moves
An audio modulator in a silent room is correct and completely still. The pane
says `no input` beside the reach when that is what is happening, and the meter
at the top of the window is the same fact. **Check that Sialk is hearing
something before assuming a modulator is broken** — it is the single most
common confusion.
An LFO needs no audio and will move regardless. If an LFO moves and audio does
not, the problem is the input, not Sialk.
## The audio
Sialk listens to a system input device and analyses it: loudness, three bands,
onsets, and a tempo. That analysis reaches every layer through
[the audio contract](/contract/), and drives every audio modulator.
To play music into it, route your output back to an input — an aggregate device,
a loopback, or simply a microphone pointed at the room. A microphone is fine and
is what most people start with.
## The output
The picture is previewed in the right-hand column at all times, so you can
rehearse before the room sees anything.
**fullscreen** puts it on a screen of its own, chrome-free and cursor-free,
while the controls stay on your laptop. With a second display connected it goes
there. With only one, macOS gives it a Space of its own — swipe back and forth.
Press it again, or `Esc`, to close it.
The output is letterboxed, never stretched: a 16:9 show on a 16:10 projector
gets bars, not distortion.
## Two views of one surface
The same controls, arranged two ways, and `V` switches between them. **Perform**
gives the picture most of the window, with the layers and parameters in a rail
beside it — the view a show runs in, and the default. **Build** is the columns,
with the parameters widest — the view a show is prepared in. Nothing exists in
one view that is not in the other; the keys are identical; the choice is
remembered on this machine and never travels in a show file.
## Keys
They work while the Sialk window is focused, and nowhere else — Sialk never
takes a key from the rest of your machine.
| | |
| --- | --- |
| `1`–`9` | select a layer |
| `[` `]` | opacity down / up by 0.05 |
| `{` `}` | opacity down / up by 0.25 |
| `\` | toggle the selected layer on or off |
| `b` / `B` | next / previous blend mode |
| `r` | reset the selected layer |
| `v` | switch between the two views of the surface |
| `f` | fullscreen |
| `⌘S` | save the show |
| `⇧⌘S` | save it somewhere else, and go on saving there |
| `Esc` | close the fullscreen stage |
## Shows
⌘S writes a `.sialk` file to `~/Documents/Sialk/`: every layer, where it points,
its mix, and every parameter value and modulator. Reopening it puts the set
back as you left it. ⇧⌘S saves it somewhere else — the show takes that file's
name, and ⌘S goes there from then on.
### Your sketch's own controls
If your sketch has a **lil-gui or dat.GUI panel**, Sialk reads it and puts every
control it can drive on the parameters list — under the panel's own name, with
the labels and ranges you gave them. Bind them, modulate them, save them with
the show. Your `onChange` runs exactly as it does when somebody drags the knob.
Sialk works out each slider's range by asking the panel rather than guessing,
and puts the control back where it found it. A control with no range —
`gui.add(state, 'x')` with no min and max — is left alone. Tweakpane panels are
recognised but not yet playable.
A show **references your sketches where they live** — it does not copy them.
Keep editing them in your own editor; the show opens what is there now, and
tells you if a sketch has moved or changed since it was saved.
A sketch that cannot be found **keeps its place in the stack**, marked
`not found`, with its mix and its modulators intact. Plug the drive in, reopen,
and the layer comes back exactly as it was — and saving in the meantime cannot
lose it.
## When something goes wrong
Every run writes a log to `~/Documents/Sialk/logs/`, without being asked. It
records the machine, the GPU, the frame rate, dropped frames, per-layer
transfer counts and memory — and nothing about you, your sketches, or their
content.
Messages appear along the bottom of the window. Repeats are counted rather than
repeated, so `×12` means the same thing happened twelve times.
If something is wrong, send the log to
[beta@sialk.app](mailto:beta@sialk.app) with a sentence about what you were
doing. That is exactly what the beta is for.