OpenTok is an API from TokBox that enables websites to weave live group video communication into their online experience. Check out http://www.tokbox.com/ for more information.
This is the official OpenTok Ruby Server SDK for generating Sessions, Tokens, and retriving Archives. Please visit our getting started page if you are unfamiliar with these concepts.
To install using bundler, add Opentok to your gemfile
and run bundle install
:
gem 'opentok'
To install as a regular gem just type gem install opentok
You need an api-key and secret. Request them at http://www.tokbox.com/opentok/tools/js/apikey.
In order to use any of the server side functions, you must first create an OpenTokSDK
object with your developer credentials.
OpenTokSDK
takes 2-3 parameters:
key (string) - Given to you when you register
secret (string) - Given to you when you register
# Creating an OpenTok Object API_KEY = '' # should be a string API_SECRET = '' # should be a string OTSDK = OpenTok::OpenTokSDK.new API_KEY, API_SECRET
Use your OpenTokSDK
object to create session_id
createSession
takes 1-2 parameters:
location (string) - give Opentok a hint on where you are running your application
properties (object) - OPTIONAL. Set peer to peer asenabled
ordisabled
. Disabled by default
# Creating Session object, passing request IP address to determine closest production server session_id = OTSDK.createSession( request.ip ) # Creating Session object with p2p enabled sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"} # or disabled sessionId = OTSDK.createSession( @location, sessionProperties )
With the generated sessionId, you can start generating tokens for each user.
generate_token
takes in hash with 1-4 properties:
session_id (string) - REQUIRED
role (string) - OPTIONAL. subscriber, publisher, or moderator
expire_time (int) - OPTIONAL. Time when token will expire in unix timestamp
connection_data (string) - OPTIONAL. Metadata to store data (names, user id, etc)
# Generating a token token = OTSDK.generateToken :session_id => session, :role => OpenTok::RoleConstants::PUBLISHER, :connection_data => "username=Bob,level=4"
To Download or delete archived video, you must have an Archive ID which you get from the javascript library. If you are unfamiliar with archiving concepts, please visit our archiving tutorial
OpenTok SDK has a function deleteArchive
that lets you delete videos in a recorded archive.
Use your OpenTokSDK
object to call deleteArchive
deleteArchive
takes in 2 parameters and returns a true or false boolean representing the success of the delete request
archive_id (string) - REQUIRED
token (string) - REQUIRED. This token MUST have a moderator role, and it should be generated with the same session_id used to create the archive
returns
true: Success, the archive is deleted
false: Archive does not exist (perhaps it was already deleted or never created), invalid token (perhaps it does not have the moderator role or it's generated with the wrong session_id)
Example:
successful = OTSDK.deleteArchive( archive_id, token )
OpenTok SDK allows you to stich up to 4 videos together in an archive.
Use your OpenTokSDK
object to call stitchArchive
stitchArchive takes in 1 parameter and returns a hash object with code, message, and location if stitch is successful.
archive_id (string) - REQUIRED
returns:
{:code=>201, :message=>"Successfully Created", :location=>response["location"]}
{:code=>202, :message=>"Processing"}
{:code=>403, :message=>"Invalid Credentials"}
{:code=>404, :message=>"Archive Does Not Exist"}
{:code=>500, :message=>"Server Error"}
Example:
result = OTSDK.stitchArchive archive_id if result[:code] == 201 return result[:location] end
With your moderator token and OpentokSDK Object, you can generate OpenTokArchive Object, which contains information for all videos in the Archive
getArchiveManifest()
takes in 2 parameters: archiveId and moderator token
archive_id (string) - REQUIRED. token (string) - REQUIRED. returns an
OpenTokArchive
object.
The resources property of this object is array ofOpenTokArchiveVideoResource
objects, and eachOpenTokArchiveVideoResource
object represents a video in the archive.
Example:(Make sure you have the OpentokSDK Object)
@token = '...' # token generated with corresponding session @archiveId = '5f74aee5-ab3f-421b-b124-ed2a698ee939' #Obtained from Javascript Library otArchive = OTSDK.getArchiveManifest(@archiveId, @token)
OpenTokArchive.resources
is an array of OpenTokArchiveVideoResource
objects. OpenTokArchiveVideoResource has getId()
method that returns the video_id
getId()
will return the video ID (a String)
Example:
otArchive = OTSDK.getArchiveManifest(@archiveId, @token) otVideoResource = otArchive.resources[0] videoId = otVideoResource.getId()
OpenTokArchive
has downloadArchiveURL
that will return an url string for downloading the video in the archive. You must call this function every time you want the file, because this url expires after 24 hours
video_id (string) - REQUIRED
token (string) - REQUIRED
returns url string
Example:
url = otArchive.downloadArchiveURL(video_id, token)