General Usage Information

TheArtCollider depends on you sharing data. ie: reading, processing and providing.

To achieve a truly distributed system you should setup your own streaming server. However to get started quickly we provide a few dedicated servers for your convenience and for relaying streams behind low bandwidth links.

We provide examples and detailed information for connecting with

• Pure-Data - real-time graphical programming environment (multi platform)
• MaxMSP/Jitter - commercial interactive graphical programming environment (OSX, windows)
• processing.org - JAVA based image & animation framework (multi-platform)
• Flowmixer - real-time vision-mixer (OSX)
• oggZCap - screen-capture (OSX)

on the respective wiki-pages. This page deals with framework-independent ways to connect to the Collider; ie. command-line scripts and non-standard solutions.

If you come up with other solutions, please post them here.

Note that you don’t have to open any port to receive streams. Port forwarding (if behind router) has only to be enabled when running a local Icecast2 server (audio/video OUT).

The easiest way to view online footage is to launch VLC. Select File → Open Network from it’s Menu and paste the URL of a project there. A list of projects is available from the Yellow Pages (Read more about the yellow-pages).

Note that you can download streams with Firefox or Safari using a stream address like http://xx.xx.xx.xx:8000/inoutvideo.ogg

You can do it using the command line :

[Terminal] > curl http://xx.xx.xx.xx:8000/inoutvideo.ogg > outFile.ogg

Type Ctrl-C to stop the download

“curl” can use a LOT of different options. Some that can be useful are :

• -s will mask the progress bar and make curl silent.
• –show-error when used with -s will show you errors.
• -m interger:maxTimeInSecond will stop the process after the maxTime value. This will generate a “TimeOut” error. eg. -m 10 to stop after 10 sec
• –fail will tell curl not to download anything if the file doesn’t exists.

For example, if I want to save an audio stream for 5 sec to my hard disk:

[Terminal] >  curl -s http://xx.xx.xx.xx:8002/inoutaudio.ogg -o /somewhere/on/HD/audiograb.ogg -m 5 --show-error --fail

If it fails because the file doesn’t exists, you’ll see this in your console :

[Terminal] curl: (22) The requested URL returned error: 404

If everything went right it will be :

[Terminal] curl: (28) Operation timed out after 5000 milliseconds with 304262 bytes received

With VLC installed in /Applications (on Mac OSX):

[Terminal] > cd /Applications/VLC.app/Contents/MacOS
[Terminal] > ./vlc http://xx.xx.xx.xx:8002/inoutvideo.ogg -Idummy -V image --image-out-format=png --image-out-prefix=/out --image-out-ratio=20

Note: on GNU/Linux you can skip the cd /Applications/… and simply invoke vlc <options> <URL>.

Adding options :

• –image-out-ratio=20: one image out of 20 is recorded
• –image-out-replace: if you want to overwrite a single file
• –no-drop-late-frames: to avoid freezing

please read icecast server for an introduction on A/V streaming in general.

Use oggfwd:

[Terminal] > cat myFile.ogg | oggfwd theartcollider.net 8002 inoutpass myprojectname.ogg

From a DV camera:

[Terminal] > dbgrab --format raw - | ffmpeg2theora -f dv -o /dev/stdout | oggfwd theartcollider.net 8002 inoutpass myprojectname.ogg

Using ffmpeg2theora:

Here’s how to encode a pictures-sequence to an OGG stream and directly send it to Icecast server. This can also be used while the pictures are generated.

[Terminal] > ffmpeg2theora -f image2 --inputfps 8 --speedlevel 2 /yourFolder/picturename%06d.png --framerate 8 -o - | oggfwd theartcollider.net 8002 inoutpass myprojectname.ogg

with picturename%06d.png corresponding to all pictures contained in a folder with this kind of name : file000001.png, file000002.png… adapt the %0xd to your naming style (file001.png should be file%03.png). When using this method to transmit a video-stream while the pictures are being generated, carefully choose the inputfps and framerate setting: if the pictures are generated slower than the stream is sent to the server, oggfwd will stop when the last image is reach. On the other side, if the stream is sent too slowly, it will be outdated compare to the picture sequence state. Some tests should be done to find a good balance depending of the CPU speed and other conditions (i.e. other software running at the same time that will produce the pictures sequence).

A simple shell script using this mechanism and afterwards deleting the image files would look like this:

#/bin/bash
ICEHOST=theartcollider.net
ICEPORT=8002
ICEPASS=XXXX

NAME=my_title

TAGS="Video,Test,Fun"
DESC="My encoded stream"
URL="http://wiki.citu.info/user/My_Name"
MOUNT=$NAME.ogg
MYFOLDER=$1

ffmpeg2theora -f image2 --inputfps 8 -F 8 --speedlevel 2 --noaudio \
"$MYFOLDER/image%06d.png" -o - \
| oggfwd -p -g "$TAGS" -d "$DESC" -n "$NAME" -u "$URL" $ICEHOST $ICEPORT $ICEPASS $MOUNT

rm $MYFOLDER/*.png
#rm -rf $MYFOLDER/

#/bin/bash
ICEHOST=theartcollider.net
ICEPORT=8002
ICEPASS=XXXX

NAME=my_title

TAGS="File,Test,Fun"
DESC="My Re-encoded stream"
URL="http://wiki.citu.info/user/My_Name"
MOUNT=$NAME.ogg

cat /path/to/myfile.flv \
| ffmpeg2theora --inputfps 25 -F 25 --speedlevel 2 --videoquality 1 --noaudio -o - -\
| oggfwd -p -g "$TAGS" -d "$DESC" -n "$NAME" -u "$URL" $ICEHOST $ICEPORT $ICEPASS $MOUNT

You can record the screen activity by using the application recordmydesktop which is available on most GNU/Linux distributions:

Read the section feed_icecast2_using_command_line above, basically you’ll replace the file-source there with:

[Terminal] > recordmydesktop -width 320 -height 240 --on-the-fly-encoding | ...

A more robust solution would make use of named-pipes:

# create a "named-pipe"
cd /tmp
mkfifo test.ogv

# send everything from the named-pipe to the Collider
cat /tmp/test.ogv | oggfwd av.theartcollider.net 8000 inoutsource /myDesktop.ogg &
# feed the pipe "test.ogv" (recordmydesktop automatically adds ".ogv")
recordmydesktop --overwrite --fps 15 --no-sound --on-the-fly-encoding -o test

Use OggZCap to send a part of your screen.

gstreamer is and open-source multimedia framework. We have a couple of example command-lines for using gstreamer in the miscellaneous section.

Download and install the Xiph Quicktime Components. They allow you to play and record OGG files with any Quicktime compatible software (Max/MSP for instance).

On Gnu/Linux the ffmpeg command-line utility and mplayer/mencoder can be used to read/write OGG/Theora/Vorbis files. ffmpeg2theora provides a wrapper to ffmpeg for easy encoding.

On Mac OS X, the command line tool qt_tools can be used to convert any video that Quicktime can read into something else, like another video file, a screenshot, or an images sequence. This assume that you already have a video file. All explanations are on the website.

A typical command line to convert and OGG file to an images sequence would be :

[Terminal] > qt_export yourMovie.ogg --exporter=grex imgSeq.jpg

To run this, you have to install Xith plug-in for Quicktime .