opentok 2.2.4 → 2.3.0

data/lib/opentok/client.rb

@@ -1,11 +1,16 @@
 require "opentok/exceptions"
+require "extensions/hash"
 
+require "active_support/inflector"
 require "httparty"
 
 module OpenTok
   # @private For internal use by the SDK.
   class Client
     include HTTParty
+
+    default_timeout 1 # Set HTTParty default timeout (open/read) to 1 second
+
     # TODO: expose a setting for http debugging for developers
     # debug_output $stdout
 
@@ -19,7 +24,8 @@ module OpenTok
     end
 
     def create_session(opts)
-      response = self.class.post("/session/create", :body => opts)
+      opts.extend(HashExtensions)
+      response = self.class.post("/session/create", :body => opts.camelize_keys!)
       case response.code
       when (200..300)
         response
@@ -28,11 +34,13 @@ module OpenTok
       else
         raise OpenTokError, "Failed to create session. Response code: #{response.code}"
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
     def start_archive(session_id, opts)
-      body = { "sessionId" => session_id }
-      body["name"] = opts[:name] unless opts[:name].nil?
+      opts.extend(HashExtensions)
+      body = { "sessionId" => session_id }.merge(opts.camelize_keys!)
       response = self.class.post("/v2/partner/#{@api_key}/archive", {
         :body => body.to_json,
         :headers => { "Content-Type" => "application/json" }
@@ -51,6 +59,8 @@ module OpenTok
       else
         raise OpenTokArchiveError, "The archive could not be started"
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
     def get_archive(archive_id)
@@ -65,6 +75,8 @@ module OpenTok
       else
         raise OpenTokArchiveError, "The archive could not be retrieved."
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
     def list_archives(offset, count)
@@ -82,6 +94,8 @@ module OpenTok
       else
         raise OpenTokArchiveError, "The archives could not be retrieved."
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
     def stop_archive(archive_id)
@@ -102,6 +116,8 @@ module OpenTok
       else
         raise OpenTokArchiveError, "The archive could not be stopped."
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
     def delete_archive(archive_id)
@@ -118,7 +134,8 @@ module OpenTok
       else
         raise OpenTokArchiveError, "The archive could not be deleted."
       end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
-
   end
 end

data/lib/opentok/constants.rb

@@ -2,4 +2,5 @@ module OpenTok
   API_URL = "https://api.opentok.com"
   TOKEN_SENTINEL = "T1=="
   ROLES = { subscriber: "subscriber", publisher: "publisher", moderator: "moderator" }
+  ARCHIVE_MODES = Set.new([:manual, :always])
 end

data/lib/opentok/opentok.rb

@@ -5,6 +5,7 @@ require "opentok/token_generator"
 require "opentok/archives"
 
 require "resolv"
+require "set"
 
 module OpenTok
   # Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
@@ -21,11 +22,11 @@ module OpenTok
   # @!method generate_token(options)
   #   Generates a token for a given session.
   #
-  #   @param [String] sessioin_id The session ID of the session to be accessed by the client using
+  #   @param [String] session_id The session ID of the session to be accessed by the client using
   #     the token.
   #
   #   @param [Hash] options A hash defining options for the token.
-  #   @option options [String] :role The role for the token. Set this to one of the following
+  #   @option options [Symbol] :role The role for the token. Set this to one of the following
   #     values:
   #     * <code>:subscriber</code> -- A subscriber can only subscribe to streams.
   #
@@ -64,7 +65,7 @@ module OpenTok
     #   (https://dashboard.tokbox.com).
     # @param [String] api_secret Your OpenTok API key.
     # @param [String] api_url Do not set this parameter. It is for internal use by TokBox.
-    def initialize(api_key, api_secret , api_url = ::OpenTok::API_URL)
+    def initialize(api_key, api_secret, api_url=::OpenTok::API_URL)
       @api_key = api_key.to_s()
       @api_secret = api_secret
       # TODO: do we really need a copy of this in the instance or should we overwrite the module
@@ -92,41 +93,46 @@ module OpenTok
     #
     # @param [Hash] opts (Optional) This hash defines options for the session.
     #
-    # @option opts [String] :media_mode Determines whether the session will transmit streams the
+    # @option opts [Symbol] :media_mode Determines whether the session will transmit streams the
     #   using OpenTok Media Router (<code>:routed</code>) or not (<code>:relayed</code>).
     #   By default, this property is set to <code>:relayed</code>.
     #
-    #   With the <code>mediaMode</code> property set to <code>:relayed</code>, the session
+    #   With the <code>media_mode</code> property set to <code>:relayed</code>, the session
     #   will attempt to transmit streams directly between clients. If clients cannot connect due to
     #   firewall restrictions, the session uses the OpenTok TURN server to relay audio-video
     #   streams.
     #
-    #   With the <code>mediaMode</code> property set to <code>:routed</code>, the session
-    #   will use the {http://tokbox.com/#multiparty OpenTok Media Router}.
+    #   With the <code>media_mode</code> property set to <code>:routed</code>, the session will use
+    #   the {https://tokbox.com/opentok/tutorials/create-session/#media-mode OpenTok Media Router}.
     #   The OpenTok Media Router provides the following benefits:
     #
     #   * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
-    #     (When the <code>mediaMode</code> property is set to <code>:relayed</code>,
+    #     (When the <code>media_mode</code> property is set to <code>:relayed</code>,
     #     each client must send a separate audio-video stream to each client subscribing to
     #     it.)
     #   * The OpenTok Media Router can improve the quality of the user experience through
-    #     {http://tokbox.com/#iqc Intelligent Quality Control}. With
-    #     Intelligent Quality Control, if a client's connectivity degrades to a degree that
+    #     {https://tokbox.com/platform/fallback audio fallback and video recovery}. With
+    #     these features, if a client's connectivity degrades to a degree that
     #     it does not support video for a stream it's subscribing to, the video is dropped on
     #     that client (without affecting other clients), and the client receives audio only.
     #     If the client's connectivity improves, the video returns.
-    #   * The OpenTok Media Router supports the {http://tokbox.com/platform/archiving archiving}
+    #   * The OpenTok Media Router supports the
+    #     {https://tokbox.com/opentok/tutorials/archiving archiving}
     #     feature, which lets you record, save, and retrieve OpenTok sessions.
     #
     # @option opts [String] :location  An IP address that the OpenTok servers will use to
     #     situate the session in its global network. If you do not set a location hint,
     #     the OpenTok servers will be based on the first client connecting to the session.
     #
+    # @option opts [Symbol] :archive_mode Determines whether the session will be archived
+    #     automatically (<code>:always</code>) or not (<code>:manual</code>). When using automatic
+    #     archiving, the session must use the <code>:routed</code> media mode.
+    #
     # @return [Session] The Session object. The session_id property of the object is the session ID.
     def create_session(opts={})
 
       # normalize opts so all keys are symbols and only include valid_opts
-      valid_opts = [ :media_mode, :location ]
+      valid_opts = [ :media_mode, :location, :archive_mode ]
       opts = opts.inject({}) do |m,(k,v)|
         if valid_opts.include? k.to_sym
           m[k.to_sym] = v
@@ -150,12 +156,18 @@ module OpenTok
       unless params[:location].nil?
         raise "location must be an IPv4 address" unless params[:location] =~ Resolv::IPv4::Regex
       end
+      # archive mode is optional, but it has to be one of the valid values if present
+      unless params[:archive_mode].nil?
+        raise "archive mode must be either always or manual" unless ARCHIVE_MODES.include? params[:archive_mode].to_sym
+      end
+
+      raise "A session with always archive mode must also have the routed media mode." if (params[:archive_mode] == :always && params[:media_mode] == :relayed)
 
       response = client.create_session(params)
       Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
     end
 
-    # An Archives object, which lets you work with OpenTok 2.0 archives.
+    # An Archives object, which lets you work with OpenTok archives.
     def archives
       @archives ||= Archives.new client
     end

data/lib/opentok/session.rb

@@ -17,11 +17,14 @@ module OpenTok
   # @attr_reader [String] location The location hint IP address. See the OpenTok.createSession()
   #   method.
   #
+  # @attr_reader [String] archive_mode Whether the session will be archived automatically
+  #  (<code>:always</code>) or not (<code>:manual</code>).
+  #
   # @!method generate_token(options)
   #   Generates a token.
   #
   #   @param [Hash] options
-  #   @option options [String] :role The role for the token. Set this to one of the following
+  #   @option options [Symbol] :role The role for the token. Set this to one of the following
   #     values:
   #     * <code>:subscriber</code> -- A subscriber can only subscribe to streams.
   #
@@ -49,7 +52,7 @@ module OpenTok
       :session_id => ->(instance) { instance.session_id }
     })
 
-    attr_reader :session_id, :media_mode, :location, :api_key, :api_secret
+    attr_reader :session_id, :media_mode, :location, :archive_mode, :api_key, :api_secret
 
     # @private
     # this implementation doesn't completely understand the format of a Session ID
@@ -65,7 +68,7 @@ module OpenTok
     # @private
     def initialize(api_key, api_secret, session_id, opts={})
       @api_key, @api_secret, @session_id = api_key, api_secret, session_id
-      @media_mode, @location = opts.fetch(:media_mode, :relayed), opts[:location]
+      @media_mode, @location, @archive_mode = opts.fetch(:media_mode, :relayed), opts[:location], opts.fetch(:archive_mode, :manual)
     end
 
     # @private

data/lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '2.2.4'
+  VERSION = '2.3.0'
 end

data/sample/Archiving/README.md

@@ -25,7 +25,7 @@ Finally, start the server using Bundler to handle dependencies
 $ bundle exec ruby archiving_sample.rb
 ```
 
-Visit <http://localhost:9393> in your browser. You can now create new archives (either as a host or
+Visit <http://localhost:4567> in your browser. You can now create new archives (either as a host or
 as a participant) and also play archives that have already been created.
 
 ## Walkthrough
@@ -38,7 +38,7 @@ main application (archiving_sample.rb).
 
 ### Creating Archives – Host View
 
-Start by visiting the host page at <http://localhost:9393/host> and using the application to record
+Start by visiting the host page at <http://localhost:4567/host> and using the application to record
 an archive. Your browser will first ask you to approve permission to use the camera and microphone.
 Once you've accepted, your image will appear inside the section titled 'Host'. To start recording
 the video stream, press the 'Start Archiving' button. Once archiving has begun the button will turn
@@ -65,27 +65,33 @@ end
 If you've completed the HelloWorld walkthrough, this should look familiar. This handler simply
 generates the three strings that the client (JavaScript) needs to connect to the session: `api_key`,
 `session_id` and `token`. After the user has connected to the session, they press the
-'Start Archiving' button, which sends an XHR (or Ajax) request to the <http://localhost:9393/start>
+'Start Archiving' button, which sends an XHR (or Ajax) request to the <http://localhost:4567/start>
 URL. The route handler for this URL is shown below:
 
 ```ruby
-get '/start' do
+post '/start' do
   archive = settings.opentok.archives.create settings.session.session_id, {
-    :name => "Ruby Archiving Sample App"
+    :name => "Ruby Archiving Sample App",
+    :output_mode => params[:output_mode],
+    :has_audio => params[:has_audio] == "on",
+    :has_video => params[:has_video] == "on"
   }
   body archive.to_json
 end
 ```
 
 In this handler, `opentok.archives.create` is called with the `session_id` for the session that
-needs to be archived. The optional second argument is a hash which contains a `:name` key. The value
-is a string that will be stored with the archive and can be read later. In this case, as in the
+needs to be archived. The optional second argument is a hash which defines optional properties
+for the archive. The `:name` value defines the archive's name, which is stored with the archive and
+can be read later. The `:has_audio`, `:has_video`, and `:output_mode` values are read from the
+request body; these define whether the archive will record audio and video, and whether it will
+record streams individually or to a single file composed of all streams. In this case, as in the
 HelloWorld sample app, there is only one session created and it is used here and for the participant
 view. This will trigger the recording to begin. The response sent back to the client's XHR request
 will be the JSON representation of the archive, which is returned from the `to_json()` method. The
 client is also listening for the `archiveStarted` event, and uses that event to change the
 'Start Archiving' button to show 'Stop Archiving' instead. When the user presses the button this
-time, another XHR request is sent to the <http://localhost:9393/stop/:archiveId> URL where
+time, another XHR request is sent to the <http://localhost:4567/stop/:archiveId> URL where
 `:archiveId` represents the ID the client receives in the 'archiveStarted' event. The route handler
 for this request is shown below:
 
@@ -109,7 +115,7 @@ be found in the `public/js/host.js` file. Read about the
 ### Creating Archives - Participant View
 
 With the host view still open and publishing, open an additional window or tab and navigate to
-<http://localhost:9393/participant> and allow the browser to use your camera and microphone. Once
+<http://localhost:4567/participant> and allow the browser to use your camera and microphone. Once
 again, start archiving in the host view. Back in the participant view, notice that the red blinking
 indicator has been shown so that the participant knows his video is being recorded. Now stop the
 archiving in the host view. Notice that the indicator has gone away in the participant view too.
@@ -137,7 +143,7 @@ in the client, in code that can be found in the `public/js/participant.js` file.
 
 ### Past Archives
 
-Start by visiting the history page at <http://localhost:9393/history>. You will see a table that
+Start by visiting the history page at <http://localhost:4567/history>. You will see a table that
 displays all the archives created with your API Key. If there are more than five, the older ones
 can be seen by clicking the "Older →" link. If you click on the name of an archive, your browser
 will start downloading the archive file. If you click the "Delete" link in the end of the row

data/sample/Archiving/archiving_sample.rb

@@ -7,7 +7,7 @@ class ArchivingSample < Sinatra::Base
 
   set :api_key, ENV['API_KEY']
   set :opentok, OpenTok::OpenTok.new(api_key, ENV['API_SECRET'])
-  set :session, opentok.create_session :media_mode => :routed
+  set :session, opentok.create_session(:media_mode => :routed)
   set :erb, :layout => :layout
 
   get '/' do
@@ -58,9 +58,12 @@ class ArchivingSample < Sinatra::Base
     redirect archive.url
   end
 
-  get '/start' do
+  post '/start' do
     archive = settings.opentok.archives.create settings.session.session_id, {
-      :name => "Ruby Archiving Sample App"
+      :name => "Ruby Archiving Sample App",
+      :output_mode => params[:output_mode],
+      :has_audio => params[:has_audio] == "on",
+      :has_video => params[:has_video] == "on"
     }
     body archive.to_json
   end

data/sample/Archiving/public/js/host.js

@@ -1,5 +1,5 @@
 var session = OT.initSession(sessionId),
-    publisher = OT.initPublisher("publisher"),
+    publisher = OT.initPublisher('publisher'),
     archiveID = null;
 
 session.connect(apiKey, token, function(err, info) {
@@ -10,28 +10,41 @@ session.connect(apiKey, token, function(err, info) {
 });
 
 session.on('streamCreated', function(event) {
-  session.subscribe(event.stream, "subscribers", { insertMode: "append" });
+  session.subscribe(event.stream, 'subscribers', { insertMode: 'append' });
 });
 
 session.on('archiveStarted', function(event) {
   archiveID = event.id;
-  console.log("ARCHIVE STARTED");
-  $(".start").hide();
-  $(".stop").show();
+  console.log('ARCHIVE STARTED');
+  $('.start').hide();
+  $('.stop').show();
+  disableForm();
 });
 
 session.on('archiveStopped', function(event) {
   archiveID = null;
-  console.log("ARCHIVE STOPPED");
-  $(".start").show();
-  $(".stop").hide();
+  console.log('ARCHIVE STOPPED');
+  $('.start').show();
+  $('.stop').hide();
+  enableForm();
 });
 
 $(document).ready(function() {
-  $(".start").click(function(event){
-    $.get("start");
+  $('.start').click(function (event) {
+    var options = $('.archive-options').serialize();
+    disableForm();
+    $.post('/start', options).fail(enableForm);
   }).show();
-  $(".stop").click(function(event){
-    $.get("stop/" + archiveID);
+  $('.stop').click(function(event){
+    $.get('stop/' + archiveID);
   }).hide();
 });
+
+
+function disableForm() {
+  $('.archive-options-fields').attr('disabled', 'disabled');
+}
+
+function enableForm() {
+  $('.archive-options-fields').removeAttr('disabled');
+}

data/sample/Archiving/views/host.erb

@@ -12,6 +12,30 @@
           <div id="subscribers"><div id="publisher"></div></div>
         </div>
         <div class="panel-footer">
+          <form class="archive-options">
+              <fieldset class="archive-options-fields">
+                  <div class="form-group">
+                      <p class="help-block">Archive Options:</p>
+                      <label class="checkbox-inline">
+                          <input type="checkbox" name="has_audio" checked> Audio
+                      </label>
+                      <label class="checkbox-inline">
+                          <input type="checkbox" name="has_video" checked> Video
+                      </label>
+                  </div>
+
+                  <div class="form-group">
+                      <p class="help-block">Output Mode:</p>
+                      <label class="radio-inline">
+                          <input type="radio" name="output_mode" value="composed" checked> Composed
+                      </label>
+                      <label class="radio-inline">
+                          <input type="radio" name="output_mode" value="individual"> Individual
+                      </label>
+                  </div>
+              </fieldset>
+          </form>
+          <br>
           <button class="btn btn-danger start">Start archiving</button>
           <button class="btn btn-success stop">Stop archiving</button>
         </div>

data/sample/HelloWorld/README.md

@@ -26,7 +26,7 @@ Finally, start the server using Bundler to handle dependencies
 $ bundle exec ruby hello_world.rb
 ```
 
-Visit <http://localhost:9393> in your browser. Open it again in a second window. Smile! You've just
+Visit <http://localhost:4567> in your browser. Open it again in a second window. Smile! You've just
 set up a group chat.
 
 ## Walkthrough

data/spec/cassettes/OpenTok_Archives/should_create_archives.yml

@@ -5,7 +5,7 @@ http_interactions:
     uri: https://api.opentok.com/v2/partner/123456/archive
     body:
       encoding: UTF-8
-      string: '{"sessionId":"SESSIONID","name":""}'
+      string: '{"sessionId":"SESSIONID"}'
     headers:
       X-Tb-Partner-Auth:
       - 123456:1234567890abcdef1234567890abcdef1234567890

data/spec/cassettes/OpenTok_Archives/should_create_audio_only_archives.yml

@@ -0,0 +1,50 @@
+---
+http_interactions:
+- request:
+    method: post
+    uri: https://api.opentok.com/v2/partner/123456/archive
+    body:
+      encoding: UTF-8
+      string: '{"sessionId":"SESSIONID","hasVideo":false}'
+    headers:
+      X-Tb-Partner-Auth:
+      - 123456:1234567890abcdef1234567890abcdef1234567890
+      User-Agent:
+      - OpenTok-Ruby-SDK/<%= version %>
+      Content-Type:
+      - application/json
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Wed, 19 Mar 2014 01:49:22 GMT
+      Content-Type:
+      - application/json
+      Transfer-Encoding:
+      - chunked
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "createdAt" : 1395193762293,
+          "duration" : 0,
+          "id" : "d7f4d2a3-da74-414d-868a-190532a835bc",
+          "name" : "ARCHIVE NAME",
+          "partnerId" : 123456,
+          "reason" : "",
+          "sessionId" : "SESSIONID",
+          "size" : 0,
+          "status" : "started",
+          "url" : null,
+          "hasAudio" : true,
+          "hasVideo" : false
+        }
+    http_version: 
+  recorded_at: Wed, 19 Mar 2014 01:49:22 GMT
+recorded_with: VCR 2.8.0