SPB Git

Repository Public

midi.md 8.6 KB

# MIDI Integration

A MIDI controller and a script meet in one place: the automation triggers. A script does not read MIDI. It reacts to sixteen numbered triggers, and you decide in the MIDI mapping which pad, button or key fires each one. This keeps scripts independent of hardware: the same script works with any controller, the keyboard or the console.

# The model

text
pad or button  →  MIDI mapping  →  target "automation.trigger.3"  →  on trigger(3) { … } in every running automation
  1. In the MIDI mapping, a control is assigned to a target. Targets are the things a control can drive: a fader, a play button, an automation trigger.
  2. When you press the pad, ORIX DJ fires trigger 3.
  3. Every running automation that has registered on trigger(3) runs that handler.

# Reacting to a trigger in a script

orixdj
automation "Pad Effects" {
    on trigger(1) {
        fx.echo.mix = 0.7
        fx.echo.enable()
        wait 1 beat
        fx.echo.mix = 0
    }
    on trigger(2) {
        fx.echo.disable()
        stop
    }
}

Start this automation and leave it running. Pad 1 throws one beat into the echo each time it is hit. Pad 2 switches the echo off and ends the automation.

Rules:

  • Triggers are numbered 1 to 16. on trigger(0) or on trigger(17) is an error (E-RANGE).
  • A trigger carries no value: no velocity, no pressure, no position. It only says "now".
  • A trigger is delivered to all running automations. Two automations may both listen to trigger 1.
  • A trigger fired when nothing listens is ignored. It is not kept for an automation started later.
  • A handler exists from the moment its on statement runs. Start the automation before you need the pad.
  • A paused automation does not receive triggers.
  • The handler runs at the next scheduler step after the press, a few milliseconds later. It is not quantized. To land on the grid, wait inside the handler:
orixdj
on trigger(1) {
    wait nextBeat                 // or: wait nextBar
    deck.A.loop(1 beat)
    wait 1 bar
    deck.A.loopExit()
}
wait 16 bars
stop

See Events for everything about handlers.

# Other ways to fire a trigger

  • The console: trigger 3.
  • A keyboard shortcut assigned to the target "Automation trigger 3".
console
> trigger 3
Trigger 3 fired

They are equivalent to the pad. This is convenient for rehearsing a pad routine without the controller.

# Mappable targets

A MIDI mapping assigns a control to a target identifier. These are the targets of this version.

# Automation

Target Kind Effect
automation.trigger.1 … automation.trigger.16 trigger Fires the automation trigger of that number
automation.panic trigger Emergency stop: stops every automation and bypasses every effect

Map automation.panic to a button you can find without looking. It is the fastest way out of a script that misbehaves.

# Per deck (X = A, B, C, D)

Target Kind Effect
deck.X.play trigger Play / pause
deck.X.cue trigger Cue
deck.X.setCue trigger Set the cue point
deck.X.sync toggle Sync
deck.X.keylock toggle Key lock
deck.X.quantize toggle Quantize
deck.X.reverse toggle Reverse
deck.X.cueMonitor toggle Headphone cue (the script path is deck.X.cue)
deck.X.volume value Channel fader
deck.X.gain value Trim
deck.X.eq.high, deck.X.eq.mid, deck.X.eq.low value EQ bands
deck.X.filter value Filter knob
deck.X.tempo value Tempo fader, ±8 % (moving it switches sync off)
deck.X.keyShift value Key shift
deck.X.loopExit, deck.X.loopHalve, deck.X.loopDouble trigger Loop controls
deck.X.loop.1, .2, .4, .8, .16 trigger Loop of that many beats
deck.X.jump.-4, .-1, .1, .4 trigger Beat jump
deck.X.hotcue.1 … deck.X.hotcue.8 trigger Hot cue pad: stores the position when empty, jumps to it when set
deck.X.brake trigger Tape stop

# Mixer

Target Kind
mixer.crossfader value
mixer.master.volume value
mixer.cue.mix value
mixer.cue.volume value
mixer.master.limiter toggle

# Master effects

For each effect of the master rack (reverb, delay, echo, flanger, phaser, chorus, distortion, bitcrusher, highpass, lowpass, bandpass, tremolo, autopan, gate, compressor, limiter, beatrepeat, noise):

Target Kind
fx.<effect>.enabled toggle
fx.<effect>.mix value

# Kinds and mapping modes

Kind What the control does
value Sets a position from 0 to 1, scaled to the range of the control (faders follow a fader law, frequencies are logarithmic)
toggle Flips a switch
trigger Does something once per press

A mapping also has a mode that says how the hardware control behaves: absolute (fader or knob), relative (endless encoder), toggle, trigger or momentary (active while held). A control is identified by its kind (note, cc or pitchBend), its MIDI channel (0 to 15) and its number (0 to 127).

Most target identifiers look like script paths, and most address the same control as the path. Three do not exist as script paths: deck.X.tempo, deck.X.cueMonitor, and the numbered forms such as deck.X.loop.4. Conversely, a script can reach many things that have no direct MIDI target, such as the parameters of channel effects. That is exactly what triggers are for.

# What scripts can and cannot do with MIDI

A script can A script cannot
React to triggers 1…16 Read notes, velocities, control changes or pitch bend
Do anything in the handler: effects, loops, transitions Know which device or pad fired the trigger
Wait for the grid inside the handler Receive a value from a knob or fader
Run alongside your hands on the same controller Send MIDI: light pads, move motor faders, send clock
Create or change MIDI mappings

If you need a knob to control "how much", map the knob to a real parameter (for example fx.echo.mix) and let the script read that parameter:

orixdj
on trigger(1) {
    let amount = fx.echo.mix          // the knob mapped to fx.echo.mix sets the amount
    fx.echo.feedback = 0.3 + amount * 0.5
    fx.echo.enable()
    wait 2 bars
    fx.echo.disable()
}
wait 16 bars
stop

# Hands and scripts on the same control

A fader moved by hand and a script writing the same control do not lock each other out: each change takes effect when it arrives. While a script ramps a control, the ramp writes it at every scheduler step, so a hand movement on that control is overwritten almost at once until the ramp ends. If you want to take over, stop the automation (or hit the emergency stop), then move the control.

# Pad layouts that work well

Scripts that listen to pads usually run for the whole set. A few conventions make them easier to live with:

  • Keep one long-running "pads" automation rather than several; you can see all the assignments in one file.
  • Give each handler a self-contained move that puts back what it changed.
  • Use a variable as a "busy" flag when a pad should not be re-triggered while its move is in progress.
  • Reserve one pad for a handler that restores the controls the others touch.
orixdj
automation "Pads" {
    var busy = false

    on trigger(1) {                     // filter drop for one bar
        if not busy {
            busy = true
            wait nextBar
            deck.A.filter.highpass = 400Hz
            wait 1 bar
            deck.A.filter.highpass = 20Hz
            busy = false
        }
    }

    on trigger(2) {                     // reverb swell into the next bar
        fx.reverb.mix = 0
        fx.reverb.enable()
        over 1 bar curve easeIn { fx.reverb.mix -> 0.6 }
        fx.reverb.mix = 0
        fx.reverb.disable()
    }

    on trigger(16) {                    // put everything back and quit
        deck.A.filter.highpass = 20Hz
        fx.reverb.disable()
        stop
    }
}

# Asking Claude Studio for a mapping

Claude Studio has a task for creating a MIDI mapping from a description of your controller. The answer is a mapping profile, not a script: a list of controls with a target and a mode each. ORIX DJ checks it locally before offering it: mappings to targets that do not exist are removed and listed, and the profile is validated. Nothing is applied without your decision.

Files main
Menu

Theme