Utilisation

Un article de InOutWiki.

Sommaire

DOWNLOAD and INSTALL

Files

All files (needed, additionals, examples, sources) are available at http://io.citu.fr/download.


CONNEXION (control/data streams)

The InOutOscGroups client (patched OSCgroups) is the only NECESSARY module to join the InOut network.

It allows:

  • The creation of an InOut project
  • Emission and Reception of control (name, description, etc...) and data (data stream) OSC messages

Please refer to the Communication page for more informations on the syntax of the OSC messages.

InOutConnector (Mac OS X)

If you are using Mac OS X, the InOut folder must be placed on the root folder of your startup disk.

  • InOutConnector : the InOutConnector Application for Mac OS X (using InOutOscGroups from the Config folder)
  • Config folder :
    • InOutOscGroups : used to connect to the InOut network on Any Platform
    • icecast : icecast server for Mac OS X (required if audio/video OUT)
      • config.xml : icecast server configuration file
      • logs : icecast server log files
    • darkice : darkice for Mac OS X (useful to pipe audio OUT through jack to the icecast server)
      • config.cfg : darkice configuration file (audio quality / icecast server settings)
    • InOutComponent : used to simulate a video input source on Mac OS X (useful for video IN)
      • InOutComponentControl.txt : used by InOutConnector to communicate with InOutComponent
      • InOutComponent.component : to put in /Library/Quicktime/


Image:inout_connexion.jpg


NOTE : When you use the InOutConnector application, OSC messages from OscGroups are available at 2 ports :

  • 9001
  • 9011

Manually, using InOutOscGroups (on any platform)

You can connect to the InOut network even if you are not using Mac OS X.

You have to launch the OscGroupClient yourself, using your login and pass :

[Terminal] > OscGroupClient io.citu.fr 22242 22243 9002 9001 myLogin myPassword inout pass

You can then use OSC messages to communicate with others (you may use another ports, depending on the above command) :

  • UDP Port 9002 to send messages to the server
  • UDP Port 9001 to receive messages from the server

To update informations about your project and to know what to do next, please refer to the Communication page.

Monitoring

After having launched the OscGroupClient, if your connexion is successful, a blank client is created, with default parameters.

Your project should be available on the monitoring pages : http://io.citu.fr.


Note that the server project produces :

Using those files (xml, txt, png, ogg), anyone can produce his custom monitoring interface.


Three monitoring propositions (produced by the CITU Lab) are available at http://io.citu.fr :

  • List : list of available projects and previews of streams (txt, png)
  • Network : Processing applet showing connexions on a map
  • Map : Locations of connected projects using the Google Map API


EXAMPLES (audio/video streams)

There isn't any absolute solution to connect your audio/video streams to the InOut network.

However, you may find below some examples that can help you receiving or emiting Icecast2 streams.


IN : Receiving

Note that you don't have to open any port to receive streams. Port forwarding (if behind router) have to be done only for the Icecast2 server (audio/video OUT)

Audio using MaxMSP

Assuming you have an Icecast server running

You may take a look on the OggPro externals.

Video using MaxMSP

You may use the jit.desktop object:

  • Read an Icecast2 stream and display it on screen (with VLC for example)
  • Record the screen activity on the same position through the jit.desktop object

Save an Icecast2 stream into a file

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

You can do it using the command line :

[Terminal] > curl http://xx.xx.xx.xx:8002/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. Find a list of error codes at [1]

-m interger:maxTimeInSecond will stop the process after the maxTime value. Will generate a "TimeOut" error. Usage : -m 10 to stop after 10 sec

--fail will tell curl not to download anything if the file doesn't exists. Without it, you won't have the "404 error" from HTML if you're downloading a file that's not there, beacaus curl will download the HEADER, so no error is generated.

for example, if I want to save an audio stream for 5 sec to my hard disk with all possible errors so I can manage it :

[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

Produce a sequence of images from Icecast2 using VLC

With VLC installed in the /Applications folder :

[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

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

Audio using VLC and Jack

Use VLC to play the stream and route VLC output into your application input (using JackPilot route window).

You can refer to the many Jack help pages.

Image:inout_jackRoutingWindow.png

Video input using InOutComponent (Mac OS X) [unstable]

Used to simulate a video input source on Mac OS X

Move the /InOut/Config/InOutComponent/InOutComponent.component file into your /Library/Quicktime/ folder.

Audio or Video files from Icecast2 using a script

You may use the icecast2ogg script available at [2]

Some informations included.

OUT : Sending

ICECAST2 SERVER

NECESSARY, if you want to send Video or Audio


Notes :

  • If you are behind a router, you have to route the 8002 TCP port to your local IP address, to let others access to your Icecast2 server.
  • Icecast2 is already available for Mac OS X in the Config folder. To launch the server, you just have to click "launch Icecast" in the InOutConnector application.
  • Icecast2 is available for Windows as an installer at www.icecast.org


If you want to launch the server manually, you can use :

[Terminal] > icecast2 -c /InOut/Config/icecast/icecast2Config.xml &

You may want to modify the icecast2Config.xml file to set :

  • Maximum number of clients
  • Socket port (8002 by default)
  • Web server directory
  • Logs directory
  • ...

Audio using MaxMSP

Assuming you have an Icecast server running

You may take a look on the OggPro externals.

Video using MaxMSP

Assuming you have an Icecast server running

  1. Lauch the video stream using the jit.broadcast object (default parameters)
  2. Get the stream address (in the logs window) : rtsp://xxx.xxx.xx:8554/jitStream
  3. Route the produced rtsp stream to the icecast2 server using VLC (working with 0.9.5 version) :
    1. Either manually using the VLC interface
    2. Or using the "MaxToIcecast_vlc" launchers (Mac OS X, Windows) available at [3]
    3. Or using the command line : ./vlc rtsp://xx.xx.xx.xx:8554/jitStream --sout='#transcode{vcodec=theo,vb=1024}:standard{access=shout,mux=ogg,dst=source:inoutpass@localhost:8002/inoutvideo.ogg}'

Audio using Jack and Darkice

if you want to receive or send Audio. assuming you have an Icecast server running

  • Download and install JackOSX and reboot
  • Launch JackPilot (/Applications/Jack/JackPilot) and start Jack Audio Server.

If you really want to do this from the terminal, you can launch the server by typing :

[Terminal] > /usr/local/bin/jackd -R -d coreaudio -r 44100 -p 1024 -o 2 -i 2 &

To launch the JackPilot interface :

[Terminal] > /usr/bin/open /Applications/Jack/JackPilot.app


Darkice is used to create a Jack output link to the Icecast2 server.

If you are using Mac OS X :

  • Unzip the folder /InOut/Config/darkice4INTELstatic.zip or darkice4PPCstatic.zip depending on your Mac.
  • Launch InOutConnector and press the Launch Darkice button.


To do it with the command line :

[Terminal] > /InOut/Config/darkice-0.18.1patched/src/darkice -c /InOut/Config/darkiceConfig.cfg &

You may want to modify the darkiceConfig.cfg file, to set :

  • audio settings and quality (sampleRate, bitsPerSample, channels, bitrate, ...)
  • Icecast server address (if using a distant Icecast2 server for example)

Feed Icecast2 using command line

Using oggfwd :

[Terminal] > cat myFile.ogg | oggfwd localhost 8002 inoutpass inoutvideo.ogg

From a DV camera :

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

Using ffmpeg2theora :

Here's how to encode a pictures sequence to an ogg stream and directly send it to Icecast server. This can be used while the pictures are generated!!

[Terminal] > ffmpeg2theora -f image2 --inputfps 8 --speedlevel 2 /yourFolder/picturename%06d.png --framerate 8 -o - | oggfwd localhost 8002 inoutpass inoutvideo.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 send a video stream while the pictures are being generated, beware of the inputfps and framerate setting : if the still 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 fine 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 -> 3D engine for instance).

Screen Capture (Linux)

You can record the screen activity by using the application recordmydesktop :

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

Screen Capture (Mac OS X) [unstable on very recent macs]

You can use the InOutConnector app to send a part of your screen to your local Icecast2 server.

TIPS

Using Ogg (through Quicktime) (Max OS X/Windows)

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).

Using Quicktime with the command line (Mac OS X)

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.

Typical command line to convert and ogg file to an images sequence sould be :

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

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

Usage of a config file is also avaible. See the man pages of qt_export

InOut
Observer
Participer