MOD Pedalboard Extension

http://moddevices.com/ns/modpedal#

Overview

The modpedal: namespace defines the vocabulary used in pedalboard files — the LV2 bundles that describe a saved plugin graph on a MOD device or the MOD Desktop application.

A pedalboard is stored as an LV2 bundle on disk. Its root resource is declared as a modpedal:Pedalboard, and the individual plugin instances within it each carry modpedal:instanceNumber and optionally modpedal:preset annotations. Canvas dimensions, the unit that wrote the file and the file's format version are stored on the root resource.

Two kinds of information live in a pedalboard file: what the plugin author declared (read from the plugin's own TTL, and never copied into modpedal: terms) and what the user did in this pedalboard — placement, presets, ordering, naming. Every modpedal: property describes the second kind. A per-instance annotation made by the user therefore belongs here, not in mod:, which describes the plugin as shipped.

Note for tool authors: Pedalboard files are written and read by the MOD platform (mod-ui / mod-host). Plugin developers do not write pedalboard files — this namespace is documented here for the benefit of developers building tools that read or generate pedalboard bundles (e.g. exporters, converters, backup tools).

Prefixes

@prefix modpedal: <http://moddevices.com/ns/modpedal#> .
@prefix lv2:      <http://lv2plug.in/ns/lv2core#> .
@prefix ingen:    <http://drobilla.net/ns/ingen#> .
@prefix rdfs:     <http://www.w3.org/2000/01/rdf-schema#> .
@prefix midi:     <http://lv2plug.in/ns/ext/midi#> .
@prefix mod:      <http://moddevices.com/ns/mod#> .

Class

Class	Description
`modpedal:Pedalboard`	The RDF type of a pedalboard resource. Every pedalboard bundle declares its root resource as `a modpedal:Pedalboard , lv2:Plugin`. The `lv2:Plugin` typing allows the bundle to be discovered by standard LV2 tooling.

Properties on the Pedalboard resource

Property	Type	Description
`modpedal:formatVersion`	integer	Version of the file format: which `modpedal:` terms a writer of this file may have used. See Format versions. Absent means 1. Written from MOD OS 1.15 on.
`modpedal:version`	integer	Save counter of this pedalboard: starts at 0 and increases by one every time the pedalboard is saved. It says nothing about the file format — use `modpedal:formatVersion` for that. (Earlier revisions of this page described it as a format version; that was wrong.)
`modpedal:width`	integer	Width of the pedalboard canvas in pixels, as set by the user. Determines the scrollable area of the pedalboard editor.
`modpedal:height`	integer	Height of the pedalboard canvas in pixels, as set by the user.
`modpedal:unitName`	string	Marketing name of the unit that saved the file, for example `"MOD Dwarf"`.
`modpedal:unitModel`	string	Model identifier of the unit that saved the file, for example `"dwarf"`.
`modpedal:addressings`	URI (relative)	The JSON file holding hardware and MIDI addressings of this pedalboard, always `<addressings.json>` next to the main TTL.
`modpedal:screenshot`, `modpedal:thumbnail`	URI (relative)	Rendered images of the pedalboard canvas, `<screenshot.png>` and `<thumbnail.png>` in the bundle. May be missing until the first screenshot is generated.

Properties on plugin instance blocks

Each plugin instance in the pedalboard graph is represented as an ingen:Block resource. The following modpedal: properties are used on these block resources.

Property	Type	Description
`modpedal:instanceNumber`	integer	Unique integer identifier for this plugin instance within the pedalboard. Used internally to route control messages between mod-ui and mod-host. Assigned sequentially starting from 0 when the plugin is added to the pedalboard. Must be unique across all instances in a pedalboard.
`modpedal:preset`	URI	The URI of the LV2 preset currently active on this plugin instance. If absent or empty, no preset is loaded (the plugin uses its current port values).
`modpedal:instanceLabel`	string	Name the user gave to this plugin instance, shown instead of the plugin's own name in the pedalboard editor and on the device. Absent means the plugin's name is used. This is not `mod:label`, which is the short display name set by the plugin author and is never written into pedalboard files. Format 2 (MOD OS 1.15).
`modpedal:performanceVisible`	boolean	Whether this instance is shown in the performance view. Absent means visible. Format 2 (MOD OS 1.15).
`modpedal:performanceIndex`	integer	Position of this instance in the performance view, lowest first. Absent means "after every instance that has one", in `modpedal:instanceNumber` order. Format 2 (MOD OS 1.15).

MIDI bindings on control ports

A control port bound to MIDI carries a midi:binding blank node of type midi:Controller, using the standard LV2 MIDI vocabulary plus the port range:

</graph/gain/gain>
    ingen:value 0.5 ;
    midi:binding [
        a midi:Controller ;
        midi:channel 0 ;
        midi:controllerNumber 7 ;
        lv2:minimum -20.0 ;
        lv2:maximum 20.0 ;
    ] ;
    a lv2:ControlPort , lv2:InputPort .

How MOD reads midi:controllerNumber. Values 0–127 are a 7-bit Control Change number. The value 131 means pitch bend (MOD OS 1.13 and later; the platform has no separate property for it). No other value is defined by this revision of the page.

Format versions

modpedal:formatVersion is an integer that says which modpedal: terms the writer of the file was allowed to use. It is assigned on this page and bumped whenever a term is added to the set a MOD platform writes. A reader that finds a number higher than its own should tell the user that the file was made on a newer version and that saving it will drop what this version does not know; a number equal or lower loads silently.

Writers never preserve terms they do not know: a pedalboard file is regenerated from the running state on every save. Terms outside this page (third-party vocabulary) are therefore lost when the file is saved by a platform that does not implement them.

Format	Written by	Terms added
`1` (or absent)	MOD OS up to 1.14	Everything on this page except the rows marked "Format 2".
`2`	MOD OS 1.15	`modpedal:formatVersion`, `modpedal:instanceLabel`, `modpedal:performanceVisible`, `modpedal:performanceIndex`.

Example pedalboard TTL

@prefix modpedal: <http://moddevices.com/ns/modpedal#> .
@prefix ingen:    <http://drobilla.net/ns/ingen#> .
@prefix lv2:      <http://lv2plug.in/ns/lv2core#> .
@prefix rdfs:     <http://www.w3.org/2000/01/rdf-schema#> .
@prefix midi:     <http://lv2plug.in/ns/ext/midi#> .

<>
    a modpedal:Pedalboard , lv2:Plugin ;
    rdfs:label "My Pedalboard" ;
    modpedal:formatVersion 2 ;
    modpedal:version 7 ;
    modpedal:width   3200 ;
    modpedal:height  1200 ;
    ingen:block
        </graph/gain> ,
        </graph/reverb> .

</graph/gain>
    a ingen:Block ;
    lv2:prototype <http://example.com/plugins/my-gain> ;
    modpedal:instanceNumber 0 ;
    modpedal:instanceLabel "Clean boost" ;
    modpedal:performanceVisible true ;
    modpedal:performanceIndex 0 ;
    ingen:enabled true ;
    ingen:canvasX 200.0 ;
    ingen:canvasY 300.0 .

</graph/reverb>
    a ingen:Block ;
    lv2:prototype <http://example.com/plugins/my-reverb> ;
    modpedal:instanceNumber 1 ;
    modpedal:preset <http://example.com/plugins/my-reverb/presets/hall> ;
    modpedal:performanceVisible false ;
    ingen:enabled true ;
    ingen:canvasX 500.0 ;
    ingen:canvasY 300.0 .