MIDI Glass layout files, a guide for AI agents

Windows MIDI Glass (“MIDI Glass”) is the Windows MIDI Services app for building your own touch control surface. You put knobs, faders, pads, buttons, and keys on a page, choose what MIDI each one sends, and play it with a finger, a pen, or a mouse. Each design is called a layout, and each layout is one .midilayout file.

This article is written for AI agents and online AI chats that build layouts for people. It’s also for anyone who wants to write or check a layout file by hand. If you’re asking an AI to build a layout for you, give it the link to this article and ask it to read the whole page before it starts.

MIDI Glass is a preview app. The layout file described here is version 1. Later versions can add settings, and MIDI Glass keeps reading version 1 files when they do.

For AI agents: Read this article from start to finish before you write anything. Follow Building a layout for someone as your process, and use The layout file as your reference. You usually can’t see MIDI Glass yourself, so the notes marked For agents point out mistakes that load without an error and give the customer the wrong layout.

The rules that matter most:

1. Ask before you build. Get the device names, the manual, the screen, and what goes on the page. Don’t guess controller numbers.
2. Use a built-in theme, by its exact name. Don’t invent theme settings.
3. Count groups and channels from 0 in the file. People, manuals, and MIDI Glass’s own screens count them from 1.
4. Name each device the way Windows shows it, and match it by name. You can’t know a device’s ID.
5. Write strict JSON. No comments, no comma after the last item, and no hexadecimal numbers.
6. Say what MIDI Glass can’t do before the customer finds out. See What MIDI Glass can’t do.
7. Draw a mockup from your file and get a yes before you hand it over.

On this page:

• What a layout is
• Building a layout for someone
• Where layout files go, and how to bring one in
• What MIDI Glass can’t do
• The layout file
• Mistakes that are easy to miss

What a layout is

• A layout has one or more pages of controls. A page has a fixed size in pixels. When the layout runs, the page is scaled to fit the window or the screen without being stretched, so it keeps its shape.
• Each control has a position, a size, a name, and a list of messages: rows that say what the control sends, when it sends it, and where.
• A layout has its own device table. A message names a device from that table, never the hardware itself. Point that name at different hardware and every control that uses it follows.
• A layout names a theme, which decides how everything looks. A control doesn’t store a color. It stores one of the theme’s six colors, called slots, so a new theme recolors everything at once and the colors keep their meaning.
• A layout can also have sequences: lists of steps, such as a bank select, a program change, and a pause, that a button runs.

Building a layout for someone

1. Ask first

Ask these before you write anything. Put them in one message, in plain words, and offer a sensible answer for each so the customer can just say yes.

For agents: If the customer can’t give you a device name yet, use a short placeholder and tell them that MIDI Glass will show the device as missing until they pick it. Don’t make up a name that looks real.

2. Find the messages

Take every number from the manual or a published MIDI implementation chart, and tell the customer where each one came from so they can check it.

MIDI 2.0 profiles. MIDI Glass sends messages. It doesn’t use MIDI-CI, so it can’t turn a profile on or ask a device what it supports. Check that the device or plug-in already uses the profile, then send the messages the profile describes. Where the profile needs something MIDI Glass can’t do, such as attaching an articulation to every note a keyboard plays, say so and offer what it can do instead.

3. Pick a page size and a theme

Pick the page size closest to the shape of the customer’s screen. The page scales to fit, so its shape matters more than its exact size.

For a toolbar or a palette, also read How to make a floating toolbar or palette in MIDI Glass.

Use a built-in theme. MIDI Glass comes with twenty-five, and they’ve been checked for contrast and readability. Write its exact name in theme, capital letters and all, and leave themeColors out. A name MIDI Glass doesn’t know silently gives the customer Studio Dark.

The built-in themes are: Studio Dark, Airy System, Bigwig, Blueprint, Bone, Cathode, Chicago, Daylight, Five-iSH, Good Form, Groovy, Groovy Dark, Hard Sector, High contrast, Insert Coin, Jove, Night Drive, Off-world Colonies, Soft Sector, Supersaw, Terminal Amber, Terminal Green, Tonal Dark, Tonal Light, and Visor.

The shipping themes describes each one, and says what it costs, such as colors that are hard to tell apart. Read the row for the theme you pick.

If the customer wants a look of their own, design a theme file as well, following Designing a theme for someone else, and name that theme in the layout.

4. Lay out the page

• Positions are page pixels. x and y are the control’s top left corner, measured from the top left of the page, with y growing downward. width and height are its size.
• Use multiples of 4. The editor snaps to 4 pixels and its grid is 8, so a layout on that grid lines up when the customer edits it.
• Keep every control on the page. A control that hangs off any edge doesn’t show when the layout runs.
• Start from the default sizes below, and don’t go smaller for a touch screen. They’re for a 1280 × 800 page. For another page size, multiply by √(√(width² + height²) ÷ 1509), then round to a multiple of 4. That’s about 1.2 for 1920 × 1080 and 1.48 for 2736 × 1824.
• Leave room for names. Most themes print a control’s name under it, about 20 pixels tall. Jove, Supersaw, Five-iSH, Soft Sector, Hard Sector, and Good Form print it above.
• Group related controls in a Group control, called panel in the file, the way a hardware panel has sections. Leave about 32 pixels inside the top of the Group for its name, and 16 to 24 pixels on the other sides.
• Order matters. Controls are drawn in the order they’re listed, so the first is at the back. List each Group before the controls it frames.
• Give every control a name in label, even one whose name you hide. It’s what a screen reader says.
• Number keyboardOrder from 1 in the order a person reads the page: section by section, left to right, top to bottom. It’s the order the Tab key and a screen reader follow.
• Use the theme’s six slots to mean something, such as one slot per section, and keep each slot’s meaning across pages.
• For more than one page, put a page tab for every page on every page, in the same place.

5. Write the file

• JSON, saved as UTF-8. A byte order mark is allowed, but not needed.
• Strict JSON. No comments, no comma after the last item in a list or an object, and no hexadecimal numbers. JSON has no 0x.
• Names for choices, spelled exactly as this article shows them, capital letters included: "controlChange", "fitToScreen".
• Leave out what you don’t need. Anything you leave out takes the default in The layout file. MIDI Glass writes every setting back the next time it saves the layout.
• Ids are text, unique in the whole layout: every page’s id, and every control’s id on every page. MIDI Glass writes GUIDs, but any unique text works, such as cutoff or page-mix.

If you can run commands on the customer’s PC, write the file with PowerShell 7, which finds the Documents folder even when it has been moved into OneDrive:

$folder = Join-Path ([Environment]::GetFolderPath('MyDocuments')) 'MIDI Layouts'
New-Item -ItemType Directory -Path $folder -Force | Out-Null

$path = Join-Path $folder 'Synth basics.midilayout'
if (Test-Path -LiteralPath $path) { throw 'A layout with that name is already there. Pick another name.' }

[IO.File]::WriteAllText($path, $json, [Text.UTF8Encoding]::new($false))

If you’re an online chat, give the customer the file as a download named after the layout, ending in .midilayout. If you can only show text, put the whole file in one code block and tell them how to save it: paste it into Notepad, select File > Save as, set Save as type to All files, type a name that ends in .midilayout, and leave Encoding at UTF-8.

For agents: Don’t change a layout file that’s open in MIDI Glass. The app saves its own copy as the customer works, and it can write over your change. Write a new file instead.

6. Check it

Go through Mistakes that are easy to miss for every file. If you can run PowerShell 7, save this as Test-MidiGlassLayout.ps1 and run pwsh -File Test-MidiGlassLayout.ps1 -Path "<layout file>". It reads the file as strictly as MIDI Glass does, and lists the mistakes that load without an error.

param([Parameter(Mandatory)][string]$Path)

$text = [IO.File]::ReadAllText($Path)
$null = [Text.Json.JsonDocument]::Parse($text)   # throws on a comment, a trailing comma, or a hexadecimal number
$layout = $text | ConvertFrom-Json
$problems = [Collections.Generic.List[string]]::new()

$themes = 'Studio Dark', 'Airy System', 'Bigwig', 'Blueprint', 'Bone', 'Cathode', 'Chicago', 'Daylight', 'Five-iSH', 'Good Form', 'Groovy', 'Groovy Dark', 'Hard Sector', 'High contrast', 'Insert Coin', 'Jove', 'Night Drive', 'Off-world Colonies', 'Soft Sector', 'Supersaw', 'Terminal Amber', 'Terminal Green', 'Tonal Dark', 'Tonal Light', 'Visor'
$controlKinds = 'knob', 'fader', 'pad', 'button', 'toggle', 'xyPad', 'meter', 'lamp', 'readout', 'label', 'image', 'pageTab', 'panel', 'joystick', 'ribbon', 'pianoKeyboard', 'beatClock', 'timeDisplay', 'lfo', 'turntable', 'wheel', 'switch', 'steps', 'line', 'notePads', 'hexPads'
$messageKinds = 'note', 'controlChange', 'programChange', 'pitchBend', 'channelPressure', 'perNoteController', 'registeredController', 'assignedController', 'systemExclusive', 'rawUmp', 'sequence', 'goToPage', 'mackieControl'
$numbered = 'note', 'controlChange', 'programChange', 'perNoteController', 'registeredController', 'assignedController'

$pageWidth = $layout.pageWidth ?? 1280
$pageHeight = $layout.pageHeight ?? 800
$devices = @($layout.devices | ForEach-Object { $_.name })
$pageIds = @($layout.pages | ForEach-Object { $_.id })
$sequences = @($layout.sequences | ForEach-Object { $_.name })
$controlIds = [Collections.Generic.HashSet[string]]::new([StringComparer]::Ordinal)

if ($null -eq $layout.themeColors -and $layout.theme -cnotin $themes) { $problems.Add("'$($layout.theme)' isn't a built-in theme. Unless that theme file is installed, the customer sees Studio Dark.") }
if ($pageIds.Count -eq 0) { $problems.Add('The layout has no pages.') }
foreach ($name in ($devices | Group-Object -CaseSensitive | Where-Object Count -gt 1).Name) { $problems.Add("Two devices are named '$name'.") }
foreach ($id in ($pageIds | Group-Object -CaseSensitive | Where-Object Count -gt 1).Name) { $problems.Add("Two pages have the id '$id'.") }
foreach ($name in ($sequences | Group-Object -CaseSensitive | Where-Object Count -gt 1).Name) { $problems.Add("Two sequences are named '$name'.") }

foreach ($page in $layout.pages) {
    foreach ($c in $page.controls) {
        $where = "'$($c.label)' ($($c.id)) on page '$($page.name)'"
        if (-not $c.id -or -not $controlIds.Add($c.id)) { $problems.Add("$where needs an id of its own.") }
        if ($c.kind -cnotin $controlKinds) { $problems.Add("$where has the kind '$($c.kind)', which MIDI Glass opens as a knob.") }
        if (-not $c.label) { $problems.Add("$where has no label, so a screen reader can't name it.") }
        $x = $c.x ?? 0; $y = $c.y ?? 0; $w = $c.width ?? 56; $h = $c.height ?? 56
        if ($w -le 0 -or $h -le 0) { $problems.Add("$where has no size.") }
        elseif ($x -lt 0 -or $y -lt 0 -or ($x + $w) -gt $pageWidth -or ($y + $h) -gt $pageHeight) { $problems.Add("$where hangs off the page, so it won't show when the layout runs.") }
        $slot = $c.hueSlot ?? 0
        if ($slot -lt -1 -or $slot -gt 6 -or ($slot -eq -1 -and -not $c.literalColor)) { $problems.Add("$where needs a hueSlot from 0 to 6, or -1 with a literalColor.") }
        foreach ($m in $c.messages) {
            $kind = $m.kind ?? 'controlChange'
            if ($kind -cnotin $messageKinds) { $problems.Add("$where sends '$kind', which isn't a message kind."); continue }
            if (($m.trigger ?? 'changes') -cnotin @('turnsOn', 'turnsOff', 'changes', 'touched', 'released')) { $problems.Add("$where has the trigger '$($m.trigger)'.") }
            if ($kind -ceq 'goToPage') { if ($m.targetPage -cnotin $pageIds) { $problems.Add("$where goes to a page that isn't in the layout.") }; continue }
            if ($kind -ceq 'sequence') { if ($m.sequence -cnotin $sequences) { $problems.Add("$where runs a sequence that isn't in the layout.") }; continue }
            if (-not $m.device) { $problems.Add("$where has a row with no device, so the row sends nothing.") }
            elseif ($m.device -cnotin $devices) { $problems.Add("$where sends to '$($m.device)', which isn't in devices.") }
            if (($m.group ?? 0) -notin -1..15 -or ($m.channel ?? 0) -notin 0..15) { $problems.Add("$where has a group or a channel outside 0 to 15. The file counts from 0.") }
            $limit = if ($kind -cin @('registeredController', 'assignedController')) { 16383 } else { 127 }
            if (($kind -cin $numbered) -and ($m.number ?? 0) -notin 0..$limit) { $problems.Add("$where has the number $($m.number), outside 0 to $limit.") }
            if ($kind -ceq 'rawUmp' -and $c.kind -cne 'beatClock') {
                $words = @($m.words)
                if ($words.Count -notin 1..4 -or @($words | Where-Object { $_ -is [string] -or $_ -lt 0 -or $_ -gt 4294967295 }).Count -gt 0) { $problems.Add("$where needs one to four words, written as decimal numbers.") }
            }
            if ($kind -ceq 'systemExclusive' -and $m.systemExclusive -notmatch '^([0-9A-Fa-f]{2})+$') { $problems.Add("$where needs its bytes as hexadecimal text with no spaces, like F07E7F0601F7.") }
        }
        if ($c.feedback.enabled -and $c.feedback.device -and $c.feedback.device -cnotin $devices) { $problems.Add("$where listens to '$($c.feedback.device)', which isn't in devices.") }
    }
}

if ($problems.Count -gt 0) { $problems; exit 1 }
'No problems found.'

A file that passes can still send the wrong controller. Only the manual and the customer can tell you that.

7. Show the customer a mockup

Show the customer what they’ll get before you hand it over, and ask them to confirm the controls, the names, the colors, and what each one sends. Draw the mockup from the file you wrote, using its own positions and sizes, so what they approve is what they get.

If MIDI Glass is installed and you can run commands, it can draw the first page for you:

midiglass --thumbnail "<layout file>" "<picture.png>" 1600

The last number is the width of the picture in pixels. The picture shows the page in the layout’s theme, with each control as an outline in its color. It doesn’t show names or values, so it’s a check on positions and colors rather than a finished picture. It’s drawn without opening a window or touching any device. The command returns 0 when it works, 2 when an argument is missing, 3 when the file can’t be read as a layout, and 4 when the picture can’t be written.

The real thing is better still: midiglass --run "<layout file>" opens the layout in MIDI Glass, so the customer can look at every page and try it. Opening it sends nothing until a control is touched, unless a control is set to send its value when the layout starts, or a beat clock, LFO, or Steps control is set to start running.

If you’re an online chat, draw the mockup yourself as HTML, SVG, or a picture. This page draws every page of a layout file in Studio Dark’s colors. Paste the whole layout file where it says, and change the six colors to your theme’s if you know them:

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<title>Layout mockup</title>
<style>
  body { margin: 24px; background: #2B2B2B; color: #E8EAED; font: 14px "Segoe UI", sans-serif; }
  .page { position: relative; overflow: hidden; margin: 8px 0 32px; background: radial-gradient(ellipse 65% 100% at 50% -10%, #1D1E21, #121316 58%, #07080A); }
  .control { position: absolute; box-sizing: border-box; border: 1px solid; border-radius: 7px; background: rgba(23, 24, 27, 0.86); }
  .round { border-radius: 50%; }
  .panel { background: rgba(23, 24, 27, 0.45); }
  .bare { border-color: transparent !important; background: none; }
  .name { position: absolute; left: -40px; right: -40px; text-align: center; color: #D7DAE0; font: 12px "Segoe UI Variable Text", "Segoe UI", sans-serif; }
  .caption { left: 10px; right: auto; text-align: left; }
</style>
<p>A mockup drawn from the layout file. It isn't a MIDI Glass screenshot.</p>
<div id="pages"></div>
<script type="application/json" id="layout">
PASTE THE WHOLE LAYOUT FILE HERE
</script>
<script>
  const layout = JSON.parse(document.getElementById('layout').textContent);
  const slots = ['#4FC3F7', '#81C784', '#FFC247', '#FF7043', '#BA68C8', '#4DD0E1'];   // Studio Dark, slots 0 to 5
  const round = ['knob', 'turntable', 'joystick', 'lamp'];
  const width = layout.pageWidth ?? 1280, height = layout.pageHeight ?? 800;
  const scale = Math.min(1, 1200 / width);
  for (const page of layout.pages) {
    const heading = document.createElement('h2');
    heading.textContent = page.name || page.id;
    const host = document.createElement('div');
    host.className = 'page';
    Object.assign(host.style, { width: width * scale + 'px', height: height * scale + 'px' });
    for (const c of page.controls ?? []) {
      const slot = c.hueSlot ?? 0;
      const box = document.createElement('div');
      box.className = 'control' + (round.includes(c.kind) ? ' round' : '') + (c.kind === 'panel' ? ' panel' : '') + (c.style === 'bare' ? ' bare' : '');
      Object.assign(box.style, {
        left: c.x * scale + 'px', top: c.y * scale + 'px',
        width: (c.width ?? 56) * scale + 'px', height: (c.height ?? 56) * scale + 'px',
        borderColor: slot === -1 ? c.literalColor : (slots[slot] ?? slots[0])
      });
      const placed = c.labelPlaced ?? (c.kind === 'panel' ? 'inside' : 'below');
      if (c.label && placed !== 'none') {
        const name = document.createElement('div');
        name.className = 'name' + (c.kind === 'panel' ? ' caption' : '');
        name.textContent = c.label;
        name.style.top = placed === 'above' ? '-18px' : placed.startsWith('inside') ? '6px' : 'calc(100% + 4px)';
        box.append(name);
      }
      host.append(box);
    }
    document.getElementById('pages').append(heading, host);
  }
</script>
</html>

Beside the mockup, list what each control sends in plain words, such as “Cutoff: CC 74 on channel 1” or “Filter: NRPN 7:54 on channel 1”. Customers check that list more carefully than the picture.

Label the mockup as a mockup. A theme draws much more than outlines: knob arcs, fader caps, lights, and textures. If the customer wants to see the real thing, they can open the file in MIDI Glass and look before they play it.

8. Hand it over

Tell the customer how to get the file into MIDI Glass, using Where layout files go, and how to bring one in. Then tell them:

• Which device each name in the layout stands for, and how to point it at different hardware if a device shows as missing: open the layout in the editor, select Layout… > Pages and devices… > Outputs, and pick the device.
• What the layout can’t do that they asked for, and what you did instead.
• Where each number came from, so they can check it against the manual.

Where layout files go, and how to bring one in

MIDI Glass keeps its layouts in Documents › MIDI Layouts, one .midilayout file per layout. The library shows every layout file in that folder. A picture or a video a layout uses sits next to it, in the same folder.

• The Documents folder isn’t always C:\Users\<name>\Documents. On many PCs it has been moved into OneDrive. In File Explorer, select Documents and look for MIDI Layouts there.
• To add a layout to the library, copy its file into that folder. MIDI Glass reads the folder when it starts, so if it’s already open, close it and open it again to see the new layout.
• To try a layout without adding it, double-click the file in File Explorer, or select Open a file… in the MIDI Glass library. It runs in its own window from wherever the file is. The first time you double-click one, Windows asks which app to open it with: pick MIDI Glass.
• A layout with pictures travels as a .zip package. In the library, select … (More options) > Import a layout package…. Make one in MIDI Glass with Package for another PC… on a card’s … menu. A package holds its files without compression, and MIDI Glass refuses a zip whose files are compressed, which is what most zip tools do. So rather than making a package yourself, give the customer the layout file and its pictures, and ask them to put them all in the layouts folder.
• Older versions of MIDI Glass named layout files .midilayout.json. The app still reads those, and renames them to .midilayout when it starts.
• Themes live in Documents › MIDI Layouts › Themes. See Where theme files live.

System exclusive. A layout opened from outside the layouts folder asks before it sends system exclusive, because the wrong system exclusive can harm a device. If your layout sends system exclusive, give the customer the file outside the layouts folder, such as in Downloads, so they see that question the first time. They can copy it into the folder once they trust it.

What MIDI Glass can’t do

Tell the customer about these before they find out on their own.

• A control can’t change what another control sends. There’s no “selected articulation” that a keyboard follows, and no shift button that changes what the knobs do. A button can run a sequence that moves another control to a value, and a beat clock can take its tempo from a knob, but that’s all. Use more pages, or more controls, instead.
• Keyboards and pads play plain notes. They can’t add a MIDI 2.0 note attribute, such as an articulation, to the notes they play. A button can send one complete MIDI 2.0 note on, attribute and all, with a raw message, and another to end it.
• A per-note controller row always uses controller 0. For any other per-note controller, use a raw message.
• Nothing shows text from a device. A readout shows a value, and a meter and a lamp show levels and activity. There’s no track name, no patch name, and no list of messages on a running page.
• No MIDI-CI. MIDI Glass can’t turn a profile on, or ask a device what it supports.
• No logic. No conditions, no variables, and no scripts.
• Mackie Control is partial. MIDI Glass doesn’t speak HUI, doesn’t answer the handshake some DAWs use to find a surface, and doesn’t show the DAW’s meters, V-Pot rings, or display text.
• Saved, but not working yet. These settings are kept in the file but don’t do anything yet, so leave them out: a page’s sharedBand, the layout’s publishesVirtualDevice and preferredDisplayId, a tempo that follows incoming clock, a device’s sendsBeatClock, any pickup other than jump, holdLayer messages and sequence steps, and a keyboard’s showNoteNames.

The layout file

A complete example

This layout has a section with two knobs, a volume fader, a pitch wheel, a hold toggle, and a pad that plays middle C. It sends to the built-in Default App Loopback (A), so you can try it on any PC with Windows MIDI Services: open MIDI Monitor on Default App Loopback (B) and watch what it sends. For a real device, change the name in match.

{
  "fileVersion": 1,
  "name": "Synth basics",
  "description": "Filter, volume, pitch bend, hold, and a pad for one synth.",
  "pageWidth": 1280,
  "pageHeight": 800,
  "canvasWidth": 1280,
  "canvasHeight": 800,
  "theme": "Studio Dark",
  "scaleMode": "fitToScreen",
  "devices": [
    {
      "name": "Synth",
      "match": { "transportSuppliedEndpointName": "Default App Loopback (A)" },
      "matchMode": "endpointName"
    }
  ],
  "pages": [
    {
      "id": "main",
      "name": "Main",
      "controls": [
        {
          "id": "filter-section", "kind": "panel", "label": "Filter",
          "x": 48, "y": 48, "width": 368, "height": 264,
          "hueSlot": 0, "labelPlaced": "inside", "keyboardOrder": 1
        },
        {
          "id": "cutoff", "kind": "knob", "label": "Cutoff",
          "x": 80, "y": 112, "width": 120, "height": 120,
          "hueSlot": 0, "aspectLocked": true, "keyboardOrder": 2,
          "messages": [
            { "trigger": "changes", "kind": "controlChange", "device": "Synth", "group": 0, "channel": 0, "number": 74 }
          ]
        },
        {
          "id": "resonance", "kind": "knob", "label": "Resonance",
          "x": 264, "y": 112, "width": 120, "height": 120,
          "hueSlot": 0, "aspectLocked": true, "keyboardOrder": 3,
          "messages": [
            { "trigger": "changes", "kind": "controlChange", "device": "Synth", "group": 0, "channel": 0, "number": 71 }
          ]
        },
        {
          "id": "volume", "kind": "fader", "label": "Volume",
          "x": 464, "y": 48, "width": 56, "height": 264,
          "hueSlot": 1, "defaultValue": 0.8, "keyboardOrder": 4,
          "messages": [
            { "trigger": "changes", "kind": "controlChange", "device": "Synth", "group": 0, "channel": 0, "number": 7 }
          ]
        },
        {
          "id": "bend", "kind": "wheel", "label": "Bend",
          "x": 568, "y": 48, "width": 56, "height": 264,
          "hueSlot": 4, "defaultValue": 0.5, "returnsToDefault": true, "keyboardOrder": 5,
          "messages": [
            { "trigger": "changes", "kind": "pitchBend", "device": "Synth", "group": 0, "channel": 0 }
          ]
        },
        {
          "id": "hold", "kind": "toggle", "label": "Hold",
          "x": 48, "y": 376, "width": 136, "height": 56,
          "hueSlot": 2, "keyboardOrder": 6,
          "messages": [
            { "trigger": "turnsOn", "kind": "controlChange", "device": "Synth", "group": 0, "channel": 0, "number": 64 },
            { "trigger": "turnsOff", "kind": "controlChange", "device": "Synth", "group": 0, "channel": 0, "number": 64 }
          ]
        },
        {
          "id": "middle-c", "kind": "pad", "label": "C4",
          "x": 232, "y": 376, "width": 96, "height": 96,
          "hueSlot": 3, "aspectLocked": true, "keyboardOrder": 7,
          "messages": [
            { "trigger": "turnsOn", "kind": "note", "device": "Synth", "group": 0, "channel": 0, "number": 60 },
            { "trigger": "turnsOff", "kind": "note", "device": "Synth", "group": 0, "channel": 0, "number": 60 }
          ]
        }
      ]
    }
  ],
  "sequences": []
}

The tables below list every setting. If left out is what MIDI Glass uses when a file doesn’t have the key.

The top level

_comment is ignored. Any other key MIDI Glass doesn’t know is kept and written back, but it doesn’t do anything.

Devices

Matching a device by name. You can’t know a device’s ID, so match by name:

{ "name": "Synth", "match": { "transportSuppliedEndpointName": "Prophet Rev2" }, "matchMode": "endpointName" }

MIDI Glass compares the name in match with each device’s own name and with the name Windows shows for it, which the customer may have changed in MIDI Settings. Capital letters don’t matter, but everything else must be the same. If match has no name, it compares the device’s name instead. When MIDI Glass saves a device the customer picked, match also holds the device’s ID and USB details, which is how it tells two identical devices apart.

Pages

Controls

These keys work on every kind of control.

Some kinds have one more block of settings. See Settings for some kinds of control.

Messages

Each row in messages says when the control sends, what it sends, and where.

The message kinds are note, controlChange, programChange, pitchBend, channelPressure, perNoteController, registeredController (an RPN), assignedController (an NRPN), systemExclusive, rawUmp, sequence, goToPage, and mackieControl.

When each trigger sends:

• A changes row is sent whenever the control moves, at the control’s position between minimum and maximum. On a button, a toggle, or a pad, it sends the maximum when the control turns on and the minimum when it turns off.
• A turnsOn row is sent when a button, toggle, or pad turns on, and sends its maximum. A turnsOff row is sent when it turns off, and sends its minimum.
• A touched row is sent when a finger first touches the control, and sends its maximum. A released row is sent when the finger lets go, and sends its minimum.
• Rows on the same trigger go out in the order they’re listed.

What each kind of control usually sends. These are the rows MIDI Glass gives a new control. Copy their shape.

Values

The two ends of a row, minimum and maximum, are each an object with a value and a scaling. A control at rest sends the minimum, a control at full travel sends the maximum, and anything between is in proportion. Leave both out for the full range.

• fraction is a share of the full range, from 0 to 1. It works on MIDI 1.0 and MIDI 2.0 devices alike, so use it unless you have a reason not to. To send exactly 100 out of 127, write 100 ÷ 127, about 0.7874. MIDI Glass rounds to the nearest step.
• absolute is the exact number that goes on the wire. Its range depends on the message: 0 to 127 for a MIDI 1.0 note velocity, controller, or channel pressure; 0 to 16383 for MIDI 1.0 pitch bend; 0 to 65535 for a MIDI 2.0 note velocity; and 0 to 4294967295 for every other MIDI 2.0 value.
• A row goes out as MIDI 1.0 when its device’s protocol is midi1, or when the row has "midi1Protocol": true. That only applies to notes, controllers, program changes, pitch bend, and channel pressure. RPNs, NRPNs, and per-note controllers always go out as MIDI 2.0, and Windows converts them for a MIDI 1.0 device. Every other row goes out as MIDI 2.0, and Windows converts it for a MIDI 1.0 device too.
• When a value is a code, such as a pad color where 5 is red and 21 is green, set the device’s protocol to midi1 and write the code as an absolute value, so the device gets exactly that number.
• A minimum above the maximum turns the control upside down.
• A note is on when its value is at least half way, and off below that. A turnsOn row plays the note at the maximum velocity, and a turnsOff row sends a note off with the minimum as its release velocity.
• A program change sends its number. Its value doesn’t matter.

For agents: Don’t write absolute values for a MIDI 2.0 device unless you mean MIDI 2.0 numbers. "value": 127 with absolute on a MIDI 2.0 controller is 127 out of 4294967295, which is next to nothing.

Stops

detents gives a control stops, like a selector:

• { "mode": "evenSteps", "scaling": "fraction", "step": 0.25 } stops at 0, 25, 50, 75, and 100 percent.
• { "mode": "explicitValues", "scaling": "absolute", "stops": [ 10, 17, 38, 39, 40, 57 ] } stops at exactly those values. Each stop gets an equal share of the travel, wherever its value falls.
• "mode": "continuous" is no stops, the same as leaving detents out.

step and stops use the same units as scaling.

Listening

A control with a feedback block moves or lights up when a device sends something, not only when it’s touched. That’s how a fader follows a DAW, and how a lamp shows activity.

"feedback": { "enabled": true, "mode": "message", "kind": "controlChange", "device": "DAW", "group": 0, "channel": 0, "number": 7 }

Settings for some kinds of control

Mono keyboard, in keyboard:

Note pads and hex pads, in pads:

Switch, in switch: { "positions": [ "Saw", "Square", "Sine" ] }, two to sixteen names, first to last. Give the switch one row per position:

"switch": { "positions": [ "Saw", "Square", "Sine" ] },
"messages": [
  { "trigger": "changes", "kind": "controlChange", "device": "Synth", "number": 70, "position": 0, "maximum": { "value": 0, "scaling": "fraction" } },
  { "trigger": "changes", "kind": "controlChange", "device": "Synth", "number": 70, "position": 1, "maximum": { "value": 0.5, "scaling": "fraction" } },
  { "trigger": "changes", "kind": "controlChange", "device": "Synth", "number": 70, "position": 2, "maximum": { "value": 1, "scaling": "fraction" } }
]

Steps, in sequencer:

LFO, in lfo:

Beat clock, in clock:

Turntable, in turntable: degreesForFullRange, 15 to 1440 with 180 if left out, is how far the platter turns for its full range, and showsGrip, true if left out, draws ridges around its edge.

Line, in line: thickness, 1 to 64 with 1 if left out; color as #RRGGBB, the theme’s if left out; and ends, which is useTheme, square, or faded. A line runs the long way across its rectangle. Give it "labelPlaced": "none".

Image, in picture:

A Group can carry a picture too, which fills its frame.

Names and looks

Sequences

A sequence is a list of steps that a button runs, in sequences at the top of the file. A control runs it with a row of kind sequence.

This button selects bank 0, then program 12 as a manual counts it, then sets the volume:

"sequences": [
  {
    "name": "Load patch 12",
    "mode": "once",
    "steps": [
      { "kind": "sendMessage", "message": { "kind": "controlChange", "device": "Synth", "number": 0, "maximum": { "value": 0, "scaling": "fraction" } } },
      { "kind": "sendMessage", "message": { "kind": "programChange", "device": "Synth", "number": 11 } },
      { "kind": "wait", "waitMilliseconds": 50 },
      { "kind": "sendMessage", "message": { "kind": "controlChange", "device": "Synth", "number": 7, "maximum": { "value": 0.7874, "scaling": "fraction" } } }
    ]
  }
]

{
  "id": "patch-12", "kind": "button", "label": "Patch 12",
  "x": 48, "y": 520, "width": 136, "height": 56, "keyboardOrder": 8,
  "messages": [ { "trigger": "turnsOn", "kind": "sequence", "sequence": "Load patch 12" } ]
}

Pages and page tabs

Every page needs a tab for every page, so the customer can get back. A tab’s id has to be unique, so the copies on each page need ids of their own.

"pages": [
  {
    "id": "play", "name": "Play",
    "controls": [
      { "id": "play-tab-play", "kind": "pageTab", "label": "Play", "x": 48, "y": 16, "width": 120, "height": 36, "keyboardOrder": 1,
        "messages": [ { "trigger": "turnsOn", "kind": "goToPage", "targetPage": "play" } ] },
      { "id": "play-tab-mix", "kind": "pageTab", "label": "Mix", "x": 176, "y": 16, "width": 120, "height": 36, "keyboardOrder": 2,
        "messages": [ { "trigger": "turnsOn", "kind": "goToPage", "targetPage": "mix" } ] }
    ]
  },
  {
    "id": "mix", "name": "Mix",
    "controls": [
      { "id": "mix-tab-play", "kind": "pageTab", "label": "Play", "x": 48, "y": 16, "width": 120, "height": 36, "keyboardOrder": 1,
        "messages": [ { "trigger": "turnsOn", "kind": "goToPage", "targetPage": "play" } ] },
      { "id": "mix-tab-mix", "kind": "pageTab", "label": "Mix", "x": 176, "y": 16, "width": 120, "height": 36, "keyboardOrder": 2,
        "messages": [ { "trigger": "turnsOn", "kind": "goToPage", "targetPage": "mix" } ] }
    ]
  }
]

System exclusive

Write the bytes as hexadecimal text with no spaces, in systemExclusive, with or without the F0 at the start and the F7 at the end: "systemExclusive": "F07E7F0601F7". Every byte between them must be 7F or below. A message can be up to 512 kilobytes.

Raw messages

A rawUmp row sends one to four 32-bit words exactly as written. It’s how a button sends a message MIDI Glass has no row for, such as a MIDI 2.0 note on with an attribute.

• The words are decimal numbers. JSON has no hexadecimal, so 0x40903C02 must be written as 1083194370. In PowerShell, [Convert]::ToUInt32('40903C02', 16) does the conversion.
• The words carry their own group and channel. The row’s group and channel aren’t used, but its device is.

This pad sends a MIDI 2.0 note on for middle C on group 1 and channel 1, at velocity C000, with attribute type 02 and attribute data 0001, and ends it with a note off. Attribute type 02 means a profile, such as one for orchestral articulations, decides what the data means. Take the attribute type and data from the device’s manual or the profile’s specification.

{
  "id": "articulation-pad", "kind": "pad", "label": "Middle C, attribute 1",
  "x": 48, "y": 600, "width": 96, "height": 96, "aspectLocked": true, "keyboardOrder": 9,
  "messages": [
    { "trigger": "turnsOn", "kind": "rawUmp", "device": "Synth", "words": [ 1083194370, 3221225473 ] },
    { "trigger": "turnsOff", "kind": "rawUmp", "device": "Synth", "words": [ 1082145792, 0 ] }
  ]
}

Those words are 40903C02 C0000001 and 40803C00 00000000.

Mackie Control functions

To control a DAW set up for a Mackie Control surface, give its device "protocol": "mackieControl", and give each control one changes row of kind mackieControl with a function instead of a number: { "trigger": "changes", "kind": "mackieControl", "device": "DAW", "function": "play" }. The function sends the press and the release, or the position and the touch, by itself. How to control your DAW with Mackie Control in MIDI Glass explains the DAW side.

Limits

MIDI Glass reads a layout up to 16 megabytes, with up to 64 pages, 1,024 controls on a page, 32 rows on a control, 32 devices, and 256 sequences of up to 512 steps. Text is cut off at 1,024 characters. Anything past a limit is dropped.

Mistakes that are easy to miss

For agents: Each of these loads without an error and gives the customer the wrong layout.

• A group or a channel is counted from 1. Channel 10 is 9 in the file.
• A program is counted from 1. Program 1 is 0 in the file.
• An NRPN or RPN is written as the LSB alone, or as two rows of CC 99 and CC 98. Write one assignedController or registeredController row with MSB × 128 + LSB.
• A theme name is misspelled or wrongly capitalized, such as Studio dark, so the customer sees Studio Dark anyway, or high contrast and they see Studio Dark instead of High contrast.
• A device in match is a name that’s only close to the real one, so the device shows as missing.
• A message names a device that isn’t in devices, or spells it differently, so it sends nothing.
• A button, toggle, or pad has a turnsOn note row but no turnsOff row, so the note never ends.
• The turnsOn and turnsOff rows of a pair have different notes, channels, or devices, so the note off goes somewhere else and the note keeps playing.
• A value for a MIDI 2.0 device is written as an absolute 0 to 127, so it’s next to nothing.
• A hexadecimal number is written in JSON, such as 0x40903C02 or "40903C02" in words. Only decimal numbers work.
• A control hangs off the edge of the page, so it doesn’t show.
• A Group is listed after the controls it frames, so it’s drawn over them.
• Two controls share an id, often page tabs copied from one page to the next.
• A control has no label, so a screen reader has nothing to say.
• A control’s kind is misspelled, such as xypad or slider, so it opens as a knob.
• A picture is named by a path. Only a plain file name, of a file next to the layout, is used.
• A control is set to send its value when the layout opens, and it’s a volume at 0, which mutes the device the moment the layout opens.
• The layout depends on something in What MIDI Glass can’t do.