diff --git a/README.md b/README.md index b1e44bc..d97975d 100644 --- a/README.md +++ b/README.md @@ -489,7 +489,7 @@ Reference documentation is available at :hls) property is set to an empty [Hash] object. The HLS URL is returned in the response. - # The (:rtmp) property is set to an [Array] of Rtmp [Hash] properties. - # For each RTMP , specify (:serverUrl) for the RTMP server URL, + # + # For multiple RTMP streams, the (:rtmp) property is set to an [Array] of Rtmp [Hash] objects. + # For each RTMP hash, specify (:serverUrl) for the RTMP server URL, # (:streamName) such as the YouTube Live stream name or the Facebook stream key), - # and (optionally) (:id), a unique ID for the stream. + # and (optionally) (:id), a unique ID for the stream. If you specify an ID, it will be + # included in the (broadcast_json) response from the Client#start_broadcast method call, + # and is also available in the (broadcast_json) 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 (:rtmp) property value in the (:outputs) [Hash]. + # + # For HLS, the (:hls) property in the (:outputs) [Hash] is set to a HLS [Hash] + # object. This object includes the following optional properties: + # - (:dvr) (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. + # - (:low_latency) (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 (broadcast_json) response from the Client#start_broadcast + # method call, and is also available in the (broadcast_json) response from the + # Broadcasts#find method. # # @option options [string] resolution # The resolution of the broadcast: either "640x480" (SD, the default) or "1280x720" (HD). @@ -58,11 +80,11 @@ def initialize(client) # @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 diff --git a/lib/opentok/opentok.rb b/lib/opentok/opentok.rb index 9062a7d..b031865 100644 --- a/lib/opentok/opentok.rb +++ b/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.) # # * :moderator -- 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() diff --git a/lib/opentok/streams.rb b/lib/opentok/streams.rb index f75a187..d40498b 100644 --- a/lib/opentok/streams.rb +++ b/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) diff --git a/lib/opentok/version.rb b/lib/opentok/version.rb index 4ef1a91..1da2337 100644 --- a/lib/opentok/version.rb +++ b/lib/opentok/version.rb @@ -1,4 +1,4 @@ module OpenTok # @private - VERSION = '4.3.0' + VERSION = '4.4.0' end diff --git a/spec/opentok/broadcasts_spec.rb b/spec/opentok/broadcasts_spec.rb index 27dfe07..f0eb8d0 100644 --- a/spec/opentok/broadcasts_spec.rb +++ b/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 => {