Merge pull request #243 from opentok/devx-5926-devx-5937-hls-ll-and-dvr

DEVX-5926 and DEVX-5937 Add dvr and lowlatency options for HLS Broadcasts

README.md

@@ -489,7 +489,7 @@ 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 by logging into your
-[TokBox account](https://tokbox.com/account).
+[Vonage Video API account](https://tokbox.com/account).
 
 The OpenTok Ruby SDK requires Ruby 2.1.0 or greater.
 

lib/opentok/archives.rb

@@ -51,11 +51,10 @@ def initialize(client)
     # @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 this REST method
-    #   { https://tokbox.com/developer/rest/#selecting-archive-streams }. You can specify whether a
+    #   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. 
     #   In composed archives, in both automatic and manual modes, the archive composer includes streams based
-    #   on stream prioritization rules { https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules }.
+    #   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.
     # @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 three keys:

lib/opentok/broadcasts.rb

@@ -42,27 +42,49 @@ def initialize(client)
     #   the maximum duration is reached. You can set the maximum duration to a value from 60 (60 seconds) to 36000 (10 hours).
     #   The default maximum duration is 4 hours (14,400 seconds).
     #
-    # @option options [Hash] outputs
+    # @option options [Hash] outputs (Required)
     #   This object defines the types of broadcast streams you want to start (both HLS and RTMP).
     #   You can include HLS, RTMP, or both as broadcast streams. If you include RTMP streaming,
     #   you can specify up to five target RTMP streams (or just one).
-    #   The (<code>:hls</code>) property is set  to an empty [Hash] object. The HLS URL is returned in the response.
-    #   The (<code>:rtmp</code>)  property is set  to an [Array] of Rtmp [Hash] properties.
-    #   For each RTMP , specify (<code>:serverUrl</code>) for the RTMP server URL,
+    #
+    #   For multiple RTMP streams, the (<code>:rtmp</code>) property is set to an [Array] of Rtmp [Hash] objects.
+    #   For each RTMP hash, specify (<code>:serverUrl</code>) for the RTMP server URL,
     #   (<code>:streamName</code>) such as the YouTube Live stream name or the Facebook stream key),
-    #   and (optionally) (<code>:id</code>), a unique ID for the stream.
+    #   and (optionally) (<code>:id</code>), a unique ID for the stream. If you specify an ID, it will be
+    #   included in the (<code>broadcast_json</code>) response from the Client#start_broadcast method call,
+    #   and is also available in the (<code>broadcast_json</code>) response from the Broadcasts#find method.
+    #   Vonage streams the session to each RTMP URL you specify. Note that OpenTok live streaming
+    #   supports RTMP and RTMPS.
+    #   If you need to support only one RTMP URL, you can set a Rtmp [Hash] object (instead of an array of
+    #   objects) for the (<code>:rtmp</code>) property value in the (<code>:outputs</code>) [Hash].
+    #
+    #   For HLS, the (<code>:hls</code>) property in the (<code>:outputs</code>) [Hash] is set to a HLS [Hash]
+    #   object. This object includes the following optional properties:
+    #   - (<code>:dvr</code>) (Boolean).  Whether to enable
+    #     {https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr DVR functionality}
+    #     (rewinding, pausing, and resuming)
+    #     in players that support it (true), or not (false, the default). With DVR enabled, the HLS URL will
+    #     include a ?DVR query string appended to the end.
+    #   - (<code>:low_latency</code>) (Boolean). Whether to enable
+    #     {https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency low-latency mode}
+    #     for the HLSstream.
+    #     Some HLS players do not support low-latency mode. This feature is incompatible with DVR mode HLS
+    #     broadcasts (both can't be set to true). This is a beta feature.
+    #   The HLS URL is included in the (<code>broadcast_json</code>) response from the Client#start_broadcast
+    #   method call, and is also available in the (<code>broadcast_json</code>) response from the
+    #  Broadcasts#find method.
     #
     # @option options [string] resolution
     #   The resolution of the broadcast: either "640x480" (SD, the default) or "1280x720" (HD).
     #
     # @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"),
     #   all streams in the session can be included in the broadcast. When streams are selected manually ("manual"),
-    #   you specify streams to be included based on calls to this REST method
-    #   { https://tokbox.com/developer/rest/#selecting-broadcast-streams }. You can specify whether a
+    #   you specify streams to be included based on calls to the
+    #   {Broadcasts#add_stream} method. You can specify whether a
     #   stream's audio, video, or both are included in the broadcast.
     #   For both automatic and manual modes, the broadcast composer includes streams based
-    #   on stream prioritization rules { https://tokbox.com/developer/guides/archive-broadcast-layout/#stream-prioritization-rules }.
+    #   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.
     #
     # @return [Broadcast] The broadcast object, which includes properties defining the broadcast,
@@ -75,6 +97,13 @@ def initialize(client)
     def create(session_id, options = {})
       raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
       raise ArgumentError, "options cannot be empty" if options.empty?
+      raise ArgumentError, "outputs property is required in options" unless options.has_key?(:outputs)
+      raise ArgumentError, "outputs must be a Hash" unless options[:outputs].is_a? Hash
+      if options[:outputs].has_key?(:hls)
+        dvr = options[:outputs][:hls][:dvr]
+        low_latency = options[:outputs][:hls][:low_latency]
+        raise ArgumentError, "dvr and low_latency can't both be true for HLS" if hls_dvr_and_low_latency_options_both_true?(dvr, low_latency)
+      end
       broadcast_json = @client.start_broadcast(session_id, options)
       Broadcast.new self, broadcast_json
     end
@@ -263,5 +292,9 @@ def audio_and_video_options_both_false?(has_audio, has_video)
       has_audio == false && has_video == false
     end
 
+    def hls_dvr_and_low_latency_options_both_true?(dvr, low_latency)
+      dvr == true && low_latency == true
+    end
+
   end
 end

lib/opentok/opentok.rb

@@ -42,9 +42,9 @@ module OpenTok
   #       streams, and signal. (This is the default value if you do not specify a role.)
   #
   #     * <code>:moderator</code> -- In addition to the privileges granted to a
-  #      publisher, a moderator can perform moderation functions, such as forcing clients
-  #      to disconnect, to stop publishing streams, or to mute audio in published streams. See the
-  #      {https://tokbox.com/developer/guides/moderation/ Moderation developer guide}.
+  #       publisher, a moderator can perform moderation functions, such as forcing clients
+  #       to disconnect, to stop publishing streams, or to mute audio in published streams. See the
+  #       {https://tokbox.com/developer/guides/moderation/ Moderation developer guide}.
   #   @option options [integer] :expire_time The expiration time, in seconds since the UNIX epoch.
   #     Pass in 0 to use the default expiration time of 24 hours after the token creation time.
   #     The maximum expiration time is 30 days after the creation time.
@@ -77,8 +77,8 @@ class OpenTok
     # @param [String] api_key The OpenTok API key for your
     #   {https://tokbox.com/account OpenTok project}.
     # @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] :api_url Do not set this parameter. It is for internal use by Vonage.
+    # @option opts [Symbol] :ua_addendum Do not set this parameter. It is for internal use by Vonage.
     # @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()

lib/opentok/streams.rb

@@ -92,18 +92,16 @@ def force_mute(session_id, stream_id)
     # by calling the disable_force_mute() method.
     #
     # @param [String] session_id The session ID.
-    # @param [Hash] opts An optional hash defining options for muting action. For example:
+    # @param [Hash] opts An optional hash defining options for the muting action. For example:
+    #   {
+    #     "excluded_streams" => [
+    #       "excludedStreamId1",
+    #       "excludedStreamId2"
+    #     ]
+    #   }
     # @option opts [Array] :excluded_streams The stream IDs for streams that should not be muted.
     # This is an optional property. If you omit this property, all streams in the session will be muted.
     #
-    # @example
-    # {
-    #   "excluded_streams" => [
-    #     "excludedStreamId1",
-    #     "excludedStreamId2"
-    #   ]
-    # }
-    #
     def force_mute_all(session_id, opts = {})
       opts['active'] = 'true'
       response = @client.force_mute_session(session_id, opts)

lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '4.3.0'
+  VERSION = '4.4.0'
 end

spec/opentok/broadcasts_spec.rb

@@ -45,6 +45,22 @@
       broadcast.create(nil, {})
     }.to raise_error(ArgumentError)
   end
+  it 'raises an error if outputs is not set in options' do
+    opts = { maxDuration: 5400 }
+    expect { broadcast.create(nil, opts) }.to raise_error(ArgumentError)
+  end
+  it 'raises an error if outputs is set in options but is not a Hash' do
+    opts = { outputs: [] }
+    expect { broadcast.create(nil, opts) }.to raise_error(ArgumentError)
+  end
+  it 'raises an error if an HLS Broadcast object has both dvr and low_latency options set to true' do
+    opts = {
+      outputs: {
+        hls: { dvr: true, low_latency: true}
+      }
+    }
+    expect { broadcast.create(nil, opts) }.to raise_error(ArgumentError)
+  end
   it 'fetches a hls broadcast url', :vcr => { :erb => { :version => OpenTok::VERSION + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"} } do
     opts = {
         :outputs => {