Flumotion - your streaming media server

WHAT IT IS
----------

Flumotion is a streaming media server based on GStreamer and Twisted.

This is the first public development series of Flumotion.
It will probably still contain bugs, be difficult to install (since
you need recent dependencies), and cause you some headaches.

On the other hand, when it works and you are capturing your Firewire camera
on one machine, encoding to Theora on a second (with an overlay, of course), 
encoding the audio to Vorbis on a third, muxing to Ogg on a fourth, and then
streaming both audio and video from a fifth, audio only from a sixth,
video only from a seventh, and capturing all three streams to disk from
an eigth, you feel very good about yourself.

And you also have too many computers.

REQUIREMENTS
------------

You need:

GStreamer - 0.8.7 or higher
GStreamer plugins - 0.8.5 or higher
PyGTK - 2.4.0 or higher
GStreamer python bindings - 0.7.93 or higher
Twisted - 1.3.0
Python Imaging Library

And depending on what codecs you want to use:

libvorbis 1.0.1 or higher
libogg 1.1 or higher
libtheora 1.0alpha3 or higher

And if you want to build documentation:

epydoc

ISSUES
------

Some issues have been brought to our attention.  Please take note if you
run into them:
- locales with a comma as a decimal point trigger problems in the XML parsing.
  Run with LANG=C if you run into this
- When encoding to Vorbis, prefer to use quality instead of absolute bitrate.
  For absolute bitrate, for each sample rate a limited range of bitrates is
  allowed.

A FIRST TEST
------------

Once everything is built and installed,
you can try this to start the server:

terminal 1:
  flumotion-manager -v -T tcp conf/managers/default/planet.xml

terminal 2:
  flumotion-worker -v -T tcp -u user -p test

terminal 3:
  flumotion-admin -v
  Choose transport "TCP", and "user" and "test" in the dialog

  Go through the wizard, chosing defaults.

  Double-click the http component after the wizard has completed

terminal 4:
  gst-launch gnomevfssrc location=http://localhost:8800 ! oggdemux name=mux
             mux. ! { queue ! vorbisdec ! audioconvert ! alsasink }
             mux. ! { queue ! theoradec ! ffmpegcolorspace ! ximagesink }

  (make sure you type all of this on only one command line !)

Alternatively, you can use any theora-enabled network player to see the stream.

terminal 5:
  for a in `seq 1 10`; do ( flumotion-tester http://localhost:8800 & ); done

  This will throw 10 processes with 100 clients each at the server.  Hopefully,
  all of them will return success at the end of their run !

DOCUMENTATION
-------------

A manual is being written.  You can access the current work in progress at
http://www.flumotion.net/doc/flumotion/manual/html/

Flumotion also comes with API documentation.  You need epydoc to build them.

HACKING
-------

You can use jhbuild with the flu.modules and jhbuildrc file provided in misc/

This will set up everything except for Twisted for you from source.

SECURITY
--------

Read the security chapter in the aforementioned manual to get started.

Flumotion uses SSL transport by default.  For this you need a PEM certificate
file.  For security reasons you should generate this yourself when installing
from source.

The sample configuration file for the manager contains some htpasswd-style
crypted credentials, for a user named "user" and a password "test".  Use
these only for testing; make sure you change them before putting Flumotion
into production.

The sample configuration also only allows localhost connections, to make
sure you change the configuration before moving it into production.
Remove the host entry from the sample planet.xml file to allow other hosts
to connect.

ABOVE AND BEYOND
----------------

You can subscribe to our development list.  Information is at
http://lists.fluendo.com/mailman/listinfo/flumotion-devel

You can visit us on IRC: #fluendo on irc.freenode.org

You can visit our issues tracker:
https://core.fluendo.com/tracker/

LICENSING
---------

This version of the Flumotion Streaming Server is dual-licensed.

The GPL applies to all code files shipped with this version.
See LICENSE.GPL

The files may only be used together with or as part of the Flumotion
Advanced Streaming Server:
- under the terms of the Flumotion Advanced Streaming Server Commercial
  License Agreement; and
- when you have purchased or hold a valid Flumotion Advanced Streaming Server
  license.

If the conditions of this licensing strategy are not clear to you, please
contact Christian Schaller (christian@fluendo.com) or call +34-933-17.51.53

TESTING
-------
For testing purposes of your streams, you can run some GStreamer pipelines
to verify if things work as they should.

- multipart/jpeg stream (video only):
  gst-launch -v gnomevfssrc location=http://localhost:8802 ! multipartdemux ! jpegdec ! xvimagesink
