Merge pull request #252 from opentok/dev

Version 4.5.0

Author: superchilled

CHANGES.md

@@ -1,3 +1,10 @@
+# 4.5.0
+
+* Adds support for multiple archives and records feature [#248](https://github.com/opentok/OpenTok-Ruby-SDK/pull/248)
+* Adds Experience Composer functionality [#249](https://github.com/opentok/OpenTok-Ruby-SDK/pull/249)
+* Updates code comments to make explicit support for 1080p resolution for Archive and Broadcast [#246](https://github.com/opentok/OpenTok-Ruby-SDK/pull/246)
+* Updates various other documentation/code comments [#250](https://github.com/opentok/OpenTok-Ruby-SDK/pull/250)
+
 # 4.4.0
 
 * Implements DVR Pause/Resume and HLS Low-Latency options for Broadcasts [#243](https://github.com/opentok/OpenTok-Ruby-SDK/pull/243)

README.md

@@ -1,24 +1,27 @@
 # OpenTok Ruby SDK
 
 ![Coverage Status](https://github.com/opentok/OpenTok-Ruby-SDK/workflows/CI/badge.svg)
-[![codecov](https://codecov.io/gh/opentok/OpenTok-Ruby-SDK/branch/master/graph/badge.svg)](https://codecov.io/gh/opentok/opentok-ruby-sdk) 
+[![codecov](https://codecov.io/gh/opentok/OpenTok-Ruby-SDK/branch/master/graph/badge.svg)](https://codecov.io/gh/opentok/opentok-ruby-sdk)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
 
 <img src="https://assets.tokbox.com/img/vonage/Vonage_VideoAPI_black.svg" height="48px" alt="Tokbox is now known as Vonage" />
 
-The OpenTok Ruby SDK lets you generate
-[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/).
+The OpenTok Ruby SDK provides methods for:
 
-# Installation
+* Generating [sessions](https://tokbox.com/developer/guides/create-session/) and
+  [tokens](https://tokbox.com/developer/guides/create-token/) for
+  [OpenTok](https://www.vonage.com/communications-apis/video/) applications
+* 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)
+* [Sending signals to clients connected to a session](https://tokbox.com/developer/guides/signaling/)
+* [Disconnecting clients from sessions](https://tokbox.com/developer/guides/moderation/rest/)
+* [Forcing clients in a session to disconnect or mute published audio](https://tokbox.com/developer/guides/moderation/)
+* Working with OpenTok [Experience Composers](https://tokbox.com/developer/guides/experience-composer)
 
-## Bundler (recommended):
+## Installation
+
+### Bundler (recommended):
 
 Bundler helps manage dependencies for Ruby projects. Find more info here: <http://bundler.io>
 
@@ -34,15 +37,15 @@ Allow bundler to install the change.
 $ bundle install
 ```
 
-## RubyGems:
+### RubyGems:
 
 ```
 $ gem install opentok
 ```
 
-# Usage
+## Usage
 
-## Initializing
+### Initializing
 
 Load the gem at the top of any file where it will be used. Then initialize an `OpenTok::OpenTok`
 object with your OpenTok API key and API secret.
@@ -53,7 +56,7 @@ require "opentok"
 opentok = OpenTok::OpenTok.new api_key, api_secret
 ```
 
-### Initialization Options
+#### Initialization Options
 
 You can specify a custom timeout value for HTTP requests when initializing a new `OpenTok::OpenTok`
 object:
@@ -67,7 +70,7 @@ opentok = OpenTok::OpenTok.new api_key, api_secret, :timeout_length => 10
 The value for `:timeout_length` is an integer representing the number of seconds to wait for an HTTP
 request to complete. The default is set to 2 seconds.
 
-## Creating Sessions
+### Creating Sessions
 
 To create an OpenTok Session, use the `OpenTok#create_session(properties)` method.
 The `properties` parameter is an optional Hash used to specify the following:
@@ -101,7 +104,7 @@ session = opentok.create_session :archive_mode => :always, :media_mode => :route
 session_id = session.session_id
 ```
 
-## Generating Tokens
+### Generating Tokens
 
 Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
 You can generate a token either by calling the `opentok.generate_token(session_id, options)` method,
@@ -111,7 +114,7 @@ the Token. For layout control in archives and broadcasts, the initial layout cla
 published from connections using this token can be set as well.
 
 ```ruby
-# Generate a Token from just a session_id (fetched from a database)
+## Generate a Token from just a session_id (fetched from a database)
 token = opentok.generate_token session_id
 
 # Generate a Token by calling the method on the Session (returned from createSession)
@@ -126,7 +129,7 @@ token = session.generate_token({
 });
 ```
 
-## Working with Streams
+### 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
@@ -152,7 +155,7 @@ expect(all_streams.total).to eq 2
 expect(all_streams[0].layoutClassList[1]).to eq "focus"
 ```
 
-## Working with Archives
+### Working with Archives
 
 You can only archive sessions that use the OpenTok Media Router
 (sessions with the media mode set to routed).
@@ -185,8 +188,7 @@ 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
+For composed archives you can set the resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait).. The `resolution` parameter is optional and could be included in the options
 hash (second argument) of the `opentok.archives.create()` method.
 
 ```ruby
@@ -316,9 +318,9 @@ 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.
+[OpenTok archiving](/developer/guides/archiving/) developer guide.
 
-## Signaling
+### Signaling
 
 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
@@ -343,16 +345,13 @@ 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
+### 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.
 
@@ -451,12 +450,25 @@ for more details.
 You can also change the layout of an individual stream dynamically. Refer to
 [working with Streams](#working-with-streams).
 
-## Force disconnect
+### 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
+### Forcing clients in a session to mute published audio
+
+You can force the publisher of a specific stream to stop publishing audio using the 
+`opentok.streams.force_mute(session_id, stream_id)` method.
+
+You can force the publisher of all streams in a session (except for an optional list of streams)
+to stop publishing audio using the `opentok.streams.force_mute_all(session_id, opts)`
+method. You can then disable the mute state of the session by calling the
+`opentok.streams.disable_force_mute(session_id)` method.
+
+For more information, see
+[Muting the audio of streams in a session](https://tokbox.com/developer/guides/moderation/#force_mute).
+
+### 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
@@ -473,7 +485,17 @@ response = opentok.sip.dial(session_id, token, "sip:[email protected]
 For more information on SIP Interconnect, see the
 [OpenTok SIP Interconnect](https://tokbox.com/developer/guides/sip/) developer guide.
 
-# Samples
+### Working with Experience Composers
+
+You can start an [Experience Composer](https://tokbox.com/developer/guides/experience-composer)
+by calling the `opentok.renders.start(session_id, options)` method.
+
+You can stop an Experience Composer by calling the `opentok.renders.stop(render_id, options)` method.
+
+You can get information about Experience Composers by calling the `opentok.renders.find(render_id)`
+and `opentok.renders.list(options)` methods.
+
+## Samples
 
 There are three sample applications included in this repository. To get going as fast as possible, clone the whole
 repository and read the README in each of the sample directories:
@@ -482,23 +504,23 @@ repository and read the README in each of the sample directories:
 - [Archiving](sample/Archiving/README.md)
 - [Broadcast](sample/Broadcast/README.md)
 
-# Documentation
+## Documentation
 
 Reference documentation is available at <http://www.tokbox.com//opentok/libraries/server/ruby/reference/index.html>.
 
-# Requirements
+## Requirements
 
 You need an OpenTok API key and API secret, which you can obtain by logging into your
 [Vonage Video API account](https://tokbox.com/account).
 
 The OpenTok Ruby SDK requires Ruby 2.1.0 or greater.
 
-# Release Notes
+## Release Notes
 
 See the [Releases](https://github.com/opentok/opentok-ruby-sdk/releases) page for details
 about each release.
 
-## Important changes since v2.2.0
+### Important changes since v2.2.0
 
 **Changes in v4.0.0:**
 
@@ -530,7 +552,7 @@ See the reference documentation
 <http://www.tokbox.com/opentok/libraries/server/ruby/reference/index.html> and in the
 docs directory of the SDK.
 
-# Development and Contributing
+## Development and Contributing
 
 Interested in contributing? We :heart: pull requests! See the [Development](DEVELOPING.md) and
 [Contribution](CONTRIBUTING.md) guidelines.

lib/opentok/archive.rb

@@ -34,7 +34,9 @@ module OpenTok
     #   reason the archive stopped (such as "maximum duration exceeded") or failed.
     #
     # @attr [string] resolution
-    #   The resolution of the archive (either "640x480", "1280x720", "480x640", or "720x1280").
+    #   The resolution of the archive, either "640x480" (SD landscape, the default), "1280x720" (HD landscape),
+    #  "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait).
+    #   You may want to use a portrait aspect ratio for archives that include video streams from mobile devices (which often use the portrait aspect ratio).
     #   This property is only set for composed archives.
     #
     # @attr [string] session_id
@@ -70,12 +72,13 @@ module OpenTok
     #   set to null. The download URL is obfuscated, and the file is only available from the URL for
     #   10 minutes. To generate a new URL, call the Archive.listArchives() or OpenTok.getArchive() method.
   class Archive
-
+    attr_reader :multi_archive_tag
     # @private
     def initialize(interface, json)
       @interface = interface
       # TODO: validate json fits schema
       @json = json
+      @multi_archive_tag = @json['multiArchiveTag']
     end
 
     # A JSON-encoded string representation of the archive.

lib/opentok/archives.rb

@@ -39,20 +39,28 @@ def initialize(client)
     #   (a video track is included). If you set both  <code>has_audio</code> and
     #   <code>has_video</code> to <code>false</code>, the call to the <code>create()</code>
     #   method results in an error.
+    # @option options [String] :multiArchiveTag (Optional) Set this to support recording multiple archives for the same session simultaneously. 
+    #    Set this to a unique string for each simultaneous archive of an ongoing session. You must also set this option when manually starting an archive 
+    #    that is {https://tokbox.com/developer/guides/archiving/#automatic automatically archived}. Note that the `multiArchiveTag` value is not included
+    #    in the response for the methods to {https://tokbox.com/developer/rest/#listing_archives list archives} and 
+    #    {https://tokbox.com/developer/rest/#retrieve_archive_info retrieve archive information}. If you do not specify a unique `multiArchiveTag`, 
+    #    you can only record one archive at a time for a given session. 
+    #    {https://tokbox.com/developer/guides/archiving/#simultaneous-archives See Simultaneous archives}.
     # @option options [String] :output_mode Whether all streams in the archive are recorded
     #     to a single file (<code>:composed</code>, the default) or to individual files
     #     (<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.
+    # @option options [String] :resolution The resolution of the archive, either "640x480" (SD landscape,
+    #  the default), "1280x720" (HD landscape), "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280"
+    #  (HD portrait), or "1080x1920" (FHD portrait). This property only applies to composed archives. If you set
+    #  this property and set the outputMode property to "individual", a call to the method
+    #  results in an error.
     # @option options [String] :streamMode (Optional) Whether streams included in the archive are selected
     #   automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"),
     #   all streams in the session can be included in the archive. When streams are selected manually ("manual"),
     #   you specify streams to be included based on calls to the {Archives#add_stream} method. You can specify whether a
-    #   stream's audio, video, or both are included in the archive. 
+    #   stream's audio, video, or both are included in the archive.
     #   In composed archives, in both automatic and manual modes, the archive composer includes streams based
     #   on {https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules stream prioritization rules}.
     #   Important: this feature is currently available in the Standard environment only.

lib/opentok/broadcast.rb

@@ -20,7 +20,10 @@ module OpenTok
   #   For this start method, this timestamp matches the createdAt timestamp.
   #
   # @attr [string] resolution
-  #   The resolution of the broadcast: either "640x480" (SD, the default) or "1280x720" (HD). This property is optional.
+  #   The resolution of the broadcast: either "640x480" (SD landscape, the default), "1280x720" (HD landscape),
+  #   "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920" (FHD portrait).
+  #   You may want to use a portrait aspect ratio for broadcasts that include video streams from mobile devices (which often use the portrait aspect ratio).
+  #   This property is optional.
   #
   # @attr [string] streamMode
   #   Whether streams included in the broadcast are selected automatically ("auto", the default) or manually ("manual").
@@ -43,12 +46,13 @@ module OpenTok
   #     * "offline" --     The OpenTok platform could not connect to the remote RTMP server. This is due to an unreachable server or an error in the RTMP handshake. Causes include rejected RTMP connections, non-existing RTMP applications, rejected stream names, authentication errors, etc. Check that the server is online, and that you have provided the correct server URL and stream name.
   #     * "error" --       There is an error in the OpenTok platform.
   class Broadcast
-
+    attr_reader :multi_broadcast_tag
     # @private
     def initialize(interface, json)
       @interface = interface
       # TODO: validate json fits schema
       @json = json
+      @multi_broadcast_tag = @json['multiBroadcastTag']
     end
 
     # A JSON-encoded string representation of the broadcast.

lib/opentok/broadcasts.rb

@@ -37,6 +37,12 @@ def initialize(client)
     #   If you do not specify an initial layout type, the broadcast uses the best fit
     #   layout type.
     #
+    # @option options [String] :multiBroadcastTag (Optional) Set this to support multiple broadcasts for the same session simultaneously. 
+    #   Set this to a unique string for each simultaneous broadcast of an ongoing session. Note that the `multiBroadcastTag` value is *not* included 
+    #   in the response for the methods to {https://tokbox.com/developer/rest/#list_broadcasts list live streaming broadcasts} and 
+    #   {https://tokbox.com/developer/rest/#get_info_broadcast get information about a live streaming broadcast}. 
+    #   {https://tokbox.com/developer/guides/broadcast/live-streaming#simultaneous-broadcasts See Simultaneous broadcasts}.
+    #
     # @option options [int] maxDuration
     #   The maximum duration for the broadcast, in seconds. The broadcast will automatically stop when
     #   the maximum duration is reached. You can set the maximum duration to a value from 60 (60 seconds) to 36000 (10 hours).
@@ -75,7 +81,9 @@ def initialize(client)
     #  Broadcasts#find method.
     #
     # @option options [string] resolution
-    #   The resolution of the broadcast: either "640x480" (SD, the default) or "1280x720" (HD).
+    #   The resolution of the broadcast: either "640x480" (SD landscape, the default), "1280x720" (HD landscape),
+    #   "1920x1080" (FHD landscape), "480x640" (SD portrait), "720x1280" (HD portrait), or "1080x1920"
+    #   (FHD portrait).
     #
     # @option options [String] :streamMode (Optional) Whether streams included in the broadcast are selected
     #   automatically ("auto", the default) or manually ("manual"). When streams are selected automatically ("auto"),