flosc Tutorial v0.7
..what it is..
flosc is a communication gateway, written by ben chun, that allows macromedia flashMX to talk with any software that can understand UDP data. while this includes many sound programming tools, the options are limited only by your curiosity. flosc is also fully open source, and ben chun encourages participation in its development.
flosc is comprised of a java server and a suite of actionscript functions. together, they allow communication between UDP-friendly software and flashMX via flash's XMLSocket feature, which reads and writes TCP-formatted data. flosc will run on any system that supports java and can run flashMX, including win98/2000/XP, linux, and macOSX.
..what it does..
the name 'flosc' is a contraction of 'flash' and 'OSC', or Open Sound Control. OSC is a data format, similar to MIDI but faster and more flexible, that can be used by an increasing number of software and firmware systems. flosc translates actionscript data into OSC format, sends the OSC data in TCP format to its 'Gateway' java server via actionscript's XMLSocket, and finally sends the OSC data in UDP format out the other end of the java server. the process is fully reversible -- flosc can send and receive data in either direction.
flosc is a very open-ended software. while the name implies a bridge between flash and OSC, the Gateway java server exists solely to translate between TCP and UDP data. as such, it can be used for any application that requires communication between the two formats.
also, due to flosc's ability to send data both directions, there are many possibilities even when flosc is used in the intended manner. it can be used to create a flash interface for a max app, to generate graphics and sound that respond to one another, and to control flash via MIDI. flosc is still relatively underused, and there are many avenues yet to be explored.
this section is a quick, step-by-step instruction on how to
get flosc working. read below for more detailed information.
..Gateway java server..
the backbone of flosc is its java server. the java server is centered around a class called 'Gateway'. Gateway sets up 'OSCServer', which sends and receives UDP data, 'TCPServer', which sends and receives TCP data, and routes all data through these servers.
the flosc download contains a number of java .class (compiled) and .java (source) files. place these files in the same folder, wherever you wish; the location does not matter as long as all of the .class files are together in the same folder.
the flosc download also includes an .fla file, with all of the actionscript functions used by flosc. those are discussed in the next section.
Gateway can be run in a DOS shell on windows,
or in Terminal on macOSX. the first step in
using flosc is to start Gateway:
(both windows and mac)
to make things easier on yourself in the future,
you can write a shortcut to do all this for you
with a double-click:
..using flosc's actionscript..
the first thing to do is to set up your communication. you can type values for IP address and port into the input text boxes in the default flash template included in the flosc download, or you can choose to set the variables directly in your code. note that the input boxes seem to be a bit buggy; sometimes you will type a value in, hit connect, and the number will change. be sure that the values in the text boxes show the values you want.
once you have your lines of communication set up, all that's left is to communicate! do this with the parseMessages() function (for incoming data) and the sendOSC() function (for outgoing data).
you must call sendOSC(), and pass it a variable name, value, IP address, and port, every time you wish to send information to your sound app. i often place my sendOSC() calls within onEnterFrame(), onMouseMove(), and onMouseDown() handlers, in order generate changes in sound coninuously or with user input.
you can call sendOSC() as often as you like, but be aware that UDP data is prone to dropped packets in high-traffic applications. in other words, if you're trying to send a single value to trigger something, and there is a lot of other network traffic (perhaps you have 4 other flash apps all sending data to the same sound application), make sure to heavily debug and check the data on the sound app side.
parseMessages() is called automatically whenever flash
receives XML data. within parseMessages(), use the
this section is a breakdown of the functions of the individual, uh, functions included in the flash part of the flosc package. refer to the previous section for a quick runthrough of how to use them.
connect() / disconnect() / handleConnect(succeeded) / handleClose()
OSCPacket(address, port, time, xmlData)
sendOSC(name, arg, destAddr, destPort)
depending on your choice of sound software, you will have to get the necessary objects in order to allow your software to send and receive UDP data and to translate it between UDP and OSC formats. this is a list of what you need, where to find it, and how to use it.
your input setup should start with an otudp read object, with the port set to the 'flash port', the second of the two paramaeters you passed to java Gateway and the port you set in your flash app. take the outlet to the inlet of an OpenSoundControl object; take the second outlet of the OSC object to a route object, from which you'll route out all of your incoming variables by name.
your output setup will send lists with variable name-value pairs into a trigger object. the trigger object sends to the OSC object whatever name-value pairs are fed into it, followed by a bang to push the data through the OSC object into a otudp write object. the otudp write object will have the IP address to the machine running your flash app, followed by the 'OSC port', the first of the two parameters you passed to java Gateway.
so you wanna run your flosc app online, do you? me too. i haven't yet found a way to do this successfully. i imagine it would require a server that could continually run your sound application, which would receive data over IP from a flash app sitting in a user's browser.
the main problem with this is finding a server on which you can run your sound app continuously, and on which you have access to start and stop the app. you'll have to continously monitor the sound app to make sure it's still running.
the other option is to go with a downloadable application that opens the java server, flash app, and sound app automatically. this is obviously not as fun, because it not only requires more work on the user's end, but effectively eliminates the possibility of a multi-user online application.
as always, feel free to contact me with any experiments
you've done in this area. i'm eager to hear of successes
with online apps!
email me at eric [at] transmote [dot] com.
..stuff you need..
this section is a handy list of all the stuff you'll need
to run flosc, and then some.
and this section is an ever-expanding list of works
people have created with flosc. check em out.