MIDI Remote API

https://steinbergmedia.github.io/midiremote_api_doc
Admin
The Steinberg MIDI Remote API allows developers to create scripts that bridge MIDI controller...
Tokens:52,682
Snippets:283
Trust Score:8.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Example MIDI Remote API Script File Path

Source: https://steinbergmedia.github.io/midiremote_api_doc/getting-started

Illustrates a concrete example of a MIDI Remote API script file path based on the defined structure.

```plaintext
<Driver Scripts Folder>/Local/Nektar/Impact_LX49Plus/Nektar_Impact_LX49Plus.js  

```

--------------------------------

### Simple Device Driver Setup

Source: https://steinbergmedia.github.io/midiremote_api_doc/online-ide

Initializes the device driver, MIDI input, and output ports for a simple device.

```javascript
//-----------------------------------------------------------------------------
// 1. DRIVER SETUP
//-----------------------------------------------------------------------------
var midiremote_api = require('midiremote_api_v1')
var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'SimpleDevice', 'Steinberg Media Technologies GmbH')
var midiInput = deviceDriver.mPorts.makeMidiInput('SimpleDevice IN')
var midiOutput = deviceDriver.mPorts.makeMidiOutput('SimpleDevice OUT')
```

--------------------------------

### MIDI Remote API Driver Setup

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/simpledevice

Initializes the device driver, MIDI ports, and defines port detection logic for a fictional MIDI controller.

```javascript
//-----------------------------------------------------------------------------
// 1. DRIVER SETUP - create driver object, midi ports and detection information
//-----------------------------------------------------------------------------

// get the api's entry point
var midiremote_api = require('midiremote_api_v1')

// create the device driver main object
var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'SimpleDevice', 'Steinberg Media Technologies GmbH')

// create objects representing the hardware's MIDI ports
var midiInput = deviceDriver.mPorts.makeMidiInput()
var midiOutput = deviceDriver.mPorts.makeMidiOutput()

// define all possible names the device's MIDI ports could have
// NOTE: Windows and macOS handle port naming differently
deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('SimpleDevice IN')
    .expectOutputNameEquals('SimpleDevice OUT')

deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('SimpleDevice (MIDI IN)')
    .expectOutputNameEquals('SimpleDevice (MIDI OUT)')

```

--------------------------------

### Create Detection Unit

Source: https://steinbergmedia.github.io/midiremote_api_doc/api-details/detection-unit

Demonstrates how to create a Detection Unit object, which is the starting point for defining the MIDI device detection process.

```APIDOC
## Create Detection Unit

### Description
This operation shows how to instantiate a Detection Unit using a device driver object. The Detection Unit is essential for defining how MIDI devices and their ports are automatically identified.

### Method
```javascript
const detectionUnit = deviceDriver.makeDetectionUnit()
```

### Parameters
This method does not take any parameters directly but operates on the `deviceDriver` object.

### Request Example
```javascript
var midiremote_api = require('midiremote_api_v1')
var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'SimpleDevice', 'Steinberg Media Technologies GmbH')
const detectionUnit = deviceDriver.makeDetectionUnit()
```

### Response
- **detectionUnit** (object) - An object representing the newly created detection unit.
```

--------------------------------

### Create a Detection Unit - JavaScript

Source: https://steinbergmedia.github.io/midiremote_api_doc/api-details/detection-unit

Initializes the device driver and creates a Detection Unit object. This is the starting point for defining device detection logic.

```javascript
var midiremote_api = require('midiremote_api_v1')  
  
// create the device driver main object  
var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'SimpleDevice', 'Steinberg Media Technologies GmbH')  
  
const detectionUnit = deviceDriver.makeDetectionUnit()
```

--------------------------------

### MIDI Remote API Driver Setup

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Sets up the MIDI Remote API driver, defines MIDI input and output ports, and configures device detection for multiple port pairs.

```javascript
//-----------------------------------------------------------------------------
// 0. INCLUDE common functions
//-----------------------------------------------------------------------------
var helper = require('./helper')

//-----------------------------------------------------------------------------
// 1. DRIVER SETUP - create driver object, midi ports and detection information
//-----------------------------------------------------------------------------

var midiremote_api = require('midiremote_api_v1')

var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'RealWorldDevice', 'Steinberg Media Technologies GmbH')

var midiInput = deviceDriver.mPorts.makeMidiInput()
var midiOutput = deviceDriver.mPorts.makeMidiOutput()

deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('RealWorld In')
    .expectOutputNameEquals('RealWorld Out')

deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('MIDIIN (RealWorld)')
    .expectOutputNameEquals('MIDIOUT (RealWorld)')

deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('MIDIIN (RealWorld) 2')
    .expectOutputNameEquals('MIDIOUT (RealWorld) 2')

deviceDriver.makeDetectionUnit().detectPortPair(midiInput, midiOutput)
    .expectInputNameEquals('MIDIIN (RealWorld) 3')
    .expectOutputNameEquals('MIDIOUT (RealWorld) 3')

var surface = deviceDriver.mSurface
```

--------------------------------

### Transport Controls Setup

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Initializes the transport controls section of the device layout, defining its position and dimensions.

```javascript
function makeTransport(x, y) {
    var transport = {}

    var w = 2
    var h = 2

    var currX = x
```

--------------------------------

### Create Command Bindings for Buttons

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/commandbindings

This snippet demonstrates how to create buttons on the surface and bind them to specific host commands like 'Undo' and 'Redo'. It's part of the driver setup, surface layout, and host mapping process.

```javascript
var midiremote_api = require('midiremote_api_v1')
var deviceDriver = midiremote_api.makeDeviceDriver('ExampleCompany', 'CommandButtonDevice', 'Steinberg Media Technologies GmbH')

// ...

var button1 = deviceDriver.mSurface.makeButton(0, 0, 2, 1)
var button2 = deviceDriver.mSurface.makeButton(2, 0, 2, 1)
var button3 = deviceDriver.mSurface.makeButton(4, 0, 2, 1)

// ...

var page = deviceDriver.mMapping.makePage('Main Page')

page.makeCommandBinding(button1.mSurfaceValue, 'Edit', 'Undo')
page.makeCommandBinding(button2.mSurfaceValue, 'Edit', 'Redo')
page.makeCommandBinding(button3.mSurfaceValue, /*[PLACE TO PASTE COPIED SNIPPET]*/)
```

--------------------------------

### StartValue

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Indicates if transport has been started. It provides callbacks for value, display, title, and color changes, and supports increment/decrement operations.

```APIDOC
## StartValue

### Description
Indicates if transport has been started. It provides callbacks for value, display, title, and color changes, and supports increment/decrement operations.

### Properties
* **mOnProcessValueChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , value : _number_)
* **mOnDisplayValueChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , value : _string_ , units : _string_)
* **mOnTitleChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , objectTitle : _string_ , valueTitle : _string_)
* **mOnColorChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , r : _number_ , g : _number_ , b : _number_ , a : _number_ , isActive : _boolean_)

### Methods
* **increment**(**activeMapping** : _ActiveMapping_)
* **decrement**(**activeMapping** : _ActiveMapping_)
```

--------------------------------

### Get Host Application Version String

Source: https://steinbergmedia.github.io/midiremote_api_doc/new_in_v1.2

Retrieve the host application's version string using `getVersionString()` from `mDefaults.mAppVersion`. Ensure the necessary properties exist before calling.

```javascript
if (midiremote_api.mDefaults && midiremote_api.mDefaults.mAppVersion && midiremote_api.mDefaults.mAppVersion.getVersionString) {  
    var hostVersion = midiremote_api.mDefaults.mAppVersion.getVersionString()  
    console.log('Host version: ' + hostVersion)  
}  

```

--------------------------------

### MixerBankZone Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Provides methods to include or exclude various channel types from a mixer bank zone, set follow visibility, create mixer bank channels, and get runtime IDs.

```APIDOC
## MixerBankZone Methods

### Description
Methods for configuring and managing mixer bank zones.

### Methods
* **includeAudioChannels**() : _this_
* **includeInstrumentChannels**() : _this_
* **includeSamplerChannels**() : _this_
* **includeMIDIChannels**() : _this_
* **includeFXChannels**() : _this_
* **includeGroupChannels**() : _this_
* **includeVCAChannels**() : _this_
* **includeInputChannels**() : _this_
* **includeOutputChannels**() : _this_
* **includeWindowZoneMainChannels**() : _this_
* **includeWindowZoneLeftChannels**() : _this_
* **includeWindowZoneRightChannels**() : _this_
* **excludeAudioChannels**() : _this_
* **excludeInstrumentChannels**() : _this_
* **excludeSamplerChannels**() : _this_
* **excludeMIDIChannels**() : _this_
* **excludeFXChannels**() : _this_
* **excludeGroupChannels**() : _this_
* **excludeVCAChannels**() : _this_
* **excludeInputChannels**() : _this_
* **excludeOutputChannels**() : _this_
* **excludeWindowZoneMainChannels**() : _this_
* **excludeWindowZoneLeftChannels**() : _this_
* **excludeWindowZoneRightChannels**() : _this_
* **setFollowVisibility**(**followVisibility** : _boolean_) : _this_
* **makeMixerBankChannel**() : _MixerBankChannel_
* **getRuntimeID**(**activeMapping** : _ActiveMapping_) : _number_
```

--------------------------------

### Direct Access Feature Check

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

Guard script usage with feature checks if your script still supports older host versions. This example shows how to check for the availability of the makeDirectAccess method.

```javascript
var driver = midiremote_api.makeDeviceDriver('ExampleCompany', 'DirectAccessDevice', 'Example Author')  
var page = driver.mMapping.makePage('Main')  
var hostObject = page.mHostAccess.mTrackSelection.mMixerChannel  
if (page.mHostAccess.makeDirectAccess) {  
  var da = page.mHostAccess.makeDirectAccess(hostObject)  
}
```

--------------------------------

### Query Mixer Channel Properties via DirectAccess

Source: https://steinbergmedia.github.io/midiremote_api_doc/new_in_v1.2

Use DirectAccess helper methods like `isMixerChannelVisible`, `getMixerChannelIndex`, and `getMixerChannelZone` to get information about mixer channels.

```javascript
var objectID = da.getBaseObjectID(activeMapping)  
  
var isVisible = da.isMixerChannelVisible(activeMapping, objectID)  
var channelIndex = da.getMixerChannelIndex(activeMapping, objectID)  
var channelZone = da.getMixerChannelZone(activeMapping, objectID)  
console.log('visible=' + isVisible + ', index=' + channelIndex + ', zone=' + channelZone)  

```

--------------------------------

### Create Mixer Page with Channel Bindings

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Sets up a 'Mixer' page, including sub-pages for volume, pan, and send levels, and binds various surface elements to mixer channel parameters.

```javascript
function makePageMixer() {
    var page = makePageWithDefaults('Mixer')

    var knobSubPageArea = page.makeSubPageArea('Knobs')

    var subPageVolume = makeSubPage(knobSubPageArea, 'Volume')
    var subPagePan = makeSubPage(knobSubPageArea, 'Pan')

    var subPageListSendLevel = []

    var numSendLevelSubPages = midiremote_api.mDefaults.getNumberOfSendSlots ()
    for(var subPageIdx = 0; subPageIdx < numSendLevelSubPages; ++subPageIdx) {
        var nameSubPage = 'Send Level ' + (subPageIdx + 1).toString()
        var subPageSendLevel = makeSubPage(knobSubPageArea, nameSubPage)
        subPageListSendLevel.push(subPageSendLevel)
    }

    var hostMixerBankZone = page.mHostAccess.mMixConsole.makeMixerBankZone()
        .excludeInputChannels()
        .excludeOutputChannels()

    page.makeActionBinding(surfaceElements.btn_prevChannelBank.mSurfaceValue, hostMixerBankZone.mAction.mPrevBank)
    page.makeActionBinding(surfaceElements.btn_nextChannelBank.mSurfaceValue, hostMixerBankZone.mAction.mNextBank)

    page.makeActionBinding(surfaceElements.btn_prevBinding.mSurfaceValue, knobSubPageArea.mAction.mPrev)
    page.makeActionBinding(surfaceElements.btn_nextBinding.mSurfaceValue, knobSubPageArea.mAction.mNext)

    function bindChannelBankItem(index) {
        var channelBankItem = hostMixerBankZone.makeMixerBankChannel()

        var knobValue = surfaceElements.knobStrips[index].knob.mSurfaceValue
        var selectedButtonValue = surfaceElements.knobStrips[index].button.mSurfaceValue

        var muteValue = surfaceElements.faderStrips[index].btnMute.mSurfaceValue
        var soloValue = surfaceElements.faderStrips[index].btnSolo.mSurfaceValue
        var faderValue = surfaceElements.faderStrips[index].fader.mSurfaceValue

        page.makeValueBinding (knobValue, channelBankItem.mValue.mVolume).setSubPage(subPageVolume)
        page.makeValueBinding (knobValue, channelBankItem.mValue.mPan).setSubPage(subPagePan)

        for(var subPageIdx = 0; subPageIdx < numSendLevelSubPages; ++subPageIdx) {
            var sendLevel = channelBankItem.mSends.getByIndex(subPageIdx).mLevel
            var subPage = subPageListSendLevel[subPageIdx]
            page.makeValueBinding (knobValue, sendLevel).setSubPage(subPage)
        }

        page.makeValueBinding (selectedButtonValue, channelBankItem.mValue.mSelected)

        page.makeValueBinding (muteValue, channelBankItem.mValue.mMute).setTypeToggle()
        page.makeValueBinding (soloValue, channelBankItem.mValue.mSolo).setTypeToggle()
        page.makeValueBinding (faderValue, channelBankItem.mValue.mVolume)
    }

    for(var i = 0; i < 8; ++i)
        bindChannelBankItem(i)

    return page
}
```

--------------------------------

### Create Selected Track Page with Quick Controls

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Sets up a 'Selected Track' page and binds surface knobs to the quick controls of the currently selected track.

```javascript
function makePageSelectedTrack() {
    var page = makePageWithDefaults('Selected Track')

    var selectedTrackChannel = page.mHostAccess.mTrackSelection.mMixerChannel

    for(var idx = 0; idx < surfaceElements.knobStrips.length; ++idx)
        page.makeValueBinding (surfaceElements.knobStrips[idx].knob.mSurfaceValue, selectedTrackChannel.mQuickControls.getByIndex(idx))
      
    return page
}
```

--------------------------------

### API 1.3+ Method Availability Check

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

For API 1.3 additions, check method availability before calling. This example demonstrates checking for the getParameterProcessValueType method.

```javascript
if (da.getParameterProcessValueType) {  
  // API 1.3+ method usage  
}
```

--------------------------------

### SurfaceCustomValueVariable

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Represents a continuous value state of a SurfaceElement. It allows for setting and getting process and display values, and handling changes in value, title, and color.

```APIDOC
## SurfaceCustomValueVariable

### Description
Represents a continuous value state of a SurfaceElement. It inherits from _SurfaceValue_ and is referenced by _Surface_, _ValueBinding_, _CommandBinding_, and _ActionBinding_.

### Properties
* **mMidiBinding** : _SurfaceValueMidiBinding_
* **mOnProcessValueChange** : _function_ (activeDevice : _ActiveDevice_ , value : _number_ , diff : _number_)
* **mOnDisplayValueChange** : _function_ (activeDevice : _ActiveDevice_ , value : _string_ , units : _string_)
* **mOnTitleChange** : _function_ (activeDevice : _ActiveDevice_ , objectTitle : _string_ , valueTitle : _string_)
* **mOnColorChange** : _function_ (activeDevice : _ActiveDevice_ , r : _number_ , g : _number_ , b : _number_ , a : _number_ , isActive : _boolean_)
* **mTouchState** : _SurfaceValueTouchState_

### Methods
* **setProcessValue**(**activeDevice** : _ActiveDevice_ , **value** : _number_) : void
* **getProcessValue**(**activeDevice** : _ActiveDevice_) : _number_
* **setDisplayValue**(**activeDevice** : _ActiveDevice_ , **value** : _string_) : void
* **getDisplayValue**(**activeDevice** : _ActiveDevice_) : _string_
```

--------------------------------

### QuickControls Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Methods for interacting with Quick Controls.

```APIDOC
## QuickControls

### Properties

* **mOnTitleChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , title : _string_)
* **mOnColorChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , r : _number_ , g : _number_ , b : _number_ , a : _number_ , isActive : _boolean_)

### Methods

* **getByIndex**(**index** : _number_) : _QuickControlValue_
  * Description: Retrieves a QuickControlValue by its index.
* **getSize**() : _number_
  * Description: Returns the total number of Quick Controls.
* **getRuntimeID**(**activeMapping** : _ActiveMapping_) : _number_
  * Description: Retrieves the runtime ID for the given active mapping.
```

--------------------------------

### Initialize DirectAccess Core API

Source: https://steinbergmedia.github.io/midiremote_api_doc/new_in_v1.2

Use `makeDirectAccess` to enable DirectAccess for a host object. Guard this call with a feature check for compatibility with older API versions.

```javascript
var driver = midiremote_api.makeDeviceDriver('ExampleCompany', 'DA Device', 'Example Author')  
var page = driver.mMapping.makePage('DA Core')  
var hostObject = page.mHostAccess.mTrackSelection.mMixerChannel  
  
if (page.mHostAccess.makeDirectAccess) {  
    var da = page.mHostAccess.makeDirectAccess(hostObject)  
  
    page.mOnActivate = function (activeDevice, activeMapping) {  
        da.activate(activeMapping)  
  
        var rootObjectID = da.getBaseObjectID(activeMapping)  
        var childCount = da.getNumberOfChildObjects(activeMapping, rootObjectID)  
        console.log('DA root child count = ' + childCount)  
    }  
  
    page.mOnDeactivate = function (activeDevice, activeMapping) {  
        da.deactivate(activeMapping)  
    }  
}  

```

--------------------------------

### HostAction Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Abstract class for host actions, with concrete implementations for specific actions.

```APIDOC
## HostAction

### Description
Abstract class for host actions, with concrete implementations for specific actions.

## HostPluginParameterBankZoneAction

### Description
Represents an action to trigger a host plugin parameter bank zone.

### Methods
* **trigger**(**activeMapping** : _ActiveMapping_)

## HostInsertEffectViewerAction

### Description
Represents an action to trigger a host insert effect viewer.

### Methods
* **trigger**(**activeMapping** : _ActiveMapping_)

## MixerBankZoneAction

### Description
Represents an action to trigger a mixer bank zone.

### Methods
* **trigger**(**activeMapping** : _ActiveMapping_)
```

--------------------------------

### Create and Wire DirectAccess Instance

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

This snippet demonstrates how to create a DirectAccess instance for a host object and manage its activation and deactivation within the page lifecycle. Use this for API version 1.2 and later.

```javascript
var driver = midiremote_api.makeDeviceDriver('ExampleCompany', 'DirectAccessDevice', 'Example Author')
var page = driver.mMapping.makePage('DirectAccess Page')
var hostObject = page.mHostAccess.mTrackSelection.mMixerChannel

// API 1.2+
if (page.mHostAccess.makeDirectAccess) {
  var da = page.mHostAccess.makeDirectAccess(hostObject)

  page.mOnActivate = function (activeDevice, activeMapping) {
    da.activate(activeMapping)
  }

  page.mOnDeactivate = function (activeDevice, activeMapping) {
    da.deactivate(activeMapping)
  }
}
```

--------------------------------

### Surface Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Methods for emulating hardware surface elements like buttons, knobs, and faders.

```APIDOC
## Surface
> Emulates hardware surface elements.
Referenced by: _DeviceDriver_
**Methods**
  * **makePushEncoder**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _PushEncoder_
  * **makeKnob**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _Knob_
  * **makeFader**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _Fader_
  * **makeButton**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _Button_
  * **makeModWheel**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _ModWheel_
  * **makePitchBend**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _PitchBend_
  * **makeTriggerPad**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _TriggerPad_
  * **makePadXY**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _PadXY_
  * **makeJoyStickXY**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _JoyStickXY_
  * **makeLamp**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _Lamp_
  * **makeBlindPanel**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _BlindPanel_
  * **makePianoKeys**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_ , **firstKeyIndex** : _number_ , **lastKeyIndex** : _number_) : _PianoKeys_
  * **makeLabelField**(**x** : _number_ , **y** : _number_ , **w** : _number_ , **h** : _number_) : _SurfaceLabelField_
  * **makeControlLayerZone**(**name** : _string_) : _ControlLayerZone_
  * **makeCustomValueVariable**(**name** : _string_) : _SurfaceCustomValueVariable_
```

--------------------------------

### Get Runtime ID of Selected Host Object

Source: https://steinbergmedia.github.io/midiremote_api_doc/new_in_v1.2

Obtain the runtime ID of the currently selected host object, such as a mixer channel, using the `getRuntimeID` method. This is useful for runtime-specific operations.

```javascript
var selectedChannel = page.mHostAccess.mTrackSelection.mMixerChannel  
  
page.mOnActivate = function (activeDevice, activeMapping) {  
    var runtimeID = selectedChannel.getRuntimeID(activeMapping)  
    console.log('Selected channel runtime ID: ' + runtimeID)  
}  

```

--------------------------------

### Host Mapping for Mixer Controls

Source: https://steinbergmedia.github.io/midiremote_api_doc/online-ide

Creates a mixer page and binds surface knobs to host track volume and send levels.

```javascript
//-----------------------------------------------------------------------------
// 3. HOST MAPPING
//-----------------------------------------------------------------------------
var page = deviceDriver.mMapping.makePage('Example Mixer Page')
var selectedTrackChannel = page.mHostAccess.mTrackSelection.mMixerChannel
page.makeValueBinding(knob1.mSurfaceValue, selectedTrackChannel.mValue.mVolume)
page.makeValueBinding(knob2.mSurfaceValue, selectedTrackChannel.mSends.getByIndex(0).mLevel)
page.makeValueBinding(knob3.mSurfaceValue, selectedTrackChannel.mSends.getByIndex(1).mLevel)
page.makeValueBinding(knob4.mSurfaceValue, selectedTrackChannel.mSends.getByIndex(2).mLevel)
```

--------------------------------

### Ports Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Methods for creating MIDI input and output ports for device drivers.

```APIDOC
## Ports
> Device driver sub section for creating midi port objects.
Referenced by: _DeviceDriver_
**Methods**
  * **makeMidiInput**(**name** : _string_) : _DeviceMidiInput_
  * **makeMidiOutput**(**name** : _string_) : _DeviceMidiOutput_
```

--------------------------------

### Create Transport Buttons and Bind MIDI CC

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Defines a function to bind MIDI Control Change messages to buttons and then creates several transport buttons (Rewind, Forward, Stop, Start, Cycle, Record) with their respective MIDI bindings.

```javascript
function bindMidiCC(button, chn, num) {
    button.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(chn, num)
}

transport.btnRewind = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnRewind, 15, 112)
currX = currX + w

transport.btnForward = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnForward, 15, 113)
currX = currX + w

transport.btnStop = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnStop, 15, 114)
currX = currX + w

transport.btnStart = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnStart, 15, 115)
currX = currX + w

transport.btnCycle = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnCycle, 15, 116)
currX = currX + w

transport.btnRecord = surface.makeButton(currX, y, w, h)
bindMidiCC(transport.btnRecord, 15, 117)
currX = currX + w

return transport
}
```

--------------------------------

### Create Surface Elements and Bindings

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Initializes various surface elements including track navigation buttons, binding navigation buttons, channel bank navigation buttons, knob strips, fader strips, transport controls, and piano keys. Each button is bound to a specific MIDI Control Change message.

```javascript
function makeSurfaceElements() {
    var surfaceElements = {}

    surfaceElements.btn_prevTrack = surface.makeButton(0, 7, 2, 1)
    surfaceElements.btn_prevTrack.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 102)

    surfaceElements.btn_nextTrack = surface.makeButton(2, 7, 2, 1)
    surfaceElements.btn_nextTrack.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 103)

    surfaceElements.btn_prevBinding = surface.makeButton(0, 3, 2, 1)
    surfaceElements.btn_prevBinding.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 81)
      
    surfaceElements.btn_nextBinding = surface.makeButton(0, 4, 2, 1)
    surfaceElements.btn_nextBinding.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 82)
      
    surfaceElements.btn_prevChannelBank = surface.makeButton(2, 3, 2, 1)
    surfaceElements.btn_prevChannelBank.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 85)
      
    surfaceElements.btn_nextChannelBank = surface.makeButton(2, 4, 2, 1)
    surfaceElements.btn_nextChannelBank.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 86)

    surfaceElements.numStrips = 8

    surfaceElements.knobStrips = {}
    surfaceElements.faderStrips = {}

    var xKnobStrip = 5
    var yKnobStrip = 0

    surfaceElements.knobStripBlindPanel = surface.makeBlindPanel(xKnobStrip, yKnobStrip + 2, surfaceElements.numStrips * 2, 2)

    for(var i = 0; i < surfaceElements.numStrips; ++i) {
        surfaceElements.knobStrips[i] = makeKnobStrip(i, xKnobStrip, yKnobStrip)
        surfaceElements.faderStrips[i] = makeFaderStrip(i, 24, 0)
    }

    surfaceElements.transport = makeTransport(41, 7)

    surfaceElements.pianoKeys = surface.makePianoKeys(5, 10, 48, 7, 0, 48)

    return surfaceElements
}

var surfaceElements = makeSurfaceElements()
```

--------------------------------

### HostStripEffectSlotGate

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Represents a Gate effect slot within a host strip. It inherits from _HostObject_ and provides properties for controlling the plugin's state (on, bypass, edit, automation) and event handlers for plugin identity, title, and color changes. It also includes a method to get the runtime ID.

```APIDOC
## HostStripEffectSlotGate

### Description
Represents a Gate effect slot. Provides properties for plugin state and event handlers for various plugin changes.

### Properties
* **mOn** : _PluginOnValue_
* **mBypass** : _PluginBypassValue_
* **mEdit** : _PluginEditValue_
* **mAutomationRead** : _AutomationReadValue_
* **mAutomationWrite** : _AutomationWriteValue_
* **mParameterBankZone** : _HostPluginParameterBankZone_
* **mOnChangePluginIdentity** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , pluginName : _string_ , pluginVendor : _string_ , pluginVersion : _string_ , formatVersion : _string_)
* **mOnTitleChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , title : _string_)
* **mOnColorChange** : _function_ (activeDevice : _ActiveDevice_ , activeMapping : _ActiveMapping_ , r : _number_ , g : _number_ , b : _number_ , a : _number_ , isActive : _boolean_)

### Methods
* **getRuntimeID**(**activeMapping** : _ActiveMapping_) : _number_
```

--------------------------------

### Knob Strip Creation and MIDI Binding

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Creates a knob strip with a knob, a button, and two trigger pads, binding them to MIDI Control Change and Note messages respectively.

```javascript
function makeKnobStrip(knobIndex, x, y) {
    var knobStrip = {}
      
    knobStrip.knob = surface.makeKnob(x + 2 * knobIndex, y, 2, 2)
    knobStrip.knob.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 21 + knobIndex).setTypeRelativeTwosComplement()

    knobStrip.button = surface.makeButton(x + 2 * knobIndex, y + 4, 2, 1)
    knobStrip.button.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToControlChange(15, 51 + knobIndex)

    knobStrip.pad1 = surface.makeTriggerPad(x + 2 * knobIndex, y + 5, 2, 2)
    knobStrip.pad1.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToNote(15, 96 + knobIndex)

    knobStrip.pad2 = surface.makeTriggerPad(x + 2 * knobIndex, y + 7, 2, 2)
    knobStrip.pad2.mSurfaceValue.mMidiBinding.setInputPort(midiInput).bindToNote(15, 112 + knobIndex)

    return knobStrip
}
```

--------------------------------

### HostBinding

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

An abstract base class for bindings within the host, serving as a base for value, command, and action bindings.

```APIDOC
## HostBinding

### Description
An abstract base class for bindings within the host, serving as a base for value, command, and action bindings.

### Inherited By
- _ValueBinding_
- _CommandBinding_
- _ActionBinding_

### Referenced By
- _FactoryMappingPage_
```

--------------------------------

### Create Host Mapping Page with Defaults

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Defines a function to create a mapping page and sets up default bindings for track selection and transport controls. This includes both action bindings for track navigation and value bindings for transport functions.

```javascript
//-----------------------------------------------------------------------------
// 3. HOST MAPPING - create mapping pages and host bindings
//-----------------------------------------------------------------------------

function makePageWithDefaults(name) {
    var page = deviceDriver.mMapping.makePage(name)

    page.makeActionBinding(surfaceElements.btn_prevTrack.mSurfaceValue, page.mHostAccess.mTrackSelection.mAction.mPrevTrack)
    page.makeActionBinding(surfaceElements.btn_nextTrack.mSurfaceValue, page.mHostAccess.mTrackSelection.mAction.mNextTrack)

    page.makeValueBinding(surfaceElements.transport.btnRewind.mSurfaceValue, page.mHostAccess.mTransport.mValue.mRewind)
    page.makeValueBinding(surfaceElements.transport.btnForward.mSurfaceValue, page.mHostAccess.mTransport.mValue.mForward)
    page.makeValueBinding(surfaceElements.transport.btnStop.mSurfaceValue, page.mHostAccess.mTransport.mValue.mStop).setTypeToggle()
    page.makeValueBinding(surfaceElements.transport.btnStart.mSurfaceValue, page.mHostAccess.mTransport.mValue.mStart).setTypeToggle()
    page.makeValueBinding(surfaceElements.transport.btnCycle.mSurfaceValue, page.mHostAccess.mTransport.mValue.mCycleActive).setTypeToggle()
}
```

--------------------------------

### Safe Parameter Writing

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

Demonstrates how to safely set parameter values and use edit-lock APIs for coordinated changes.

```APIDOC
## setParameterHalf

### Description
Sets a parameter to a specific value (0.5).

### Method
```javascript
setParameterHalf(da, activeMapping, objectID, parameterTag)
```

### Parameters
- **da**: The DirectAccess instance.
- **activeMapping**: The active mapping.
- **objectID**: The ID of the object.
- **parameterTag**: The tag of the parameter.

## Edit Lock API

### Description
Provides methods to manage parameter edit locks, ensuring atomic updates during coordinated changes.

### Methods
- `da.getParameterEditLockState(activeMapping, objectID, parameterTag)`: Gets the current edit lock state.
- `da.setParameterEditLockState(activeMapping, objectID, parameterTag, true/false)`: Sets the edit lock state.
```

--------------------------------

### Convert Parameter Values - JavaScript

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

Demonstrates converting parameter values between process value and plain value formats. Use these methods when you need to send or interpret parameter data in different representations.

```javascript
var processValue = 0.5
var plainValue = da.convertParameterProcessValueToPlain(activeMapping, objectID, parameterTag, processValue)
var backToProcess = da.convertParameterPlainToProcessValue(activeMapping, objectID, parameterTag, plainValue)
```

--------------------------------

### Device Detection Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Methods for detecting MIDI devices and their ports.

```APIDOC
## DeviceDetectionUnit

> Define device auto detection.

**Methods**
  * **detectPortPair**(**inputPort** : _DeviceMidiInput_ , **outputPort** : _DeviceMidiOutput_) : _DetectionPortPair_
  * **detectSingleInput**(**inputPort** : _DeviceMidiInput_) : _DetectionSingleInput_
```

--------------------------------

### MidiRemoteAPI

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

The entry point to the MIDI Remote API. It provides access to host defaults and allows for the creation of device drivers.

```APIDOC
## MidiRemoteAPI

### Description
Entry point to the **MIDI Remote API**.

### Properties
* **mDefaults** : _HostDefaults_

### Methods
* **makeDeviceDriver**(**vendorName** : _string_ , **deviceName** : _string_ , **createdBy** : _string_) : _DeviceDriver_
```

--------------------------------

### MIDI Remote API Host Mapping

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/simpledevice

Creates a mapping page and binds the surface controls to host parameters like track volume and send levels.

```javascript
//-----------------------------------------------------------------------------
// 3. HOST MAPPING - create mapping pages and host bindings
//-----------------------------------------------------------------------------

// create at least one mapping page
var page = deviceDriver.mMapping.makePage('Example Mixer Page')

// create host accessing objects
var hostSelectedTrackChannel = page.mHostAccess.mTrackSelection.mMixerChannel


// bind surface elements to host accessing object values
page.makeValueBinding(knob1.mSurfaceValue, hostSelectedTrackChannel.mValue.mVolume)
page.makeValueBinding(knob2.mSurfaceValue, hostSelectedTrackChannel.mSends.getByIndex(0).mLevel)
page.makeValueBinding(knob3.mSurfaceValue, hostSelectedTrackChannel.mSends.getByIndex(1).mLevel)
page.makeValueBinding(knob4.mSurfaceValue, hostSelectedTrackChannel.mSends.getByIndex(2).mLevel)

```

--------------------------------

### DirectAccess Callbacks

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

Explains how to use callback hooks for incremental updates and cache invalidation.

```APIDOC
## DirectAccess Callbacks

### Description
Supports callback hooks for incremental updates to manage cache invalidation and targeted refresh logic.

### Available Callbacks
- `mOnObjectChange`: Called when an object changes.
- `mOnObjectWillBeRemoved`: Called when an object is about to be removed.
- `mOnParameterChange`: Called when a parameter changes.

### Example Usage (`mOnObjectWillBeRemoved`)
```javascript
da.mOnObjectWillBeRemoved = function (activeDevice, activeMapping, objectID) {
  delete objectCache[objectID];
}
```
```

--------------------------------

### HostDefaultsAppVersion

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Provides information about the host application's version.

```APIDOC
## HostDefaultsAppVersion

### Description
Referenced by: _HostDefaults_

### Methods
* **getVersionString**() : _string_
```

--------------------------------

### HostAccess

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Provides objects and methods to bind the defined Surface to host functions.

```APIDOC
## HostAccess

Provides objects and methods to bind the defined Surface to host functions.

**Properties**
  * **mTransport** : _Transport_
  * **mMixConsole** : _MixConsole_
  * **mControlRoom** : _HostControlRoom_
  * **mTrackSelection** : _TrackSelection_
  * **mMouseCursor** : _HostMouseCursor_
  * **mFocusedQuickControls** : _FocusedQuickControls_

**Methods**
  * **makeDirectAccess**(**hostObject** : _HostObject_) : _HostObjectDirectAccess_
```

--------------------------------

### SurfaceValueMidiBinding

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Provides methods for configuring MIDI bindings for surface values, including setting input/output ports, consuming MIDI messages, and binding to various MIDI events like notes and control changes.

```APIDOC
## SurfaceValueMidiBinding

### Description
Provides methods for configuring MIDI bindings for surface values. It is referenced by _SurfaceElementValue_ and _SurfaceCustomValueVariable_.

### Methods
* **setInputPort**(**inputPort** : _DeviceMidiInput_) : _this_
* **setOutputPort**(**outputPort** : _DeviceMidiOutput_) : _this_
* **setIsConsuming**(**isConsuming** : _boolean_) : _this_
* **bindToNote**(**channelNumber** : _number_ , **pitch** : _number_) : _MidiBindingToNote_
* **bindToControlChange**(**channelNumber** : _number_ , **controlChangeNumber** : _number_) : _MidiBindingToControlChange_
* **bindToControlChange14Bit**(**channelNumber** : _number_ , **controlChangeNumber** : _number_) : _MidiBindingToControlChange14Bit_
* **bindToControlChange14BitNRPN**(**channelNumber** : _number_ , **controlChangeNumber** : _number_) : _MidiBindingToControlChange14BitNRPN_
* **bindToPitchBend**(**channelNumber** : _number_) : _MidiBindingToPitchBend_
* **bindToChannelPressure**(**channelNumber** : _number_) : _MidiBindingToChannelPressure_
```

--------------------------------

### HostControlRoom Methods

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

This section details the methods available on the HostControlRoom object for accessing and managing control room features.

```APIDOC
## HostControlRoom Methods

### getCueChannelByIndex
Retrieves a cue channel by its index.

**Parameters**
- **index** (number) - The index of the cue channel to retrieve.

### getPhonesChannelByIndex
Retrieves a phones channel by its index.

**Parameters**
- **index** (number) - The index of the phones channel to retrieve.

### getExternalInputChannelByIndex
Retrieves an external input channel by its index.

**Parameters**
- **index** (number) - The index of the external input channel to retrieve.

### getTalkbackChannelByIndex
Retrieves a talkback channel by its index.

**Parameters**
- **index** (number) - The index of the talkback channel to retrieve.

### getMonitorChannelByIndex
Retrieves a monitor channel by its index.

**Parameters**
- **index** (number) - The index of the monitor channel to retrieve.

### getSelectSourceExternalInputValueByIndex
Retrieves the value for selecting an external input source by its index.

**Parameters**
- **index** (number) - The index of the external input source.

### getSelectTargetMonitorValueByIndex
Retrieves the value for selecting a monitor target by its index.

**Parameters**
- **index** (number) - The index of the monitor target.

### getMaxTalkbackChannels
Returns the maximum number of talkback channels supported.

### getMaxExternalInputChannels
Returns the maximum number of external input channels supported.

### getMaxCueChannels
Returns the maximum number of cue channels supported.

### getMaxPhonesChannels
Returns the maximum number of phones channels supported.

### getMaxMonitorChannels
Returns the maximum number of monitor channels supported.

### getRuntimeID
Retrieves the runtime ID for a given active mapping.

**Parameters**
- **activeMapping** (ActiveMapping) - The active mapping for which to retrieve the runtime ID.

```

--------------------------------

### Create Sub-Page with Activation Callback

Source: https://steinbergmedia.github.io/midiremote_api_doc/examples/realworlddevice

Creates a sub-page and defines a callback function to be executed when the sub-page is activated.

```javascript
function makeSubPage(subPageArea, name) {
    var subPage = subPageArea.makeSubPage(name)
    var msgText = 'sub page ' + name + ' activated'
    subPage.mOnActivate = function(activeDevice) {
        console.log(msgText)
    }
    return subPage
}
```

--------------------------------

### MIDI Remote API Script File Structure

Source: https://steinbergmedia.github.io/midiremote_api_doc/getting-started

Defines the standard directory structure and naming convention for MIDI Remote API script files.

```plaintext
<Driver Scripts Folder>/Local/<vendor>/<device>/<vendor>_<device>.js  

```

--------------------------------

### ActiveDevice

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Manages the state of a detected and activated device.

```APIDOC
## ActiveDevice

### Description
Represents a detected and activated device of a specific DeviceDriver.

### Methods
* **setState**(**key** : _string_ , **val** : _string_)
* **getState**(**key** : _string_) : _string_
```

--------------------------------

### Plugin Manager

Source: https://steinbergmedia.github.io/midiremote_api_doc/advanced-topics/direct-access

Details how to use the plugin manager for slot-level plugin browsing and assignment.

```APIDOC
## Plugin Manager

### Description
Provides access to `da.mPluginManager` for slot-level plugin browsing and assignment.

### Methods
- `da.mPluginManager.getNumberOfPluginCollections(activeMapping, pluginSlotObjectID)`: Gets the number of plugin collections.
- `da.mPluginManager.getIndexOfActivePluginCollection(activeMapping, pluginSlotObjectID)`: Gets the index of the active plugin collection.
- `da.mPluginManager.getPluginCollectionByIndex(activeMapping, pluginSlotObjectID, index)`: Gets a plugin collection by its index.
- `da.mPluginManager.trySetSlotPlugin(activeMapping, pluginSlotObjectID, pluginUID, true)`: Attempts to set a plugin for a slot.

### Example Usage
```javascript
var collectionCount = da.mPluginManager.getNumberOfPluginCollections(activeMapping, pluginSlotObjectID);
var activeCollectionIndex = da.mPluginManager.getIndexOfActivePluginCollection(activeMapping, pluginSlotObjectID);

if (activeCollectionIndex >= 0 && activeCollectionIndex < collectionCount) {
  var collection = da.mPluginManager.getPluginCollectionByIndex(activeMapping, pluginSlotObjectID, activeCollectionIndex);
  if (collection.mEntries.length > 0) {
    var pluginUID = collection.mEntries[0].mPluginUID;
    da.mPluginManager.trySetSlotPlugin(activeMapping, pluginSlotObjectID, pluginUID, true);
  }
}
```
```

--------------------------------

### HostDefaults

Source: https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference

Provides access to host application defaults and information, such as application version and the number of effect slots.

```APIDOC
## HostDefaults

### Description
Referenced by: _MidiRemoteAPI_

### Properties
* **mAppVersion** : _HostDefaultsAppVersion_

### Methods
* **getAppName**() : _string_
* **getNumberOfInsertEffectSlots**() : _number_
* **getNumberOfStripEffectSlots**() : _number_
* **getNumberOfSendSlots**() : _number_
* **getNumberOfQuickControls**() : _number_
* **getMaxControlRoomTalkbackChannels**() : _number_
* **getMaxControlRoomExternalInputChannels**() : _number_
* **getMaxControlRoomCueChannels**() : _number_
* **getMaxControlRoomPhonesChannels**() : _number_
* **getMaxControlRoomMonitorChannels**() : _number_
* **getMaxGainFactor**() : _number_
```
Tokens:
Raw