Session

The session view is the panel in the centre of the window, below the transport bar and left of the settings in the shipped arrangement (see Panels). It is the non-linear side of MusicStation: instead of one timeline it shows a grid of clip slots - tracks as columns, scenes as rows - and starts the clips you put there whenever you want them. The launch quantisation is what makes that musical: a clip is not started the instant you click, it is armed first, and the engine starts it on the next boundary. Clips launched while music runs therefore stay in time, and a scene starts as one gesture.

The view has three parts: its header line with the title, the Quantisation select and the message of the last rejected gesture; the scene column on the left with one launch button per row; and the grid of clip slots, one cell per track and scene. Everything that needs the engine is disabled while the interface is not connected to it (see Engine status) - a gesture would then have nobody to answer it.

The engine stays the authority: it sends the whole session state as a snapshot at most 30 times a second, and the grid shows exactly that snapshot. A gesture appears at once and is taken back when the engine rejects it; the header line then names the reason in the language of the interface. Filling a slot with a file is the one gesture with a longer way to go, because the engine decodes the file before the clip exists (see Files: drag and drop).

Session grid

The clip grid of the session view, and the place this chapter is about. Tracks are the columns, scenes are the rows, and the scene column on the left names each row. The engine reports the size of the grid with every snapshot; in this version it is fixed to 16 tracks and 16 scenes, so the grid holds up to 256 slots. The labels count from 1 (Track 1, Scene 1), the engine addresses the cells from 0 - what you read is always the number the interface prints.

Each cell is one clip slot and shows what the engine reports for it; a slot has one of four states (see Clip slot). The snapshot lists only the slots that hold a clip: a slot that is not listed is empty, and an empty slot never stops what is playing on its track - it simply has nothing to start.

The rules that hold for every gesture in the grid:

One clip per track. At most one clip of a track plays. Launching a different clip of that track stops the clip that is running at the very same boundary, so the two transitions share one boundary instead of overlapping.
The engine is the truth. Every snapshot replaces the whole grid; the view keeps no copy of its own. The immediate reaction of a gesture only bridges the moment between your click and the answer.
Quantised. Launches and stops happen at the quantisation in effect, not at the moment of the click.
No names of its own. Track and scene names never travel between engine and interface; the row and column labels are the numbers, and the name a slot shows is the file name of its clip.
One tab stop. The cells of the grid form a single tab stop, so Tab reaches the grid once and the arrow keys walk it from there; the scene buttons on the left keep their own tab stops, one per row (see Launch the focused slot (Enter)).
Files arrive by drag and drop from a Finder window onto a cell (see Files: drag and drop).

The same grid exists on the iPad remote. It mirrors the desktop live and launches clips, stops and scenes, but it cannot load files, because the path of a file lives on the desktop machine (see Session grid of the remote).

Clip slot

One cell of the grid: the clip of one track and one scene, and the only place a clip starts. What a cell shows depends on the state the engine reports for that slot - there are four of them:

Empty - the snapshot does not list the slot: the cell is flat and shows nothing. Clicking it, or pressing Enter on it, does nothing at all: there is no clip to start, so no command is sent (the engine would answer not_found).
Stopped - the slot holds a clip that is not producing samples. The cell shows the file name of the clip without folder and extension and its length as m:ss.d (minutes, seconds, tenths).
Playing - the clip is producing samples, fade-in and fade-out included. The cell wears the accent colour while it runs, also while only its fade-out tail is still sounding.
Waiting for its start (armed) - the clip has been launched and is waiting for its quantisation boundary. The cell wears an accent outline and blinks until the engine starts the clip; the blink is the only thing that tells you the launch is still on its way. With reduce motion switched on, the outline stays and the blink is dropped.

How to use a slot:

Click the cell, or focus it and press Enter, to launch the clip (see Launch the focused slot (Enter)). A stopped slot is armed and starts at the next boundary, with a 5 ms fade-in.
A slot that is already playing is relaunched by the same gesture: the sounding material keeps playing until the boundary, then the clip starts again at frame 0 with a 5 ms fade-in and one start event - the slot never stopped producing samples, so there is no gap with a fade-out. A relaunch can therefore click at the boundary; that is a documented limitation, not a fault.
Launching a different clip of the same track stops the clip that is running there at the same boundary (see Session grid).
Stopping is the session-wide gesture: press Stop in the transport bar - the button works whenever the engine is reachable, so it also cancels an armed launch while the transport stands still. Space stops while the transport runs. Every clip that is producing samples then stops right away - its 5 ms fade-out begins with the next audio block, not at the quantisation boundary - and every armed launch is cancelled - a slot that was only waiting for its start never starts. A cell has no stop button of its own; on the iPad remote a tap on the slot does it (see below).
While the engine decodes a file into the slot the cell pulses (with reduce motion: a dashed border instead) and is announced as busy; the slot keeps its old content until the engine answers (see Files: drag and drop).
An occupied cell also carries the loop switch of its clip.

The cell is not a button in the sense of the rest of the window: it is what the arrow keys move inside the grid, and the controls inside it (the slot itself and its loop switch) stay operable with the mouse but hold no tab stop of their own. On the iPad remote a cell is tapped instead of clicked, and a tap on a slot that is playing or waiting stops it (a waiting slot is a launch that has not happened yet, so the tap cancels it).

Scene launch

The button at the left of every row, labelled Scene <n>: it starts the whole scene with one gesture (the command scene.launch). Every slot of that row that holds a clip is armed at the same quantisation boundary, in ascending track order, so the row enters together; a clip that is already playing on one of its tracks is relaunched at that boundary, and a clip of another scene that plays on one of its tracks is stopped at the same boundary (see Session grid).

Empty slots of the scene are left alone: they never stop what happens to be playing on their track. That is what makes a scene the safe way to start a song section - it only touches the tracks that actually hold a clip in that row, and an empty row is simply a no-op.

One press is one gesture: the auto-repeat of a held key is ignored, so a held Enter launches the scene once. A scene can also be launched from the keyboard: put the focus on the scene button (each row has its own tab stop) and press Enter (see Launch the focused slot (Enter)). Since a scene launch arms the row at the quantisation boundary, the silent slots of the row blink until the boundary. A slot that is already playing keeps its playing look during that time, because it keeps producing samples until it restarts at the boundary.

The iPad remote carries the same button per row: tap the play symbol with the scene number to launch that scene on the Mac (see Session grid of the remote).

Quantisation

The select in the header line of the session view (Quantisation, German: Quantisierung). It sets where a launch or a stop lands musically: not at the moment you click, but at the next boundary of the chosen length. MusicStation reckons in quarter notes and assumes a 4/4 bar, so the value is what the beat grid of a normal song expects. The seven values:

Off - no boundary is waited for: the gesture takes effect as soon as the engine applies it, which is the start of the next audio block. This is the setting for triggering things by hand and for material that already fits.
1/16 - the next sixteenth note. The tightest value, for one-shots and short re-triggers.
1/4 - the next quarter note, i.e. the next beat in 4/4.
1 bar - the next bar line, the value most songs are played with.
2 bars, 4 bars, 8 bars - the next multiple of that many bars. Use them when a section should enter on an even number of bars.

A fresh session reports Off: the engine waits for no boundary until you choose a value. The value belongs to the session, not to a device, so the desktop and the remote always show the same one.

What the value does and does not do:

It applies to clip launches, to the stop of a single slot and to scene launches. Stop in the transport bar is the exception: it stops the sounding clips right away instead of waiting for a boundary (see Clip slot).
It applies from the moment the engine applies the change. A launch that is already armed keeps the boundary it was armed at - choosing a new value never drags a waiting clip into a different beat.
A boundary can only be reached while the playhead moves, and the engine moves it while the transport runs. An armed launch, or the stop of a clip that is producing samples, therefore lands on its boundary during playback; with the transport stopped it is carried out right away only if the playhead already sits exactly on the chosen boundary - bar 1 after Enter, or any other boundary of the chosen value. Otherwise the slot stays armed and silent, and its cell keeps blinking until you start playback. Only cancelling an armed launch never waits for a boundary (see Clip slot). This is a limitation of this version.
The select shows the value the engine last reported. Choosing one shows it at once and sends session.setQuantization; if the engine rejects the command, the select jumps back and the header line shows the translated message (for example that the engine is busy).
The select is disabled while the interface is not connected to the engine.

The iPad remote has the same picker with the same seven values; it changes the quantisation for all clients, because the value belongs to the session, not to a device (see Session grid of the remote).

Loop

The switch inside every occupied clip slot, labelled Loop: it decides whether the clip wraps at its end or ends there. Each clip owns its own flag; there is no switch for an empty slot.

Loop on - the clip jumps from its last frame back to its first one. There is no fade at the loop point, so a clip that is cut to a whole number of bars loops seamlessly. The start event of the clip is emitted once and not on every pass, so the loop itself is silent in the protocol.
Loop off - the clip plays through once and stops at the end of its material: the slot fades out over 5 ms, stops by itself and afterwards reads stopped. The next launch starts at the first frame again.

A file that arrives by drag and drop is loaded with Loop on. The flag is engine state like every other value of the grid: your click is shown at once and sent with clip.setLoop, and a rejected command takes the switch back to the engine's answer. The engine uses the flag when the clip reaches its end, so flipping it while the clip plays decides what happens at the next end - not what already happened.

The switch is small and sits at the right edge of the cell; it is not a tab stop of its own, because the cells of the grid form one tab stop. Mouse: click it. Keyboard: put the focus on the slot and press L (see Loop of the focused slot (L)). The iPad remote has no loop switch in this version - a clip's loop flag is set on the desktop.

Files: drag and drop

A clip gets into a slot by dragging an audio file out of a Finder window and dropping it onto a cell of the grid. The addressed slot takes the file; the engine decodes it and the clip appears with its name and its length.

What happens on the way:

Drag one audio file over the grid. The slot under the pointer is marked with the accent ring, so you can see which cell you are aiming at. Moving within one cell does not flicker, and dragging outside the grid clears the mark again.
Let go over the cell. The path of the file is handed to the engine, which decodes the whole file before anything can play - the source is resampled to the sample rate of the engine on the way.
While the decode runs, the addressed cell pulses (with reduce motion: a dashed border) and is announced as busy. The slot keeps its previous content for that time, and the grid never shifts.
When the engine answers, the slot shows the new clip: the file name without folder and extension, its length as m:ss.d, and the loop switch - loaded with Loop on. Loading a slot that was playing stops it without a fade and without a stop event.

What the engine accepts, and what it refuses:

Formats: WAV, AIFF and FLAC. Anything else, a missing or unreadable file, more than two channels, more than five minutes of audio at the engine's sample rate, or a total of all loaded clips above 2 GiB is rejected. The header line of the session view then shows the translated message, e.g. that the audio file could not be loaded and that its format and length should be checked.
One file per slot per drop. If Finder hands several files to the grid at once, only the first one is loaded into the addressed slot; the others are ignored. To fill several slots, drop once per slot.
One decode per slot. A second drop onto a slot whose first file is still being decoded is ignored; a drop onto another slot runs in parallel.
A live connection. A drop while the interface is not connected to the engine does nothing, and the cell of a slot that is currently decoding cannot be loaded again.

Dropping a file needs the MusicStation application, not just a browser window: the path of the file has to be handed from the shell of the application to the engine, and a plain browser preview of the interface has no such connection, so a drop there does nothing. The iPad remote cannot load files at all, because it addresses a path on the machine that runs the engine (see Session grid of the remote).

Launch the focused slot (Enter)

Enter starts what the keyboard focus is on inside the grid: the clip of the focused clip slot, or the whole scene of a focused scene launch button. The key is the registered launch gesture of the grid, and the grid takes the press for itself, so the same key does not jump to bar 1 while the focus is inside the grid - that is what Enter does everywhere else in the window (see Position).

How to use it:

Tab reaches the grid once: the cells of the grid form one single tab stop, and the scene buttons on the left are separate tab stops, one per row. The focus ring shows which cell is active.
Arrow keys move the focus one cell at a time and wrap around the edges of the grid: right from the last track returns to the first, up from the first scene to the last. Home and End jump to the first and the last track of the row, PageUp and PageDown to the first and the last scene of the grid. These keys are consumed by the grid, so they do not scroll the page.
Enter launches. On a cell it is the same gesture as clicking the slot, on a scene button it is Scene launch. One press is one gesture: a held key does not launch again.
An empty slot is a no-op: the press is still taken by the grid (Enter does not jump to bar 1), but no command is sent. The same holds while the interface is not connected - the grid is disabled, a press changes nothing.
Space stays the transport's. On a focused cell Space still starts and stops playback (see Play/Stop (Space)) and does not launch the slot; F1 still opens the manual of the control under the pointer. The grid consumes only the keys that are its own.
L flips the loop flag of the focused slot (see Loop of the focused slot (L)).

The iPad remote has no keyboard: there a slot is started and stopped by tapping it (see Session grid of the remote).

Loop of the focused slot (L)

L (lower case l as well as upper case L, so CapsLock does not matter) flips the loop switch of the clip slot the focus is on: the engine receives clip.setLoop with the negated flag. The key exists because the loop switch of a cell is not a tab stop of its own - the cells of the grid form a single tab stop - so this is how the keyboard reaches it.

The focus has to be inside the grid and on an occupied slot. On an empty slot, or while the interface is not connected to the engine, the press changes nothing.
One press is one flip: a held key does not toggle the flag back and forth.
The effect is the same as clicking the switch, including the immediate reaction and the rollback when the engine rejects the command (see Loop).
The press belongs to the grid, so nothing else in the window reacts to it.

The iPad remote has no loop switch in this version, so it has no equivalent of this key either (see Session grid of the remote).

Workflow: load a clip and launch it

Open the MusicStation application (not a browser preview - only the application can hand a dropped file to the engine, see Files: drag and drop).
Drag a WAV, AIFF or FLAC file out of a Finder window onto the cell of Track 1, Scene 1. The cell is marked while the file hovers over it; the slot pulses while the engine decodes it.
Wait until the pulse stops: the slot now shows the file name and the length of the clip, and its Loop switch is on.
Pick the launch quantisation in the header line of the session view, for example 1 bar (see Quantisation).
Press Tab until the grid has the focus, walk to the cell with the arrow keys and press Enter
- or simply click the slot. The cell starts to blink: the clip is armed.
Start playback with Space if the transport is not running yet: the clip starts at its boundary (right away, while the stopped playhead still sits on bar 1) and the cell wears the accent colour while it plays. Space again stops playback - the sounding clips stop with it (see Clip slot).
Fill the other slots of the first scene the same way and press Enter on the Scene 1 button (or the button itself) to start the whole row in one gesture (see Scene launch).