Surface scripts

A surface script teaches TuttiDAW a MIDI controller it does not know. It reads the controller's messages, answers with commands and keeps its lights in step with the song.

What a surface script is

A surface script is one plain JavaScript file that calls defineSurface(). It says which MIDI ports it needs, which incoming messages belong to the controller, what to do when one arrives and what the controller's lights should show.

The script runs in a sandbox: a Web Worker inside an isolated frame. It cannot reach the network, load other code, read the page or touch your projects. It never edits the song directly: it sees a read-only snapshot of the state and returns commands, and TuttiDAW checks every command before it runs it.

Make one in the editor

  1. Open Settings (Ctrl+, or Cmd+,), go to Link, Tempo & MIDI and find the Control Surface table.
  2. Choose Edit scripts… under the table, or New script… in a row's type chooser. A new script starts from a commented footswitch template.
  3. Write the script. Saving (Ctrl+S or Cmd+S) checks it and reloads every row that runs it. If the new version fails, the row stays off and the error is shown with its line and column when they are known.
  4. Choose the script as a row's type, then pick the controller's input and output ports in that row.
  5. Watch the MIDI monitor (the messages coming in and going out on the row's ports) and the console (the script's console.log lines, its errors and why it was stopped) while you play the controller.

When you are signed in, your scripts are saved in your account and follow you to any computer. When you are signed out, they are kept in this browser; the first time you sign in, TuttiDAW asks whether to copy them into your account. Import .js and Export .js move a script in and out as a file.

API v1

Everything goes through defineSurface(). Its object has these fields:

  • id: lowercase letters, digits and dashes (64 characters at most).
  • name: what the Control Surface table shows (80 characters at most).
  • apiVersion: 1. A script written for another version is refused with a message that says so.
  • ports: one to four ports, each with a role (main, ext1…), kind: 'midi', input, output and required. sysex: true asks for System Exclusive.
  • match.portName: a hint for which port the controller usually has. The row's ports are always the ones you choose.
  • consume: the incoming messages that belong to the controller, by role, status byte and optional first data byte (each a value or a [low, high] range). They do not reach your tracks. TuttiDAW decides this itself from the list, without asking the script.
  • params: the parameters the snapshot holds: remote targets, or @bank (the controlled device's bank), @mixer (the selected track) and @master. A script can only change parameters that are in its snapshot.
  • onInput(input, snapshot): called for each message on an input role. Return an array of commands (an empty one does nothing).
  • render(snapshot): returns the desired feedback state: an object whose midi field lists, for each output role, the messages to show as [status, data1, data2]. TuttiDAW compares it with what it sent before and sends only the changes.

Both functions are synchronous. A promise counts as no answer.

The snapshot

The snapshot is a frozen object: apiVersion and revision; transport (playing, recording, tempo); tracks (id, name, color, selected, muted, solo, armed, armable); params (by target: label, travel, position, text, and options and bipolar when they apply); bank (the @bank targets in knob order); and grid (the clip slots inside the ring the script set with setRing, or null).

Commands

Commands are a closed list. Anything else, or a command with a wrong field, is dropped and counted.

  • Parameters: writeParam (a target and a 0–1 travel) and moveParam (an absolute position or a relative encoder step).
  • Transport: togglePlay, toggleRecord and setTransport.
  • Tracks and devices: setTrackState, selectTrack, selectTrackId, selectDevice and toggleDeviceOn.
  • Buttons: press and edge, for the global and track controls a remote mapping can press.
  • Session View: clipEdge, fireScene, stopTrack and setRing.
  • Notes and MIDI: note plays a note into the role's note input, and send sends one MIDI message out of a role.
{ op: 'writeParam', target: 'track:<id>:volume', travel: 0.8 }
{ op: 'moveParam', target: snapshot.bank[0], key: 'knob1', move: { kind: 'relative', encoding: 'twosComplement', value: 1 } }
{ op: 'toggleRecord' }
{ op: 'setTransport', playing: true }
{ op: 'selectTrack', direction: 1 }
{ op: 'send', role: 'main', data: [0xb0, 80, 127] }

Feedback and send

Use render for state that can be replaced, like a lit button or a ring of LEDs. Use the send command for one-time messages, such as a greeting to the controller when it starts.

Output goes only to the port you chose for that role in the row. With Output set to None, nothing is sent. System Exclusive is sent only after you allow it for the script, and you are asked again when the script changes.

Limits

The limits keep a buggy or hostile script from slowing down the editor. A script that breaks them has its messages dropped, or is stopped and its row shows why.

  • Source: 256 KB per script, 100 scripts per account.
  • Inputs: 32 waiting for an answer; more are dropped.
  • Commands: 64 per answer, 200 per second.
  • MIDI output: 1,000 messages per second; a render state holds up to 512 entries.
  • Parameters: 64 in a snapshot.
  • Watchdog: the script must start within 5 seconds, answer a render within 1 second and answer the heartbeat within 2 seconds.
  • Console: lines are rate-limited and only the latest ones are kept.

Example: a footswitch

This script turns a footswitch that sends CC 80 into a record button. A press toggles Arrangement Record, and the footswitch's LED shows whether TuttiDAW is recording.

export default defineSurface({
  id: 'my-footswitch',
  name: 'My Footswitch',
  apiVersion: 1,
  // one MIDI port pair, called "main"
  ports: [{ role: 'main', kind: 'midi', input: true, output: true, required: true }],
  // a hint: the port the footswitch usually has
  match: { portName: 'FS-4' },
  // CC 80 on channel 1 is the footswitch's, not the tracks'
  consume: [{ role: 'main', status: 0xb0, data1: 80 }],
  onInput(input, snapshot) {
    const [status, cc, value] = input.data;
    // a press (value > 0) toggles Arrangement Record; the release does nothing
    if (status === 0xb0 && cc === 80 && value > 0) {
      console.log('footswitch pressed');
      return [{ op: 'toggleRecord' }];
    }
    return [];
  },
  render(snapshot) {
    // the LED: CC 80 back to the footswitch, lit while recording
    const on = snapshot && snapshot.transport.recording;
    return { midi: { main: [[0xb0, 80, on ? 127 : 0]] } };
  },
});

To try it, save it, choose My Footswitch as a row's type and pick the footswitch's ports. Press the switch and watch the monitor: CC 80 comes in, and the LED message goes out.

Open the studio and write a script for your controller.

Scopri TuttiDAW - la workstation audio online, senza registrazione per iniziare