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 can 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.

You can pin all of the widgets in a workspace by enabling the 'Pin Widgets' checkbox. This makes it so no widgets can be moved, deleted or created. You can however still select widgets and change their settings.

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.

Overlay Workspace

Along with the 32 switchable Workspaces, starting in version 1.7.3 there is also an Overlay Workspace which will always be drawn onto of the current Workspace (unless you turn off it's Display). This Workspace can be edited using the 'Edit Overlay' toggle on the Workspace bar at the bottom. If you open your project in an older version this workspace will not exist though. You can control the Display of the Overlay workspace via the OSC Address /OSCpilot/Overlay/Show. You can send 0 and 1 to this address to hide and show it.

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

Startup Workspace

Which workspace the file starts up in can be chosen via the command line as well by using the argument -workspace <1-32>. e.g

oscpilot.exe -workspace 5 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.

OSC Socket - Up to 5 different OSC sockets may be setup in a project. The A, B C, D and E checkboxes determine which of these sockets the widget interacts with. This includes both sending and receiving values from that socket.

Extra OSC Args - A space separated list of extra OSC arguments that can be sent along with every message. For applications that require extra arguments beyond just the OSC Address to target specific functionality. Put a single # where you want the value of the widget to be included in the message. If # isn't included, then the value will be set as the last argument to the message.

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.

MIDI Ch, MIDI CC and MIDI Note can all be given multiple values to sent to multiple MIDI Channels/CC/Notes at the same time when the widget is interacted with. E.g Channel = “1 2” and Note = “5 10”, will send to (Channel 1, Note 5), (Channel 1, Note 10), (Channel 2, Note 5) and (Channel 2, Note 10)

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 On, only interactions that begin within this widget will effect it. Interactions will continue even if dragged off of the widget. When Off, a touch/click can be dragged onto this widget from anywhere (blank space or another widget) and will start interacting with it. Interactions that leave the widget will stop effecting it as well.

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 particularly useful for sending control messages such as /Workspace/Select to change workspaces using a button widget. When using /Workspace/Select, make sure to change the 'On' value to the value you want to send for that message. 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. This can be a float (0.0, 0.5 etc), an integer (0, 2, 10 etc.) or a string. It will send an OSC message of the corresponding type when the On or Off event occurs. If the field is left blank, no message will be send for that event. If both fields are blank then a message containing only the OSC Address with no arguments is sent.

CC Value Off/On - The CC value that is sent when the button is released/turned off or pressed/turned on. If the field is left blank, 0 and 127 will be sent respectively.

OSC Re-send Interval - If this field is filled in with a numeric value, the button will re-send it's On value at regular intervals while the button is in it's On state. The interval is specified in seconds, and can be fractional. E.g 0.5 will mean every 500ms. Note that the send interval will not be exact enough for things such as musical beats, and is meant more for regular triggers or heartbeat messages to receiving apps.

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. In addition to using it's circular bar, a Dial can also be controlled by clicking and dragging horizontally from it's center.

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

CC Value Low/High - The CC 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 can start anywhere in the slider, and will drag relative to that start position. 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.

Touched - OSC address to use to send a message when the pad is touched and/or released.

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.

Buttons and Sliders can have their OSC Address further customized by including # in the OSC Address. The button or slider index will be placed where the # is located in the address, instead of at the end. E.g /test/#/layer will send to OSC addresses /test/1/layer, /test/2/layer etc.

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. Declare these uniforms/varyings in your shader yourself to access them.

Note that while OSC/PILOT uses (0,0) as the coordinate for the top-left of the widget when setting/getting the value for MIDI and OSC, GLSL uses (0,0) as bottom-left for it's origin, so these coordinates are converted over for the GLSL shader.

// 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], with (-1, -1) being the lower left corner of the widget.
uniform vec2 mouse;
uniform vec2 iMouse;

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

// The position of the current pixel within the widget, Value in range [-1, 1], with (-1, -1) being the lower left corner of the widget. You can compare this to iMouse to determine how close the current pixel is to the mouse position. E.g if (length(iMouse - surfacePosition) < 0.1)

varying vec2 surfacePosition;

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. The scale is saved on the host machine, not into the .plt file. It is saved along with path of the .plt file to the machine's local.cfg file, so the same .plt file on different machines can have different scales set for it. If you rename the file or move it to a new directory on the the same machine, you'll need to re-set the scale (unless you use Save-As within OSC/PILOT).

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

A, B, C, D, E - Up to 5 different OSC sockets can be configured, and widgets can be setup to interact with all, some or none of those sockets on a per-widget basis.

Project Specific - Determines if the OSC settings are saved inside the .plt file as part of the project, or if the settings are system wide. System wide OSC settings will be used for all projects running on that system that don't have 'Project Specific' enabled.

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.

Edit Server

To more easily send project files to the iOS version of OSC/PILOT. The desktop version can be setup to be an Edit Server the iOS version connects to. You enable the server here, and connect to the desktops IP/Port in the iOS app, you can press the 'Update' button in the iOS app and the current project will be replaced with the current project loaded into OSC/PILOT running on the desktop.

Note that the iOS version will save a local copy of the project using the filename currently in use in the desktop instance, so be sure to name your projects well and avoid duplicate names to avoid overwriting projects.

MIDI Settings

MIDI Outout 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.

MIDI Input Device - Select which MIDI device to receive messages 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, https://en.wikipedia.org/wiki/Open_Sound_Control) 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, appended 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.

Label widgets support 'Send', which causes the Label's text to be sent out over OSC. This in particular is useful when editing the label in 'Play' mode, and using the OSC Loopback to cause a button to trigger the send.

Button and Label widgets support 'Text', which can be used to set the text value for these widgets. Labels can still also be controlled using their main OSC address.

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