opentok 3.1.0 → 4.1.2

data/lib/opentok/archives.rb

@@ -48,6 +48,17 @@ module OpenTok
     #   default) or "1280x720" (HD). This property only applies to composed archives. If you set
     #   this property and set the outputMode property to "individual", the call the method
     #   results in an error.
+    # @option options [Hash] :layout Specify this to assign the initial layout type for
+    #   the archive. This applies only to composed archives. This is a hash containing two keys:
+    #   <code>:type</code> and <code>:stylesheet<code>. Valid values for <code>:type</code> are
+    #   "bestFit" (best fit), "custom" (custom), "horizontalPresentation" (horizontal presentation),
+    #   "pip" (picture-in-picture), and "verticalPresentation" (vertical presentation)).
+    #   If you specify a "custom" layout type, set the <code>:stylesheet</code> key to the
+    #   stylesheet (CSS). (For other layout types, do not set the <code>:stylesheet</code> key.)
+    #   If you do not specify an initial layout type, the archive uses the best fit
+    #   layout type. For more information, see
+    #   {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing
+    #   the video layout for composed archives}.
     #
     # @return [Archive] The Archive object, which includes properties defining the archive,
     #   including the archive ID.
@@ -66,7 +77,7 @@ module OpenTok
         "Resolution cannot be supplied for individual output mode" if options.key?(:resolution) and options[:output_mode] == :individual
 
       # normalize opts so all keys are symbols and only include valid_opts
-      valid_opts = [ :name, :has_audio, :has_video, :output_mode, :resolution ]
+      valid_opts = [ :name, :has_audio, :has_video, :output_mode, :resolution, :layout ]
       opts = options.inject({}) do |m,(k,v)|
         if valid_opts.include? k.to_sym
           m[k.to_sym] = v
@@ -198,7 +209,7 @@ module OpenTok
       type = options[:type]
       raise ArgumentError, "custom type must have a stylesheet" if (type.eql? "custom") && (!options.key? :stylesheet)
       valid_non_custom_type = ["bestFit","horizontalPresentation","pip", "verticalPresentation", ""].include? type
-      raise ArgumentError, "type is not valid or stylesheet not needed" if !valid_non_custom_type
+      raise ArgumentError, "type is not valid" if !valid_non_custom_type && !(type.eql? "custom")
       raise ArgumentError, "type is not valid or stylesheet not needed" if valid_non_custom_type and options.key? :stylesheet
       response = @client.layout_archive(archive_id, options)
       (200..300).include? response.code

data/lib/opentok/broadcasts.rb

@@ -138,7 +138,7 @@ module OpenTok
       type = options[:type]
       raise ArgumentError, "custom type must have a stylesheet" if (type.eql? "custom") && (!options.key? :stylesheet)
       valid_non_custom_type = ["bestFit","horizontalPresentation","pip", "verticalPresentation", ""].include? type
-      raise ArgumentError, "type is not valid" if !valid_non_custom_type
+      raise ArgumentError, "type is not valid" if !valid_non_custom_type && !(type.eql? "custom")
       raise ArgumentError, "stylesheet not needed" if valid_non_custom_type and options.key? :stylesheet
       response = @client.layout_broadcast(broadcast_id, options)
       (200..300).include? response.code

data/lib/opentok/client.rb

@@ -12,18 +12,20 @@ module OpenTok
   class Client
     include HTTParty
 
-    open_timeout 2 # Set HTTParty default timeout (open/read) to 2 seconds
-
     # TODO: expose a setting for http debugging for developers
     # debug_output $stdout
 
-    def initialize(api_key, api_secret, api_url, ua_addendum="")
+    attr_accessor :api_key, :api_secret, :api_url, :ua_addendum, :timeout_length
+
+    def initialize(api_key, api_secret, api_url, ua_addendum='', opts={})
       self.class.base_uri api_url
       self.class.headers({
-        "User-Agent" => "OpenTok-Ruby-SDK/#{VERSION}" + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}" + (ua_addendum ? " #{ua_addendum}" : "")        
+        "User-Agent" => "OpenTok-Ruby-SDK/#{VERSION}" + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}" + (ua_addendum ? " #{ua_addendum}" : "")
       })
       @api_key = api_key
       @api_secret = api_secret
+      @timeout_length = opts[:timeout_length] || 2
+      self.class.open_timeout @timeout_length
     end
 
     def generate_jwt(api_key, api_secret)

data/lib/opentok/constants.rb

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

data/lib/opentok/opentok.rb

@@ -69,7 +69,7 @@ module OpenTok
     # @private
     # don't want these to be mutable, may cause bugs related to inconsistency since these values are
     # cached in objects that this can create
-    attr_reader :api_key, :api_secret, :api_url, :ua_addendum
+    attr_reader :api_key, :api_secret, :timeout_length, :api_url, :ua_addendum
 
     ##
     # Create a new OpenTok object.
@@ -79,9 +79,11 @@ module OpenTok
     # @param [String] api_secret Your OpenTok API key.
     # @option opts [Symbol] :api_url Do not set this parameter. It is for internal use by TokBox.
     # @option opts [Symbol] :ua_addendum Do not set this parameter. It is for internal use by TokBox.
+    # @option opts [Symbol] :timeout_length Custom timeout in seconds. If not provided, defaults to 2 seconds.
     def initialize(api_key, api_secret, opts={})
       @api_key = api_key.to_s()
       @api_secret = api_secret
+      @timeout_length = opts[:timeout_length] || 2
       @api_url = opts[:api_url] || API_URL
       @ua_addendum = opts[:ua_addendum]
     end
@@ -212,7 +214,7 @@ module OpenTok
 
     protected
     def client
-      @client ||= Client.new api_key, api_secret, api_url, ua_addendum
+      @client ||= Client.new api_key, api_secret, api_url, ua_addendum, timeout_length: @timeout_length
     end
 
   end

data/lib/opentok/sip.rb

@@ -30,8 +30,6 @@ module OpenTok
     #   PSTN phones.
     # @option opts [Hash] :headers This hash defines custom headers to be added
     #   to the SIP ​INVITE​ request initiated from OpenTok to the your SIP platform.
-    #   Each of the custom headers must start with the ​"X-"​ prefix, or the call
-    #   will result in a Bad Request (400) response.
     # @option opts [Hash] :auth This object contains the username and password
     #   to be used in the the SIP INVITE​ request for HTTP digest authentication,
     #   if it is required by your SIP platform.

data/lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '3.1.0'
+  VERSION = '4.1.2'
 end

data/opentok.gemspec

@@ -16,17 +16,18 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
 
-  spec.add_development_dependency "bundler", "~> 1.5"
-  spec.add_development_dependency "rake", "~> 10.1.1"
-  spec.add_development_dependency "rspec", "~> 2.14.1"
-  spec.add_development_dependency "webmock", "~> 2.3.2"
-  spec.add_development_dependency "vcr", "~> 2.8.0"
-  spec.add_development_dependency "yard", "~> 0.9.11"
+  bundler_version = RUBY_VERSION < '2.1' ? '~> 1.5' : '>= 1.5'
+  spec.add_development_dependency "bundler", bundler_version
+  spec.add_development_dependency "rake", "~> 12.0.0"
+  spec.add_development_dependency "rspec", "~> 3.9.0"
+  spec.add_development_dependency "webmock", ">= 2.3.2"
+  spec.add_development_dependency "vcr", ">= 2.8.0"
+  spec.add_development_dependency "yard", ">= 0.9.11"
   # TODO: exclude this for compatibility with rbx
   # spec.add_development_dependency "debugger", "~> 1.6.6"
 
   spec.add_dependency "addressable", "~> 2.3" #  2.3.0 <= version < 3.0.0
-  spec.add_dependency "httparty", "~> 0.15.5"
+  spec.add_dependency "httparty", ">= 0.18.0"
   spec.add_dependency "activesupport", ">= 2.0"
-  spec.add_dependency "jwt", "~> 1.5.6"
+  spec.add_dependency "jwt", ">= 1.5.6"
 end

data/sample/Broadcast/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+gem "sinatra", "~> 1.4.4"
+gem "opentok", :path => "../../"

data/sample/Broadcast/README.md

@@ -0,0 +1,201 @@
+# OpenTok Broadcasting Sample for Ruby
+
+This is a simple demo app that shows how you can use the OpenTok Ruby SDK to broadcast 
+sessions and how to stop them, change the layout of the broadcast and/or the streams within.
+
+## Running the App
+
+First, download the dependencies using [Bundler](http://bundler.io)
+
+```
+$ bundle install
+```
+
+Next, add your OpenTok API key and API secret to the environment variables. There are a few ways to do
+this but the simplest would be to do it right in your shell.
+
+```
+$ export API_KEY=0000000
+$ export API_SECRET=abcdef1234567890abcdef01234567890abcdef
+```
+
+Finally, start the server using Bundler to handle dependencies
+
+```
+$ bundle exec ruby broadcast_sample.rb
+```
+
+Visit <http://localhost:4567> in your browser. You can now create new broadcast (with a host and
+as a participant) and also view those broadcasts.
+
+## Walkthrough
+
+This demo application uses the same frameworks and libraries as the HelloWorld sample. If you have
+not already gotten familiar with the code in that project, consider doing so before continuing.
+
+The explanations below are separated by page. Each section will focus on a route handler within the
+main application (broadcast_sample.rb).
+
+### Creating Broadcasts – Host View
+
+The Host view manages the broadcasting process. Visit the host page at <http://localhost:4567/host>.
+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 broadcasting
+the video stream, press the 'Start Broadcast' button. You can specify the maximum duration,
+resolution, and layout of the broadcast. Once broadcasting has begun the button will turn
+green and change to 'Stop Broadcast'. Click this button when you are done broadcasting.
+
+The host page basically sets up the OpenTok session with the API key and secret you provided.
+If a previously started broadcast exists, it defaults to it, along with the layout and the stream
+that has the focus:
+
+```ruby
+  get '/host' do
+     api_key = settings.api_key
+     session_id = settings.session.session_id
+     token = settings.opentok.generate_token(session_id, role: :publisher, initialLayoutClassList: ['focus'])
+ 
+     erb :host, locals: {
+         apiKey: api_key,
+         sessionId: session_id,
+         token: token,
+         initialBroadcastId: settings.broadcast_id,
+         focusStreamId: settings.focus_stream_id,
+         initialLayout: settings.broadcast_layout
+     }
+   end
+```
+
+This handler generates the three strings that the client (JavaScript) needs to connect
+to the session: `apiKey`, `sessionId`, and `token`. The `initialBroadcastId` is the broadcast ID,
+`focusStreamId` is the stream ID that has the current focus (if there is one), and
+`initialLayout` is the initial layout for the current broadcast in progress (if there is one).
+(We will discuss focus stream and broadcast layout below.)
+
+In the host page, the user presses the 'Start Broadcast' 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
+  post '/start' do
+     opts = {
+         :maxDuration => params.key?("maxDuration") ? params[:maxDuration] : 7200,
+         :resolution =>  params[:resolution],
+         :layout => params[:layout],
+         :outputs => {
+             :hls => {}
+         }
+     }
+     broadcast = settings.opentok.broadcasts.create(settings.session.session_id, opts)
+     settings.broadcast_id = broadcast.id
+     body broadcast.to_json
+  end
+```
+
+In this handler, `opentok.broadcasts.create` is called with the `session_id` for
+the OpenTok session to broadcast. The optional second argument is a hash which defines
+optional properties for the broadcast. It consists of `maxDuration` of the broadcast,
+`resolution`, and broadcast `layout`. This sample app starts an HLS broadcast (not RTMP),
+so it only specifies an `hls` property of the `outputs` property. See the
+[Ruby SDK documentation](https://github.com/opentok/OpenTok-Ruby-SDK) for information
+on adding RTMP broadcast 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 broadcasting to begin. The response sent back to the client’s XHR request
+will be the JSON representation of the broadcast, which is returned from the `to_json()` method. 
+
+You can view the HLS broadcast by opening the root URL (<http://localhost:4567/>) in
+a different tab and clicking the `Broadcast URL` button. The code for handling this is as follows:
+
+```ruby
+  get '/broadcast' do
+    return 'No broadcast id exists' if settings.broadcast_id.nil? || settings.broadcast_id.empty?
+    broadcast = settings.opentok.broadcasts.find settings.broadcast_id
+    redirect broadcast.broadcastUrls['hls'] if broadcast.status == 'started'
+ end
+```
+
+The route for Stop Broadcast has the following code:
+
+```ruby
+  get '/stop/:broadcastId' do
+    broadcast = settings.opentok.broadcasts.stop settings.broadcast_id
+    settings.broadcast_id = nil
+    settings.focus_stream_id = ''
+    settings.broadcast_layout = 'horizontalPresentation'
+    body broadcast.to_json
+  end
+```
+
+The settings revert backs to the settings when you start the app.
+
+The host page includes a `Toggle Layout` button, which toggles between
+`verticalPresentation` and `horizontalPresentation`.
+
+The route for `Toggle Layout` has the following code:
+
+```ruby
+   post '/broadcast/:broadcastId/layout' do
+     layoutType = params[:type]
+     settings.opentok.broadcasts.layout(settings.broadcast_id, type: layoutType)
+     settings.broadcast_layout = layoutType
+   end
+```
+
+This calls the `opentok.broadcasts.layout()` method, setting the broadcast layout to
+the layout type defined in the POST request's body. In this app, the layout type is
+set to `horizontalPresentation` or `verticalPresentation`, two of the [predefined layout
+types](https://tokbox.com/developer/guides/broadcast/live-streaming/#predefined-layout-types)
+available to live streaming broadcasts.
+
+### Creating Broadcast - Participant View
+
+With the host view still open and publishing, open an additional tab and navigate to
+<http://localhost:4567/participant> and allow the browser to use your camera and microphone.
+You will now see the participant in the broadcast.
+
+```ruby
+  get '/participant' do
+    api_key = settings.api_key
+    session_id = settings.session.session_id
+    token = settings.opentok.generate_token(session_id, role: :publisher)
+
+    erb :participant, locals: {
+        apiKey: api_key,
+        sessionId: session_id,
+        token: token,
+        focusStreamId: settings.focus_stream_id,
+        layout: settings.broadcast_layout
+    }
+  end
+```
+
+### Changing the layout classes for streams
+
+In the host page, if you click on either the host or a participant video, that video gets
+the `focus` layout in the broadcast. The host page sends the `focus` stream ID and
+the other streams' layout class lists can be cleared, as shown below:
+
+```ruby
+ post '/focus' do
+    hash = { items: [] }
+    hash[:items] << { id: params[:focus], layoutClassList: ['focus'] }
+    settings.focus_stream_id = params[:focus]
+    if params.key?('otherStreams')
+      params[:otherStreams].each do |stream|
+        hash[:items] << { id: stream, layoutClassList: [] }
+      end
+    end
+    settings.opentok.streams.layout(settings.session.session_id, hash)
+ end
+```
+
+The host client page also uses OpenTok signaling to notify other clients when the layout type and
+focus stream changes, and they then update the local display of streams in the HTML DOM accordingly.
+However, this is not necessary. The layout of the broadcast is unrelated to the layout of
+streams in the web clients.
+
+When you view the broadcast stream, the layout type and focus stream changes, based on calls
+to the `OpenTok.setBroadcastLayout()` and `OpenTok.setStreamClassLists()` methods during
+the broadcast.
+
+For more information, see [Configuring video layout for OpenTok live streaming
+broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts).

data/sample/Broadcast/broadcast_sample.rb

@@ -0,0 +1,97 @@
+require 'sinatra/base'
+require 'opentok'
+
+raise "You must define API_KEY and API_SECRET environment variables" unless ENV.has_key?("API_KEY") && ENV.has_key?("API_SECRET")
+
+class BroadcastSample < 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 :erb, :layout => :layout
+  set :broadcast_id, nil
+  set :focus_stream_id, ''
+  set :broadcast_layout, 'horizontalPresentation'
+
+  get '/' do
+    erb :index
+  end
+
+  get '/host' do
+    api_key = settings.api_key
+    session_id = settings.session.session_id
+    token = settings.opentok.generate_token(session_id, role: :publisher, initialLayoutClassList: ['focus'])
+
+    erb :host, locals: {
+        apiKey: api_key,
+        sessionId: session_id,
+        token: token,
+        initialBroadcastId: settings.broadcast_id,
+        focusStreamId: settings.focus_stream_id,
+        initialLayout: settings.broadcast_layout
+    }
+  end
+
+  get '/participant' do
+    api_key = settings.api_key
+    session_id = settings.session.session_id
+    token = settings.opentok.generate_token(session_id, role: :publisher)
+
+    erb :participant, locals: {
+        apiKey: api_key,
+        sessionId: session_id,
+        token: token,
+        focusStreamId: settings.focus_stream_id,
+        layout: settings.broadcast_layout
+    }
+  end
+
+  post '/start' do
+    opts = {
+        :maxDuration => params.key?("maxDuration") ? params[:maxDuration] : 7200,
+        :resolution =>  params[:resolution],
+        :layout => params[:layout],
+        :outputs => {
+            :hls => {}
+        }
+    }
+    broadcast = settings.opentok.broadcasts.create(settings.session.session_id, opts)
+    settings.broadcast_id = broadcast.id
+    body broadcast.to_json
+  end
+
+  get '/broadcast' do
+    return 'No broadcast id exists' if settings.broadcast_id.nil? || settings.broadcast_id.empty?
+    broadcast = settings.opentok.broadcasts.find settings.broadcast_id
+    redirect broadcast.broadcastUrls['hls'] if broadcast.status == 'started'
+  end
+
+  get '/stop/:broadcastId' do
+    broadcast = settings.opentok.broadcasts.stop settings.broadcast_id
+    settings.broadcast_id = nil
+    settings.focus_stream_id = ''
+    settings.broadcast_layout = 'horizontalPresentation'
+    body broadcast.to_json
+  end
+
+  post '/broadcast/:broadcastId/layout' do
+    layoutType = params[:type]
+    settings.opentok.broadcasts.layout(settings.broadcast_id, type: layoutType)
+    settings.broadcast_layout = layoutType
+  end
+
+  post '/focus' do
+    hash = { items: [] }
+    hash[:items] << { id: params[:focus], layoutClassList: ['focus'] }
+    settings.focus_stream_id = params[:focus]
+    if params.key?('otherStreams')
+      params[:otherStreams].each do |stream|
+        hash[:items] << { id: stream, layoutClassList: [] }
+      end
+    end
+    settings.opentok.streams.layout(settings.session.session_id, hash)
+  end
+
+  # start the server if ruby file executed directly
+  run! if app_file == $0
+end