opentok 3.0.3 → 4.1.1

data/lib/opentok/sip.rb

@@ -1,7 +1,40 @@
 require "opentok/client"
 
+# An object that lets you use the OpenTok SIP gateway.
 module OpenTok
   class Sip
+    # Dials a SIP gateway to input an audio-only stream into your OpenTok session.
+    # See the {https://tokbox.com/developer/guides/sip/ OpenTok SIP developer guide}.
+    #
+    # @example
+    #    opts = { "from" => "14155550101@example.com",
+    #      "auth" => { "username" => sip_username,
+    #        "password" => sip_password },
+    #      "headers" => { "X-KEY1" => "value1",
+    #        "X-KEY1" => "value2" },
+    #      "secure" => "true"
+    #    }
+    #    response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.example.com;transport=tls", opts)
+    # @param [String] session_id The session ID corresponding to the session to which
+    #   the SIP gateway will connect.
+    # @param [String] token The token for the session ID with which the SIP user
+    #   will use to connect.
+    # @param [String] sip_uri The SIP URI the OpenTok SIP gateway will dial.
+    # @param [Hash] opts A hash defining options for the SIP call. For example:
+    # @option opts [String] :from The number or string that will be sent to the final
+    #   SIP number as the caller. It must be a string in the form of "from@example.com",
+    #   where from can be a string or a number. If from is set to a number
+    #   (for example, "14155550101@example.com"), it will show up as the incoming
+    #   number on PSTN phones. If from is undefined or set to a string (for example,
+    #   "joe@example.com"), +00000000 will show up as the incoming number on
+    #   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.
+    # @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.
+    # @option opts  [true, false] :secure Wether the media must be transmitted
+    #   encrypted (​true​) or not (​false​, the default).
     def dial(session_id, token, sip_uri, opts)
       response = @client.dial(session_id, token, sip_uri, opts)
     end

data/lib/opentok/stream.rb

@@ -0,0 +1,46 @@
+require "active_support/inflector"
+
+module OpenTok
+  # Represents information about a stream in an OpenTok session.
+  #
+  # @attr [string] id
+  #   The stream ID.
+  #
+  # @attr [string] name
+  #   The name of the stream.
+
+  # @attr [string] videoType
+  #   The videoType property is either "camera" or "screen".
+  #
+  # @attr [array] layoutClassList
+  #   An array of the layout classes for the stream.
+  class Stream
+
+    # @private
+    def initialize(json)
+      # TODO: validate json fits schema
+      @json = json
+    end
+
+    # A JSON-encoded string representation of the stream.
+    def to_json
+      @json.to_json
+    end
+
+
+    # @private ignore
+    def method_missing(method, *args, &block)
+      camelized_method = method.to_s.camelize(:lower)
+      if @json.has_key? camelized_method and args.empty?
+        # TODO: convert create_time method call to a Time object
+        if camelized_method == 'outputMode'
+          @json[camelized_method].to_sym
+        else
+          @json[camelized_method]
+        end
+      else
+        super method, *args, &block
+      end
+    end
+  end
+end

data/lib/opentok/stream_list.rb

@@ -0,0 +1,18 @@
+require "opentok/stream"
+
+
+module OpenTok
+  # A class for accessing a list of Stream objects.
+  class StreamList < Array
+
+    # The total number streams.
+    attr_reader :total
+
+    # @private
+    def initialize(json)
+      @total = json['count']
+      super json['items'].map { |item| Stream.new item }
+    end
+
+  end
+end

data/lib/opentok/streams.rb

@@ -0,0 +1,79 @@
+require 'opentok/client'
+require 'opentok/stream'
+require 'opentok/stream_list'
+
+module OpenTok
+  # A class for working with OpenTok streams. It includes methods for getting info
+  # about OpenTok streams and for setting layout classes for streams.
+  class Streams
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Use this method to get information on an OpenTok stream.
+    #
+    # For example, you can call this method to get information about layout classes used by an OpenTok stream.
+    # The layout classes define how the stream is displayed in the layout of a broadcast stream.
+    # For more information, see {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @param [String] stream_id The stream ID within the session.
+    # @return [Stream] The Stream object.
+    # @raise [ArgumentError] stream_id or session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def find(session_id, stream_id)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      raise ArgumentError, 'stream_id not provided' if session_id.to_s.empty?
+      stream_json = @client.info_stream(session_id, stream_id)
+      Stream.new stream_json
+    end
+
+    # Use this method to get information on all OpenTok streams in a session.
+    #
+    # For example, you can call this method to get information about layout classes used by OpenTok streams.
+    # The layout classes define how the stream is displayed in the layout of a live streaming
+    # broadcast or a composed archive. For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @return [StreamList] The StreamList of Stream objects.
+    # @raise [ArgumentError] The stream_id or session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def all(session_id)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      response_json = @client.info_stream(session_id, '')
+      StreamList.new response_json
+    end
+
+    # Use this method to set the layout of a composed (archive or broadcast) OpenTok stream.
+    #
+    # For example, you can call this method to set the layout classes of an OpenTok stream.
+    # The layout classes define how the stream is displayed in the layout of a live streaming
+    # broadcast or a composed archive. For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @param [Hash] opts  A hash with one key <code>items</code> and value as array of objects having <code>stream_id</code> and <code>layoutClassList</code> properties.
+    # For more information, see Layout{https://tokbox.com/developer/rest/#change-stream-layout-classes-composed}
+    # @raise [ArgumentError] The session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokStreamLayoutError] The layout operation could not be performed due to incorrect layout values.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def layout(session_id, opts)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      raise ArgumentError, 'opts is empty' if opts.empty?
+      response = @client.layout_streams(session_id, opts)
+      (200..300).include? response.code
+    end
+
+  end
+end

data/lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '3.0.3'
+  VERSION = '4.1.1'
 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