OSC / Pilot

Docs

Overview

OSC/PILOT is a lean and easy to use UI building tool that can communicate via both OSC and MIDI to any application that supports those protocols. OSC/PILOT supports both Multi-Touch Touchscreen interaction as well as regular mouse interaction.

Widgets are dragged into workspaces and can have parameters adjusted to customize their look and behavior.

General Interface

The interface of OSC/PILOT is designed to be simple and easy to use. The UI has two modes, Play-mode, and Edit-mode. You can switch between play and edit mode in two ways. Either by pressing the TAB key on your keyboard or by swiping the UI. To enter Edit mode, swipe down from the top right of the UI. To exit Edit mode and return to Play mode, swipe up from the bottom right of the UI. You need to drag all the way from one edge to the other to complete the transition.

Edit Mode

When in Edit mode, the UI will have a grid in the background to help place widgets. Widgets can be added to the UI by dragging them from the row of widgets at the top of the UI. Once a widget is added or selected, a box to control it's parameters is available in the upper right of the UI. What each parameter does is detailed in the 'Widgets' section of this documentation.

On the bottom right there is a button to minimize/maximize the window, as well as the button to bring up the Color Palette editor. The Color Palette editor allows multiple colors to be created, and each of these colors can be assigned to the widgets in their parameters. More colors can be added to the palette by pressing the + button on the bottom of the editor. Colors in the palette can be re-ordered by dragging them around. Note that widgets use the color based on it's position in the palette, so moving a color will change the colors of widgets. A color can be deleted by dragging the color all the way up or down out of the palette. The set of colors in the palette and be imported and exported to a file, so you can use them between projects. Additional the size of the layout grid can be controlled here. The default grid size is 16.

In Edit mode you can move between multiple 'Workspaces'. A workspace holds a single UI. You can have up to 32 different workspaces. Changing between workspaces can be done in one of three ways. The first is using the controls on the bottom of Edit mode. The second is by sending an OSC message to the application to the OSC Address /Workspace/Select. The value of the message should be an integer or float starting at 1, to say which workspace to change to. The final way to change is when in Play mode, detailed below. A value of -1 will move to the workspace to the left, a value of -2 will move to the workspace to the right. A value of 0 does nothing.

You can use a Button widget with OSC Loopback enabled to create a button that will change workspaces by assigning it's OSC Address to /Workspace/Select and setting the On value to the workspace number, or -1/-2, as the OSC On value.

Play Mode

When in Play mode you can switch between workspaces by swiping with two fingers left or right. There is no way to move between workspaces in Play mode with just the mouse, you'll need to switch into Edit mode quickly to do that.

You can force an instance of OSC/PILOT to be locked into Play Mode by launching it with the argument -show. E.g

oscpilot.exe -show C:/Path/To/Project/File.plt

Widgets

Common Parameters

These are the common parameters that many or all of the widget have.

Label - Each widget can be given a label. This label is purely for informational purposes and isn't used to control behavior or data that is send/received. The label is not visible in the Play mode UI.

Opacity - Controls how opaque or transparent the widget is. Use this to make the widget transparency so you can see other widgets behind it.

Background - Enabled or Disable the background color.

Glow Strength -  If Glow is enabled globally in the settings, this controls how strong the glow is on this one widget.

Border - Controls if the border is shown around the widget. Some widgets have this as a toggle, others have it as a slider to control the border's opacity.

OSC Address - The OSC address this widget's sends and receives values on. If this field just has /, then OSC is disabled for this widget. Some widgets such as Button/Slider Matrix widgets will automatically append to the Address name to differentiate between the multiple buttons/sliders in the widget.

MIDI Ch - The MIDI channel to send this widget’s values to. Must be between 1 and 16. The same channel will be used for both Control Change (CC) or Note messages. Should not contain any other characters except numbers. 

MIDI CC - The MIDI Control Change number to send this widget’s value to. Must be between 0 and 127. Should not contain any other characters except numbers.

MIDI Note - The MIDI note number to send this widget’s value to. Must be between 0 and 127. Should not contain any other characters but numbers. Not all widgets support MIDI note.

Bring To Front - Put this widget in front of all the other widgets. Used to layer widgets. Widgets in front will block mouse/touch interaction with widgets behind them. Null and Label widgets will not block interaction though.

Send To Back - Put this widget behind all the other widgets.

Constrained - When Off, a press on this widget that then gets dragged onto other widgets will also cause them to be pressed. Otherwise only this widget will get affected, even if the press is dragged onto another one.

Button

Either a toggle or a momentary button. Sends 0.0 and 1.0 to the OSC receiver, 0 and 127 to the MIDI device, by default.

Circular - Change the look of the button to circular instead of square.

OSC Loopback - When this is enabled, OSC messages from this button will not be sent over the network, but instead be sent back into OSC/PILOT. This is particluarly useful for sending control messages such as /Workspace/Select to change workspaces using a button widget. When this is enabled the Button will ignore any incoming OSC messages that are send to it's address.

Read Only - Make this widget not accept input from the mouse/touchscreen. It will respond to OSC messages sent to it though. Useful to be used as notifications from your OSC application.

OSC Off/On - The OSC value that is sent when the button is released/turned off or pressed/turned on.

Value - The CC Value that will be sent when the Button is pressed/turned on.

Velocity - The Velocity value that will be use for the Note On message went when the button is pressed/turned on.

Toggle - If On, the Button will switch between the On and Off states each time it is pressed, rather than always returning to Off when it’s released.

The Button widget also includes parameters from the Label widget to give itself a label directly.

Slider and Dial

Either a horizontal or vertical slider. It will send values between 0 and 1 over OSC and values between 0 and 127 over MIDI. A dial is a circular slider.

OSC Low/High - The OSC value range the slider or dial will send from it's low to high point..

Smoothing - If On, the slider will gradually approach the target position rather than moving at the same rate the touch interaction.

Return To - If enabled, the slider will return to this value when it’s released.

Return To Speed - The speed at which the slider will return to the ‘Return To’ value.

Steps - If On, the slider will have discreet steps rather than be all possible values between 0 and 1. The parameter controls how many steps there will be.

Bidirectional - If On, the slider will be centered at 0.5 instead of 0, and be able to be dragged above and below this value.

Jump To Value - If On, the slider will go directly to where it is pressed (with a delay if Smoothing is enabled). When this is Off the press must start where the slider currently is, and drag from there. When this is off it helps avoid having the value jump, and only allow for smoother changes.

Horizontal - Change the slider to be horizontal instead of vertical.

Show Value - Display text of the current value for the slider/dial. Will always show between 0.0 and 1.0, regardless of the OSC Low/High setting.

Pad

A two value widget, will send a value for the X and Y position pressed. The top--left is 0,0 and the bottom-right is 1,1.

Label

A widget to display text on the UI. The OSC tag is for the OSC application to send text to be shown in this widget, rather than to be used to send OSC data out of OSC/PILOT.

Text - The text to show.

Font Size - The size of the text. Can be non-integer values such as 10.5 as well.

Align - Aligns the text to the left, center or right of the widget.

Auto Size - Automatically size the text horizontally to fit into the widget, taking into account the margin. The Font Size and Align are ignored when this is used.

Margin - Add padding on the left/right edge of the widget when aligning to left or right.

Bold - Enable bold for the text

 

Sliders and Buttons

A matrix of N by M sliders or buttons grouped together. For MIDI it will send out to the CC or Note starting at the specified one, and increasing by 1 for each slider. The lowest numbered one will be the top-left one, and increasing to the bottom-left. By default this widget will send to a different OSC address for each slider/button. Each slider/button's address will have a '/X/Y' suffix appended to it denoting the row and column of the slider. X will be placed by the row and Y will be replaced by the column. The rows and column numbers are 1-based. The 1,1 slider is the top-left one. For Buttons the 'SINGLE OSC ADDRESS' parameter can change this behavior, detailed below.

Columns - How many columns of sliders there are.

Rows - How many rows of sliders there are.

Padding - How much visual space is between each of the slider widgets. Increasing this will reduce the size of the sliders.

Single OSC Address - Buttons Only: When this parameter is enabled, only the original OSC Address will be used The values sent to this address will be the button number last pressed, starting with 1.0 for the top-left button. In this mode you often will not get messages saying a button is depressed, and it won't be possible to know which button was depressed, since multiple buttons may have been pressed at the same time.

Radio Mode - Buttons only: If enabled, only 1 button can be pressed at a time. If one is On and another is pressed, the one that is currently On will change to Off.

Null

This widget is just to help visually organize the UI. It doesn’t send or receive any values, and can’t be interacted with. It can be used to draw lines, squares and circles around and between widgets.

Circular - Controls if the border is circular or square.

Horizontal Line - Draws a horizontal line in the middle of the widget.

Vertical Line - Draws a vertical line in the middle of the widget.

Image

Loads an image from disk to be displayed in the UI. Supports .png and .jpg file formats. The image will be saved into the .plt project file.

Native Res - The widget will be sized to match the native resolution of the image. It can’t be resized when this is turned on.

Keep Aspect - The aspect ratio of the widget will match the aspect ratio of the image when this is on.

GLSL

For the GLSL hackers out there, this widget can be used to render a GLSL pixel/fragment shader into a widget. The widget follows the glslsandbox.com GLSL interface. That is, it provides values for the following uniforms that can be used to create generative GLSL content. Multiple aliases for the same uniform values are supported in case incoming shaders use different uniform names.

// The current time in seconds. Counts up from when the application starts, but may not start at 0.
uniform float time;
uniform float iTime;

// The X/Y position the widget was last interacted at. Values in range [-1, 1]
uniform vec2 mouse;
uniform vec2 iMouse;

// The resolution of the widget, in pixels
uniform vec2 resolution;
uniform vec2 iResolution;
uniform vec2 surfaceSize;

KEYS

Creates a visual piano keyboard.

Keys - Control how many white keys are in the keyboard.

 

NDI

Creates an NDI® input widget for viewing video coming in over the NDI protocol. 

NDI® is a registered trademark of NewTek, Inc.

http://ndi.tv/

Source Computer - The name of the computer/device hosting the NDI feed.

Source Name - The unique name given to the source feed.

Bandwidth - Controls if the video should be sent over using high or low bandwidth mode. For smaller widgets low bandwidth mode is likely sufficient since it will reduce the resolution.

Settings

General Settings

The Settings dialog can be reached by pressing the 'Settings' button in the upper left when in Edit mode. Settings are saved per machine, except for UI Scale, which is saved per project file, per machine.

UI Scale - Will scale the full UI by that given amount. Useful when loading projects made with different resolution monitors onto other machines.

Confirm Delete - Controls whether a confirmation dialog comes up before deleting a widget.

Confirm Quit - Controls whether a confirmation dialog comes up before quitting the application

Swipe To Change Space - Controls whether changing between workspaces can be done via a two finger swipe on the Play mode UI.

Glow - Enable or disables the overall Glow effect on the UI.

Transitions - Selects the transition style that occurs when changing between workspaces. Select 'Instant' if no transition is desired.

OSC Settings

Host - The IP address of the machine where you want to send OSC message to. OSC/PILOT will accept messages coming from any machine, they do not need to be coming from the machine listed in this setting. You can use 255.255.255.255 to broadcast OSC messages from OSC/PILOT to all machines on your LAN.

Send To Port - The port on Host to send OSC message to

Listen On Port - The port on the machine OSC/PILOT is running on to listen for OSC messages.

MIDI Settings

MIDI Out Device - Select which MIDI device to send messages out on. This setting is saved per-machine, so all projects will use the same MIDI device on any one machine.

Communication

OSC

OSC (Open Sound Control, http://opensoundcontrol.org/introduction-osc) is a UDP based network communication protocol that the majority of audio and visual tools out there support. It can send and receive message on arbitrarily named 'OSC Address's, and supports floating point values, which allows for much higher resolution than the 127 unique values that MIDI supports. Almost all widgets that support sending over OSC for an address, also support receiving on the same address to control the widget externally. So for example an external computer sending to the OSC Address of a slider can control the slider's position. This can be used to send graphical feedback to the UI, or to set all of the widgets into a desired starting state.

Along with sending and receiving values over each widgets OSC address, some widgets also have extra OSC addresses available to control other aspects of their look. These extra addresses are composed from the base OSC address for the widget, appened with '/OSCpilot/' followed by the setting to change. All widgets support controlling their Color and Opacity. So for example to control the opacity of a widget that has /slider1 as it's OSC address via OSC you'd send a value between 0-1 to /slider1/OSCpilot/Opacity.

'Color' should be an integer value, selecting the 0-based palette index of the color you want the widget to take on.

'Opacity' should be between 0-1.

Sliders, Pads and Buttons support 'ReadOnly', which should be a boolean or 0/1 integer to control the Read-only state of the widget.

Label widgets support 'FontColor', which is the 0-based palette index of the color you want the font to use.

MIDI

Most widgets also support sending to (but not receiving) MIDI. Any of the MIDI devices install on the system should be selectable from the Settings. To send MIDI over the network, such as controlling Ableton running on another machine, we suggest using rtpMIDI. To send MIDI within the same machine for applications both running on the same machine, we suggest loopMIDI