== Introduction
NOTE: RAYDASH HAS BEEN SHUT DOWN AND THIS EXTENSION NO LONGER WORKS

Raydash allows you to easily integrate live video and/or audio into your
Rails applications. Your server will need to be able to make outgoing connections api.raydash.com on port 8080. You will need a userid and secret to access Raydash's servers. This can be obtained by signing up for the beta at http://www.raydash.com. Next, you will follow the instructions below. You will be using helpers to embed videostream and videorecord flash objects into your application for playing and recording real-time audio and/or video.

== Quickstart

1) Add the following to your Gemfile:

   gem "raydash", :git => 'git://github.com/gersh/Raydash-Ruby-on-Rails.git'

2) Configure your project your userid and secret with the following command:

   rails g raydash:install [userid] [secret]

If you set the environment variables RAYDASH_USERID and RAYDASH_SECRET or use the Heroku plugin you can just call:

   rails g raydash:install

This will generate the required configuration files to use Raydash


4) Create a controller for your app. For example,

      def index()
          @token = Raydash.getToken()
      end           

You may also set a customGroup for your token to track it. This can be done with:
    Raydash.getToken("dummyblack","YOUR_CUSTOM_GROUP")

dummyblack is the default for pointing the token. You can also point the token to view existing token's stream.

5) Add the proper header information to your layout. Often, this is
app/views/layouts/application.html.erb. You will need add the
following into the header:

          <%= raydash_header %>
6) Create a view to display the video. You will utilize two helpers
provided by raydash: 'videostream' and 'videorecord'. These will embed
a streaming ability, and a recording ability respectively. 

A sample view might look like:
  
        <%= videostream(@token,"video_in") %>
        <%= videorecord(@token,"video_out") %>

In this sample, @token specifies the token we are connecting to,
and "video_in" and "video_out" are div ids. 


7) Assuming you have configured the necessary routes (E.X adding:
            match '/YOUR_CONTROLLER' => 'YOUR_CONTROLLER#index'
to routes 'routes.rb', you should be
able to load the page, and enable your camera. The streaming
capabilities will also be enabled but the stream isn't connect to
anything.

8) You can create new tokens, which point to existing tokens with:

Raydash.getToken(oldTokenName)

You can directly connect your token to a given token with:
          def connect_token()
		Raydash.getToken(params[:old_token])
          end

          with route
          '/videos/route/:id1/:id2' => 'YOUR_CONTROLLER#connect_to'

When connect_to is called, it will point on stream at another stream. This can be accomplished with:
	
	raydash.changeStream(myToken,otherToken)

Note, this will only point it one way. If you want to point it the other way, you will also need to call:

	raydash.changeStream(otherToken,myToken)

== Helpers
These can be used within any view you use the Raydash gem.
=== raydash_header()
Generates the html for the header to include necessary javascript files to use raydash
=== videostream(token,id,height="640",width="480",videoOff="0")
Adds an flash element that plays video and sound

- token The token for the stream. You can generate a new token with Raydash.getToken(), or it is done automatically in models generated with "rails g raydash:model". 
- id The div id for use within the HTML. This can be useful for interacting with the javascript API
- height The height of the videostream
- width The width of the videostream
- videoOff if "1", it will hide the video, and only stream audio.
=== videorecord(token,id,height="640",width="480",hideCamera="0",videoOff="0")
Adds a flash element to record and send to the server video and sound

- token The token for the stream. You can generate a new with Raydash.getToken(), or it is done automatically in models generated with "rails g raydash:model".
- id The div id for use within the HTML. This can be useful for interacting with the javascript API
- height The height of videorecord
- width The width of videorecord
- hideCamera if "1", it will hide the camera. This is useful is you don't want to show the camera
- videoOff if "1", it will only stream audio.

== Javascript API
Generally, most functionality should be performed via the backend API. However, there is a Javascript API for working with the flash elements for certain purposes. You can call these elements by using document.getElementById("id"), where id is the id you specify when you add the element to your page 
=== Videostream
==== play()
If you aren't currently playing the stream, start playing. Generally, the stream auto-starts when you load the page in your web browser, so it is unneccessary to use this
==== stop()
Stop playing any stream. Note: It is often preferrable to use changeStream in the backend API to switch to a black stream. There is a special token, "dummyblack" on the server for this purpose 
=== Videorecord
==== play()
If you aren't currently recording the stream, it starts recording. Generally, the recording auto-starts when you load the page in your web browser, so it is unneccessary to use this
==== stop()
Totally stops all recording.
==== changeResolution(width,height)
Changes the resolution and size of the video recording
-width The new width
-height The new height

== Backend-API library

=== Raydash.getToken(streamName="",customGroup="")
This function gets a token. A token is needed for every recording or
viewing video box in the application. 

streamName is an optional parameter that is another token created with
this function. If specified, the display stream will show the stream
from the call of that function

customGroup This is an optional parameter for tracking different tokens
=== Raydash.changeStream(output_token, input_token)
The function re-points where a token is streaming from. We can
dynamically change where any stream is pointing, dynamically. You can point to the input_token "dummyblack" to make the window totally black.

output_token is the name of the token we are streaming to. If we have
a video stream initialized with this token, if will immediately start
displaying content from the input_token.

input_token refers to a videorecord that has been initialized with its stream

== Raydash.changeStreamRand(token, params)
This changes to a random other stream satisfying the given criteria
The token is the token of the stream you want to point. Params can be:
	:active => true will connect to streams that are active
	:twoWay => true will make a two-way connection
	:customGroup The custom group we to connect with
== Raydash.changeStreamNext(token,params)
	:active => true will connect to streams that are active
	:twoWay => true will make a two-way connection
	:customGroup The custom group we to connect with

=== Raydash.getStreamInfo(token)
Returns a hash-array with information about the token. 
	
=== Raydash.startRecord(token)
Starts recording for a given token

=== Raydash.stopRecord(token,bucket)

token To stop recording for

bucket Amazon S3 bucket to put it into. Note, you must first call Raydash.setUserInfo to set the your amazon key and secret

=== Raydash.setUserInfo(amazonKey,amazonSecret,callbackUrl="")

amazonKey Key for saving onto amazon s3. This key must have permissions to save to S3 buckets

amazonSecret The secret for the key

callbackUrl A calbackUrl for sending notifications on changes in streams