root/indytube/tags/plumi-0.1-3/README

What is IndyTube?
-----------------

This is a very basic script for reencoding arbitrary video files to
flash video (flv), and then including this video in the browser with a
flash video player.  The exact same approach can be used to embed a
cortado java player that can play ogg theora files, but the files here
don't do that yet.  The overriding design goal is to make it
absolutely trivial for the largest number of users to view video
content, while still making the original files available for download,
and not compromising privacy and anonymity of uploaders and viewers by
relying on a commercial service like YouTube or Google Video.

Design: Why not build this into the cms?
--------------------------------

Video transcoding, even on good hardware, is a time-intensive task.
So any CMS that wanted to support embedded video would probably need
to run the encoding job in an asynchronous process anyway.  On systems
that do support asynchronous production processes, like Mir, you
probably wouldn't want to put big encoding jobs into the queue anyway,
because no one wants to wait 20 minutes for a video to finish encoding
when they need to update the startpage.  Running the video encoding in
a separate process also allows the encoding process to get "nice'd" 
to an appropriate priority so it doesn't bring down your server.  
It also means that it is very easy to graft support for embedded 
video onto any existing cms that stores video in the file system.

This script uses Twisted networking framework, to run every 60 seconds
or whatever you like, and scan a directory files for new videos to 
encode.

What do I need to run this?
--------------------------- 

* Python 2.4 or higher

* Flowplayer, available from http://flowplayer.sourceforge.net

        This provides a nice embedded flash video player, you should
        download a copy and put a copy on your web site.

* Mencoder, the Mplayer video encoder/decoder swiss army knife.  

        This is better than ffmpeg because it is designed to handle
        any proprietary cruft that your users throw at it.
        Get it from www.mplayerhq.hu, or, for debian packages, from
        www.debian-multimedia.org

* FLVTool2, http://inlet-media.de/flvtool2
        
        You need to be able to write some metadata to the file so
        users can seek during playback.  This ruby program does the
        trick (make sure you've got ruby installed!)

* Cheetah template library for Python.
        
        You can get this from http://www.cheetahtemplate.org/, or just
        'apt-get install python-cheetah'

* Twisted networking - 
        You can get this from http://www.twistedmatrix.com
        or 'apt-get install python-twisted'

* For OggTheora support, you need ffmpeg2theora and Cortado applet

How do I set it up?
-------------------

First, you need to open up indytube.py and change the config variables
to something sensible(TODO SOON: pull out to command line args).  Here
you need to set the paths for your orginal and encoded files, plus
urls for the resources like the flowplayer files and your splash
screen image(an Indymedia one is included here if you need one).  You
can also tweak the encoder options(sensible defaults are included for
small video files and quick encoding with decent quality) and turn off
encoding altogether.  There's logging settings for debugging, and a
way to specify the maximum number of encoders you'd like to run in
parallel, and at what priority.

You also might want to customize the include.template, which is used
to generate a fragment to be included in any page with video.  The
basic idea is that the cms template is tweaked to pull in this
template, which does nothing if it isn't there, and also to include a
"waiting for encoder" message, which a bit of javascript in the
generated include fragment "turns off".

An example, for mir, might make this more clear.  What you need to do
is go into the place in the article template where the link to the
video file attached to an article happens, and add something like:

  <div id="waiting4encoder${media.id}">
        <i>Waiting for encoder...check back in 10 minutes for flash version.</i>
  </div>
  <!--#include virtual="/media/${media.creationdate.formatted["yyyy/MM"]}/${media.id}.flv.inc" -->

Make sure that the "waiting4encoder" div preceds the include file!
Notice you can also put something like:

        <!--#config errmsg=" " -->

if you want to suppress the [an error occurred while processing this
directive] stuff that will happen while you're waiting for an encoder.

Then, just set up indytube.py to run every minute or so out of cron.
If the maximum numbers of encoders are already running, it just
stops. Otherwise, it will check for video files in the directory
you've specified, see if they've already been encoded, or if another
encoder is already handling them, and if not, generate the flv file
and the include file.  And then you've got streaming embedded video.
 

Still Todo:
-----------

* Configuration via command-line options
* Video thumbnail generation (how do you find a non-blank frame automatically?)