MOD GUI Extension

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

Overview

The modgui: namespace defines the vocabulary for attaching a graphical user interface to an LV2 plugin. A plugin with a modgui:gui declaration will display a custom HTML/CSS icon on the MOD pedalboard canvas instead of the generic plugin icon.

The GUI is declared in a separate modgui.ttl file inside the plugin bundle, referenced from manifest.ttl via rdfs:seeAlso. The actual GUI files (HTML, CSS, images) live in a subdirectory of the bundle, typically named modgui/.

All GUI metadata is nested inside a blank node attached to the plugin via modgui:gui. Properties marked required must be present for the GUI to load. All others are optional.

Prefixes

@prefix modgui: <http://moddevices.com/ns/modgui#> .
@prefix lv2:    <http://lv2plug.in/ns/lv2core#> .
@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .

Bundle Setup

In your manifest.ttl, add a reference to modgui.ttl:

<http://example.com/plugins/my-plugin>
    a lv2:Plugin ;
    lv2:binary <my-plugin.so> ;
    rdfs:seeAlso <my-plugin.ttl> ,
                 <modgui.ttl> .

Properties

Top-level

Property	Used on	Description
`modgui:gui` required	Plugin resource	Blank node containing all GUI metadata for this plugin. The plugin resource must have exactly one `modgui:gui` declaration.

File references (inside the gui blank node)

Property	Type	Description
`modgui:resourcesDirectory` required	path	Path to the directory containing all GUI assets, relative to the bundle root. Conventionally named `modgui`. All other file references should point to files inside this directory.
`modgui:iconTemplate` required	path	Path to the HTML template file rendered as the plugin icon on the pedalboard canvas. This is the primary visual representation of the plugin. The template has access to port values via JavaScript and can include interactive controls.
`modgui:stylesheet`	path	Path to a CSS file applied to the icon template. Scoped to the plugin icon element.
`modgui:javascript`	path	Path to a JavaScript file loaded alongside the icon template. Use for custom control behaviour beyond what the standard template variables provide.
`modgui:settingsTemplate`	path	Path to an HTML template rendered in the plugin settings panel (opened via the gear icon). Use when the settings panel should differ from the icon template. If absent, the settings panel uses the icon template.
`modgui:screenshot`	path	Path to a full-size PNG image of the rendered plugin icon. Used in the plugin store and listing pages as a static preview. Dimensions should match the actual rendered icon size.
`modgui:thumbnail`	path	Path to a small PNG thumbnail of the plugin icon. Used in search results, plugin lists, and other compact display contexts. Recommended size: 256×256 px or smaller.
`modgui:knob`	path	Path to a custom knob image used when the icon template uses the standard knob widget. The image should be a sprite sheet or single frame compatible with the MOD knob rendering system. ⚠ TODO (Filipe): confirm expected image format and dimensions.
`modgui:panel`	path	Path to the panel background image for the plugin icon. ⚠ TODO (Filipe): confirm whether this is still actively used.

Display metadata (inside the gui blank node)

Property	Type	Description
`modgui:brand`	string	Brand name displayed on the plugin icon, overriding the plugin-level `mod:brand` for GUI display purposes.
`modgui:label`	string	Plugin label displayed on the plugin icon, overriding `mod:label` for GUI display purposes.
`modgui:color`	string	Accent color for this plugin in the MOD plugin store, expressed as a CSS hex color string (e.g. `"#3a7bd5"`). Used for store cards and category display.
`modgui:model`	string	⚠ TODO (Filipe): confirm purpose and whether this is still active.
`modgui:documentation`	URI or path	URL or path to documentation for this plugin. Displayed as a "docs" link in the plugin information panel.
`modgui:discussionURL`	URI	URL to a forum thread or discussion page for this plugin. Displayed as a community link in the plugin information panel.

Port declarations (inside the gui blank node)

Property	Type	Description
`modgui:port`	blank node list	Declares the control ports exposed in the GUI. Each entry is a blank node with `lv2:index`, `lv2:symbol`, and `lv2:name`. The index is a sequential zero-based counter local to the `modgui.ttl` (it does not need to match the port index in the main plugin `.ttl`). Symbol and name must exactly match those in the main plugin `.ttl`.
`modgui:monitoredOutputs`	string list	List of control output port symbols whose values should be streamed to the browser in real time. Use this for output ports that display meters, tuner readings, or other live feedback in the plugin icon. The host will push value updates for these ports over the WebSocket connection.

Complete Example

@prefix modgui: <http://moddevices.com/ns/modgui#> .
@prefix lv2:    <http://lv2plug.in/ns/lv2core#> .

<http://example.com/plugins/my-reverb>
    modgui:gui [
        modgui:resourcesDirectory <modgui> ;
        modgui:iconTemplate       <modgui/icon.html> ;
        modgui:stylesheet         <modgui/style.css> ;
        modgui:screenshot         <modgui/screenshot.png> ;
        modgui:thumbnail          <modgui/thumbnail.png> ;

        modgui:brand "MyBrand" ;
        modgui:label "Reverb" ;
        modgui:color "#3a7bd5" ;

        modgui:documentation  "https://example.com/reverb-docs" ;
        modgui:discussionURL  "https://forum.mod.audio/t/my-reverb/1234" ;

        modgui:port [
            lv2:index  0 ;
            lv2:symbol "decay" ;
            lv2:name   "Decay Time" ;
        ] , [
            lv2:index  1 ;
            lv2:symbol "mix" ;
            lv2:name   "Dry/Wet Mix" ;
        ] ;
    ] .

Monitored Outputs Example

@prefix modgui: <http://moddevices.com/ns/modgui#> .
@prefix lv2:    <http://lv2plug.in/ns/lv2core#> .

<http://example.com/plugins/my-tuner>
    modgui:gui [
        modgui:resourcesDirectory <modgui> ;
        modgui:iconTemplate       <modgui/icon.html> ;

        modgui:monitoredOutputs "freq" , "note" , "cents" ;

        modgui:port [
            lv2:index  0 ;
            lv2:symbol "freq" ;
            lv2:name   "Frequency" ;
        ] ;
    ] .