# The Framey Ruby Gem

This gem can be used for easy Rails integration with the Framey video recording service. See http://framey.com for more information.

# Dependencies:

* httparty (ruby gem)
* swfobject (javascript file)

# Installation

If not using bundler, do:

`gem install framey`

otherwise in your Gemfile:

`gem framey`

# User / Development Flow

* You make a page on your site that displays the Framey flash video recorder
* Your user visits that page and clicks record
* If your user likes the video she just recorded, she clicks "Publish"
* After a little while, Framey pings your servers at a specified callback url with a url to the video file
* You can choose to store those urls on your end, or just the id of the Framey video to access it later on Framey via an API call
* You then display the video to your user using either the Framey video player or your own favorite flash video player

# Usage

First, sign up at http://framey.com to get an API key and secret and to set your callback url. 

Then in environment.rb do:

    Framey.configure do |config|
      config.api_key = "[YOUR API KEY]"                             # required
      config.api_secret = "[YOUR API SECRET]"                       # required
      config.api_timeout = [API SIGNATURE EXPIRATION IN MINUTES]    # optional (15 by default)
      config.max_recording_time = [DEFAULT MAXIMUM VIDEO LENGTH]    # optional (30 by default)
    end

To render the Framey video recorder in an ActionView (example assumes ERB) do:

    <%= javascript_include_tag "swfobject" %>
    <%= render_recorder({
      :max_time => 60,                 # maximum allowed video length in seconds (optional, defaults to 30)
      :session_data => {               # custom parameters to be passed along to your app later (optional)
        :user_id => <%= @user.id %>    # you may, for example, want to relate this recording to a specific user in your system
      }
    }) %>
    
When your user then views this recorder, records a video, and clicks "Publish", your app receives a POST to the specified callback url with the following parameters:

    {
      :video => {
        :name => [video name],                  # this is the video's UUID within the Framey system
        :filesize => [filesize],                # the filesize in bytes of the video
        :duration => [duration],                # the duration of the video in seconds
        :state => [state],                      # the state of the video, in this case "uploaded"
        :views => [number of views],            # the number of times this video has been viewed, in this case 0
        :data => [the data hash you specified], # this is the exact data you specified in the :session_data hash when rendering the recorder
        :url => [video url],                    # url to the flash video file on framey that you can feed into a video player later
        :thumbnail => [thumbnail url]           # url to the thumbnail image that was generated for this video 
      }
    } 
    
To render the Framey video player in an ActionView (example assumes ERB) do:

    <%= javascript_include_tag "swfobject" %>
    <%= render_player({
      :video_url => "[video url]",          # the video url received in the callback (required)
      :thumbnail_url => "[thumbnail url]",  # the thumbnail url received in the callback (required)
      :progress_bar_color => "0x123456",    # the desired color for the progress bar (optional, defaults to black)
      :volume_bar_color => "0x123456",      # the desired color for the volume bar (optional, defaults to black)
    })%>
    
Note that you don't have to use the Framey video player, though, and can use any other flash video player you'd like.

To get updated stats information about a given video, do:

    @video = Framey::Api.get_video("[framey video name]")
    
This returns a simple Framey::Video object, like so:

    #<Framey::Video:0x1037b4450 @state="uploaded", @filesize=123456, @name="c96323e0-54b1-012e-9d34-7c6d628c53d4", @thumbnail="http://framey.com/videos/c96323e0-54b1-012e-9d34-7c6d628c53d4/thumbnail.jpg", @data={"user_id" => 1}, @url="http://framey.com/videos/c96323e0-54b1-012e-9d34-7c6d628c53d4/source.flv", @views=12, @duration=15.62>
    
To delete a video on Framey, do:

    @video.delete!

or:

    Framey::Api.delete_video("[framey video name]")

# Other Documentation

* http://rubydoc.info/gems/framey/1.0.0/frames

# License

(The MIT License)

Copyright (c) 2011 FIX

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
'Software'), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.