From d1f4cc02c5d25f3fcedd23dec21d897e40668f47 Mon Sep 17 00:00:00 2001 From: superchilled <karl@superchilled.co.uk> Date: Wed, 20 Apr 2022 11:51:20 +0100 Subject: [PATCH 1/5] Updating code comments for Broadcasts#create method --- lib/opentok/broadcasts.rb | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/lib/opentok/broadcasts.rb b/lib/opentok/broadcasts.rb index 6dfbf91..5c53b0f 100644 --- a/lib/opentok/broadcasts.rb +++ b/lib/opentok/broadcasts.rb @@ -42,15 +42,35 @@ 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. + # TokBox 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 DVR functionality + # { https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr } (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>:lowLatency</code>) (Boolean). Whether to enable low-latency mode for the HLSstream. + # { https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency } + # 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). From 40a28107be366dbc77759bc48fa1986e0beaace5 Mon Sep 17 00:00:00 2001 From: superchilled <karl@superchilled.co.uk> Date: Wed, 20 Apr 2022 12:38:28 +0100 Subject: [PATCH 2/5] Updating Broadcasts#create method and adding helper method --- lib/opentok/broadcasts.rb | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/lib/opentok/broadcasts.rb b/lib/opentok/broadcasts.rb index 5c53b0f..687336b 100644 --- a/lib/opentok/broadcasts.rb +++ b/lib/opentok/broadcasts.rb @@ -64,7 +64,7 @@ def initialize(client) # { https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr } (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>:lowLatency</code>) (Boolean). Whether to enable low-latency mode for the HLSstream. + # - (<code>:low_latency</code>) (Boolean). Whether to enable low-latency mode for the HLSstream. # { https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency } # 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. @@ -95,6 +95,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 @@ -283,5 +290,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 From a77fb85ced59689b3c00d6b045cee96c9cffdc4d Mon Sep 17 00:00:00 2001 From: superchilled <karl@superchilled.co.uk> Date: Wed, 20 Apr 2022 12:38:51 +0100 Subject: [PATCH 3/5] Udpating specs to test changes to Broadcasts#create method --- spec/opentok/broadcasts_spec.rb | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) 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 => { From 3e43e48cff7613500ab15758b19f65e027b421df Mon Sep 17 00:00:00 2001 From: Jeff Swartz <jeff.swartz@vonage.com> Date: Wed, 4 May 2022 12:16:42 -0700 Subject: [PATCH 4/5] Some docs edits --- README.md | 2 +- lib/opentok/archives.rb | 5 ++--- lib/opentok/broadcasts.rb | 18 ++++++++++-------- lib/opentok/opentok.rb | 10 +++++----- lib/opentok/streams.rb | 16 +++++++--------- 5 files changed, 25 insertions(+), 26 deletions(-) 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 <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. diff --git a/lib/opentok/archives.rb b/lib/opentok/archives.rb index 2b36bec..f29971f 100644 --- a/lib/opentok/archives.rb +++ b/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: diff --git a/lib/opentok/broadcasts.rb b/lib/opentok/broadcasts.rb index 687336b..1ea2246 100644 --- a/lib/opentok/broadcasts.rb +++ b/lib/opentok/broadcasts.rb @@ -53,19 +53,21 @@ def initialize(client) # 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. - # TokBox streams the session to each RTMP URL you specify. Note that OpenTok live streaming + # 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 DVR functionality - # { https://tokbox.com/developer/guides/broadcast/live-streaming/#dvr } (rewinding, pausing, and resuming) + # - (<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 low-latency mode for the HLSstream. - # { https://tokbox.com/developer/guides/broadcast/live-streaming/#low-latency } + # - (<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 @@ -78,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, 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.) # # * <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() 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) From 93013c416d3f48835121caf00dbe184fc93f1d8d Mon Sep 17 00:00:00 2001 From: superchilled <karl@superchilled.co.uk> Date: Thu, 5 May 2022 12:40:55 +0100 Subject: [PATCH 5/5] Bumping version number to 4.4.0 (next minor increment) --- lib/opentok/version.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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