opentok 3.0.3 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 679a364a592829ee29acad18146e680f82d2a3de
-  data.tar.gz: 1d822425e30d6aa05e41768348fd9863b85677a4
+  metadata.gz: 4baddcff5e72cad62caf5c0046c8a2eb3cc375b3
+  data.tar.gz: 59b84a91a65d5841f76f4251a26ea99739386117
 SHA512:
-  metadata.gz: 0e0fdf3a74c811f22c535c1829eb9109ce7f8e2c45ab711796ee97a5891658aa2ab3d5625f9ddf953ddcbb27241ddb339261fec7d5321145ed012469cc896a1f
-  data.tar.gz: '0741182e612a82221688abda4226a5138e1051a47ad5d0f8a3e59005461935a2af711ba338721d37d2a42954e4113f43733ec2cbfca0c0a0ee77d83222701319'
+  metadata.gz: 5bdaf9b065a6e5449b9753d42e3fd906e9afa66635d71b74ae0f2965bc34e138de2a253f4707d0bbbe3fe972584db3f9f235129c55ec1dfb09b4669ef2de0eb1
+  data.tar.gz: ad070ca9e3e516b96c9cbd8aff45ccd9b1f593f657688f8b1c90894c1b72bcb5c9dc53ccea0d19c7ef7d813951645709a6daa3855362625bd3e976be87118f80

data/README.md

@@ -3,10 +3,14 @@
 [![Build Status](https://travis-ci.org/opentok/OpenTok-Ruby-SDK.png)](https://travis-ci.org/opentok/OpenTok-Ruby-SDK)
 
 The OpenTok Ruby SDK lets you generate
-[sessions](http://www.tokbox.com/opentok/tutorials/create-session/) and
-[tokens](http://www.tokbox.com/opentok/tutorials/create-token/) for
-[OpenTok](http://www.tokbox.com/) applications, and
-[archive](https://tokbox.com/opentok/tutorials/archiving) OpenTok sessions.
+[sessions](https://tokbox.com/developer/guides/create-session/) and
+[tokens](https://tokbox.com/developer/guides/create-token/) for
+[OpenTok](http://www.tokbox.com/) applications. It also includes methods for
+working with OpenTok [archives](https://tokbox.com/developer/guides/archiving),
+working with OpenTok [live streaming
+broadcasts](https://tokbox.com/developer/guides/broadcast/live-streaming/),
+working with OpenTok [SIP interconnect](https://tokbox.com/developer/guides/sip),
+and [disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/).
 
 # Installation
 
@@ -17,7 +21,7 @@ Bundler helps manage dependencies for Ruby projects. Find more info here: <http:
 Add this gem to your `Gemfile`:
 
 ```ruby
-gem "opentok", "~> 3.0.3"
+gem "opentok", "~> 3.1.0"
 ```
 
 Allow bundler to install the change.
@@ -47,11 +51,19 @@ opentok = OpenTok::OpenTok.new api_key, api_secret
 
 ## Creating Sessions
 
-To create an OpenTok Session, use the `OpenTok#create_session(properties)` method. The
-`properties` parameter is an optional Hash used to specify whether you are creating a session that
-uses the OpenTok Media Server and specifying a location hint. The `session_id` method of the
-returned `OpenTok::Session` instance is useful to get a sessionId that can be saved to a persistent
-store (e.g. database).
+To create an OpenTok Session, use the `OpenTok#create_session(properties)` method.
+The `properties` parameter is an optional Hash used to specify the following:
+
+* Whether the session uses the [OpenTok Media
+  Router](https://tokbox.com/developer/guides/create-session/#media-mode),
+  which is required for some OpenTok features (such as archiving)
+
+* A location hint for the OpenTok server.
+
+* Whether the session is automatically archived.
+
+The `session_id` method of the returned `OpenTok::Session` instance is useful to
+get a sessionId that can be saved to a persistent store (such as a database).
 
 ```ruby
 # Create a session that will attempt to transmit streams directly between clients.
@@ -96,8 +108,37 @@ token = session.generate_token({
 });
 ```
 
+## Working with Streams 
+
+Use this method to get information for an OpenTok stream or for all streams in a session.
+For example, you can call this method to get information about layout classes used by an
+OpenTok stream. 
+
+To get information of a specific stream in a session, call
+`opentok.streams.find(session_id, stream_id)`. The return object is a `Stream` object and
+you can access various stream properties as shown in the following example (using RSpec notations):
+
+```ruby
+expect(stream).to be_an_instance_of OpenTok::Stream
+expect(stream.videoType).to eq 'camera'
+expect(stream.layoutClassList.count).to eq 1
+expect(stream.layoutClassList.first).to eq "full"
+```
+
+To get information on all streams in a session, call `opentok.streams.all(session_id)`.
+The return value is a `StreamList` object:
+
+```ruby
+expect(all_streams).to be_an_instance_of OpenTok::StreamList
+expect(all_streams.total).to eq 2
+expect(all_streams[0].layoutClassList[1]).to eq "focus"
+```
+
 ## Working with Archives
 
+You can only archive sessions that use the OpenTok Media Router
+(sessions with the media mode set to routed).
+
 You can start the recording of an OpenTok Session using the `opentok.archives.create(session_id,
 options)` method. This will return an `OpenTok::Archive` instance. The parameter `options` is an
 optional Hash used to set the `has_audio`, `has_video`, and `name` options. Note that you can
@@ -127,6 +168,19 @@ archive = opentok.archives.create session_id :output_mode => :individual
 The `:output_mode => :composed` setting (the default) causes all streams in the archive to be
 recorded to a single (composed) file.
 
+For composed archives you can set the resolution of the archive, either "640x480" (SD, the default)
+or "1280x720" (HD). The `resolution` parameter is optional and could be included in the options
+hash (second argument) of the `opentok.archives.create()` method. 
+
+```ruby
+opts = {
+    :output_mode => :composed,
+    :resolution => "1280x720"
+}
+
+archive = opentok.archives.create session_id, opts
+```
+
 You can stop the recording of a started Archive using the `opentok.archives.stop_by_id(archive_id)`
 method. You can also do this using the `Archive#stop()` method.
 
@@ -175,14 +229,194 @@ Note that you can also create an automatically archived session, by passing in `
 as the `:archive_mode` property of the `options` parameter passed into the
 `OpenTok#create_session()` method (see "Creating Sessions," above).
 
+You can set the [layout](https://tokbox.com/developer/rest/#change_composed_archive_layout) of an archive:
+
+```ruby
+opts = { :type => "verticalPresentation" }
+opentok.archives.layout(archive_id, opts)
+```
+
+The hash `opts` has two entries:
+
+* The `type` is the layout type for the archive.  Valid values 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 `stylesheet` property. 
+  (For other layout types, do not set the stylesheet property.) 
+
+See [Customizing the video layout for composed archives](https://tokbox.com/developer/guides/archiving/layout-control.html)
+for more details. 
+
+You can set the initial layout class for a client's streams by setting the layout option when you
+create the token for the client, using the `opentok.generate_token` method. And you can also change
+the layout classes of a stream as follows:
+
+```ruby
+streams_list = {
+    :items => [
+        {
+            :id => "8b732909-0a06-46a2-8ea8-074e64d43422",
+            :layoutClassList => ["full"]
+        },
+        {
+            :id => "8b732909-0a06-46a2-8ea8-074e64d43423",
+            :layoutClassList => ["full", "focus"]
+        }
+    ]
+}
+response = opentok.streams.layout(session_id, streams_list)
+```
+
+For more information on setting stream layout classes, see the
+[Changing the composed archive layout classes for an OpenTok
+stream](https://tokbox.com/developer/rest/#change-stream-layout-classes-composed).
+
+Please keep in mind that the `streams.layout` method applies to archive and broadcast streams only. 
+
 For more information on archiving, see the
 [OpenTok archiving](https://tokbox.com/opentok/tutorials/archiving/) programming guide.
 
+## Signaling
 
-## Initiating a SIP call
+You can send a signal using the `opentok.signals.send(session_id, connection_id, opts)` method.  
+If `connection_id` is nil or an empty string, then the signal is send to all valid connections in
+the session. 
+
+An example of `opts` field can be as follows:
+
+```ruby
+opts = { :type => "chat",
+         :data => "Hello"
+}
+```
+
+The maximum length of the `type` string is 128 bytes, and it must contain only letters
+(A-Z and a-z), numbers (0-9), '-', '_', and '~'.
+
+The `data` string must not exceed the maximum size (8 kB).
+
+The `connection_id` and `opts` parameter are jointly optional by default. Hence you can also 
+use `opentok.signals.send(session_id)`
+
+For more information on signaling, see the
+[OpenTok Signaling](https://tokbox.com/developer/guides/signaling/js/) programming guide.
+
+## Broadcasting
+
+You can broadcast your streams to a HLS or RTMP servers.
+
+To successfully start broadcasting a session, at least one publishing client must be connected to
+the session.
+
+You can only have one active live streaming broadcast at a time for a session (however, having more
+than one would not be useful). 
+
+The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simultaneously
+for a session. 
+
+You can only start live streaming for sessions that use the OpenTok Media Router (with the
+media mode set to routed). You cannot use live streaming with sessions that have the media mode set
+to relayed.
+
+To create a HLS only broadcast:
+```ruby
+opts = {
+  :outputs => {
+      :hls => {}
+  }
+}
+broadcast = opentok.broadcasts.create(session_id, opts)
+
+# HLS + RTMP
+opts = {
+   :outputs => {
+       :hls => {},
+       :rtmp => [
+           {
+               :id => "myOpentokStream",
+               :serverUrl => "rtmp://x.rtmp.youtube.com/live123",
+               :streamName => "66c9-jwuh-pquf-9x00"
+           }
+       ]
+   }
+}
+broadcast = opentok.broadcasts.create(session_id, opts)
+```
+
+The returned Broadcast object has information about the broadcast, like id, sessionId , projectId,
+createdAt, updatedAt, resolution, status, and a Hash of broadcastUrls. The broadcastUrls 
+consists of an HLS URL and an array of RTMP objects. The RTMP objects resembles the `rtmp` value
+in `opts` in the example above. 
+
+For more information on broadcast, see the
+[OpenTok Broadcast guide](https://tokbox.com/developer/rest/#start_broadcast) programming guide.
 
-You can initiate a SIP call using the `opentok.sip.dial(session_id, token, sip_uri, opts)` method.  This requires a SIP url. You will often need to pass options for authenticating to the SIP provider and specifying encrypted session establishment.
+To get information about a broadcast stream 
+```ruby
+my_broadcast = opentok.broadcasts.find broadcast_id
+```
+The Broadcast object returned has properties describing the broadcast, like id, sessionId,
+projectId, createdAt, updatedAt, resolution, status, and a Hash of broadcastUrls. The broadcastUrls 
+consists of an HLS URL and an array of RTMP objects. The RTMP objects resembles the `rtmp` value
+in `opts` in the example above. 
+
+To stop a broadcast:
+
+```ruby
+ my_broadcast = opentok.broadcasts.stop broadcast_id
+ 
+ # stop at a broadcast object level too
+ # 
+ my_broadcast = opentok.broadcasts.find broadcast_id
+ ret_broadcast =  my_broadcast.stop
+ 
+ # Both the above returned objects has the "broadcastUrls" property as a nil value and the status 
+ # property value is "stopped"
+```
+
+
+To change the layout of a broadcast dynamically 
+```ruby
+opentok.broadcasts.layout(started_broadcast_id, {
+        :type => "verticalPresentation"
+    })
+    
+  # On an object level
+   my_broadcast = opentok.broadcasts.find broadcast_id
+   my_broadcast.layout(
+             :type => 'pip',
+             )
+
+   # the returned value is true if successful
+```
+
+The hash above has two entries.
+
+* The `type` is the layout type for the archive. Valid values 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 `stylesheet` property.  (For other layout types,
+  do not set the stylesheet property.) 
+
+Refer to [Customizing the video layout for composed
+archives](https://tokbox.com/developer/guides/archiving/layout-control.html)
+for more details. 
+
+You can also change the layout of an individual stream dynamically. Refer to
+[working with Streams](#working-with-streams).
+
+## Force disconnect 
+
+You can cause a client to be forced to disconnect from a session by using the
+`opentok.connections.forceDisconnect(session_id, connection_id)` method.
+
+## Initiating a SIP call
 
+You can initiate a SIP call using the `opentok.sip.dial(session_id, token, sip_uri, opts)` method. 
+This requires a SIP URL. You will often need to pass options for authenticating to the SIP provider
+and specifying encrypted session establishment.
 
 ```ruby
 opts = { "auth" => { "username" => sip_username,
@@ -193,7 +427,7 @@ response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.examp
 ```
 
 For more information on SIP Interconnect, see the
-[OpenTok SIP Interconnect](https://tokbox.com/developer/guides/sip/) programming guide.
+[OpenTok SIP Interconnect](https://tokbox.com/developer/guides/sip/) developer guide.
 
 
 # Samples
@@ -210,7 +444,8 @@ Reference documentation is available at <http://www.tokbox.com//opentok/librarie
 
 # Requirements
 
-You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
+You need an OpenTok API key and API secret, which you can obtain by logging into your
+[TokBox account](https://tokbox.com/account).
 
 The OpenTok Ruby SDK requires Ruby 1.9.3 or greater.
 

data/lib/opentok/archive.rb

@@ -54,8 +54,8 @@ module OpenTok
     #   * "started" -- The archive started and is in the process of being recorded.
     #   * "stopped" -- The archive stopped recording.
     #   * "uploaded" -- The archive is available for download from the the upload target
-    #     Amazon S3 bucket or Windows Azure container you set at the OpenTok dashboard
-    #     (https://dashboard.tokbox.com).
+    #     Amazon S3 bucket or Windows Azure container you set for your
+    #     {https://tokbox.com/account OpenTok project}.
     #
     # @attr [string] url
     #   The download URL of the available MP4 file. This is only set for an archive with the status set to
@@ -71,14 +71,14 @@ module OpenTok
       @json = json
     end
 
-    # A JSON encoded string representation of the archive
+    # A JSON-encoded string representation of the archive.
     def to_json
       @json.to_json
     end
 
     # Stops an OpenTok archive that is being recorded.
     #
-    # Archives automatically stop recording after 90 minutes or when all clients have disconnected
+    # Archives automatically stop recording after 120 minutes or when all clients have disconnected
     # from the session being archived.
     def stop
       # TODO: validate returned json fits schema
@@ -95,6 +95,47 @@ module OpenTok
       @json = @interface.delete_by_id @json['id']
     end
 
+    # Sets the layout type for a composed archive. For a description of layout types, see
+    # {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing
+    # the video layout for composed archives}.
+    #
+    # @option options [String] :type 
+    #   The layout type. Set this to "bestFit", "pip", "verticalPresentation",
+    #   "horizontalPresentation", "focus", or "custom".
+    #
+    # @option options [String] :stylesheet
+    #   The stylesheet for a custom layout. Set this parameter
+    #   if you set <code>type</code> to <code>"custom"</code>. Otherwise, leave it undefined.
+    #
+    # @raise [ArgumentError] The archive_id or options parameter is empty. Or the "custom"
+    #   type was specified without a stylesheet option. Or a stylesheet was passed in for a
+    #   type other than custom. Or an invalid type was passed in.
+    #
+    # @raise [OpenTokAuthenticationError]
+    #   Authentication failed.
+    #
+    # @raise [ArgumentError]
+    #   The archive_id or options parameter is empty.
+    #
+    # @raise [ArgumentError]
+    #   The "custom" type was specified without a stylesheet option.
+    #
+    # @raise [ArgumentError]
+    #   A stylesheet was passed in for a type other than custom. Or an invalid type was passed in.
+    #
+    # @raise [ArgumentError]
+    #   An invalid layout type was passed in.
+    #
+    # @raise [OpenTokError]
+    #   OpenTok server error.
+    #
+    # @raise [OpenTokArchiveError]
+    #   Setting the layout failed.
+    def layout(opts= {})
+      # TODO: validate returned json fits schema
+      @json = @interface.layout(@json['id'], opts)
+    end
+
     # @private ignore
     def method_missing(method, *args, &block)
       camelized_method = method.to_s.camelize(:lower)

data/lib/opentok/archives.rb

@@ -24,8 +24,8 @@ module OpenTok
     # {https://tokbox.com/opentok/tutorials/archiving OpenTok archiving} programming guide.
     #
     # @param [String] session_id The session ID of the OpenTok session to archive.
-    # @param [Hash] options  A hash with the key 'name', 'has_audio', and 'has_video' (or
-    # :name.
+    # @param [Hash] options  A hash with the keys 'name', 'has_audio', 'has_video',
+    #   and 'output_mode'.
     # @option options [String] :name This is the name of the archive. You can use this name
     #   to identify the archive. It is a property of the Archive object, and it is a property
     #   of archive-related events in the OpenTok client SDKs.
@@ -44,6 +44,10 @@ module OpenTok
     #     (<code>:individual</code>). For more information on archiving and the archive file
     #     formats, see the {https://tokbox.com/opentok/tutorials/archiving OpenTok archiving}
     #     programming guide.
+    # @option options [String] :resolution The resolution of the archive, either "640x480" (SD, the
+    #   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.
     #
     # @return [Archive] The Archive object, which includes properties defining the archive,
     #   including the archive ID.
@@ -58,9 +62,11 @@ module OpenTok
     # @raise [OpenTokArchiveError] The archive could not be started.
     def create(session_id, options = {})
       raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
+      raise ArgumentError,
+        "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 ]
+      valid_opts = [ :name, :has_audio, :has_video, :output_mode, :resolution ]
       opts = options.inject({}) do |m,(k,v)|
         if valid_opts.include? k.to_sym
           m[k.to_sym] = v
@@ -97,7 +103,7 @@ module OpenTok
     # @option options [integer] :count Optional. The number of archives to be returned. The maximum
     #   number of archives returned is 1000.
     # @option options [String] :session_id Optional. The session ID that archives belong to. This is
-    #   useful when listing multiple archives for an {https://tokbox.com/developer/guides/archiving/#automatic-archives automatically archived session}
+    #   useful when listing multiple archives for an {https://tokbox.com/developer/guides/archiving/#automatic-archives automatically archived session}.
     #
     # @return [ArchiveList] An ArchiveList object, which is an array of Archive objects.
     def all(options = {})
@@ -108,7 +114,7 @@ module OpenTok
 
     # Stops an OpenTok archive that is being recorded.
     #
-    # Archives automatically stop recording after 90 minutes or when all clients have disconnected
+    # Archives automatically stop recording after 120 minutes or when all clients have disconnected
     # from the session being archived.
     #
     # @param [String] archive_id The archive ID of the archive you want to stop recording.
@@ -146,5 +152,56 @@ module OpenTok
       (200..300).include? response.code
     end
 
+    # Sets the layout type for a composed archive. For a description of layout types, see
+    # {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing
+    # the video layout for composed archives}.
+    #
+    # @param [String] archive_id 
+    #   The archive ID.
+    #
+    # @option options [String] :type 
+    #   The layout type. Set this to "bestFit", "pip", "verticalPresentation",
+    #   "horizontalPresentation", "focus", or "custom".
+    #
+    # @option options [String] :stylesheet
+    #   The stylesheet for a custom layout. Set this parameter
+    #   if you set <code>type</code> to <code>"custom"</code>. Otherwise, leave it undefined.
+    #
+    # @raise [ArgumentError]
+    #   The archive_id or options parameter is empty. Or the "custom"
+    #   type was specified without a stylesheet option. Or a stylesheet was passed in for a
+    #   type other than custom. Or an invalid type was passed in.
+    #
+    # @raise [OpenTokAuthenticationError]
+    #   Authentication failed.
+    #
+    # @raise [ArgumentError]
+    #   The archive_id or options parameter is empty.
+    #
+    # @raise [ArgumentError]
+    #   The "custom" type was specified without a stylesheet option.
+    #
+    # @raise [ArgumentError]
+    #   A stylesheet was passed in for a type other than custom. Or an invalid type was passed in.
+    #
+    # @raise [ArgumentError]
+    #   An invalid layout type was passed in.
+    #
+    # @raise [OpenTokError]
+    #   OpenTok server error.
+    #
+    # @raise [OpenTokArchiveError]
+    #   Setting the layout failed.
+    def layout(archive_id, options = {})
+      raise ArgumentError, "option parameter is empty" if options.empty?
+      raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
+      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 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
+    end
   end
 end