This extension defines a standard for generating web-based interfaces for plugins.
Plugins implementing this standard will be compatible with the MOD device and MOD host software.

The goal of this interface is to allow user to have an overview of several connected plugins and quickly access main controls of each one, while still being able to fully configure each one individually, all this in a web-based environment.
So each plugin has two interfaces, one for its 'icon' and another for its 'settings'.

The 'icon' is a representation designed to look like a real device, and will be connected to other plugin icons by cables to make pedalboards. Ideally, each icon will have:

The 'settings' interface is a panel with all controls of the plugin. It can be designed to occupy the whole screen.

To provide this interface for Icon and Settings, the following resources can be used:

Note: To help the creation of interfaces, several base layouts have been created in the mod-sdk project.

Index

ClassesPropertiesFiles

Reference

Class modgui:Gui

Graphical User Interface

The web interface definition for this plugin.
It's defined by html templates for icon and settings panel, plus css, images and other media that's contained in the resources directory.

Restriction on modgui:stylesheet
owl:cardinality 1
A modgui MUST have a stylesheet.
Restriction on modgui:screenshot
owl:cardinality 1
A modgui MUST have a screenshot.
Restriction on modgui:thumbnail
owl:cardinality 1
A modgui MUST have a thumbnail.
Restriction on modgui:iconTemplate
owl:cardinality 1
A modgui MUST have an icon template.
Restriction on modgui:resourcesDirectory
owl:cardinality 1
A modgui MUST have a resources directory.
In domain ofmodgui:resourcesDirectory
modgui:brand
modgui:color
modgui:port
modgui:iconTemplate
modgui:screenshot
modgui:knob
modgui:thumbnail
modgui:javascript
modgui:templateData
modgui:panel
modgui:label
modgui:stylesheet
modgui:settingsTemplate
modgui:monitoredOutputs
modgui:model
In range ofmodgui:gui

Class modgui:MonitoredOutput

Monitored Output

The class which represents a MOD GUI monitored output (control port).

A MOD GUI that wants to receive notifications of control output values can do so by listing output port symbols. The host will keep track of port changes and notify the MOD GUI when it happens.

To enable monitor of output ports add the following code to your MOD GUI definition, modifying as needed:

modgui:monitoredOutputs [
  lv2:symbol "out1" ;
] , [
  lv2:symbol "out2" ;
] ;

The MOD GUI will receive the events in its javascript function, just like it does for input controls.

Restriction on lv2:symbol
owl:cardinality 1
A monitored output MUST have exactly one lv2:symbol.
In range ofmodgui:monitoredOutputs

Class modgui:Port

Port

The class which represents a MOD GUI port.

This is used by the SDK wizard to save the last selected state of each knob or combo-box on the screen.

Restriction on lv2:name
owl:minCardinality 1
A port MUST have exactly one lv2:name.
Restriction on lv2:symbol
owl:cardinality 1
A port MUST have exactly one lv2:symbol.
Restriction on lv2:index
owl:cardinality 1
A port MUST have exactly one lv2:index.
In range ofmodgui:port

Property modgui:brand

brand

The brand selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:color

color

The color selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:gui

graphical user interface

Relates a plugin to the a MOD Graphical User Interface

OWL TypeObject Property
Domainlv2:Plugin
Rangemodgui:Gui

Property modgui:iconTemplate

icon template

A template that will be used to render the HTML icon of this plugin. The value of this property must be a URI that resolves to a Mustache template.

The syntax and guidelines for templates are the same for modgui:iconTemplate and modgui:settingsTemplate, so this documentation applies to both.

General guidelines

To build the interface, follow these guidelines:

  • Start with a basic HTML template and use the MOD SDK to test it.
  • Use the {{{ns}}} tag inside the template to access images and media inside the bundle. More explanation on this at modgui:templateData.
  • If you need new styles, always prefix them with the name of your project. In HTML all css classes are global, so this is necessary to avoid messing with the general interface.
  • Use the mod-role attribute to mark elements that are functional for the plugin (see below).

Functionality

Some elements in your layout are just informative for the user, like the effect name, branding and background img. Others are functional, like the knobs and footswitch. A functional element is marked as so by the "mod-role" attribute, and other mod-* attributes may be used as parameters. The following functional elements may be indicated:

Bypass

MOD compatible hosts MUST implement a bypass in each plugin loaded. Two elements are responsible for this, the bypass footswitch and bypass light indicator.

The footswitch is an element identified by the mod-role="bypass" attribute. Once clicked, the effect bypass will be turned on or off, and the light indicator will be changed as so.

The light indicator is identified by mod-role="bypass-light". It will automatically receive the class on or off, so designers are expected to implement a background image for each of these classes, or equivalent.

Control buttons

Each plugin can have buttons to control plugin's parameters. Each button is identified by the attribute mod-role="input-control-port" and configured by mod-port-symbol attribute, which must hold the port's symbol, and mod-widget attribute, that defines which widget to use. The available widgets are film, select and custom-select, and each of them expects a certain HTML structure in this element.

Film widget

The film widget works like a movie film: it uses a big stripe of images and roll it to choose a scene, giving the impression of an animation. So, if you use mod-widget="film", this element is expected to have a background-image style, with one big horizontal sprite as background. User will be able to change that parameter by clicking on the control button and dragging the mouse up or down. As this is done, the background image will be moved to reflect the new state.

The minimum value of that port will be represented by the first position of the sprite and the maximum value by the last one. The number of steps will be calculated by dividing the background width by the element's width, considering the background-size style. The actual number of steps will be the minimum between the number of images in sprite and the steps limited by lv2 definition (by pprops:rangeSteps, lv2:enumeration or lv2:toggled.

For example, suppose you want to build a horizontal slider that can hold 10 different positions occupies an area of 150x30 pixels, to control the drive parameter of your plugin. For that, you could:

  • Design an image of 1500x30 pixels, each piece of 150x30 representing one position of the slider;
  • Save it inside the modgui:resourcesDirectory directory, in your bundle, as slider.png
  • Put the following code into your HTML: <div mod-role="input-control-port" mod-port-symbol="drive" style="width: 150px; height: 30px; background-image: url(/resources/slider.png{{{ns}}}">
  • Suppose you wanted to use the same sprite for a half sized version of the slider, you could instead use the style "width: 75px; height: 15px; background-image: url(/resources/slider.png{{{ns}}}; background-size: auto 15px;"
Select widget

The select widget is a simple <select> html element with available options, each one representing one value for this control port. It's mainly intended to be used for ports with the lv2:enumeration property, but can be used for any case in which picking values from a limited set is desired.

So, if you use mod-widget="select", this element is expected to be a <select> and contain several options, each of them must have the value attribute reflecting the float value of this property.

Custom select widget

This widget is similar in functionality to select widget, but instead of a select html element holding options, you can choose any element types to represent the widget and the options. If you use mod-role="custom-select", this element is expected to have children elements with the attributes mod-role="enumeration-option" and mod-port-value="(float value)". The selected element will receive the selected class, and so you can define your CSS as to highlight it as desired.

In case you want a list of options to be shown when the widget is clicked, you should mark the element containing the options with mod-widget-property="hidden". When this happens, every click on the widget will toggle that element's visibility.

Control values

To allow user to see the minimum, maximum and current value of a plugin, three mod-roles are available: input-control-minimum, input-control-maximum and input-control-value. All of them expect a mod-port-symbol attribute containing the symbol of the port.

The input-control-minimum, input-control-maximum will have have it's text content set to be the formatted minimum and maximum values accepted by this control, as defined by the lv2:minimum and lv2:maximum properties respectively. The input-control-value will be dinamically changed everytime the value of the control port changes.

All values are formatted according to the units:unit's and units:render property of this port, with some considerations. First, any %f will be rendered as %.2f, otherwise interface is messed up with huge representations. Second, if lv2:integer property is declared, then any %f, %.Xf or so will be substituted by %d.

Audio ports

Each plugin has audio input and output ports. They are identified by mod-role="input-control-port" and mod-role="output-control-port" attributes respectively, and both must have a mod-port-symbol property containing the port symbol.

For implementing the connections, each output will receive a <div> element inside, representing a jack (this will be automatically inserted). This jack can be dragged by user and dropped inside an input, and so a connection will be made.

This does not apply to Settings template

Drag handle

Plugins can be dragged around the pedalboard dashboard. To define which area of the plugin can be clicked for dragging, an element with the attribute mod-role="drag-handle" can be defined.

This does not apply to Settings template

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:javascript

javascript

A Javascript file containing a declaration of an anonymous function which will be called once when plugin interface is first rendered and everytime a port value is changed.

This function will receive as parameter an object containing:

  • event: a dictionary indicating the context in which the function is called. Contains the "type" key, that can be either "start" (first call) or "change", when a port value is changed. In the latter case, it will also contain they key "symbol", indicating which port has changed.
  • values: a dictionary containing the values of all control ports of this plugin.
  • icon: the JQuery object encapsulating the DOM object of the main plugin interface.
  • settings: JQuery object with the settings screen interface.
  • data: A object that can be used by this javascript function to store anything that should persist.
OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:knob

knob

The knob selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:label

label

The label selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:model

model

The model selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:monitoredOutputs

monitored outputs

A monitored output on a MOD GUI.

OWL TypeObject Property
Domainmodgui:Gui
Rangemodgui:MonitoredOutput

Property modgui:panel

panel

The panel selected when building a modgui through the MOD SDK.

OWL TypeDatatype Property
Domainmodgui:Gui
Rangexsd:string

Property modgui:port

port

A port on a MOD GUI.

OWL TypeObject Property
Domainmodgui:Gui
Rangemodgui:Port

Property modgui:resourcesDirectory

resources directory

This is a URI that resolves to a directory inside the bundle. Any file inside this directory will be statically served to browser, and will be available at the '/resources/' path.

For the webserver to properly identify where to look, any request for media inside this directory must have an {{{ns}}} parameter.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:screenshot

screenshot

An image with a real size screenshot of the rendered plugin interface. The value of this property must be a URI that resolves to an image.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:settingsTemplate

settings template

A template that will be used to render the HTML settings panel of this plugin. The value of this property must be a URI that resolves to a Mustache template.

To develop this, use the same guidelines and markup as described in modgui:iconTemplate. The only difference is that the audio ports here are irrelevant.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:stylesheet

stylesheet

A CSS file that holds all styles used for this plugin. The CSS will be automatically loaded on request. For implementation reasons, only one CSS file per effect is supported.

The stylesheet will be parsed for dynamic content, so the {{{ns}}} tag can be used to reference background images and other resources.

Remember that all class names must be preceded by the bundle's name to avoid conflicting with other plugins or general interface.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

Property modgui:templateData

template data
DEPRECATED

The data that will be used to render the templates defined in modgui:iconTemplate and modgui:settingsTemplate. The value of this property must be a URI that resolves to a json serialized object and its data can be inspected using the SDK's debug interface.

This parameter isn't strictly necessary to build a plugin layout, as the template can hold the final HTML file, but it's very useful to allow developers to customize layout using templates provided by the SDK, instead of editing HTML files.

The data in this file must be a dictionary. Two keys are automatically set: effect, ns.

effect

This will always hold the effect's data parsed from ttl files. The effect data format is an arbitrary structure that organizes the rdf triples in a simple way. To see that structure, use the SDK's debugging interface.

ns

All static files in folder defined by modgui:resourcesDirectory will be available to the interface, in path /resources of the webserver. To know where to look, the webserver needs a {{{ns}}} parameter.

To make this job easier, the ns variable will hold the correct url parameter, so if you want to customize your template (say, have your brand image in the pedal), you can refer to it like this:
<img alt="Brand image example" src="/resources/brand.png{{{ns}}}"/>

In the example above, the brand.png file inside the modgui:resourcesDirectory would be served.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing
owl:deprecated true

Property modgui:thumbnail

screenshot

An image with a small representation of the rendered plugin interface. The value of this property must be a URI that resolves to an image with maximum size of 256x64px.

OWL TypeObject Property
Domainmodgui:Gui
Rangeowl:Thing

History

Version 2.0 (2016-03-28)
  • Code rewrite and domain switch.
Version 1.0 (2014-10-14)
  • First stable release.