Thursday, March 28, 2019

OSCgroups Tutorial


I wrote this because I couldn't find an OSCgroups for Dummies tutorial.

OSC stands for Open Sound Control, a communication protocol that functions like MIDI. It's a protocol that allows computers to communicate with one another. It is much more powerful than MIDI, but at the same time it can be a bit clumsy to use, as it operates over computer networks (rather than dedicated hardware, as MIDI does) and so requires that that the the IP address and port number of the receiver be specified in order for an OSC message to be successfully transmitted. As you can imagined, this can easily become be a fiddly and tedious requirement.

OSCgroups is a data distribution program that simplifies matters by enabling group members to send OSC messages to every other member without knowing or specifying each member's IP address. Group members simply register with a central server, which handles the task of forwarding all OSC messages received to all registered computers. OSCgroups consists of two independent files: a server executable, and a client executable. They are tiny programs that are run from the command line in a Terminal window. This is a very economical form of programming, but not a very intuitive one, which is why beginners can use some tips when getting started. Unfortunately, the files do not come bundled with instructions, which is why something like this tutorial may come in handy to newbies. Interested parties may download the files from here: 


and here:


I should mention here that I am not going to go into detail about OSC. OSCgroups is basically a program for people who are already familiar with and use OSC, and who are looking for ways to streamline their communication routines.

The way this all works is that the OSCgroups client program is run on each of the participating computers. OSC capable software (such as Pure Data, MAX/MSP, and Resolume, to name only a few) running on such a member computer sends its OSC messages to this client program, which passes the messages to a third computer, a central server. It is this server which ensures that all member computers receive copies of every message it receives. (See graphic below)

So basically in order to join a group, a computer needs little more than the group name and the group password. It is not clear to me why a member needs a personal password, but OSCgroups requires each member to make one.




ALL PARTICIPATING COMPUTERS:

1)    Put the two files OscGroupServer and OscGroupClient in a convenient folder (e.g. on the Desktop, in Documents, etc.)  A convenient folder is one that  can be reached without too many cd operations from the Terminal.

2)    Log all computers onto a common network. This network can be a LAN or a wifi network. The network needn’t be connected to the Internet. On the other hand, the network can be the internet itself. People have used OSCgroups to perform and collaborate while physically being in different countries.

SERVER:
One can use dedicated OSCgroups servers on the internet (see below), but I favor running my own server over a small, private network isolated from the internet.

Paranoia says it would be best to run the server on a separate and dedicated computer, but it IS possible (and, my friend and resource person Chris B assures me, "normal") to run it together with a client on a single computer.

Computers communicate with each other through things called ports. Ports are essentially numbered data addresses in the computer where data is exchanged. When doubleclicked, the OscGroupsServer program grabs port number 22242 for its use. This is good enough for me, but if you want to use a different port, you can specify it (along with other items) by running the program from a Terminal window. Type ./OscGroupServer -h to learn about the other items/specifications.

NOTE: When clients log onto the server, it is possible that the server computer will have to manually be told to accept the connections.

CLIENT:

The Client program is the file named OscGroupsClient. To run it, you will have to know the IP address of the server. On a Mac, this is done by clicking on the Wifi icon and then clicking Open Network Preferences on the menu. On Windows, it's easiest to type

ipconfig /all

in a Terminal Window. Terminal is a programming window usually found in the Accessories folder of the Start Menu.

NOTE: the IP address 127.0.0.1 is a special address that basically means "this computer". The word "localhost" means the same thing and can sometimes be used in place of "127.0.0.1"  Both terms are used when passing OSC messages within a single computer. 

OscGroupClient cannot be run by being double-clicked, as it requires several arguments to be specified in order to run properly.
OscGroupClient must be run, and the arguments specified, from a terminal window.

Mac: Open a Terminal window, cd to the folder where the OscGroupClient file is located. run the OscGroupClient file by typing
a command like the following:

./oscgroupclient 192.168.1.101 22242 22243 22244 22245 john abcd beatles wxyz

The ./ identifies the sentence as an executable command.
The arguments following oscgroupclient refer to the following values. 

oscgroupclient serveraddress serverport localtoremoteport localtxport localrxport username password groupname grouppassword

If the Mac insists the file is damaged, Go to System Preferences>Security & Privacy>General, and unlock the lock icon in the lower left corner. Give the Mac permission to run files from “Anywhere”, and lock the icon again.

Windows: Open a Terminal window, cd to the folder where the files are located. Run the OscGroupClient file by typing a command like the following:

oscgroupclient 192.168.1.101 22242 22243 22244 22245 john abcd beatles wxyz

The arguments following “oscgroupclient" refer to the following items: 

oscgroupclient serveraddress serverport localtoremoteport localtxport localrxport username password groupname grouppassword

When clients log onto servers, it is possible that the server computer will have to manually be told to accept the connections.

You can test that the client file is working by logging onto a server on the internet, e.g. oscgroups.kiben.net or oscgroups.iua.upf.edu

Sample command: 
oscgroupclient oscgroups.kiben.net 22242 22243 22244 22245 john abcd beatles wxyz



PURE DATA, PROCESSING, RESOLUME, ETC

Configure the software to route messages to and from the local txport and local rxport allocated to the client.
See below for an example in puredata.

click to see full image


If multiple users are behind the same NAT and you experience difficulties. you
might like to try all using a different value for localtoremoteport
for each user, although this shouldn't usually be necessary.