Remote map format description

PARTLY IMPLEMENTED

The controller reads this file and drives the controls it names, in both directions, with per assignment takeover. Control change and note assignments are both built, a hundred and twenty-eight of each. The encoding field is not read—change assignments are taken as two's complement and no other encoding is available yet.

This document describes the format of the Electra One Remote map file.

A Remote map holds the static Remote Knobs assignments for one preset: which incoming MIDI messages drive which controls of that preset. It is what turns an external controller—an Akai MIDImix, a Novation Launchkey, a bank of faders—into a fixed control surface for a particular preset, with each fader always driving the same parameter no matter which page is on the screen.

A Remote map is a file of its own and is not part of the preset. This is deliberate. The assignments describe somebody's external controller, not the preset, and the person who wrote the preset has no way of knowing what hardware anyone else owns. Any user can take any preset—their own, or one downloaded from somebody else—and build a map for the controller sitting on their desk, without editing the preset and without the preset author having anticipated them. Maps are ordinary files, so they can be exported, kept in a library, and shared between users the same way presets are.

A remote map outranks every dynamic setting. While a preset that has one is loaded, its map is the whole of what the Remote Knobs do:

• the knob slots held in the controller configuration are switched off, and a CC the map does not mention does nothing;
• each assignment carries its own takeover, and the configuration's is not consulted;
• the Remote Knobs enable switch does not silence incoming messages. A user who has written a map for the preset in front of them has said what they want more precisely than that switch can;
• syncOnLoad may be answered by the map rather than by the configuration.

The inbound routes are the one thing that still applies, and deliberately: which port and channel the hardware speaks on is a fact about the wiring, not about any one preset, and there is nowhere else to say it. A map with no route to arrive on stays silent.

A preset with no map uses the knob slots as before. There is no setting for this - what decides is whether a map is loaded.

Several maps at once

Every live preset's map is offered incoming messages, not only the one on the screen. Two presets pinned side by side, each with a map of its own, share one controller: the assignments name controls of a particular preset, so they cannot collide unless two maps claim the same CC.

The preset on the screen is offered a message first, so a CC that two maps both claim goes to the one being looked at. That is a tie-break rather than a guarantee—nothing stops two maps overlapping, and it is worth not doing.

Because any live map switches the knob slots off, pinning a preset that carries one turns the slots off for everything, including the preset on screen.

Remote maps are made in the Electra One app. The controller has no editor for them: choosing one control out of a whole preset is work for a screen and a mouse, where the controller's own screen edits the knob slots, which are a grid of thirty-six.

A Remote map must always be associated with a preset; it cannot function independently. The association is established by placing the map file in the same preset slot as the preset file, and by referring to the preset's controls through their control and value ids. This is the same arrangement the Performance file uses.

The Remote map covers Static mode only. The Dynamic mode assignments—CC numbers mapped onto Electra's own knob slots—are global and live in the controller configuration file instead, because a slot means the same thing in every preset. See the remote object of the configuration file format.

Remote map JSON format

Top level objects

{
  "version": 1,
  "projectId": "d8WjdwYrP3lRyyx8nEMF",
  "name": "MIDImix",
  "syncOnLoad": true,
  "mappings": [
  ]
}

version

Provides information about the version of the Remote map file. Electra One uses the version information to distinguish between file formats.

• mandatory
• numeric

projectId

The projectId of the preset the map was written for. When it disagrees with the preset in the slot, the whole map is refused and nothing is mapped: the control ids would name different controls, and driving the wrong parameters is worse than driving none. The refusal is written to the log and is not shown on the screen. A map for a preset that declares no projectId omits it, and no check is made.

• optional
• string
• maxLength = 20

name

A name for the map, shown to the user when choosing between maps. Usually the name of the external controller the map was written for.

• optional
• string
• maxLength = 20

syncOnLoad

Whether to send every absolute assignment of this map outbound when the preset or a snapshot is loaded, so a motorised or lit controller is left agreeing with the parameters.

Omit it to leave the decision to the controller. Absent is not the same as false: absent means "whatever remote.syncOnLoad in the configuration says", while false overrides it for this preset. Without the distinction a map could only ever turn the behaviour on, never off.

Relative and velocity assignments are never sent—an increment carries no position and a struck pad has no light to put a velocity back on. A momentary or toggle assignment reports as a key: Note On when the value is in the upper half of its travel, Note Off when it is not, which is how a lit pad follows a switch.

• optional
• boolean, and absent means the controller decides

mappings

The assignments. Each entry binds one incoming MIDI message to one control value of the preset.

128 control changes and 128 notes, one per number of each kind: every message a map can answer, so a surface carrying a full CC set and a pad grid fits whole. Nothing is refused for want of room. Two entries naming the same cc, or the same note, are one assignment—the later one replaces the earlier.

A note and a cc of the same number are different assignments, and Note On and Note Off of one number are the same assignment.

• mandatory
• array

remoteMapping

A single assignment. Exactly one of cc and note must be present.

example:

{
   "cc": 21,
   "controlId": 7,
   "valueId": "attack",
   "type": "value"
}

cc

The MIDI CC number the assignment listens to. Mutually exclusive with note.

• optional
• numeric
• min = 0
• max = 127

note

The MIDI note number the assignment listens to. Mutually exclusive with cc.

• optional
• numeric
• min = 0
• max = 127

controlId

The identifier of the control this assignment drives. It refers to the id of an entry in the preset's controls array. The control may be on any page, and does not need to be visible.

• mandatory
• numeric
• min = 1
• max = 432

valueId

The identifier of the value within the control. Used for controls that carry more than one value—ADSR envelopes, vertical fader groups, XY pads—so that each value can be driven by its own knob or fader.

When omitted, the assignment drives the control's first value.

• optional
• string
• maxLength = 20

type

How the incoming message is read. It has to suit the kind—a note read as a position, or a cc read as a key press, is refused rather than guessed at.

For cc assignments:

• value — the CC value 0 to 127 is an absolute position
• change — the CC value is a relative increment

For note assignments:

• momentary — the control is on while the key is held
• toggle — each Note On flips the control
• velocity — the note velocity 1 to 127 sets the value

A Note On with velocity 0 is a Note Off, as every controller that sends running status releases a key that way.

What a change detent is worth is what it is worth on a knob slot, so an encoder feels the same whichever kind of assignment names it. A proportional control—a fader, an envelope segment, a macro—crosses its whole range in 128 detents, whether it holds 128 values or 16384. A list or a switch steps once per detent, the way an encoder does, however long the list is. Movement too small to have earned a whole step is kept and added to what comes next, so a slow hand still moves a narrow control. Each assignment keeps its own; fine adjustment applies here as it does to the knobs.

• optional
• enum, defaulting to value for a cc and momentary for a note

encoding

For change assignments, the relative encoding the sending device uses. Ignored otherwise. See the remote object of the configuration file format for the list of encodings.

• optional
• enum, defaults to twosComplement

takeover

What happens when the physical control and the parameter disagree—after a preset change, a snapshot recall, or anything else that moved the parameter while the fader stayed where it was.

Per assignment. One surface routinely wants more than one behaviour: a mixer's faders want pickup so recalling a snapshot cannot jump the levels, and the buttons beside them want jump because a button has nothing to catch.

Applies to absolute assignments only. A change assignment carries an increment that is applied to wherever the parameter already is, so there is nothing for it to disagree with, and a takeover on one is ignored.

An unknown or missing value is read as jump, so a map written by a newer editor loses the mode rather than the mapping. Since jump is the default, an assignment that wants it says nothing at all.

• optional
• enum, defaults to jump
  • jump — the parameter follows the incoming value immediately
  • pickup — incoming values are ignored until the control passes through the parameter's value
  • scale — the parameter moves proportionally, converging as the control reaches an end of its travel
  • nudge — the parameter moves by as much as the control moved

The takeover in the configuration file still decides the Dynamic knob slots, which have no map to carry a mode of their own. It has no effect on the assignments in a remote map.

A complete example

A map for an Akai MIDImix driving a mixer preset. The nine faders are bound to eight channel levels and a master level; the top row of knobs is bound to eight pan controls.

{
  "version": 1,
  "projectId": "d8WjdwYrP3lRyyx8nEMF",
  "name": "MIDImix",
  "mappings": [
    { "cc": 19, "controlId": 1,  "type": "value", "takeover": "pickup" },
    { "cc": 23, "controlId": 2,  "type": "value", "takeover": "pickup" },
    { "cc": 27, "controlId": 3,  "type": "value", "takeover": "pickup" },
    { "cc": 31, "controlId": 4,  "type": "value", "takeover": "pickup" },
    { "cc": 49, "controlId": 5,  "type": "value", "takeover": "pickup" },
    { "cc": 53, "controlId": 6,  "type": "value", "takeover": "pickup" },
    { "cc": 57, "controlId": 7,  "type": "value", "takeover": "pickup" },
    { "cc": 61, "controlId": 8,  "type": "value", "takeover": "pickup" },
    { "cc": 62, "controlId": 9,  "type": "value", "takeover": "pickup" },

    { "cc": 16, "controlId": 11, "type": "value" },
    { "cc": 20, "controlId": 12, "type": "value" },
    { "cc": 24, "controlId": 13, "type": "value" },
    { "cc": 28, "controlId": 14, "type": "value" },
    { "cc": 46, "controlId": 15, "type": "value" },
    { "cc": 50, "controlId": 16, "type": "value" },
    { "cc": 54, "controlId": 17, "type": "value" },
    { "cc": 58, "controlId": 18, "type": "value" }
  ]
}

The faders take pickup, so recalling a snapshot cannot make a level jump the moment somebody nudges a fader that is no longer where the parameter is. The pans say nothing and so take jump, which is what a knob nobody is watching should do.

The same preset can be given a second map for a different controller. Only one map is active in a slot at a time.

Storage and transfer

A Remote map is stored as remoteMap.json in the preset slot folder, alongside preset.json and performance.json:

ctrlv2/slots/b00/p00/remoteMap.json

It is uploaded, downloaded and removed with the File Transfer SysEx API, using the object type remoteMap. Downloading a map is what makes it shareable: the file that comes off one controller is the file another user uploads to theirs.