search

steinbergmedia / midiremote-userscripts

A place for user created MIDI Remote API scripts
MIT License
41 stars 32 forks source link

readme

MIDI Remote API - User Scripts

About

Welcome to the Steinberg MIDI Remote API.

This document will guide you through the steps of writing a MIDI Remote API Script for a specific MIDI Controller Hardware.

NOTE: Scripts are written in the ES5 version of JavaScript

How to work with this repository

  1. Make a fork of steinbergmedia/midiremote-userscripts

  2. Rename your existing …/Driver Scripts/Local folder to something else (like Local_backup)

  3. Create a new empty folder Local to replace it

  4. Clone your forked repository inside the newly created empty Local folder

  5. Copy your existing scripts from within the Local_backup folder into the Local folder

  6. Still use the parent folder of Local, the Drive Scripts folder, as the workspace folder in Visual Studio Code

  7. Make commits/pushes to your forked repo

  8. Make pull requests to the upstream repo (steinbergmedia/midiremote-userscripts)

And don't forget to regulary do “fetch and merge” from the upstream repo (steinbergmedia/midiremote-userscripts) to stay in sync.

Basic Concept

The MIDI Remote API Script acts as a mediator between a Hardware Controller and Cubase / Nuendo

The MIDI Remote API Script emulates the hardware surface. This improves usability and recognizability.

Script Structure

The MIDI Remote API Script consists of three building blocks

  1. Driver Setup

    • create driver object
    • define driver ports to be associated with existing hardware midi ports
    • specify all possible port namings for automatic device detection

  2. Surface Layout

    • visualize the hardware's surface elements (e.g. knobs, faders, buttons)
    • bind surface elements to midi messages

  3. Host Mapping

    • create mapping pages for each user workflow (e.g. mixing, playing instruments, track navigation)
 

The following image illustrates that:

 

Getting Started

To get started please perform these steps:

  1. Make sure you have Visual Studio Code installed.
We highly recommend using Visual Studio Code for writing MIDI Remote API Scripts. We provide a JSDoc based auto-completion setup. You will not have to look up types and methods in a separate documentation. Visual Studio Code will help you write scripts intuitively.

  1. Make sure the folder of the Visual Studio Code executable is added to the PATH environment variable.

  2. Make sure you have the newest Cubase / Nuendo installed.

  3. Start Cubase / Nuendo.

  4. Create a project with audio and/or instrument tracks.

  5. Open the Remote tab in the lower zone.

  1. Open the MIDI Remote Driver Scripts folder.

Mac: /Users/<Username>/Documents/Steinberg/<Cubase or Nuendo>/MIDI Remote/Driver Scripts

Windows: C:\Users\<Username>\Documents\Steinberg\<Cubase or Nuendo>\MIDI Remote\Driver Scripts

 

  1. Open a console (win: cmd, mac: terminal) and go to the MIDI Remote Driver Scripts folder.

  2. Open Visual Studio Code from the command line like this:

code .

  1. Create a script file.

The MIDI Remote API Script file follows the structure: <Driver Scripts Folder>/<Local or Public>/<vendor>/<device>/<vendor>_<device>.js

WARNING: Always use the folder Local for development, folder Public will be overwritten when starting Cubase / Nuendo.

Example: <Driver Scripts Folder>/Local/Nektar/Impact_LX49Plus/Nektar_Impact_LX49Plus.js

  1. Connect your MIDI hardware controller.

  2. Open script console.

The Script Console appears like this:

After modifying the script file press the 'Reload Scripts' button.