MOD GUI

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.

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.

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.

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

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

Relates a plugin to the a MOD Graphical User Interface

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

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 event object containing:

• type: either "start", if plugin is being instantiated, or "change", if an input port value is being changed.
• ports: an array of { symbol, value } objects with all port values, if type is "start".
• symbol: the port input port which value is being changed, if type is "change".
• value: the input port value, if type is "change".
• icon: JQuery object encapsulating the DOM object of the main plugin interface.
• settings: JQuery object with the settings screen interface.
• data: An object that can be used by this javascript function to store anything that should persist between calls.

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

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

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

A monitored output on a MOD GUI.

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

A port on a MOD GUI.

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.

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.

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.

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.

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.

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.