opentok 3.0.3 → 3.1.0

data/lib/opentok/broadcast.rb

@@ -0,0 +1,118 @@
+require "active_support/inflector"
+
+module OpenTok
+  # Represents a live streaming broadcast of an OpenTok session.
+  # See {https://tokbox.com/developer/guides/broadcast/live-streaming/ Live streaming broadcasts}.
+  #
+  # @attr [string] id
+  #   The broadcast ID.
+  #
+  # @attr [string] session_id
+  #   The session ID of the OpenTok session associated with this broadcast.
+  #
+  # @attr [string] project_id
+  #   The API key associated with the broadcast.
+  #
+  # @attr [int] created_at
+  #   The time at which the broadcast was created, in milliseconds since the UNIX epoch.
+  #
+  # @attr [int] updated_at
+  #   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.
+  #
+  # @attr [Hash] broadcastUrls is defined as follows:
+  #   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 stream, 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.
+  #
+  # @attr [string] status The status of the RTMP stream.
+  #     * "connecting" --  The OpenTok platform is in the process of connecting to the remote RTMP server.
+  #                        This is the initial state, and it is the status if you start when there are no streams published in the session.
+  #                        It changes to "live" when there are streams (or it changes to one of the other states).
+  #     * "live --         The OpenTok platform has successfully connected to the remote RTMP server, and the media is streaming.
+  #     * "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
+
+    # @private
+    def initialize(interface, json)
+      @interface = interface
+      # TODO: validate json fits schema
+      @json = json
+    end
+
+    # A JSON-encoded string representation of the broadcast.
+    def to_json
+      @json.to_json
+    end
+
+    # Stops the OpenTok broadcast.
+    def stop
+      # TODO: validate returned json fits schema
+      @json = @interface.stop @json['id']
+    end
+
+    # Sets the layout of the OpenTok broadcast.
+    #
+    # You can dynamically change the layout type of a broadcast while it is being broadcast.
+    # For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts Configuring video layout for OpenTok live streaming broadcasts}.
+    #
+    # @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 [OpenTokBroadcastError]
+    #   The broadcast layout could not be updated.
+    #
+    # @raise [OpenTokAuthenticationError]
+    #   Authentication failed. Invalid API key or secret.
+    #
+    # @raise [OpenTokError]
+    #   OpenTok server error.
+    #
+    # @raise [ArgumentError]
+    #   The broadcast_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.
+    # Refer to {https://tokbox.com/developer/rest/#change_composed_archive_layout}
+
+    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)
+      if @json.has_key? camelized_method and args.empty?
+        # TODO: convert create_time method call to a Time object
+        if camelized_method == 'outputMode'
+          @json[camelized_method].to_sym
+        else
+          @json[camelized_method]
+        end
+      else
+        super method, *args, &block
+      end
+    end
+  end
+end

data/lib/opentok/broadcasts.rb

@@ -0,0 +1,149 @@
+require "opentok/client"
+require "opentok/broadcast"
+
+
+module OpenTok
+  # A class for working with OpenTok live streaming broadcasts.
+  # See {https://tokbox.com/developer/guides/broadcast/live-streaming/ Live streaming broadcasts}.
+  class Broadcasts
+
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Starts a live streaming broadcast of an OpenTok session.
+    #
+    # Clients must be actively connected to the OpenTok session for you to successfully start
+    # a broadcast.
+    #
+    # This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams.
+    #
+    # @param [String] session_id The session ID of the OpenTok session to broadcast.
+    #
+    # @param [Hash] options A hash defining options for the broadcast.
+    # @option options [Hash] :layout Specify this to assign the initial layout  for the broadcast.
+    #   Valid values for the layout (<code>:type</code>) property are "bestFit" (best fit), "custom" (custom),
+    #   "horizontalPresentation" (horizontal presentation), "pip" (picture-in-picture), and
+    #   "verticalPresentation" (vertical presentation)).
+    #   If you specify a (<code>:custom</code>) layout type, set the (<code>:stylesheet</code>) property of the layout object
+    #   to the stylesheet. (For other layout types, do not set a stylesheet property.)
+    #   If you do not specify an initial layout type, the broadcast stream uses the Best Fit layout type.
+    #
+    # @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).
+    #   The default maximum duration is 2 hours (7200 seconds).
+    #
+    # @option options [Hash] outputs
+    #   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,
+    #   (<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.
+    #
+    # @option options [string] resolution
+    #   The resolution of the broadcast: either "640x480" (SD, the default) or "1280x720" (HD).
+    #
+    # @return [Broadcast] The broadcast object, which includes properties defining the broadcast,
+    #   including the broadcast ID.
+    #
+    # @raise [OpenTokBroadcastError] The broadcast could not be started. The request was invalid or broadcast already started
+    # @raise [OpenTokAuthenticationError] Authentication failed while starting an archive.
+    #   Invalid API key.
+    # @raise [OpenTokError] OpenTok server error.
+    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?
+      broadcast_json = @client.start_broadcast(session_id, options)
+      Broadcast.new self, broadcast_json
+    end
+
+    # Gets a Broadcast object for the given broadcast ID.
+    #
+    # @param [String] broadcast_id The broadcast ID.
+    #
+    # @return [Broadcast] The broadcast object, which includes properties defining the broadcast.
+    #
+    # @raise [OpenTokBroadcastError] No matching broadcast found.
+    # @raise [OpenTokAuthenticationError] Authentication failed.
+    #   Invalid API key.
+    # @raise [OpenTokError] OpenTok server error.
+    def find(broadcast_id)
+      raise ArgumentError, "broadcast_id not provided" if broadcast_id.to_s.empty?
+      broadcast_json = @client.get_broadcast(broadcast_id.to_s)
+      Broadcast.new self, broadcast_json
+    end
+
+
+    # Stops an OpenTok broadcast
+    #
+    # Note that broadcasts automatically stop after 120 minute
+    #
+    # @param [String] broadcast_id The broadcast ID.
+    #
+    # @return [Broadcast] The broadcast object, which includes properties defining the broadcast.
+    #
+    # @raise [OpenTokBroadcastError] The broadcast could not be stopped. The request was invalid.
+    # @raise [OpenTokAuthenticationError] Authentication failed.
+    #   Invalid API key.
+    # @raise [OpenTokError] OpenTok server error.
+    def stop(broadcast_id)
+      raise ArgumentError, "broadcast_id not provided" if broadcast_id.to_s.empty?
+      broadcast_json = @client.stop_broadcast(broadcast_id)
+      Broadcast.new self, broadcast_json
+    end
+
+    # Dynamically alters the layout an OpenTok broadcast. For more information, see
+    # For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#configuring-video-layout-for-opentok-live-streaming-broadcasts Configuring video layout for OpenTok live streaming broadcasts}.
+    #
+    # @param [String] broadcast_id
+    #   The broadcast 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 [OpenTokBroadcastError]
+    #   The broadcast layout could not be updated.
+    #
+    # @raise [OpenTokAuthenticationError]
+    #   Authentication failed. Invalid API key or secret.
+    #
+    # @raise [OpenTokError]
+    #   OpenTok server error.
+    #
+    # @raise [ArgumentError]
+    #   The broadcast_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.
+    def layout(broadcast_id, options = {})
+      raise ArgumentError, "option parameter is empty" if options.empty?
+      raise ArgumentError, "broadcast_id not provided" if broadcast_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" if !valid_non_custom_type
+      raise ArgumentError, "stylesheet not needed" if valid_non_custom_type and options.key? :stylesheet
+      response = @client.layout_broadcast(broadcast_id, options)
+      (200..300).include? response.code
+    end
+
+
+  end
+end

data/lib/opentok/client.rb

@@ -164,6 +164,72 @@ module OpenTok
       raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
+    def layout_archive(archive_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/archive/#{archive_id}/layout", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokArchiveError, "Setting the layout failed. The request was invalid or invalid layout options were given."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "Setting the layout failed. OpenTok server error."
+      else
+        raise OpenTokArchiveError, "Setting the layout failed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def forceDisconnect(session_id, connection_id)
+      response = self.class.delete("/v2/project/#{@api_key}/session/#{session_id}/connection/#{connection_id}", {
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 204
+        response
+      when 400
+        raise ArgumentError, "Force disconnect failed. Connection ID #{connection_id} or Session ID #{session_id} is invalid"
+      when 403
+        raise OpenTokAuthenticationError, "You are not authorized to forceDisconnect, check your authentication credentials or token type is non-moderator"
+      when 404
+        raise OpenTokConnectionError, "The client specified by the connection ID: #{connection_id} is not connected to the session"
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def signal(session_id, connection_id, opts)
+      opts.extend(HashExtensions)
+      connectionPath = connection_id.to_s.empty? ? "" : "/connection/#{connection_id}"
+      url = "/v2/project/#{@api_key}/session/#{session_id}#{connectionPath}/signal"
+      response = self.class.post(url, {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 204
+        response
+      when 400
+        raise ArgumentError, "One of the signal properties — data, type, sessionId or connectionId — is invalid."
+      when 403
+        raise OpenTokAuthenticationError, "You are not authorized to send the signal. Check your authentication credentials."
+      when 404
+        raise OpenTokError, "The client specified by the connectionId property is not connected to the session."
+      when 413
+        raise OpenTokError, "The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB)."
+      else
+        raise OpenTokError, "The signal could not be send."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
     def dial(session_id, token, sip_uri, opts)
       opts.extend(HashExtensions)
       body = { "sessionId" => session_id,
@@ -179,14 +245,151 @@ module OpenTok
       when 200
         response
       when 403
-        raise OpenTokAuthenticationError, "Authentication failed while dialing a sip session. API Key: #{@api_key}"
+        raise OpenTokAuthenticationError, "Authentication failed while dialing a SIP session. API Key: #{@api_key}"
       when 404
-        raise OpenTokSipError, "The sip session could not be dialed. The Session ID does not exist: #{session_id}"
+        raise OpenTokSipError, "The SIP session could not be dialed. The Session ID does not exist: #{session_id}"
       else
-        raise OpenTokSipError, "The sip session could not be dialed"
+        raise OpenTokSipError, "The SIP session could not be dialed"
       end
     rescue StandardError => e
       raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
+
+    def info_stream(session_id, stream_id)
+      streamId = stream_id.to_s.empty? ? '' : "/#{stream_id}"
+      url = "/v2/project/#{@api_key}/session/#{session_id}/stream#{streamId}"
+      response = self.class.get(url,
+                                headers: generate_headers('Content-Type' => 'application/json'))
+      case response.code
+      when 200
+        response
+      when 400
+        raise ArgumentError, 'Invalid request. You did not pass in a valid session ID or stream ID.'
+      when 403
+        raise OpenTokAuthenticationError, 'Check your authentication credentials. You passed in an invalid OpenTok API key.'
+      when 408
+        raise ArgumentError, 'You passed in an invalid stream ID.'
+      when 500
+        raise OpenTokError, 'OpenTok server error.'
+      else
+        raise OpenTokError, 'Could not fetch the stream information.'
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def layout_streams(session_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/session/#{session_id}/stream", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokStreamLayoutError, "Setting the layout failed. The request was invalid or invalid layout options were given."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "Setting the layout failed. OpenTok server error."
+      else
+        raise OpenTokStreamLayoutError, "Setting the layout failed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def start_broadcast(session_id, opts)
+      opts.extend(HashExtensions)
+      body = { :sessionId => session_id }.merge(opts.camelize_keys!)
+      response = self.class.post("/v2/project/#{@api_key}/broadcast", {
+          :body => body.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The broadcast could not be started. The request was invalid or invalid layout options or exceeded the limit of five simultaneous RTMP streams."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while starting a broadcast. API Key: #{@api_key}"
+      when 409
+        raise OpenTokBroadcastError, "The broadcast has already been started for this session."
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast could not be started"
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def get_broadcast(broadcast_id)
+      response = self.class.get("/v2/project/#{@api_key}/broadcast/#{broadcast_id}", {
+          :headers => generate_headers
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The request was invalid."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while getting a broadcast. API Key: #{@api_key}"
+      when 404
+        raise OpenTokBroadcastError, "No matching broadcast found (with the specified ID)"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "Could not fetch broadcast information."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def stop_broadcast(broadcast_id)
+      response = self.class.post("/v2/project/#{@api_key}/broadcast/#{broadcast_id}/stop", {
+          :headers => generate_headers
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The request was invalid."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while stopping a broadcast. API Key: #{@api_key}"
+      when 404
+        raise OpenTokBroadcastError, "No matching broadcast found (with the specified ID) or it is already stopped"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast could not be stopped."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def layout_broadcast(broadcast_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/broadcast/#{broadcast_id}/layout", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The layout operation could not be performed. The request was invalid or invalid layout options."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed for broadcast layout. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast layout could not be performed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
   end
 end