Raspberry Pi Web Interface Guide

The web interface allows for full control over the audio graph running on the Pi, including the flow between exported patchers, the tempo and active state of the transport, the active MIDI and audio hardware devices, and other configuration settings.

The Graph Editor provides a node-based UI for creating and managing signal flow between exported patchers. As patchers are exported to the Pi, they add to a library of nodes that can be used to configure MIDI and audio signal flow between all exported patchers and the Pi's connected Audio/MIDI hardware.

Each patcher instance running on the Pi is represented as a node where Parameters, Buffer Mappings and Ports (inport and outport data messages) for each instance can be controlled and referenced via Instance Control.

Upgrading to the latest version

To make sure you have the most up to date version of the web interface, check the Upgrading your system entry in the Raspberry Pi Setup article.

Exporting and Web Interface Access

The URL for the web interface can be found in the Raspberry Pi Export Sidebar. After exporting, a button showing Open Interface should appear, which can be clicked to open the web interface in the default browser. For convenience, a QR code will appear after export that can be followed to access the web interface.

It's important to set the Patch Name in the Target Sidebar, as this will be the name of the node when working with the graph editor. Exporting a different patcher with the same name will overwrite the existing patcher export on the device.

By default, the Run Immediately checkbox in the Target Sidebar is checked and the patcher instance will appear to be loaded, running, and connected in the graph editor. In the case that it is unchecked, the patcher instance will load without running or connections. 

Upon loading the web interface, the browser reveals the main interface with the left sidebar and the top toolbar. The left sidebar allows access to switch between the Graph Editor, Patcher Instance Control, Audio File Listing/Editing, and Settings.

The top toolbar reveals the Transport Control (metronome icon) which is addressed later in this guide, the Runner Info (satellite icon) and a CPU Usage meter that indicates the approximate CPU load the current graph's audio processing.

The Runner Info reveals the hostname or IP address of the device that runs the OSCQuery Runner as well as the the port of the OSCQuery Runner Websocket associated with the Web Interface. It also provides the version number of the associated Runner and an Xrun Count. Xruns are buffer over/under runs, indications that the audio graph didn't process audio in time.

Note : The Cycling '74 provided image runs an HTTP server that serves the interface on port 3000. The interface is accessed using either the device hostname or IP address followed by the port number. So if the pi had the hostname c74rpiand the IP address 192.168.88.111, then from any device on the local network , visit http://c74rpi.local:3000 or http://192.168.88.111:3000 to see this page.

The Graph Editor

The Graph Editor is designed to control Raspberry Pi’s MIDI and Audio signal flow between exported patchers and the Pi's connected Audio/MIDI hardware. Upon loading the Web Interface, the Graph Editor tab appears as the default view, showing all running nodes and their current connections in the main interface. 

Working with the Editor Interface

The editor is similar to Max where connections between objects(nodes) are made via "patch cords." These patch cords represent the signal flow of audio and MIDI data between nodes. Unlike Max, where signals move from top to bottom, here signals flow from left to right.

A connection can be made from an inlet to an outlet by clicking the inlet or outlet and dragging to another node's inlet or outlet. To delete a connection, click the patch cord to select it, and then click the X button that appears.

Nodes can be moved in the interface simply by clicking and dragging.

Clicking the background of the interface and dragging will adjust the orientation of the view.

The navigation panel located at the bottom left of the editor and has view options for th interfaces orientation and behavior. Zoom In and Zoom Out buttons for the editor view. Fit View will crop the view to the dimensions of the nodes and connections in the user interface. The Toggle Interactivity enables and disables locking for the ability to click toggles, which should only apply to the toggle revealed when deleting patch cords.

Nodes

Nodes in the Graph editor can be broken down into four types : Patcher Instances, System Nodes, the RNBO Control Node and other, non-RNBO managed, Jack client nodes. By default the only non-RNBO node you will see is jack_transport_link.

Patcher Instances

Each patcher exported and loaded on the Pi is represented as an instance node in the Graph Editor with the name determined by Patch Name in the Target sidebar at the time of export.

In the case that Run Immediately was disabled at the time of export, the node shouldn't appear running or connected in the Graph Editor. In the case that it Run Immediately is enabled (default), the exported patcher instance will have all of its input and output audio/MIDI inlets connected automatically to the Pi's audio/MIDI inputs and outputs with the exception of the rnbo-control MIDI inlet. this automatic connection behavior can be altered in the Patcher Instance tab in Settings. A patcher instance can be loaded more than once, creating duplicate patcher instances from the same patcher in the editor.

The Patchers button reveals a popup that lists all patchers that have been successfully exported to the Pi, including those that are not currently loaded as patcher instances in the editor. Clicking any patcher name will create and load a patcher instance in the graph editor without making any connections. To the right of each patcher name is a button to reveal an action menu to Rename or Delete any patcher. Note that this will not remove or rename any patchers that are currently loaded in the graph. It should also be noted that you can delete patchers that are in saved sets and the set will no longer include those patchers.

Each patcher instance also has a gear icon. Clicking this will open up the Instance Control tab for remote control of the patcher instance. 

To remove an instance from the graph editor, click the gear icon of the Instance and then the Unload Instance button at the top right. You can also press Backspace with the instance highlighted in the graph.

System Nodes and Connected Hardware

MIDI and Audio hardware interfaces connected to the Pi are represented by two nodes named system.

The leftmost system node in the editor represents the connected hardware MIDI and Audio Inputs. The rightmost system represents the connected hardware MIDI and Audio Outputs.

RNBO Control and MIDI Program Changes

The RNBO Control node allows for MIDI program change events to swap the current graph set, load a graph set preset, or replace the graph with a single patcher instance. Program changes will load sets or patcher instances based on alphabetical order. So, program change 0 will load the first set/patcher instance in alphabetical order, program 1 will load the next, and so on. Presets have the same alphabetical behavior except that the initial preset, if it exists, is always mapped to program 0. This functionality is only enabled if device MIDI is connected to the RNBO Control node, as pictured.

You can select the MIDI channel, or none or omni, that the runner listens for these program changes by going to the Control tab in Settings.

It's also possible to use MIDI program change events to load presets of a specific patcher instance. To enable this behavior, connect a MIDI device to the MIDI input of any patcher instance node.

As with the MIDI Program Change Channel option, instances can be configured to listen on a specific channel for program change events. This configuration option is called MIDI Program Change Channel: Load Instance Preset in the Patcher Instance tab in Settings. Presets are mapped to program numbers in alphabetical order except that if there is an initial, Load On Startup, preset, it always maps to program 0.

Graph Sets

The Graph Editor has a feature to save, edit, and load the editors layout which contains the running nodes, there metadata and all of their connections as Graph Sets.

At the top right of the Editor is the Sets button. Clicking this reveals the Graph Sets panel with a dialog to specify a name for a new set. Once that is set the save button will save the interfaces layout containing the running patcher instances, their associated metadata (which includes MIDI mapping) and all of the graph connections.

A list of saved sets will be revealed below. Click the name of any set to load it. To the right of the name is an icon that reveals an action menu. Use the action menu to Save Changes to the most recently loaded set, Overwrite, Rename or Delete existing sets. The graph can be cleared by pressing the Clear Graph Set button.

Graph Set Presets

If a set is loaded in the graph editor the Presets button can be used to save, load and edit presets for the entire graph. Graph presets contain the Parameter and Buffer mapping settings for each instance in the graph. You can specify a name and click the Save button to create a new preset. Click the name of a preset in the list below to load it. To the right of each preset is an action menu to rename or delete a preset.

When creating a Graph Set a preset is automatically created named initial, this will be loaded by default when the Graph set is loaded. The initial preset can be deleted to remove this behavior. Saving a new preset named initial or rename an existing preset to initial will create a new automatically loaded preset for the graph set.

Instance Control

Parameter values, Inports, Outports and Buffer mappings can all be visualized an manipulated via the Patcher Instance Control view.

The Instance Control can be accessed form the left sidebar under the Instance Control icon or from the loaded patcher instances nodes gear icon.

The top left window shows the name of the instance, and reveals a dropdown of all instances loaded on the device. Click the name of an instance to reveal its control view.

Parameters

Parameter control is set via the Parameters tab. All named param/param~ objects are exposed by the objects @name. The parameters @value can be set via the associated slider.

To the right above the parameters list are Search and Sort buttons. With search, quickly filter out parameters that don't contain the entered text. Sort changes the order that the parameters are listed in the view.

MIDI Mapping

MIDI map parameter controls by clicking the MIDI port icon, Enable MIDI Mapping, in the upper left above the parameter list, clicking on the appropriate parameter control and then sending a MIDI value from a connected device. The device must be connected to the MIDI input in the graph editor for mapping to work. Click the MIDI port icon again to Disable MIDI Mapping in the interface. A little indicator icon appears next to the parameter name for any MIDI mapped parameter. The mapping for a specific parameter can be removed via the Clear MIDI Mapping entry in the action menu to the right of the parameter.

Ports

With port and message control, all named inport and outport objects are exposed by their @name. Inports contain a dialog where a manual float or number can be sent for setting a value. Clicking the button with the blue icon next to that inport sends that value to update the inports state. Outports appear as numbers which represent the current state of the outport objects of the instance.

Metadata

To the right of each Parameter, Inport and Outport is an action menu that has an entry: Edit Metadata. Clicking this entry reveals a popup editor that allows for entering/editing a JSON formatted string to assign some metadata with the associated item. Use the Save button to send the edited metadata to the runner, or Cancel to undo any changes made to the metadata. Clicking the Restore Default button reverts any customization made to this metadata, returning to any @meta value that you may have associated with the item.

This metadata will be saved/restored with the graph set but make sure you save your graph set if you make any changes to your metadata that you wish to restore later.

You can read more about the metadata the runner supports in the RNBO Metadata Documentation.

Buffers

Exposed buffers in the exported patcher will appear in the Buffers tab. At the right of each listed item, use the action menu to choose to Clear Buffer Content or Change Source. Use the little pencil icon to change the buffer source. When choosing to change the source ,a list of all the audio files available on the device is revealed. Clicking the file you want and then clicking the check mark will change the buffer source. Clicking the x icon undoes the file change selection.

Virtual Keyboard

The Virtual Keyboard reveals an interactive MIDI keyboard for playing MIDI notes directly from the Web interface. Similar to kslider, this is connected to the running patcher instances MIDI input.

Octave range for the MIDI slider can be changed via the two arrows on the top right.

MIDI notes can also be played into an instance using the computer's keyboard.

Presets

Parameters and Buffer mappings for a patcher instance can all be saved, renamed, loaded, and deleted via the presets dropdown. Saved Presets to the RNBO object at the time of export will also appear in the dropdown.

To create, load, rename or delete a preset for an instance from the interface, open the presets dropdown (camera icon) from the Instance Control tab located above and to the right the instance controls. This will reveal the preset sidebar. Click on the preset name to load it. Enter a name in the text box and click Save to create a new preset. Use the action menu to the right of each preset to Rename, Delete or indicate that it should be loaded on startup.

Audio Files

Clicking on the Audio Files button presents a list of any audio files that the runner has available to load into buffers. These are stored in the directory Documents/rnbo/datafiles on the remote device. Click the Upload Files icon to send new audio files to the device, press the trash can icon next to an audio file to delete it from the device.

Transport Control

Transport control of instances with objects locked to the external transport can be set from the Transport control window. This allows for adjusting BPM for all instances containing phasor~ and metro set to@locked 1 . It can be also be synchronized to Live's transport via Ableton link.

To access the Transport control, click the play icon in the top toolbar. This will reveal the Transport control window.

To enable/disable transport control, the play button on the left will need to be clicked which will highlight it blue. When enabled, the arrows next to the bpm will change the value for transport control. Holding shift and click the arrows, the bpm will change in increments of +-10.0.

By default, the sync switch on the right is enabled (blue), showing that it is synchronized to Live's transport via Link. Enable Link in Live's preferences, and the Raspberry Pi will stay in sync with other Link-enabled devices on the same network.

Settings Menu

The settings menu for the Web interface Is represented by the gear icon in the bottom of the left toolbar. Customization of the Web interface UI, Program Change Channels, Instance and connection behavior, and Audio/MIDI hardware preferences can all be set here.

UI

The UI settings are device scoped, saved to the local storage and restored on page load.

Color Scheme Select a dark or light color scheme for the user interface.

Monitor Output Ports Activate this setting to monitor data sent out of [outport] objects on the port control tab of an instance.

Computer MIDI Keyboard Activate this Setting to play MIDI notes into an instance using the computer's keyboard, when displaying the MIDI control tab.

Parameter List: Sort Attribute Select the attribute to use to sort your parameters.

Parameter List: Sort Order Select Ascending or Descending sort order for your parameters.

Control

Determine RNBO-control behavior and set the channel for Program change

MIDI Program Change Channel: Select Set Set which channel (or none or omni) the control node should listen to for program changes to load a set by index.

MIDI Program Change Channel: Select Set Preset Set which channel (or none or omni) the control node should listen to for program changes to load a set preset by index.

MIDI Program Change Channel: Select Patcher Set which channel (or none or omni) the control node should listen to for program changes to load a patcher by index.

Auto Connect MIDI Automatically connect control to midi outs.

Instance

Auto Start Last Set Automatically start the last set configuration on runner startup.

Auto Connect Audio Automatically connect Run Immediately exported instances to audio i/o.

Auto Connect Audio by I/O Index Number Automatically connect Run Immediately exported instances to audio i/o, using the RNBO I/O index to inform the connections.

Auto Connect MIDI Automatically connect Run Immediately exported instances to midi i/o.

Auto Connect MIDI Hardware Automatically connect Run Immediately exported instances to midi hardware i/o.

Fade in Milliseconds Fade in milliseconds when creating new instances.

Fade Out Milliseconds Fade out milliseconds when closing instances.

Port To OSC Map slash prefixed port names to/from OSC messages by default.

MIDI Program Change Channel: Load Instance Preset Which channel (or none or omni) the instance should listen to for program changes to load a preset by index.

Audio

Set the connected MIDI and Audio settings for the Pi's utilized Audio and MIDI connected hardware. To apply the configuration, click the button at the bottom right of the Audio tab of the Settings window that says Apply Configuration.

Num Periods Number of periods of playback latency.

Period Frames Frames per period. This is the same as the DSP Vector Size.

Sample Rate The Sample rate of the devices audio hardware.

Interface ALSA hardware device name.

MIDI System Determine which MIDI system to use. By default Seq is selected. In the case of using Sysex, it is suggested to use the raw MIDI system.

Extra Args Add additional arguments to be passed to Jack when creating the server.