------------
Introduction
------------
Rainbow is an early prototype that provides video and audio capture
capabilities to web pages. It is currently distributed as a highly experimental
Firefox addon.

Rainbow uses a bunch of different backends depending on the platform to
capture audio and video. The ogg, theora and vorbis libraries from xiph are
used to encode them. WebM support is on our radar.

Mac: libvidcap for Video, portaudio for Audio
Windows: DirectShow for Video, and WinMM for Audio
Linux: Video not supported, ALSA for Audio

We would ultimately not want to depend on any external libraries. QTKit
backends for Video and Audio on the Mac, as well as a V4L backend for Video on
Linux are under development.

-------------
Quick testing
-------------
We have setup test pages for Rainbow on http://mozilla.github.com/rainbow/
which you can visit after you install the add-on. The domain has already been
added to the default preference 'extensions.rainbow.allowedDomains', but
if you are upgrading from an older version, you should receive a permissions
dialog.

---
API
---
The JS API offers the capability to record multiplexed audio and video files
to disk:

window.navigator.media.beginSession(params, ctx, observer);

where 'params' is a JS Object, which may contain the following properties.
The types and default values for each property are in brackets:

{
    audio:(boolean, true),
    video:(boolean, true),
    width:(int, 640),
    height:(int, 480),
    rate:(int, 22050),
    channels:(int, 1),
    quality:(float, 0.4)
}

and 'ctx' is the 2D context of a canvas on which a live preview (if video was
requested) will be drawn. 'ctx' may be null in case you do not want a preview.

'observer' is a JS function that will be called whenever a significant event
occurs. It will take two arguments, and you will usually want to switch on the
first one, which is the event type:

function onStateChange(type, data)
{
    switch (type) {
        case "session-began": window.navigator.media.beginRecord(); break;
        case "record-began": break;
        case "record-ended": break;
        case "record-finished": alert("got file " + data); break;
        case "session-ended": break;
    }
}

While beginSession only sets up Rainbow in 'preview' mode, which means
the canvas will be painted as usual, you must explicitly call beginRecord()
to start the encoding process. Calling endRecord() will result in the
'record-ended' and 'record-finished' events being passed to your observer,
and the latter's 'data' argument will be set to a DOMFile.

Please see content/example.html for sample usage of the API.

Rainbow also offers support for recording from a canvas as source (instead
of a webcam). The canvas will be sampled the rate of 30 frames per second. You
can do this by specifying the 'source' property of the params object to be
'true'. This will treat the 'ctx' argument you pass to the beginSession
function as the source of video rather than the destination of a live preview.

Please see content/example_canvas.html for an example of such usage.

---------------
Temporary Files
---------------
Rainbow does not correctly clean up files generated by it. You must manually
remove recorded OGG files from your disk. These files may be found in:

Mac: ~/Library/Caches/TemporaryItems/
Windows: C:\Users\<user>\AppData\Local\Temp\
Linux: /tmp

We are working on an API to ensure that these files get cleaned up once
the web application that requested their creation is done with them.

-------------
Common Errors
-------------
"Error: window.navigator.service is undefined"

This can mean one of two things:

- You tried to access the API from a webpage hosted on a restricted domain.
  By default, Rainbow will only allow access to web pages served from localhost,
  but you may change that by adding more domains to the
    'extensions.rainbow.allowedDomains'
  preference through about:config. The value is simply a JSON array of domains.

- The binary component itself failed to load. This may because you are using
  an older version of Firefox, or that you are running the nightly on an
  unsupported platform (see below). If this is the case the error will be
  preceded by something like:

"Error: Components.classes['@labs.mozilla.com/media/recorder;1'] is undefined"

----------------
Platform Support
----------------
On Linux, we do not support video recording.

On Windows, some DV cameras may result in garbled video.

On Mac (Snow Leopard), 64-bit versions of Minefield are not supported. You
may run your Minefield nightly in 32-bit mode like so:
$ arch -i386 /Applications/Minefield.app/Contents/MacOS/firefox-bin

--------
Building
--------
If you wish to build the binary components yourself, fetch a recent build of
the Gecko2 SDK from:
    http://ftp.mozilla.org/pub/mozilla.org/xulrunner/nightly/latest-trunk/
After extracting, set the MOZSDKDIR environment variable to point to it and
simply run `make'.

Precompiled versions of the dependencies are already included for
convenience, however if you wish to include custom versions of libvidcap,
libportaudio, libogg, libvorbis or libtheora; place them in the appropriate
directory in lib/ and the build system will automatically link with them.

You may set debug=1 to create a version of the XPCOM component with debugging
symbols.