Learn Raspberry Pi Web Interface Guide

Getting Started

Welcome to RNBO

Quickstart

RNBO Basics

Key Differences

Why We Made RNBO

Coding Resources

Fundamentals

Audio IO

Messages to rnbo~

Using Parameters

MIDI in RNBO

Messages and Ports

Polyphony and Voice Control

Audio Files in RNBO

Using Buffers

Using the FFT

Export Targets

Export Targets Overview

VST/AudioUnit
Max External Target
Raspberry Pi Target
The Web Export Target
The C++ Source Code Target

Code Export

Working with JavaScript
Working with C++

Special Topics

Sample Accurate Patching
Scala and Custom Tuning

RNBO and Max for Live

RNBO Raspberry Pi OSCQuery Runner

Metadata

Export Description

Raspberry Pi GPIO

Updating the RNBO Package

Raspberry Pi Web Interface Guide

The Raspberry Pi Web Interface provides remote control and management of patches exported to the Pi.

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 device running on the Pi is represented as a node. You can configure MIDI and audio flow between devices by making connections, similar to working with Max. Parameters, Buffer Mappings Inports and Outports for each device can be controlled and referenced via the Devices icon.

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. You can click the Web Interface link in the export configuration to navigate to the web interface.

018-web-interface-link.png

Also, after exporting, a button showing Open Interface should appear. Click this 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. You will get a warning if an export would overwrite an existing patcher.

Clicking the Run On Selected Target export button in the Target Sidebar will export and run the selected device immediately, connecting any audio/MIDI inputs and outputs to available inputs and outputs on the Pi. Selecting the Export On Selected Target will export the device to the runner without the adding the device to the current graph.

Web Interface

The web interface has three views: the main view, the left sidebar and the top toolbar. The left sidebar lets you navigate between the Graph Editor, Devices Editor, 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.

Clicking the Runner Info icon 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.

There is also the Recording button in the Top Toolbar lets you record the output from the System Record Output node, which will be addressed below in the System Record Output Node section.

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 Graph Editor is similar to Max: connections between objects(nodes) are made via "patch cords", and 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 is located at the bottom left of the editor and has view options for the interface's orientation and behavior. The Zoom In and Zoom Out buttons will increase or decrease the rendering side of the graph editor. Fit View will crop the view to the dimensions of the nodes and connections in the user interface. The Toggle Interactivity icon enables and disables the toggle for deleting selected patch cords. Auto Arrange will rearrange and auto-layout the current graph.

Nodes

Nodes in the Graph editor can be broken down into a few types: Devices, System Nodes, the RNBO Control Node, the Recording Output Node and other, non-RNBO managed, Jack client nodes. The non-RNBO node you will see include the jack_transport_link, System Input, and System Output nodes.

Devices

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

If you exported by clicking Export tn Selected Target, then the node won't appear in the graph editor until you add it manually. If you exported by clicking Run on Selected Target, then the exported device 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 Settings. A device can be loaded more than once, for example if you want to create a stereo effect using two mono effects in parallel. To do this, simply use the Add Node button to add the same patcher to the editor multiple times.

The Add Node button reveals a popup that lists all patchers that have been successfully exported to the Pi, including those that are not currently loaded as active devices in the editor. Clicking any patcher name will create and load an unconnected device in the graph editor.

003-list-of-patchers.png

Within a given node, to the right of each patcher name is a button to reveal an action menu. This menu will let you click Open Device Control to open up the Device tab for remote control of the device. The same menu will also let you Rename or Delete any patcher. Note that this will not remove or rename any patchers that are currently loaded in the graph. If you rename a patcher that is already loaded in the graph, the name as it appears in the graph will not change. However, if you delete a patcher that is part of a saved sets, then those sets will no longer include that patcher.

004-device-actions.png

You can also manage the list of uploaded patchers through the Managing Resources tab. See below for more information.

System Nodes and Connected Hardware

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

The System Input node in the editor represents the hardware MIDI and Audio Inputs that are available on the device. The System Output node represents any connected MIDI hardware 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 device. Program changes will load graphs or devices based on alphabetical order. So, program change 0 will load the first graph/device 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.

From the Control tab in Settings, you can select the MIDI channel (including none or omni) that the runner listens to for these program changes.

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

As with the MIDI Program Change Channel option, devices can be configured to listen on a specific channel for program change events. This configuration option is called MIDI Program Change Channel: Load Device Preset in the Patcher Device 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.

System Record Output Node

The System Record Output Node allows for recording the output of a device or a set of devices for a configurable number of channels. In order to record audio output, connect nodes that you want to record to the System Record Output node. You can then start and stop the recording using the record button in the right part of the top toolbar.

023-system-record-output.png

Recording can also be activated via OSC to start/stop the recording in different ways. Send a T (true) value to the address /rnbo/jack/record/active to start recording, and a F value to stop. You can also send a string to the address /rnbo/jack/record/capture to start recording to a file with a specific name. Here are some examples using the sendosc command line tool:

sendosc c74rpi.local 1234 /rnbo/jack/record/active b T
sendosc c74rpi.local 1234 /rnbo/jack/record/capture s "my_cool_recording"
sendosc c74rpi.local 1234 /rnbo/jack/record/active b F

Any finished recording will be stored on the runner and appear in the Audio Files list within the Managing Resources view. Audio recordings will be named automatically using the current date and time. From the Audio Files view, you can filter and delete recordings, but it is not currently possible to download recordings. However, all audio files are stored in the folder ~/Documents/rnbo/datafiles on the Raspberry Pi, and you can copy files from this directory in the same way as any other file. For example, you can copy files to removable media like a USB flash drive, or you can use scp to copy files from your pi over SSH.

scp pi@rnbo_pi.local:~/Documents/rnbo/datafiles/my_recording.wav ~/Desktop

To configure the recording settings open the Settings and navigate to the Record tab. This is where you can set the recording Channel Count, specifying the number of channels in the audio recording. You can also set a recording timeout. Setting a timeout other than 0 in the settings configures the recording to stop automatically after a defined amount of time in seconds. A value of 0 will keep it active until the recording is stopped, either by clicking the Record button or with an OSC message.

Graphs and Graph Presets

The Graph Menu, accessed by clicking the Open Graph Menu icon in the top-right of the web interface, has multiple features for saving, editing, and loading Graphs.

019-graph-editor-menu.png

To save the a current set, click the Save Graph option, which will prompt a dialogue for naming the graph. The Save Graph As will save the state of the currently loaded graph. Delete Graph will remove the graph from the runner.

When selecting Load Graph, a dialog will appear to load a previously saved graph. Once a graph is loaded, two options from the Open Graphs Menu are revealed : Rename Graph will allow for renaming the graph and Reload Graph will reload the graph from it's most recently saved state.

The Manage Graphs option lets you rename and delete graphs. It also lets you select which graph will load upon startup of the runner. Selecting this option opens up the Graphs tab of the Manage Graphs View, which is mentioned later in this article.

Graph Presets

If a Graph 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.

012-open-graph-preset-menu.png

When creating a Graph a preset is automatically created named initial, this will be loaded by default when the Graph 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.

013-graph-presets.png

Devices

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

Access the Devices view by clicking the Devices icon in the left toolbar, or by clicking the Open Device Control action from the action menu of a device node.

From the Devices view, the drop-down menu in the top-left shows the name of the device, and reveals a dropdown of all devices loaded on the device. Click the name of an device 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

You can configure paramete MIDI Mapping by clicking the Enable MIDI Mapping icon in the upper left above the parameter list. After clicking this icon, each parameter will get a purple hue to indicate that MIDI Mapping mode is active. To create a mapping, click on the parameter you wish to map and then send a MIDI value from a connected MIDI 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. Once a mapping has been created, an 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.

Inports and Outports

With port and message control, all named inport and outport objects are exposed by their @name.

Under the Inports tab, each inport is set contain two buttons. The target button allows for a bang to be sent to the inport object. The paper-plane button allows for a manual float or number to se set for setting a value. Clicking the button with the blue icon next to that inport sends that value to update the inports state.

Under the Outports tab Outports appear as numbers which represent the current state of the outport objects of the device. The values can be made to be visible or invisible by clicking the eye icon.

Metadata

The action menu for each Parameter, Inport, and Outport contains an Edit Metadata action. Clicking this entry reveals a popup editor that allows for entering/editing a JSON formatted string to assign metadata to 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. In the Buffers view, each buffer will appear by name in its own row. Click the three-dot icon at the right of each row to reveal the buffer Action Menu, including the actions Clear Buffer Content, Change Source, Save Contents, or Edit Metadata.

Click the Change Source icon (a little pencil) to change the buffer source. When choosing to change the source, a dropdown 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.

Save Contents allows for saving the contents from a buffer to disk. Selecting Save Contents will prompt a dialogue to provide the filename and save the content to disk.

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 devices 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 a device using the computer's keyboard.

Presets

Parameters and Buffer mappings for a device 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 device from the interface, open the presets dropdown (camera icon) from the Parameters tab located above and to the right the parameters. 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 Overwrite, Rename, Delete or indicate that it should be loaded on startup.

Parameter Views

Parameter Views let you control parameters across multiple devices. The Parameter View icon is located directly below the Devices Icon in the left toolbar of the Web Interface.

In Parameter View, click the Open Parameter View Menu icon in the top-right to navigate between parameter views. You can also click the Create Parameter View button at the bottom of the menu to create a new Parameter View.

Next to the Open Parameter View Menu, click the three-dot icon in the top right to open an action menu containing the actions New View, Manage Parameters, Rename, and Delete. Clicking New View will create and name a new Parameter view. By clicking Manage Parameters, you can select which parameters from which devices will be included in the current Parameter View. The "-" will remove the parameter from the view, and the "+" will include it in the view.

020-graph-editor-menu.png

Rename lets you rename the currently loaded Parameter View.

From the list of included parameters, you can use the action menu to the right of any listed parameter to add Metadata to the parameter, move the parameter up or down in the parameter list, or remove that parameter from the Parameter View.

MIDI Mappings View

The ability to control MIDI Mapped parameters across multiple devices can be accessed from the MIDI Mappings View. similarly to the Parameter View, the MIDI mappings view exists to view all actively MIDI mapped parameters in a simple table, and offers the ability to remove or manually edit a mapping.

021-midi-mappings.png

Managing Resources

The Manage Resources tab in the left-hand toolbar is useful for the management of graphs, patchers and audio files on the runner.

Managing Graphs

022-manage-graphs.png

The Graphs tab lets you Load, Rename, and Overwrite your saved Graphs. Clicking the star button opens a dialogue that configures whether the Startup Behavior of the runner. On startup, you can configure the runner to load a new empty graph, load the the last graph (including unsaved changes), or a specific graph.

To the right of the name of each graph 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.

Managing Patchers

You can manage the list of uploaded patchers by clicking on the Patchers tab in the left-hand toolbar. From here, you'll see a list of every patcher available on the runner. The configuration icon to the right of each patcher lets you Delete or Rename each patcher, and the Search field at the top-right lets you filter for patchers matching a particular name. Note that any changes you make here will not affect the currently loaded graph.

patchers-view.png

Managing Audio Files

Clicking on the Audio Files tab 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, or press the trash can icon next to an audio file to delete it from the device.

Transport Control

You can use the Transport control to configure the global transport. This is a global timer that coordinates all objects that are locked to an external transport. This allows for adjusting BPM for all devices containing phasor~ and metro set to@locked 1 . The transprot 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, click the play button to the left of the bpm control. 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, Device 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 device.

Computer MIDI Keyboard Activate this Setting to play MIDI notes into an device 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.

Devices

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

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

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

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

Fade in Milliseconds Fade in milliseconds when creating new devices.

Fade Out Milliseconds Fade out milliseconds when closing devices.

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

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

Recording

Channel Count The Number of Channels to provide for recording.

Timeout A timeout on seconds to use for stopping recording. Set to 0 to disable.

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.