flosc Tutorial v0.7
flosc written by ben chun.
tutorial written by eric socolofsky,
with assistance from ben chun and all flosc forum denizens.

the flosc tutorial is, like flosc, a work in progress! email me at eric [at] transmote [dot] com with any comments, questions, or suggestions.
last updated december 6, 2003.

[CONTENTS]

• Introduction
• what it is
• what it does
• Tutorial
• runthrough
• Gateway java server
• using flosc's actionscript
• actionscript functions
• sound software
• internet applications
• Links
• stuff you need
• flosc works

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.

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.

• set up your flash application to send and/or receive data, using the sendOSC() (outgoing) and parseMessages() (incoming) functions.
• set up your sound application to send and/or receive data, using the OSC parser and UDP communications object(s) for your sound software of choice.
• start the java Gateway server on the machine running the sound application. feed it the OSC port number and the flash port number.
• start your flash app and your sound app (in no particular order). you're ready to go!

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:

step one: open a command prompt
on windows:

• open a DOS prompt. (Start>Run, type command (98/ME) or cmd (NT/2000/XP))
• type cd\ and the full path of the directory into which you placed the .class files, and press ENTER. (i.e.: cd\Progra~1\flosc\gateway\)

• open a Terminal window (you can find Terminal in Applications).
• type "cd " (note the space!) and drag the folder into which you placed the .class files into the Terminal window, and press ENTER.

to make things easier on yourself in the future, you can write a shortcut to do all this for you with a double-click:

windows (.bat file):
create a new text file in any text editor, and enter the following text:

cd \pathname
java Gateway oscPort flashPort

where 'pathname' is the absolute path to the folder with the compiled java Gateway server class file (i.e. c:\Progra~1\flosc\gateway\), and oscPort and flashPort are the appropriate port numbers. save the file with a .bat extension as something like 'myFloscServer.bat'. now, you should be able to double-click the .bat file and it will automatically start your flosc server.

macOSX (.command file):
create a new text file in any text editor, and enter the following text:

cd /pathname
java Gateway oscPort flashPort

where 'pathname' is the absolute path to the folder with the compiled java Gateway server class file (i.e. /Users/ericsoco/Desktop/flosc-0.3), and oscPort and flashPort are the appropriate port numbers. save this file with a .command extension as something like 'myFloscServer.command', in a generic text file format, with no program associations. then open terminal and type 'cd ', drag the folder with the newly created commannd file into the terminal window, and hit enter. finally, type

chmod 755 myFloscServer.command

and hit enter. now, you should be able to double-click the .command file and it will automatically start your flosc server via terminal.

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 child.attributes.TYPE (variable name) and child.attributes.VALUE (variable value) to get the good data. then you do with it what you will...

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()
these functions handle the XMLSocket connection.

handleIncoming(xmlIn), displayPacketHeaders(packet)
these functions seperate the incoming XML data into individual values. they seem to be used only for debugging and tracing incoming XML data.

OSCPacket(address, port, time, xmlData)
this is the constructor function for the OSCPacket class. it seems to be used only in conjunction with handleIncoming(), in order to trace and debug incoming data.

parseMessages(node)
this is one of the good ones. it rips out usuable values (variable names and values) from incoming XML data. if you want to use incoming data in flash, modify or add to this code.

sendOSC(name, arg, destAddr, destPort)
this is the other good one. send it a variable name, the variable value, a destination IP address, and a destination port at that IP address, and it will send your data to that IP through the java Gateway server, translated into UDP format. basically, this is the one to use to communicate with your sound software.

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.

max/msp
example flash-max flosc application

max/msp requires the OpenSoundControl object and the suite of UDP objects. you can download them from from CNMAT Berkeley.

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.

pd(pure data)
pd handles udp communication natively, with its 'netsend' and 'netreceive' objects, but the suite of OSC objects are a seperate download.
download pd's OSC objects

oliver larkin has an example of how to communicate between flash and pd. this does not actually use flosc, but is handy nonetheless.

supercollider
unfortunately, i know next to nothing about supercollider. please feel free to send me any information you may have about supercollider and how to use it with flosc. email me at eric [at] transmote [dot] com.

others?
please also feel free to send me any information about any other sound software you have used to communicate with flash via flosc. email me at eric [at] transmote [dot] com.
thanks!

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.

this section is a handy list of all the stuff you'll need to run flosc, and then some.

• ben chun's flosc website.
• flosc forum! use it.
• CNMAT's OSC/UDP resources - a VERY extensive list. you should be able to find what you're looking for here.
• cycling 74's website. home of max/msp/jitter.
• pure data's website.
• supercollider's website.

and this section is an ever-expanding list of works people have created with flosc. check em out.

• a simple flash-max flosc example.
• flosc examples by sean rooney. scroll down to the 'examples' section.
• contemplace. flosc enables processing to talk to max/msp just as easily as it does flash. contemplace is a spatial personality that redesigns itself dynamically according to its conversations with its visitors.
• Casket. "Laptop Music Performance And Art Installation System".
• salon. choose your favorite 20th-century public figures and drop them in a room together. choose from margaret thatcher, mohandas gandhi, salvador dali, and vladimir nabokov, among others. coming soon.