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

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

window.navigator.media.recordToFile(params, ctx);

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.
The record call will return an object, on which you can call stop() to end
recording. It will return a DOM File object which you may then upload.

Rainbow 0.2 also offers preliminary support for sending multiplexed frames to a
websocket. Since websockets do not support binary data (yet), Rainbow will
write segments in Base64 encoding, 8192 bytes per message:

window.navigator.media.recordToSocket(params, ctx, sock);

---------------
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: Permission denied for <http://localhost> to call method
    UnnamedClass.toString on <>.
 Error: uncaught exception: unknown (can't convert to string)"

This usually means that a device to record audio or video was not found. If you
look at the command line (stderr) you will find a clearer error message. We need
to propogate this type of error correctly to JS.

"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

--------------
Video Playback 
--------------
Rainbow 0.1 produced incorrectly encoded OGG files, the audio component of
which could not be played by Firefox. Simply upgrade to Rainbow 0.2 to fix
the issue.

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