Skip to content

Open Sound Control (OSC) Interface

Jump to bottom
chichian edited this page Oct 1, 2018 · 19 revisions

trowaSoft Sequencer OSC Interface

The trowaSoft sequencers (trigSeq, trigSeq64, and voltSeq) can be controlled and send feedback via OSC. The namespace is tsseq. Currently, each sequencer instance must use different ports. In the future, sequencers may be allowed to use the same ports to listen to and talk to the same end point.

OSC functionality provided by oscpack library. For more information about OSC, please visit opensoundcontrol.org.

This feature is available as of v0.5.5.1. This interface is an alpha and will likely change as we figure out how best to integrate OSC.

It has had a major rework in v0.5.5.2 in order to work directly with TouchOSC (no PD patch required).

Please report bugs or give feedback on the OSC interface on the Github Issue Tracker.

Setup & Usage

Starting OSC

To start using OSC on the sequencer, you will need to know the IP Address of the OSC client and the input/output ports. Any PD patches we supply will likely be set to localhost (127.0.0.1), using ports 7000 and 7001.

  1. Click on the "OSC" button to bring up the OSC Configuration form on the top display screen.

  2. By default the IP Address will be set to your local machine (127.0.0.1) and if this is the first instance of a sequencer in OSC mode, the default output port will be 7000 and the default input port will be 7001. If these are not correct, then edit the form fields with your desired values (i.e. IP of your iPad if using Touch OSC). Only IPv4 is supported.

  3. Select the OSC client type (Generic or touchOSC).

  4. If you would like to have the module automatically restore the connection on load from save file, then check the Auto Con option. If the connection is active in the save file and this is checked, the module will reconnect when you reload the save.

  5. Press the [ENABLE] button to attempt to start up OSC. The blue message at the bottom should go from "OSC Not Connected" to showing the connected IP Address. The "OSC" button should also light up blue. If there were any errors connecting then it should state the error in red underneath the IP Address form field.

  6. Press the "OSC" button again to hide the configuration form.

Stopping OSC

  1. Click on the "OSC" button to bring up the OSC Configuration form on the top display screen.
  2. Press the [DISABLE] button. The blue message at the top should return to "OSC Not Connected".

Troubleshooting

If the sequencer has problems connecting:

  1. Check that you are not already using the same port on another sequencer. Currently, each sequencer will capture its own listening port so two sequencers cannot share :(.
  2. Check the client/host device is on the same network.
  3. Check that the ports are not blocked by a firewall.

TODO: Finish more troubleshooting/tips.

OSC Client Files

Some development has been done for using OSC clients on Android/iOS.

TouchOSC

Note: Please make sure you have updated your TouchOSC app and editor to the latest versions.(https://hexler.net/software/touchosc#downloads)

Download Layout file: [v0.5.5.2]

The TouchOSC layout has a tab for trigSeq, trigSeq64, and voltSeq. Currently only one sequencer in VCV can talk to your Touch OSC device at a time though.

The sequencers work directly with TouchOSC. You do NOT need a PD patch for them. Just select "TouchOSC" from the client drop down list in the sequencer.

For more information about TouchOSC, visit: (https://hexler.net/software/touchosc) (available for iOS and Android).

Lemur

(Coming soon-ish)

For more information about Lemur, visit: (https://liine.net/en/products/lemur/) (available for iOS and Android).

Purr-Data (PD) Patches

Purr-Data patches are available to communicate with various control surfaces (to translate OSC into MIDI). Obviously we don't own every controller, so you can follow the patch examples and this document to create your own PD patch for your own controller if it is not available here.

If you cannot find a file, please also check geekasaurusrex.net as that page may be more up to date.

General Purr-Data Setup

  1. Download and install Purr-Data for your platform from the releases page: https://github.com/agraef/purr-data/releases.
  2. You can now either use an existing PD patch or create your own (you can follow the Launchpad PD patch as an example).
  3. Set up the IP address, input port, and output port in the patch.
  4. Enable OSC on a trowaSoft sequencer (set up the IP and ports).

Launchpad PD Patch

This particular patch and controller are best suited for the trigSeq64.

PurrData Setup

  1. Download the PD patch trigSeq64_Launchpad.pd (or look in the trowaSoft plugin directory, in the folder "pd" and find the patch).
  2. Open the patch in PurrData.
  3. [PurrData] Change the IP Address (if needed). If you are running it on the same computer as VCV Rack, it will be 127.0.0.1 and you do not have to change anything. Otherwise this is the IP address of the computer that is running VCV Rack.
  4. [PurrData] Change the PD Output Port (if needed). This will be the trowaSoft sequencer's INPUT port (PD will output to the sequencer, the sequencer will read this in).
  5. [PurrData] Change the PD Input Port (if needed). This will be the trowaSoft sequencer's OUTPUT port (the sequencer will output over this port, PD will read this in).

VCV Rack (trigSeq64)

  1. Add a trigSeq64 to your Rack patch.
  2. Follow the Starting OSC instructions. The IP Address will be the IP Address of the computer running PurrData. If you are running PurrData on the same computer, you can leave it as 127.0.0.1.
  3. [Rack] Change the Output Port (if needed). This will be the PD INPUT port.
  4. [Rack] Change the Input Port (if needed). This will be the PD OUTPUT port.

Launchpad Mappings

Button Symbol Function Notes
learn (^) N/A – Not yet mapped
view (v) N/A – Not yet mapped
page left (<) Reset
page right (>) Play/Pause
inst (session) Jump to step Hold down (session) and press a Pad to move the playhead to that step.
fx (user 1) Set Play Length Hold down (user 1) and press a Pad to set the Play Length.
user (user 2) Set Play Pattern Hold down (user 2) and press a Pad to select the Pattern to play.
mixer (mixer) Set Edit Pattern / Edit Channel (9-16) Hold down (mixer) and press a Pad to select the Edit Pattern. Hold down (mixer) and press a RHS button to set the Edit Channel (9-16).
RHS buttons (8) (|>) Set Edit Channel Set Edit Channel to 1-8. Hold down (mixer) button at the same time for 9-16.
Pad buttons [ ] Step / Length / Pattern By default, turns on/off step for current Edit Channel. With a function key, will set the Playhead, Play Length, or Edit Pattern.

Sequencer Output OSC Messages

The following messages will be sent from the sequencer. In general, messages will only be sent when the state of that object/value changes.

NOTE: In general, numbering of items is now 1-based. For example step starts at 1 for the first step and goes from 1 to 64 for a trigSeq64.

Function Address Parameters Event Trigger / Notes
Send Play State
(Playing/Paused)		 /tsseq/play/state int playing Event:
Play state changed.
Notes:
0:Pause, 1:On
Send Play Toggle
(Playing/Paused)		 /tsseq/play/state/tog int playing Event:
Play state changed.
Notes:
0:Pause, 1:On
Send Internal Step Clock Tick
or External Clock Pulse		 /tsseq/clock int step Event:
Clock tick / step increment (from internal clock or external clock).
Notes:
New step # sent (1-16 or 1-64)
Sequencer Reset /tsseq/reset “bang” Event:
Reset button clicked or signal received.
Send Current Playing Pattern /tsseq/play/pat int pattern Event:
Playing pattern # changed.
Notes:
Pattern 1-64.
Send the Current Stored Play Pattern /tsseq/play/pat/sav int pattern Event:
Stored Play Pattern has changed.
Notes:
Pattern 1-64.
Send Current BPM /tsseq/play/bpm float bpm, int divisorId Event:
Tempo changed
Notes:
divisorId: 0:1/4, 1:1/8, 1:1/8T, 2:1/16.
The sequencer will send the BPM value (not the tempo value) for display purposes in BPM.
Send Stored BPM /tsseq/play/bpm/sav int bpm Event:
Stored BPM has changed.
Notes:
BPM should be measured in the current BPM note/divisor (i.e. ¼ notes, 1/8th notes, etc).
Send BPM Divisor /tsseq/bpmnote int divisorId Event:
BPM display changed
Notes:
divisorId: 0:1/4, 1:1/8, 1:1/8T, 2:1/16
Send Step Value /tsseq/edit/step/{step} float value Event:
Step value changed
Notes:
Value: trigSeq sends 0 or 1; voltSeq sends -10 to +10.
Send Step String [touchOSC] /tsseq/edit/step/str/{step} string valStr Event:
Step value changed
Notes:
The step number starts at 1 and is part of the address (for touchOSC). So for step 3, then the address will be “/step/str/3”.
voltSeq only. voltSeq will send a display string representating the value.
Send Step Value (Grid) [touchOSC] /tsseq/edit/stepgrid/{row}/{col} float value Event:
Step value changed
Notes:
For touchOSC multi-Push or multi-Toggle controls which are addressed by the row and col. Rows start at the bottom. Rows and columns are 1-based.
trigSeq and trigSeq64 only
Send Current Length /tsseq/play/len int stepLength Event:
Step length (play length) changed.
Notes:
Length is 1 to numSteps (numSteps has a maximum of 16 for trigSeq and voltSeq; maximum of 64 for trigSeq64).
Send the Current Stored Play Length /tsseq/play/len/sav int stepLength Event:
A step length has been stored.
Notes:
Length is 1 to numSteps (numSteps has a maximum of 16 for trigSeq and voltSeq; maximum of 64 for trigSeq64).
Send Current Output Mode
(TRIG, RTRIG, GATE)
or (VOLT, NOTE, PATT)		 /tsseq/play/omode int modeId Event:
Output mode changed
Notes:
trigSeq: (0:TRIG, 1:RTRG, 2:GATE;)
or voltSeq: (0:VOLT, 1:NOTE, 2:PATT).
Send Current Edit Pattern /tsseq/edit/pat int pattern Event:
Current Pattern being edited has changed.
Notes:
Pattern 1-64.
Send Current Edit Channel /tsseq/edit/ch int channel Event:
Current Channel being edited has changed.
Notes:
Channel 1-16.
Send Mode
(Edit, Performance)		 /tsseq/mode int mode Event:
Current Performance Mode changed.
Notes:
0: Edit, 1: Performance.
Currently the Sequencer GUIs have no way to set this, it is only settable via OSC.
Send Current Clipboard
(copied)		 /tsseq/edit/clipboard/ int pattern, int channel Event:
A pattern or channel has been copied to the clipboard
Notes:
If an ENTIRE pattern has been copied to the clipboard, then channel will be -1.
Send Current Pattern Copied to clipboard [touchOSC] /tsseq/edit/pat/cpycurr int pattern Event:
A pattern has been copied to the clipboard.
Notes:
Pattern 1-64.
Send Current Channel Copied to clipboard [touchOSC] /tsseq/edit/ch/cpycurr int channel Event:
A channel has been copied to the clipboard.
Notes:
Channel 1-16.
Send Current Step LED [touchOSC] /tsseq/step/led/{step} int value Event:
Current step has changed.
Notes:
{step} is the step number (1-maxSteps). Value is 0:Off or 1:On.
Current Step LED Color [touchOSC] /tsseq/step/led/{step}/color string color Event:
Channel has changed, step colors should change.
Notes:
{step} is the step number (1-maxSteps). Color is a touchOSC named color.
Step Color [touchOSC] /tsseq/edit/step/{step}/color string color Event:
Channel has changed, step colors should change.
Notes:
{step} is the step number (1-maxSteps). Color is a touchOSC named color.
Step Grid Color [touchOSC] /tsseq/edit/stepgrid/color string color Event:
Channel has changed, step colors should change.
Notes:
Color is a touchOSC named color.

Sequencer Input OSC Messages

The sequencer will respond to the following messages.

NOTE: In general, numbering of items is now 1-based. For example step starts at 1 for the first step and goes from 1 to 64 for a trigSeq64.

Function Address Parameters Event Trigger / Notes
Set Play State /tsseq/play/state int value Event:
Set the Play/Running state.
Notes:
0:Pause, 1:On
Toggle Play/Pause /tsseq/play/state/tog -NONE- Event:
Toggle the Play/Running state.
Notes:
Toggle the playing state on or off
Reset /tsseq/play/reset -NONE- Event:
Reset the sequencer (same as hitting the Reset button or getting a Reset signal).
Notes:
Reset the sequencer to index 0.
Change Playing Pattern /tsseq/play/pat int pattern Event:
Set the currently playing Pattern.
Notes:
Pattern 1-64. Send -1 to use the Current Stored Play Pattern from a Store Play Pattern message.
Store Play Pattern /tsseq/play/pat/sav int pattern Event:
Store/save a play pattern.
Notes:
Stores the Play Pattern. Does not jump to this pattern yet. Send a Change Playing Pattern message with -1 as the pattern to play the stored pattern.
Set BPM /tsseq/play/bpm int bpm Event:
Set the BPM value.
Notes:
Set the tempo in BPM. Uses current BPM note. Send -1 to use the current “Stored BPM” value from a Store BPM message.
Add to BPM /tsseq/play/bpm/add int addBPM Event:
Add to the BPM value.
Notes:
Add or subtract (send negative) from BPM. Uses current BPM note.
Store BPM /tsseq/play/bpm/sav int bpm Event:
Store/save a BPM value.
Notes:
Stores the play speed/BPM. Does not change to this speed yet. Send a Change BPM message with -1 as the BPM to change the speed to the stored value.
Set Tempo (0-1) /tsseq/play/tempo float tempo Event:
Add to the BPM value.
Notes:
Tempo 0.0-1.0
Add to Tempo (0-1) /tsseq/play/tempo/add float addTempo Event:
Add to the BPM value.
Notes:
Add or subtract (send negative) from Tempo. Tempo is from 0.0-1.0.
Set BPM Note /tsseq/play/bpmnote int divisorId Event:
Set the current BPM display.
Notes:
divisorId: 0:1/4, 1:1/8, 1:1/8T, 2:1/16
Add to the BPM Note Index (selection) /tsseq/play/bpmnote/add int addIx Event:
Increment or decrement in the BPM display note list.
Notes:
Jump this many in the BPM Note list (i.e. +1 to go to the next, -1 to go to the previous)
Change Step Length /tsseq/play/len int step Event:
Set the playing step length.
Notes:
Set the length (1 to numSteps)
Store Step Length /tsseq/play/len/sav int pattern Event:
Store/save a play step length.
Notes:
Stores the Play Length. Does not immediately set the step length. Send a Change Step Length message with -1 as the length to use the stored value.
Set Ouput Mode
(TRIG, RTRIG, GATE)
or (VOLT, NOTE, PATT)		 /tsseq/play/omode int modeId Event:
Set the Output Mode
Notes:
trigSeq: (0:TRIG, 1:RTRG, 2:GATE;)
or voltSeq: (0:VOLT, 1:NOTE, 2:PATT).
Change Edit Pattern /tsseq/edit/pat int pattern Event:
Set the currently editing Pattern.
Notes:
Pattern 1-64
Change Edit Channel /tsseq/edit/ch int channel Event:
Set the currently editing Channel.
Notes:
Channel 1-16
Set the Step Value /tsseq/edit/step int step, float value, (opt) int pattern, (opt) int channel Event:
Set the value for the step.
Notes:
step starts at 1 (i.e. 1-16 or 1-64) and the value is the value to set it to.
trigSeq only accepts 0 or 1.
voltSeq accepts -10 to +10.
Optionally supply Channel (1-16) & Pattern (1-64). If not specified, uses the Current Edit Channel/Pattern.
Set the Step Value /tsseq/edit/step/{step} float value Event:
Set the value for the step. (For touchOSC which cannot send > 1 arg)
Notes:
{step} should be part of the address and starts at 1 (i.e. 1-16 or 1-64). The value is the value to set it to.
trigSeq only accepts 0 or 1.
voltSeq accepts -10 to +10.
The pattern and channel may also be supplied otherwise they will apply to the pattern & channel currently being edited (shown) on the sequencer.
Toggle Edit Step /tsseq/edit/step/tog int step, (opt) float value, (opt) int pattern, (opt) int channel Event:
Toggle the value for the step.
Notes:
Toggle the current value at the given step.
For trigSeq, toggles on/off.
For voltSeq, may multiply value by -1.
Set the Step Value (Grid) [touchOSC] /tsseq/edit/stepgrid float value Event:
Set the value for the step in a grid [touchOSC].
Notes:
Set the current value at the given step on the grid for touchOSC multi-Push or multi-Toggle controls. URL should be /tsseq/edit/stepgrid, touchOSC should append “/{row}/{col}” where the {row} and {col} are 1-based and start from the bottom left. trigSeq and trigSeq64 only,.
Jump to Step Number (playing) /tsseq/play/step int step Event:
Jump the play head to this step number.
Notes:
step starts at 1 (i.e. 1-16 or 1-64).
NOTE: The currently playing step is allowed to finish, but the next tick plays this step.
Set Mode
(Edit, Performance)		 /tsseq/play/mode int mode Event:
Set the Performance mode.
Notes:
0: Edit, 1: Performance.
Currently the Sequencer GUIs have no way to set this, it is only settable via OSC.
Toggle Mode
(Edit, Performance)		 /tsseq/play/mode/tog -NONE- Event:
Toggle the Performance mode.
Copy Channel /tsseq/edit/ch/cpy (opt) int channel, (opt) int pattern Event:
Copy Channel
Notes:
Optionally supply Channel (1-16) or Channel & Pattern (1-64). If not specified, uses the Current Edit Channel/Pattern.
Copy Pattern /tsseq/edit/pat/cpy (opt) int pattern Event:
Copy Pattern
Notes:
Optionally supply Pattern (1-64). If not specified, uses Current Edit Pattern.
Copy Current Channel [touchOSC] /tsseq/edit/ch/cpycurr -NONE- Event:
Copy Channel
Notes:
Copies the Current Edit Channel.
Copy Current Pattern [touchOSC] /tsseq/edit/pat/cpycurr -NONE- Event:
Copy Channel
Notes:
Copies the Current Edit Channel.
Paste /tsseq/edit/clipboard/pst -NONE- Event:
Paste the current clipboard contents to the current Edit Pattern or Edit Channel.
Notes:
Only one item may be on the clipboard at a time (i.e. a copied Channel or copied Pattern). If nothing is on the clipboard, nothing happens.
Randomize Channel Steps /tsseq/edit/step/rnd -NONE- Event:
Randomize the current Edit Channel's step values.
Notes:
Randomizes the Current Edit Channel steps only (not the knobs). Same as using the Context Menu in Rack and choosing “Randomize”.
Initialize the module /tsseq/edit/module/init -NONE- Event:
Initialize the module.
Notes:
Initializes the module to default values. Same as using the Context Menu in Rack and choosing “Initialize”.
Request module init
(w/confirmation)		 /tsseq/edit/module/init/sav int doInit Event:
Request initialization of module.
Notes:
Set the saved Initialization signal (send 1 to initialize, 0 to clear). Does not immediately initialize the module. Will wait for either a Confirm or Cancel message (/cncl or /confirm).
Cancel/Clear the module initialization request. /tsseq/edit/module/init/clr -NONE- Event:
Cancel the module init request.
Notes:
Cancels/clears the initialization request.
Confirm the module initialization request. /tsseq/edit/module/init/confirm -NONE- Event:
Confirm the module init request.
Notes:
Cancels the initialization confirmation.
Clone this wiki locally