(1) Just the Best Parts: OSC for Artists

Just the Best Parts: Open Sound Control for Artists

By James Britt

2013 James Britt

All rights reserved. This book or any portion thereof may not be repro-
duced or used in any manner whatsoever without the express written
permission of the publisher except for the use of brief quotations in
a book review, and certain other noncommercial uses permitted by
copyright law.

Published by Neurogami and Just the Best Parts

See http://justthebestparts.com for great books.

For information please contact info@justthebestparts.com

 Contents
Chapter 0
Welcome! 1
Chapter 1
OSC: What it is, and why you should care about it 2
Whence OSC 5
OSC origins 8
Chapter 2
OSC Technical Details 11
The structure of OSC message patterns 17
Networks and stuff 20
Geeky tech summary 22
Chapter 3
Practical examples 24
Code recap 42
Wrapping up 47
Whence OSC: The really short graphic novel
 Chapter 0

Welcome!
Welcome to Just the Best Parts: OSC for Artists.
This book teaches you about Open Sound Control or, as its usu-
ally called, OSC.
It explains what OSC is, why you should care about it, and how
you can use it. It includes some simple hands-on examples that let you
see how it works and what it can do.
I hope you enjoy this book and find it useful.

A word about the illustrations

The images in the first and second chapter are part of a sequen-
tial comic about MIDI and OSC.
They are presented on their own at the end of the book.

James Britt

Just the Best Parts: OSC for Artists (1)

 Chapter 1

OSC: What it is, and why you should care

about it
OSC is a way for programs, computers, and things that contain
programs or computers to communicate. Its useful to artists because
it can connect any number of different things to one another.
Things could be almost anything electronic, from your comput-
ers mouse and keyboard to MIDI keyboards, your smart phone, and
game controllers. This category also includes computer programs for
making music, doing animation, controlling stage lighting, or manipu-
lating puppets, and so on.
This type of connection is not merely boring geek stuff. Think
about what you do as an artist, as a musician, or aswell, whatever
you do to make life a more interesting experience. If youre drawing a

(2) Just the Best Parts: OSC for Artists

picture, you might be using a pencil or charcoal to leave some marks
on paper. Or perhaps you have a brush and paints to work on a can-
vas. Or maybe youre sitting in front of a Steinway playing Mozart or
Jerry Lee Lewis. You are in some way manipulating something out
there based on whats in your head

If youre using a tool such as traditional pencils or paintbrushes,

the idea that what youre doing is out there or in some way remote
may sound odd. Suppose youre using a tablet or a mouse to create
images on your computer, or you have a MIDI keyboard wired up to a
computer or synthesizer. Youre doing the same thing you would with
more traditional tools, but its less direct. You may be seeing or hear-
ing things pretty much immediately, but you have some intermediary
technology in there.
There are two important things happening here.
One is that how odd or artificial this seems to you is a matter of
familiarity and adaptation. If you are using an electronic keyboard to
play what sounds like piano music, you are aware ofbut not terri-

Just the Best Parts: OSC for Artists (3)

bly disturbed bythe fact that you are not playing an actual piano
and there are no piano strings or other mechanical systems involved.
Indeed, the absence of these elements is actually preferred by some
musicians.
Many people even take this concept a step further and use de-
vices that look nothing like conventional music keyboards; theyre
more akin to the blinking controls of secret laboratories in 1960s
science fiction movies.
Likewise, if you are using a tablet to create drawings in Adobe
Photoshop, you might use a charcoal pencil effect to create a certain
look. Theres no charcoal or paper here, and if youre using the mouse
or trackpad, theres nothing even like a pencil. Still, you probably
dont think of this approach as peculiar.
You can go even further: in both of these situations, you can not
only use artificial tools to get good approximations of real-world ef-
fects but can also use them to generate notably unreal-world results.
There is no fixed relation between the specific tool chosen and the
end results: its your choice.
The other notable thing is that you can use such tools to make
something happen somewhere else in real-time. It may seem stun-
ningly trivial to say that your computer screen is somewhere else,
but although close, it is not the same place as where you are drawing.
And using a projector to draw for a crowd is even further away. Of
course, this argument also holds for using electronics to make music.
You may see some banality in this concept because it is, in many
ways, commonplace. But consider the implications: you can use some-
thing located here to directly control some other thing over there.
The distance between here and there is generally constrained by the
length of wires, and the selection of what things (tablet or electronic
keyboard) talk to which other things (drawing or music program) may
be limited. The tablet is probably not playing music; the music key-
board is probably not creating drawings.
Here is where OSC comes in. OSC allows you to wire up a greater

(4) Just the Best Parts: OSC for Artists

variety of things over a much larger distance.
With OSC, you could use a Nintendo Wii game controller to play
music. Or sit in the back of a theatre and control stage lighting from
your smartphone. Or put on a puppet show controlled by an Xbox Ki-
nect tracking the movement of live actors. Or use your drawing tablet
to play live music. Or use a music keyboard to generate visuals.
Some programs and devices can handle OSC right out of the box.
Others need a bit of help. In both cases, the fundamentals of OSC are
the same. Thats what youll learn about in this book, with the help of
some examples.

Whence OSC

Where did OSC come from? The explanation starts not with OSC
but with MIDI.
The Musical Instrument Digital Interface (MIDI) is a music industry
specification; it is a formal description of an essentially finite set of
commands or instructions.

Just the Best Parts: OSC for Artists (5)

 Colloquially, MIDI is how computers do music.
The MIDI standard, published in 1983, is both a software and
hardware standard; in addition to describing the format of each
message, the MIDI standard describes a type of cable connection. It
was developed to provide this standard way for electronic music
devices to communicate.

Using MIDI, some sort of music data source (such as a keyboard

or computer program) can describe, for example, the note A above
middle C, with a specific duration and key velocity. It can do it in a way
that any number of other devices or programs that work with MIDI
will reliably understand.
MIDI is extremely handy. In addition to describing notes and
chords, there are MIDI instructions for device and system commands.
And although the actual transmission of MIDI commands is a fairly
abstract computer event, there are ways to save MIDI commands to a
file. This means that you can use a computer to compose a musical
score in MIDI, save it as a file, and send that file to someone else. The

(6) Just the Best Parts: OSC for Artists

recipient can then feed your file into their own MIDI tools and play
back your score.

So far, so good. Although it is immensely useful andin prac-

tice, revolutionarysome people found MIDI lacking. MIDI imposes
assorted restrictions. For example, there are a fixed number of MIDI
commands. These are typically enough for general music applications,
but there are times when a custom instruction would be tremen-
dously useful.
MIDI is also limited in the type of data it can send. It deals only
with numbersspecifically, integers (that is, no fractions or numbers
with a decimal point).
Whats ultimately important is not whether these are, or were,
real causes for concern for most people. What matters to us is that
they motivated some people to create an alternative that did not have
these limitations. In practice, MIDI is still far more prevalent than OSC,
but because there are ways to convert OSC to MIDI (and vice versa),
you can take advantage of them both and choose whichever way

Just the Best Parts: OSC for Artists (7)

works best for your circumstances.

OSC origins
According to the OSC Web-site (http://opensoundcontrol.
org/introduction-osc),
OSC was originally developed, and continues to be a subject
of ongoing research at UC Berkeley Center for New Music
and Audio Technology (CNMAT). CNMAT is an interdisciplin-
ary research center within the UC Berkeley Department of
Music.
Before OSC there was ZIPI (Zeta Instrument Processor Interface),
an attempt to address some of the perceived shortcomings of MIDI. It
didnt catch on.
But in 1997, Matt Wright and Adrian Freed, who worked on ZIPI,
released the Open Sound Control specification.
Unlike MIDI, OSC did not define any hardware requirements. It

(8) Just the Best Parts: OSC for Artists

just specified a data format. The geek lingo for this type of standard is
transport independent. It means that you can send OSC messages
over telephone lines, over computer networks, or by carrier pigeon,
as long as whatever or whomever receives the OSC message knows
the implementation details of the transport system (i.e., telephone,
computer network, or bird) in order to extract the OSC message
content.

Surprisingly, in practice nobody uses pigeons. Instead, pretty

much all OSC implementations use computer networksthe kind you
already have.
This means that in order to start using OSC, you dont need to buy
any new hardware: you just need to get some software.

Just the Best Parts: OSC for Artists (9)

 In the next chapter, well look at the excitingly geeky details of
OSC software.

(10) Just the Best Parts: OSC for Artists

 Chapter 2

OSC Technical Details

You can read the Open Sound Control 1.0 specification at
http://opensoundcontrol.org/spec-1_0.
Theres no benefit to repeating every detail here. Instead, this
section will smooth out the sharp nerd edges to put the important
parts of the specification in practical terms.
OSC is described as a transport-independent, message-based
protocol. What does this mean in human-speak?
Imagine that you are throwing a party, and you want a band to
perform. You tell people that they should let you know if they are
interested in playing at your party, indicate the dollar amount of what
they expect to be paid, and provide a phone number for contact infor-
mation.
In other words, you want people to send you a message with the

Just the Best Parts: OSC for Artists (11)

following information:
Interested? (yes/no)
Expected compensation (a number)
Who to contact (a phone number that may have numbers
and letters)
You probably dont care if you get these messages via e-mail,
postcard, or hand-delivered papyrus scroll.
This indifference to the details of how the information gets to you
is the transport-independent part of OSC. Of course, whatever
method is used must be something you can actually handle. The same
is true for OSC, but the OSC specification doesnt say that OSC mes-
sages have to be sent in any particular way.

The presumption is that, just as when people respond to your

band request, people using OSC will work out a way that all parties
can understand. (Youll see later in this book how that happens in
practice.)
While youre looking for a party band and reading these mes-

(12) Just the Best Parts: OSC for Artists

sages, youre going to be looking for the particular information you re-
quested. You expect to find those three items of interest somewhere
in the message.
We humans are really good at pulling out information from a vari-
ety of content in assorted formats. Machines . . . less so. Its rare that
you can just throw stuff at a computer and it will know exactly what
you mean.
If you expect a large number of replies to your request, you might
want people to respond using a consistent format. You might require
potential bands to follow each of your questions with the answer on
the next line, all by itself. Or, because you know the questions, you
might simply ask people to respond with just the answers to your
questions, separated by commas, like this:
Yes, 1000, (212) 555-1212
Then, like a machine, you could process the responses quickly.
Computers have to follow predefined message formats. Even
when a machine can pull out useful data from haphazard messages,
the use of a predefined message format makes things go much faster.
The OSC specification gets into a fair amount of detail about the
format of OSC messages. Heres one of the cool things about using
OSC: unless you are writing software to send or receive OSC mes-
sages, you do not need to know these details.
You dont need to know the deep mechanics of an OSC message,
but youll want to know, at a higher level, what sorts of information
can go into an OSC message.

Just the Best Parts: OSC for Artists (13)

OSC Messages
First, some terminology. The software on your device that sends
an OSC message is an OSCclient. Whatever is receiving those mes-
sages is the OSCserver. These names may or may not seem backward
to you, but thats how the terms are used.

When people write about OSC messages, such as to describe

what messages some particular software sends or understands, they
use something that looks like this example:
/some/message/pattern i, s, f
You will also often see the descriptions written like this:
/some/message/pattern isf
The part with the slashes that looks something like a Web address
is called themessage pattern.
The text that comes after the message pattern is a list of tag
types. When an OSC client sends a message, there must be a message
pattern, and there may also be some additional information or data.
The OSC specification says that additional data can be text or a

(14) Just the Best Parts: OSC for Artists

number. (The specification is actually much more precise than that,
but this will do for now.)
Many people write out their OSC messages using single-character
tag-type notation. The OSC specification defines a very small set of tag
types. It accepts that in real life, various OSC systems may implement
nonstandard tag types, so it defines a set of type tags for a dozen or
so kinds of data that can be sent as part of an OSC message.
These are the official tag types:
OSC type tag Kind of data
i Integer
f Floating-point number
s String
b OSC blob
For the non-geeks (quite possibly everyone) reading this, some
explanation follows.
Integersare numbers without a decimal point. Theyre sometimes
called counting numbers,and theyre what you use when you . . .
well, count stuff, or ask for some specific amount of something, as in,
Id like 429 cerulean-blue marbles, please.
Floating-pointnumbershave a decimal point to express fractions.
These are the kinds of numbers you see on a credit card receipt, for
example, where they indicate (in the United States) dollars and cents;
the cents are fractions of dollars. $1034.94 for the marbles? Thats
crazy!
Stringis geek talk for one or more characters, also often called
text, or sometimes just characters. These are all strings.
Ablobis not some jelly-like thing but abinary large object. A blob
is a way to package up a whole bunch of a lot of stuff as one thing.
The binary aspect means that the data being sent are packaged in a
way that makes it easy for a computer program to figure out; unlike
strings or integers or floating-point numbers, you cant just look at it
and know what it is.

Just the Best Parts: OSC for Artists (15)

 In some cases, it may be helpful to know all the gory detailsbut
usually, its not. Youll most often use some software or tool to man-
age the sending and receiving of OSC messages, in some cases enter-
ing the values to send or the address patterns to use. You are more
likely to be struck repeatedly by lightning after winning the lottery a
few times than to have to craft your own OSC blob. If your numbers
are too big or too small, the software will yell at you.

(Im lying about that last part. Theres a lot of software that, when
given the wrong data, just fails to do something sensibleoften with
no indication about what you need to do to make things right. But the
solution rarely requires a detailed understanding of the OSC message
format. Instead, youll just have to figure out the quirks of the applica-
tion youre using.)
The bottom line is that there are a few things that any OSC setup
absolutely requires and a dozen more things that are likely to be avail-
able. Although you might not need all the details, it is helpful to know
what kinds of data you can use with OSC.

(16) Just the Best Parts: OSC for Artists

 If you are simply setting up some existing components, you can
rely on them to send valid data. However, if you are crafting your own
OSC messages, youll need to know what will work. But at that point,
you can refer to the specification for the details you need..

DIY
You do not need to be a programming guru in order to
create your own OSC software. There are existing tools,
such as Processing, that manage much of the complexity
for you. If youve ever written JavaScript or done Flash
programming, youll have no trouble using Processing. If
programming is new to you, good news: its easy to get
started with Processing.
In fact, some free software was created for the book
Kinect Hacking for Artists(in Processing) that allows you
to do some basic OSC exploration. This program is dis-
cussed later on in this book.

The structure of OSC message patterns

Message patterns look much like URLs for Web pages or direc-
tory paths on your computer. This similarity is useful in understanding
message patterns. As with Web pages and file paths, OSC messages
start out general and end up more specific.
For example, the music tracker program Renoise (http://www.
renoise.com) has a built-in OSC server, which means that you can
control your music from, among other things, your phone or tablet,
using multi-touch controls. (Its really quite slick.)
Renoise defines a core set of OSC messages it will handle. For
example, you can stop and start your song using::
/renoise/transport/start
/renoise/transport/stop
A few things to note: neither of these messages take any argu-
ments. You dont pass along any data when your client sends these

Just the Best Parts: OSC for Artists (17)

messages.
In addition, they both havethe pattern /renoise/transport.
In fact, all of the Renoise OSC messages begin with/renoise.
You can see all of the built-in Renoise OSC message athttp://
tutorials.renoise.com/wiki/Open_Sound_Control.
The messages are defined using a set of hierarchies to group sim-
ilar items
Messages that deal with the playing of a song all fall under the
pattern/renoise/transport/.
Song details are managed by the/renoise/songhierarchy.
Here youll find a number of /renoise/song/track messages, as
well as /renoise/song/sequence,/renoise/song/record,
and a few others.
Theres no law that says youmust structure your OSC messages
using a hierarchy or grouping, but doing so makes things so much eas-
ier to understand and manage.

Pattern matching
Sensible hierarchies are also good because OSC allows for pattern
matching. Suppose, for example, that you have a stage lighting system
that defines messages for setting the brightness of any given light.
Perhaps you define messages such as these:
/stage/lights/1/brightness f
/stage/lights/2/brightness f
/stage/lights/3/brightness f
Its a small stage, so there are only three lights.
For any given light, you can send a message and pass along a deci-
mal value (a.k.a. floating-point number) to indicate the brightness. 0.0
means completely off; 1.0 means as bright as the light can be. These
messages behave much like slider controls that you might have for
your lights at home.
Note the use of thefin the message description. Thats the type

(18) Just the Best Parts: OSC for Artists

tag for floating-point. But you knew that already.
With this system, you can control any light you like, and if you
want them all to be the same value, you could send three messages,
one for each light, passing along the same value:
/stage/lights/1/brightness 0.60
/stage/lights/2/brightness 0.60
/stage/lights/3/brightness 0.60
That will work, and assuming that your OSC setup is decent, it
should appear that all the lights are changing at once.
But this approach is a bit inefficient, and theres always the
chance of a mistake in which a light gets omitted or is passed a dif-
ferent value. Or perhaps theres a transmission error, and one of the
message never makes it to the OSC server.
Using OSC pattern matching, you could instead send a single mes-
sage:
/stage/lights/*/brightness 0.60
The asterisk is a wild-card placeholder, and in an OSC system that
supports pattern matching it means apply this message to any that
would match if you swapped in values for the wildcard.
In the previous example, a single message is used to set all lights
to 60% brightness.
Another advantage to using a single message with pattern match-
ing is that because it applies to all matching address patterns, you
dont have to change your messages if lights are added or removed.
Keep in mind that not everything that handles OSC will also
implement pattern matching. For example, the current version of
Renoise (2.8.1) does not do any pattern matching.

Bundled messages
OSC clients can also send message bundles. A bundle is collection
of OSC messages all sent at the same time. When an OSC server gets a
bundle, it unpacks the messages and processes them as a whole. Bun-

Just the Best Parts: OSC for Artists (19)

dles are handy for sending a set of related messages, especially when
pattern matching may not be implemented.
As with pattern matching, not every application that offers OSC
will include support for bundles. Some software might have one fea-
ture but not the other.
The OscP5 library for the Processing language, for example, hap-
pily handles message bundles but does not support pattern matching.

Networks and stuff

Because its transport independent, the OSC spec doesnt require
OSC messages to be sent in any particular way. The details for any
given situation vary depending on how OSC is being used. For exam-
ple, if you have a stage lighting system that uses OSC, it is possible
that the system uses dedicated wiring and some custom means of
sending messages. But many tools and software that use OSC take
advantage of existing technology, especially computer networks.
Software such as Renoise sends and receives OSC messages over
a standard computer network. In these cases, there are two things
you need to know about the client and the server: theIP address and
theport number.
IPis short forInternet protocol. Yes,thatInternet. The technology
that lets you view Web pages and send e-mail is also what lets you
connect multiple computers in your home and send stuff from your
phone to a computer.
You can think of IP addresses as similar to phone numbers. They
need to be unique, so that if someone gives you a number to call, you
get the right person.
But IP addresses are sort of like phone numbers for offices. When
you call an office, you are often asked for an extension. Similarly, to
reach a computer on a network, you need the IP address, but you also
need a port. You can think of a port as something like a telephone
extension.

(20) Just the Best Parts: OSC for Artists

 Often when you call an office, you reach some default exten-
sionsame thing with computers. Various activities, such as Web
browsing or e-mail, operate on specific default ports.
There is no default port for OSC systems, so when you are setting
up an OSC client and server you must indicate the IP addresses and
the port numbers to use.
IP addresses often look like this:75.125.194.82. Basically, they
are four numbers, separated by dots.
(This is not entirely the whole complete story. However, we can
ignore a bunch of technical details at this point.)
There are assorted rules and conventions for IP addresses, and
one of them is that the special address127.0.0.1always refers
to the local machine. Therefore, if you have some OSC software
and you tell it to send messages to the computer at the IP address
127.0.0.1, it will send them to same machine that is running that
OSC software.
Think of it as a way for a computer to talk to itself.
Often, you will use different devices to exchange OSC messages,
in which case you will need to know the IP address for interacting with
the outside world.
If you are on Windows, open a command prompt and enterip-
config.
If you are on a Mac, open System Preferences, then click on
Network. Click on Ethernet in the left-hand side if it is not already
selected. The IP address will be listed on the right-hand side.
Finding out the IP address of your smartphone is a little trickier;
youll have to refer to your phones manual to see what to do. Its
likely under either a Network or System option.
One important thing to note is that in most cases your phone will
have to be using a local Wi-Fi network in order to communicate with
other local computers. Also, your phone must have Internet capabili-
ties.

Just the Best Parts: OSC for Artists (21)

 Just to be clear
Computer networking is a complex topic.
The intent here is to tell you just enough things that are
true enough to be good enough to get you rolling with
OSC over a network.

Port selection
Some programs with built-in support for OSC are preconfigured to
use one or another port. For example, Renoise is set to use port 8000
by default.
TouchOSC, a mobile app for Android and iOS devices, also defaults
to port 8000 for sending OSC messages, and to port 9000 for receiving
messages.
Unless you run into a problem, these are perfectly usable values.
There are times when some other application, unrelated to OSC, may
also decide to use port 8000.
If you are having trouble sending or receiving OSC messages using
a particular port, try changing ports.
There are some restrictions on what port numbers you can use. If
you pick a port number somewhere from 8000 to 9999, you should be
okay.

Geeky tech summary

OSC messages are typically sent over a computer network. The
network connection may be from a program on one device (e.g., your
phone or a laptop) to some application on another device, or it may
be a network connection between two applications on the same de-
vice.
When setting up a device or program to send or receive OSC mes-
sages, you need to know the IP address of the recipient or sender as
well as the port number to use. If both sender and receiver are on the
same computer, you can use the IP address 127.0.0.1, which is a

(22) Just the Best Parts: OSC for Artists

predefined address that always refers to the same local machine.
OSC messages have two parts: the address pattern, which looks
much like a directory path or part of a Web-site address (/some/ad-
dress/pattern), and any values to be sent with the message.
OSC messages do not have to be sent with values; an OSC mes-
sage all by itself might be enough to convey a desired action (such as
the Renoise OSC message/renoise/transport/stop).
The OSC specification defines what essential kinds of values mes-
sages can sent: integers, floating-point numbers, text, and OSCblobs.
However, the specification also describes additional kinds of data
that an OSC system may optionally handle. These include Boolean
(i.e., true or false) values, MIDI values, and timestamps.
When people are describing the OSC messages that their sys-
tem uses, they generally indicate what kinds of values each message
requires by usingtype tagnotation: a single character describing the
kind of data for each argument. For example:
/some/address/pattern ii
is a message that must include twointegervalues.
If you are creating your own program that handles OSC, you are
pretty much free to use whatever address patterns you like. However,
for the sake of your sanity, you should think about using a sensible
hierarchy in the patterns so that naming is more intuitive.
Next up: some practical examples and suggested practices.

Just the Best Parts: OSC for Artists (23)

 Chapter 3

Practical examples
The best places to read detailed descriptions of using OSC with
real-world applications are Just the Best Parts: Kinect Hacking for
Artists and Just the Best Parts: Leap Hacking with JRuby & Process-
ing (both available at http://justthebestparts.com). For now,
though, we will look at some simple programs so that you can see OSC
in action for yourself.
To start, you need a client and a server. As you might recall, the
client is the thing that sends out OSC messages; the server listens for
them and then takes some action based on whatever message was
sent.
In practice, the lines are little blurred because some OSC servers
will send back an OSC message to the client so that the client can, for
example, update its user interface based on what the server actually
did. For example, if you send a mute track message to some music
program, you would want to know that the program did in fact mute
the designated track. Likewise, if something else causes a track to be
muted (perhaps by direct interaction with the music program), its
handy to see that reflected in any OSC clients.
Conceptually, its probably simpler to think in terms of client and
server, where the server is the primary application or device you want
to control remotely..

Example applications
There are various free or inexpensive programs that use OSC.
Some are for desktops and laptops; others run on phones and tab-
lets. If you have an Android phone or tablet, or an iPhone or iPad,
then you should get TouchOSC (http://hexler.net/software/
touchosc-android for Android; http://hexler.net/soft-
ware/touchosc for iOS). The app is free for Android devices, but

(24) Just the Best Parts: OSC for Artists

$4.99 for iOS.
The iOS version has features that are not available in the Android
version. Were going to use TouchOSC as our first client for the exam-
ple.
(If you cant get TouchOSC, or dont want to buy it, dont worry.
Were going to also look at a free alternative, although it is not a
phone program.)

Wait; code?
Yes, but dont fret.
The sample apps are written in a programming language
called Processing.
It is freely available for a variety of operating systems,
including Windows, Mac OSX, and Linux.
It was created by artists for artists.
You can use it to do fun, cool, modern stuff.
But you dont have to!
Even if you decide coding is not for you right nowand
perhaps never will beit is instructive to look at some
of the code in these examples. If you end up using OSC
for something, there is a good chance that you will not
get to see the code for the program by just using it.
However, you should have at least some idea of whats
going on behind the scenes.
OSC, programming, network communications, and so
on may have their difficult points, but theyre not magic,
and although you might not (and need not) understand
all the details, it helps to have a basic understanding of
the general concepts.
With this basic understanding, youll be much better
able to take advantage of this technologyeven without
doing any coding.

Just the Best Parts: OSC for Artists (25)

 The example uses TouchOSC to send commands to a custom pro-
gram that generates an abstract animation based on a small number
of parameters. You can download an executable version of the pro-
gram from http://justthebestparts.com/downloads.

Sample application #1: OSC Rectangles

The example program is written using the Processing language,
and you can grab the source code from http://justthebest-
parts.com/downloads/ if you want to see exactly how it works.
If you have Processing installed, you can use it to run that sample
code.
Or you can download an executable version and run that instead.
This example requires you to use TouchOSC, and select the "Mix
2" layout.
You must have the phone or tablet running TouchOSC on your
local Wi-Fi. It must be on the same local network as the computer you
use to run Processing.
Go to the TouchOSC settings, open the OSC section, and set the
host value to the IP address of the computer youre using to run
Processing. Set the value of Port (outgoing) to 8001.
The example application is not going to send any OSC back to
TouchOSC, so you dont need to change the Port (incoming) value.
Make note of the value shown for Local IP Address. You will
need this value to configure the example program.
This first example is quite basic. It allows you to control the size
and location of two rectangles on the screen. It is in many ways trivial,
but the simplicity makes clear how OSC is used to manipulate a pro-
gram.
The program comes with a few code files and one configuration
file. Open that configuration file (cleverly named config.txt)
and edit it. Be sure to use a program that edits and saves plain text
(such as Notepad or TextEdit) and not as rich text or some other

(26) Just the Best Parts: OSC for Artists

word-processing format that embeds hidden styling with the content.
When you open the file in your text editor, you should see some-
thing like this:
192.168.0.2:8000
192.168.0.15:8001
The first line is the IP address and the port number of the OSC
client (in this case, the client is whatever is running TouchOSC). The
colon separates the two numbers.
Because this example is only listening for OSC messages, and not
sending any back, you can leave that line as is.
The next line is the IP address and port number of the computer
running the drawing program. Change the first value on this line to the
IP address of the computer running the Processing example (which
should be the same value you used for Host in TouchOSC).
Set the port to the same value you used for Port (outgoing) in
TouchOSC.
Start TouchOSC, select the Mix 2 layout, and launch the OSC
Rectangles program.

A Processing quick-start guide

You can download Processing for Windows, Mac OSX,
and Linux from http://processing.org/down-
load.
To install, just unpack the zip file and move the applica-
tion files to the appropriate location on your system.
When you run processing.exe or processing.app,
you will see the Processing IDE (Integrated Development
Environmentanother name for thing you use to do
code stuff). This is where you can create or edit Pro-
cessing sketches.
Sketches is the term for Processing programs. They are
stored in your Processing sketchbook.

Just the Best Parts: OSC for Artists (27)

 The sketchbook is just a folder on your computer. If you
click File > Preferences, you can see and change the
location of your sketchbook folder.

Processing IDE

Processing sketches consist of a folder that contains at

least one file that has the same name as the folder and
ends in the .pde file extension.

Processing IDE, with some code

The creation of this initial file is taken care of for

you if you create new sketches using the Processing IDE.

(28) Just the Best Parts: OSC for Artists

 To open a sketch, click File >Open . To run a sketch, click
the button that with the sideway triangle . To stop a
sketch, click the button with the square .
Sketch code goes in the large area in the middle of the
IDE. The space below that area shows any messages
generated by your code (such as warnings or errors)
when you run a sketch.
The drawing program should give you a blank, dark gray window
(or canvas, in Processing lingo).
You can now use the controls on TouchOSC to manipulate two
triangles.
The Mix 2 layout looks like this:

TouchOSC Mix 2 Layout

There is a symmetrical set of buttons (both toggle switches and

momentary switches), rotary controls (the circle things), and some
faders. The sample program is designed to respond to only red and

Just the Best Parts: OSC for Artists (29)

green rotary controls and faders.

Driving the demo

If you play around a bit with the controls, you will see the demo
app respond, with the rectangles growing and shrinking and moving
around.
To close the program, click on the canvas and press Esc on your
keyboard.

Sample Application #1, take 2:

OSC Commander
TouchOSC is a very slick program. Still, you need either an Android
or Apple phone to run it, and if you have an iPhone, you have to pay
for TouchOSC. Regardless of whether its worth the price (it is), if you
dont have it or cant get it, fear not. There is an alternative.

OSC Commander

Its not as bitchin cool as TouchOSC, but it is free and it should

(30) Just the Best Parts: OSC for Artists

run on any desktop or laptop computer. Its called OSC Commander.
As with the demo app, OSC Commander is written in Processing.
It evolved out of necessity.
While working with and developing assorted OSC programs, I
wanted to be able to send arbitrary OSC commands in order to check
behavior. So I wrote a little tool. Over time I added this and that fea-
ture, and its now ready just in time for this book.
You can download OSC Commander(and its source code)
fromhttp://justthebestparts.com/downloads.

Using OSC Commander

OSC Commander is a single-window Processing program. When it
starts, it loads configuration data from a file namedconfig.txt .
This is the same is the configuration file used for the rectangles
example, and it uses the same format. The contents of the file look
something like this:
192.168.0.15:8081
192.168.0.15:8001
/1/fader5 0.03
The first line contains the IP address and port number used to
send OSC commands to OSC Commander.
The second line contains the IP address and port number used
by some OSC server (that is, some other program you wish to control
using OSC).
The third line is an OSC message: an address pattern and some
optional arguments.
If you run the program without any config.txt file available, the
default values are used.
You can edit these values in the text areas of the program; click-
ing the Update button updates the settings used by the program and
saves these values in config.txt.
The purpose of the program is to be able to send OSC commands

Just the Best Parts: OSC for Artists (31)

to an OSC server. There are two ways to do this.
The first is to enter an address pattern and (optionally) arguments
into the OSC message field and click the Send button. The OSC mes-
sage will be sent to whatever OSC server is listening at the IP address
and port defined in the Server address and Server port" fields.
You can use text, integers, floating-point numbers, and Boolean
(i.e., true or false) values as arguments. If you are sending text, you
must enclose that text in double quotes.
To send a Boolean value, use the single, unquoted charac-
tersTandF.
The other way to send OSC messages is to use the slider controls.
By default, they send the address pattern/1/fader[n],
where[n]is the number of the slider you are using. You can switch
the address pattern to send/1/rotary[n]using the "Rotary" ra-
dio-button just below the last slider. In both cases, the slider controls
allow you to send floating-point values between 0.0 and 1.0.
This behavior more or less mimics some of the behavior of a
TouchOSC screen.
In case you think a range of values from 0 to 1 is too limited, it
turns out that many of the various programs that handle either OSC
or MIDI control assume that the values they are sent are in that range.
Just think of it as being between 0% and 100%.
For example, if you have a volume setting in a music application,
it is convenient to think of it being set to some value between all the
way off to all the way up as loud as it can go. The alternative would
be to send an absolute value, in which case you would have to know
specifically which values the receiving program accepts.
In some cases, having to know specific values is unavoidable.
For example, when using OSC to trigger musical events, it might not
makes sense to indicate what note to play by using a percentage.
Instead, you typically indicate a specific note value. The duration of
the note is also usually indicated by a specific value, but volume may

(32) Just the Best Parts: OSC for Artists

or may not be a percentage. In any case, you need to know what each
application expects.
The first example takes the percentage value sent by the rotary
controls and adjusts it based on the size of the canvas. This way you
do not have to know the actual size of the canvas; the OSC commands
just do the right thing.
The second sample application also assumes this range and then
scales the values to something more appropriate depending on what
part of the program is being controlled.
If you want to play with the OSC Rectangle programming using
OSC Commander, you can use the OSC Message field.
The first two rotary controls (the round things) are rotary1 and
rotary2. This is the first screen of this particular TouchOSC layout, so
these controls send the OSC address patterns/1/rotary1and/1/
rotary2.
We skip the third red rotary, and move over to the green side,
where we haverotary4androtary5, which (as you might have
guessed) send patterns/1/rotary4and/1/rotary5.
The two middle slider controls are, in TouchOSC-speak, faders.
Specifically,they are fader1andfader2, with the address patterns/1/
fader1and/1/fader2.
Each of these controls send floating-point values between 0.0 and
1.0, so to mimic this in OSC Commander, you must type in the desired
address pattern and some value.
For example, the first two grow the rectangles to some visible
size, and the others move them around:
/1/fader1 0.76
/1/fader2 0.47
/1/rotary1 0.50
/1/rotary2 0.27
/1/rotary3 0.70

Just the Best Parts: OSC for Artists (33)

Whats actually happening?
First, this is not going to be a tutorial on Processing. For that,
I recommend checking out the Khan Academy Computer Science
course (https://www.khanacademy.org/cs).
Oh no! Computer science! Fear not. Its a course in learning Pro-
cessing that introduces important programming concepts as you go.
They make it fun and interesting.
However, some code will be shown with some explanation of how
some things work. If you are not already familiar with Processing, it
may seem like hand-waving. And it is, in a way. The important point is
to understand that connecting an OSC control source to pretty much
any Processing program is not terribly complicated.

Some code
Most Processing programs share some common elements. If the
program is using code from other libraries (that is, reusable code bun-
dled up in a way that makes it handy to include in other sketches),this
is declared at the start of the program.
Programs make use of things called variables. Think of variables as
placeholders, or convenient names for program things. In Processing,
you must indicate what kind of program thing a variable will be. For
example, suppose that you want to use the number 2013 in various
places in your program. You could just use that number in each and
every place, but if you later decide to change that number to 2014,
youll have to change it in all the places you used this number. That
approach can lead to mistakes.
If you instead define a variable, and use the variable everywhere
you want that number throughout your code, then theres only one
thing you would need to changethe value of the variable where its
defined.
You could declare such a variable like this:
int myFavoriteYear = 2013;
This code says that the variable calledmyFavoriteYearis

(34) Just the Best Parts: OSC for Artists

anint, meaning an integer, and it starts life with the value2013.
Again, the details of this code are not critical. What is important is
that Processing allows you to create something that holds a value that
you can reuse through your code and has some basic rules about how
you do this.
Heres another thing about variables (at least in Processing, as
well as many other programming languages): you can change them.
This ability is a mixed blessing. If different parts of your code change
variables, it can become very hard to know exactly what your program
is doing when it is running. This is especially true if you create vari-
ables that are accessible and changeable from anywhere in the pro-
gram (these are termed global variables).
In fact, global variables are seriously frowned upon by program-
mers. But were going to use them here because they make certain
things easier.
(Shh; dont tell anyone.)
The rectangle program is, as programs go, pretty simple. Process-
ing makes it easy to create and move shapes.
Heres an example:
fill(120, 255, 23);
rect(10, 20, 100, 250);
This code creates a bright green rectangle that is 100 pixels wide,
250 pixels tall, with the upper-left corner 10 pixels in and 20 pixels
down from the top left corner of the canvas.
We usefill()to set the rectangle background color, using RGB
(red, blue, green) values. Code for setting the fill color must come
before the code that draws the shape.
As you can probably guess, this code will create the exact same
rectangle shape, in the exact same place, every time.
So, if you want this to change through OSC messages, you would
have to replace some or all of those numbers used to define the rect-

Just the Best Parts: OSC for Artists (35)

angle with some variables.
Heres a simple and direct version:
// Up at the top of the program
int rectX = 10;
int rectY = 20;
int rectWidth = 100;
int rectHeight = 250;
// Later in the program
rect(rectX, rectY, rectWidth, rectHeight);
Processing, like many other programming languages, has a fea-
ture called functions. They are, in some ways, like variables, in that
they make it easier to reuse stuff. In the case of functions, that stuff
would be chunks of code. For example:
void drawRectangle(){
fill(120, 255, 23);
rect(rectX, rectY, rectWidth, rectHeight);
}
Functions allow you pass along values to use in the function code.
This way, you can reuse the function code with different values with-
out having the function refer to global variables. It makes your code
easier to work with:
void drawRectangle(int x, int y, int width, int
height){
fill(120, 255, 23);
rect(x, y, width, height);
}
Dont worry about the details of how this is written. Its just a way
to indicate that this is a function, that you need to pass it four inte-
gers, and that its not going to give you back anything useful.
Many, and perhaps most, Processing sketches have a special func-
tion called draw() that runs automatically, over and over and over

(36) Just the Best Parts: OSC for Artists

and over.
If we wanted our rectangle to change while our program ran, we
could usedraw()to repeatedly update our canvas:

int rectX = 10;

int rectY = 20;
int rectWidth = 30;
int rectHeight = 50;

void draw() {
background(0);
rectX = rectX + 10;
rectY = rectY + 10;
rectWidth = rectWidth + 10;
rectHeight = rectHeight + 10

if (rectX > width()) {

rectX = 10;
rectY = 20;
rectWidth = 30;
rectHeight = 50;
}

void drawRectangle(rectX , rectY, rectWidth,

rectHeight);
}
This rather goofy example will, on each call to draw(), set the
canvas color to black (thats the background(0); part), then incre-
ment the value of each of our variables. Eventually, the rectangle will
no longer be visible within the size of the canvas, so the code does a
simple test to see if the X coordinate is greater than the width of the

Just the Best Parts: OSC for Artists (37)

canvas. (Thats theif ( rectX > width() )part.)If so, then the code resets
our variables and we begin again.
The point is that code can repeatedly and automatically update
the canvas, and it can do so using variables that may have new values
each time.
The OSC rectangle program is somewhat similar, except that the
changes to the variables used to define the rectangles happen as a
result of the program receiving OSC messages.
To add OSC magic powers to a Processing program, you must
install the oscP5 library.
Installing in this case means grabbing the library files and plac-
ing them into your Processinglibraryfolder. Seehttp://www.so-
jamo.de/libraries/oscP5/#installation.
The rectangle program is, as Ive mentioned, an OSC server. The
program uses a global variable to manage this code:
import oscP5.*;
import netP5.*;
OscP5 oscP5;
Along withdraw(), another oft-used special Processing function
issetup(). Unlikedraw(),setup()is automatically used only once
per program: when the application first runs.
As the name suggests, this is where you put code that sets up
the things you want in place for your application. The rectangle demo
reads configuration settings from a file when it starts, and then uses
those settings to create the OSC server:

int CANVAS_WIDTH = 600;

int CANVAS_HEIGHT = 600;

void setup() {
size(CANVAS_WIDTH, CANVAS_HEIGHT);

(38) Just the Best Parts: OSC for Artists

 loadData();
oscP5 = new OscP5(this, localOSCAddress, localO-
SCPort);
}
Again, if you find the code mystifying, fear not. The key point
is that at startup the program loads a configuration file and sets up
something to handle OSC messages.
Now heres an extra-hand-wavey detail: the code for handling
OSC messages operates in the background, and when a message
comes in, it looks for a special function named oscEvent() .
If you want your program to respond to OSC message, you must
create this function. It is in this function code where you get to decide
what to do with that OSC message.
For example:
void oscEvent(OscMessage theOscMessage) {
print("### received an osc message.");
print(" addrpattern: " + theOscMessage.addrPat-
tern());
println(" typetag: " + theOscMessage.typetag());
}
print and println are ways to display text below the Process-
ing editor while your program runs. Its a handy way to have your
code tell you whats going on.
The code for oscEvent() in the rectangle demo is a little more
complex.
Again, if you are not familiar with Processing, just focus on the
main concepts.
First, we assume that the only OSC messages of interest will be
sending us a single floating-point number.
The code was written to handle any of the possible messages it
might get from TouchOSC, so it assumes that the address pattern is

Just the Best Parts: OSC for Artists (39)

going to be one of the four patterns that send floating-point numbers.
Processing allows you do some clever pattern matching to find
stuff inside chunks of text; the app uses this technique to see if the
OSC address pattern is something of interest, and if so, what the index
value is of the TouchOSC control that was used.
In other words, if the address pattern is /1/rotary2, the code
will recognize the rotary part and also know that it was rotary con-
trol number 2:

void oscEvent(OscMessage theOscMessage) {

float value = (Float)theOscMessage.arguments()[0];
int control = 2;
String[] parts = split(theOscMessage.addrPat-
tern(), "/");
println("parts[control]: " + parts[control] +
"" );
// We should have an integer (for the layout) and
a string (for the control).
String[] res;
String reRotary = "(rotary)(.)";
String reToggle = "(toggle)(.)";
String rePush = "(push)(.)";
String reFader = "(fader)(.)";

With some local variables in place, and the pattern-matching

code defined, the function checks the OSC message and checks to see
whether this was a fader message:
res = match(parts[control], reFader);
If so, then the match() function will return some useful informa-
tion. If not, it will return a special value, null.
The code looks to see if res is not null, and if thats the case, then

(40) Just the Best Parts: OSC for Artists

it acts on it:

if (res != null) {
println("FADER for " + res[2] );
rectScale[ int(res[2]) ] = map(value, 0.0, 1.0,
0.1, CANVAS_WIDTH);
return;
}
Some more hand-wavey stuff: because the program is tracking
multiple rectangles and the code is pairing up TouchOSC controls with
rectangles, the code uses an array called rectScale to store val-
ues. An array is a way to have multiple variables all in one variable. In
reality, its more complicated than that, but dont worry about that for
now. Thats a code detail that, for now, isnt important. You can get at
the items in an array using an integer index.
Essentially, what the code is doing here is looking at which fader
control is sending the OSC message, and matching that with a corre-
sponding rectangle size/location value. The map() function then takes
the OSC message value (a value between 0.0 and 1.0) and converts it
to a comparable value between 0.0 and the width of the canvas.
Finally, theres the return statement, which tells Processing to
exit the function.
If this was not a fader message, the function uses similar logic to
see whether this message was sent by a rotary control, andas with
the fader codewill use the rotary index and value to change one or
another rectangle value:

res = match(parts[control], reRotary);

if (res != null) {
int v = (int) map(value, 0.0, 1.0, 0, CANVAS_
WIDTH);
println("ROTARY for " + int(res[2]) + "; v = "

Just the Best Parts: OSC for Artists (41)

 + v );
println("Set for rect " + int(res[2]) );
rectTranslate[ int(res[2]) ] = v;
return;
}
}
And thats it for the OSC message handling. The code doesnt care
about any message that isnt a fader or rotary message, so it essen-
tially ignores them.

Code recap
The gist of all this code comes down to defining variables for use
in drawing the rectangles; these variables are then altered by different
OSC messages. Each time the draw() function is called, the canvas is
updated with new rectangles that are created using the current val-
ues.

Sample Application #2: Abstract OSC

The first sample app was purposely simple to help explain how
OSC commands can control Processing programs. This demo program
is more fun. Its something of an abstract art generator that uses some
constrained random values to continually update an image. You can
manipulate the constraints for those values using OSC.
Heres how it works: the program randomly creates two points on
the canvas. These are, technically, the start and end points for a line.
But, instead of drawing a typical straight line, the program instead
draws circles. And instead of drawing circles directly along where that
line would be, it makes the circle-line somewhat jagged.
It then creates a new end point and uses the previous end point
as the new start point for a new jagged-circle path. Oh, and while it
does this, it sort of randomly selects a new color for each new seg-
ment of jagged circles.

(42) Just the Best Parts: OSC for Artists

 Every so often the program will draw a single large, thick, white
circle, as a way to wipe out part of whats been drawn.
There is also some additional blurring and erosion applied as a
way to set up more distinct foreground and background.
The exact details of these effects are (more or less) controlled by
some program variables.
The effects can be quite entertaining. Processing is a terrific tool
for creating interesting computer visuals. You can use some essentially
simple math and geometric shapes, plus some combination of noise
and filtering, to produce stunning results. Check out the work of Mar-
ius Watz (http://mariuswatz.com) for some amazing examples .
Sometimes you get all the variables and values just right. Often,
though, you really need to play around with many different values to
see what works best. Stopping and restarting your program as you
alter values can get tedious. Being able to change these values as the
program is running makes it easy to explore various configurations.

TouchOSC Simple layout for example 2

Just the Best Parts: OSC for Artists (43)

 As with the first example, this one has OSC code in place to watch
for various messages and adjust values accordingly. This demo app is
also better suited for use with OSC Commander, as it pays attention
only to fader messages 1 though 5. If you want to use TouchOSC,
though, you can. Pick the Simple layout on the first screen.
If you use OSC Commander, the faders are, of course, in sequence
from top to bottom.
Abstract OSC also uses a config.txt file for OSC network set-
tings. Unlike the first example, this one will send back an OSC mes-
sage. If you control the program using OSC Commander, you should
see, in the OSC response field, a status update, much like this exam-
ple:
/jtbp/response "Set baseColorRange to 17"
This demo is, in many ways, the same as the first one, with one
exception: it sends back an OSC message. Heres a quick look at how
that works.
When an OSC message is received and used to alter the running
program, the program sends an message back saying what it just did.
This is done by the method informClient():
void informClient(String text){
OscMessage m = new OscMessage("/jtbp/response");
m.add(text);
println("Send to "+ oscServerAddress.address() +
":" + oscServerAddress.port() +
" /jtbp/response " + text); // DEBUG
clientOscP5.send(m, oscServerAddress);
}
Theres no point in going through the rest of code here. If you un-
derstood the previous code discussion, you should be able to look at
the source code for this program and understand what is happening.

(44) Just the Best Parts: OSC for Artists

If you didnt understand the previous code discussion, then yet an-
other geek-out would be unfairly traumatizingor, at the very least,
incredibly boring and unproductive.
The OSC sections are very much the same. One notable difference
is that the OSC code has been split out into multiple files. Indeed, the
whole programunlike the first exampleis in multiple files because
this setup is easier to work with. In the case of splitting up the OSC
code, however, a goal was to make it easier to swap out the behavior
that is specific to this program while leaving the more general-pur-
pose OSC message handling code alone. If you plan on writing your
own Processing apps that are controlled by OSC, this arrangement
may give you a head start.
When you run the sketch you get a screen that looks like this:

Left alone, the circles and colors will change automatically. The
changes are constrained by the default program settings.
If you now run the OSC Commander sketch, or use the TouchOSC
app, you can alter these settings by adjusting various controls. You

Just the Best Parts: OSC for Artists (45)

can alter color saturation, circle size, density, and some blurring/fad-
ing effects.
Here are some additional screen shots:

(46) Just the Best Parts: OSC for Artists

Wrapping up
So thats it: some real-life examples of using OSC, with source
code. If you didnt care for the code, thats fine. Hopefully you got
something from the discussion, if only some appreciation of whats
possible.

Just the Best Parts: OSC for Artists (47)

Whence OSC: The really short graphic novel
The End.