# Instrument format description

This document describes the format of the Electra One instrument file. The instrument file provides a complete definition of MIDI implementation of a particular MIDI device (synth, sampler, FX unit, etc). The instrument files are not transferred to the controller. Instead, they are used to generate preset files.

# Instrument JSON format

# JSON schema

The JSON schema of the Electra instrument file is available at GitHub (opens new window).

# Top level objects

The preset has a number of top-level objects. These are either simple elements providing info about the preset itself or complex objects that define the structure and data of the preset.

{
  "version":1,
  "id":"mpa-xctrl",
  "name":"X Controller",
  "manufacturer":"Electra.One",
  "manufacturerId":"e1",
  "categories": [
  ],
  "overlays": [
  ],
  "parameters": [
  ],
  "patch": [
  ]
}

# version

Provides information about the version of the instrument file. Electra controller uses version information to distinguish between various preset file formats.

  • optional
  • numeric
  • default = 1

# id

An unique identifier of the instrument file. The id is used to identify the developer and the instrument file itself. Suggested format is <developer>-<unique id in developer's space>. The id should not be shown to the users.

  • optional
  • string
  • minLength = 0
  • maxLength = 20

# name

A name of the instrument. The field should carry information about the model, make, or the device name.

  • mandatory
  • string
  • minLength = 0
  • maxLength = 20

# manufacturer

A name of the instrument. The field should carry information about the model, make, or the device name.

  • mandatory
  • string
  • minLength = 0
  • maxLength = 20

# categories

An array of pages. A page is a collection of controls and groups displayed to the user at once.

  • mandatory
  • array
# example:
"pages": [
   {
      "id": 1,
      "name": "OSCILLATORS"
   },
   {
      "id": 2,
      "name": "FILTER"
   }
]

# overlays

An array of overlays. An overlay is a list of text labels or graphical symbols that can be assigned to a control.

  • optional
  • array
# examples:
"overlays": [
   {
      "id": 1,
      "items": [
         {
            "value": 0,
            "label": "SAW"
         },
         {
            "value": 1,
            "label": "SQUARE"
         },
         {
            "value": 2,
            "label": "WHITE NOISE"
         },
         {
            "value": 4,
            "label": "PINK NOISE"
         }
      ]
   },
   {
      "id": 2,
      "items": [
         {
            "value": 0,
            "label": "Morph (P6)"
         },
         {
            "value": 16,
            "label": "Sinus"
         },
         {
            "value": 32,
            "label": "Triangle"
         }
      ]
   },
   {
      "id": 3,
      "items": [
         {
            "value": 0,
            "label": "Square",
            "bitmap": "AAAAAAAA/P//AQAA/P//AQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACAAQAwDACA//8/DACA//8/AAAAAAAAAAAAAAAA"
         },
         {
            "value": 1,
            "label": "Triangle",
            "bitmap": "AAAAAAAAAADgAAAAAADwAQAAAAAYAwAAAAAMBgAAAAAGDAAAAAADGAAAAIABMAAgAMAAYAAwAGAAwAAYBDAAgAEMDBgAAAMGGAwAAAYDMAYAAIwB4AMAAPgAwAEAAHAAAAAAAAAAAAAAAAAA"
         },
         {
            "value": 2,
            "label": "Saw",
            "bitmap": "AAAAAAAAAAAAwAEAAAAA8AEAAAAAnAEAAAAAhwEAAADAgQEAAABwgAEAAAAcgAEAAAAHgAEAAMABgAE4AHAAgAEOABwAgIEDAAcAgOEAwAEAgDkAcAAAgA8AHAAAgAMAAAAAAAAAAAAAAAAA"
         }
      ]
   }
]

# parameters

An array of controls. A control is a representation of one or more MIDI parameters or messages that can be controlled by the user.

  • mandatory
  • array
# examples:

A simple control with one value assigned.

"controls": [
   {
      "id": 1,
      "type": "fader",
      "name": "WHITE",
      "color": "FFFFFF",
      "bounds": [
         0,
         40,
         146,
         56
      ],
      "pageId": 1,
      "controlSetId": 1,
      "inputs": [
         {
            "potId": 1,
            "valueId": "value"
         }
      ],
      "values":[
         {
            "id": "value",
            "message": {
               "deviceId": 1,
               "type": "cc7",
               "parameterNumber": 1,
               "min": 0,
               "max": 127
            },
            "min": 0,
            "max": 127
         }
      ]
   },
   {
      "id": 2,
      "type": "fader",
      "name": "RED",
      "color": "F45C51",
      "bounds": [
         170,
         40,
         146,
         56
      ],
      "pageId": 1,
      "controlSetId": 1,
      "visible": false,
      "inputs": [
         {
            "potId": 2,
            "valueId": "value"
         }
      ],
      "values": [
         {
            "message": {
               "deviceId": 1,
               "type": "cc7",
               "parameterNumber": 2,
               "min": 0,
               "max": 127
            },
            "min": 0,
            "max": 127,
            "formatter": "formatFractions"
         }
      ]
   }
]

← Config format description →