Class: OpenTok::Archives

Inherits:
Object
  • Object
show all
Defined in:
lib/opentok/archives.rb

Overview

A class for working with OpenTok archives.

Instance Method Summary collapse

Instance Method Details

#add_stream(archive_id, stream_id, options) ⇒ Object

Adds a stream to currently running composed archive that was started with the streamMode set to “manual”. For a description of the feature, see https://tokbox.com/developer/rest/#selecting-archive-streams.

You can call the method repeatedly with add_stream set to the same stream ID, to toggle the stream’s audio or video in the archive. If you set both has_audio and has_video to false, you will get error response.

Parameters:

  • archive_id (String) —

    The archive ID.

  • stream_id (String) —

    The ID for the stream to be added to the archive

  • opts (Hash) —

    a customizable set of options

Raises:

  • (ArgumentError) —

    The archive_id parameter is empty.

  • (ArgumentError) —

    The stream_id parameter is empty.

  • (ArgumentError) —

    The has_audio and has_video properties of the options parameter are both set to “false”



286
287
288
289
290
291
292
293
294
295
296
297
 
# File 'lib/opentok/archives.rb', line 286

def add_stream(archive_id, stream_id, options)
  raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
  raise ArgumentError, "stream_id not provided" if stream_id.to_s.empty?
  if options.has_key?(:has_audio) && options.has_key?(:has_video)
    has_audio = options[:has_audio]
    has_video = options[:has_video]
    raise ArgumentError, "has_audio and has_video can't both be false" if audio_and_video_options_both_false?(has_audio, has_video)
  end
  options['add_stream'] = stream_id

  @client.select_streams_for_archive(archive_id, options)
end

#all(options = {}) ⇒ ArchiveList

Returns an ArchiveList, which is an array of archives that are completed and in-progress, for your API key.

Parameters:

  • options (Hash) (defaults to: {}) —

    A hash with keys defining which range of archives to retrieve.

Options Hash (options):

  • :offset (integer) —

    Optional. The index offset of the first archive. 0 is offset of the most recently started archive. 1 is the offset of the archive that started prior to the most recent archive. If you do not specify an offset, 0 is used.

  • :count (integer) —

    Optional. The number of archives to be returned. The maximum number of archives returned is 1000.

  • :session_id (String) —

    Optional. The session ID that archives belong to. This is useful when listing multiple archives for an automatically archived session.

Returns:

  • (ArchiveList) —

    An ArchiveList object, which is an array of Archive objects.

Raises:

  • (ArgumentError) 


149
150
151
152
153
 
# File 'lib/opentok/archives.rb', line 149

def all(options = {})
  raise ArgumentError, "Limit is invalid" unless options[:count].nil? or (0..1000).include? options[:count]
  archive_list_json = @client.list_archives(options[:offset], options[:count], options[:sessionId])
  ArchiveList.new self, archive_list_json
end

#create(session_id, options = {}) ⇒ Archive

Starts archiving an OpenTok session.

Clients must be actively connected to the OpenTok session for you to successfully start recording an archive.

You can only record one archive at a time for a given session. You can only record archives of sessions that use the OpenTok Media Router (sessions with the media mode set to routed); you cannot archive sessions with the media mode set to relayed.

For more information on archiving, see the OpenTok archiving programming guide.

Parameters:

  • session_id (String) —

    The session ID of the OpenTok session to archive.

  • options (Hash) (defaults to: {}) —

    A hash with the keys ‘name’, ‘has_audio’, ‘has_video’, and ‘output_mode’.

Options Hash (options):

  • :name (String) —

    This is the name of the archive. You can use this name to identify the archive. It is a property of the Archive object, and it is a property of archive-related events in the OpenTok client SDKs.

  • :has_audio (true, false) —

    Whether the archive will include an audio track (true) or not false). The default value is true (an audio track is included). If you set both has_audio and has_video to false, the call to the create() method results in an error.

  • :has_video (true, false) —

    Whether the archive will include a video track (true) or not false). The default value is true (a video track is included). If you set both has_audio and has_video to false, the call to the create() method results in an error.

  • :multi_archive_tag (String) — default: 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 automatically archived. Note that the ‘multiArchiveTag` value is not included in the response for the methods to list archives and retrieve archive information. If you do not specify a unique `multi_archive_tag`, you can only record one archive at a time for a given session. See Simultaneous archives.

  • :output_mode (String) —

    Whether all streams in the archive are recorded to a single file (:composed, the default) or to individual files (:individual). For more information on archiving and the archive file formats, see the OpenTok archiving programming guide.

  • :resolution (String) —

    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.

  • :stream_mode (String) — default: 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 #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. Important: this feature is currently available in the Standard environment only.

  • :layout (Hash) —

    Specify this to assign the initial layout type for the archive. This applies only to composed archives. This is a hash containing three keys: :type, :stylesheet<code> and <code>:screenshare_type. Valid values for :type are “bestFit” (best fit), “custom” (custom),

    "horizontalPresentation" (horizontal presentation),

    “pip” (picture-in-picture), and “verticalPresentation” (vertical presentation)). If you specify a “custom” layout type, set the :stylesheet key to the stylesheet (CSS). (For other layout types, do not set the :stylesheet key.) Valid values for :screenshare_type are “bestFit”, “pip”, “verticalPresentation”, “horizontalPresentation”. This property is optional. If it is specified, then the :type property must be set to “bestFit”. If you do not specify an initial layout type, the archive uses the best fit layout type. For more information, see Customizing the video layout for composed archives.

Returns:

  • (Archive) —

    The Archive object, which includes properties defining the archive, including the archive ID.

Raises:

  • (OpenTokArchiveError) —

    The archive could not be started. The request was invalid or the session has no connected clients.

  • (OpenTokAuthenticationError) —

    Authentication failed while starting an archive. Invalid API key.

  • (OpenTokArchiveError) —

    The archive could not be started. The session ID does not exist.

  • (OpenTokArchiveError) —

    The archive could not be started. The session could be peer-to-peer or the session is already being recorded.

  • (OpenTokArchiveError) —

    The archive could not be started.



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/opentok/archives.rb', line 94

def create(session_id, options = {})
  raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
  raise ArgumentError,
    "Resolution cannot be supplied for individual output mode" if options.key?(:resolution) and options[:output_mode] == :individual

  # normalize opts so all keys are symbols and only include valid_opts
  valid_opts = [
    :name,
    :has_audio,
    :has_video,
    :output_mode,
    :resolution,
    :layout,
    :multi_archive_tag,
    :stream_mode
  ]
  opts = options.inject({}) do |m,(k,v)|
    if valid_opts.include? k.to_sym
      m[k.to_sym] = v
    end
    m
  end

  archive_json = @client.start_archive(session_id, opts)
  Archive.new self, archive_json
end

#delete_by_id(archive_id) ⇒ Object

Deletes an OpenTok archive.

You can only delete an archive which has a status of “available”, “uploaded”, or “deleted”. Deleting an archive removes its record from the list of archives. For an “available” archive, it also removes the archive file, making it unavailable for download. For a “deleted” archive, the archive remains deleted.

Parameters:

  • archive_id (String) —

    The archive ID of the archive you want to delete.

Raises:



189
190
191
192
193
 
# File 'lib/opentok/archives.rb', line 189

def delete_by_id(archive_id)
  raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
  response = @client.delete_archive(archive_id)
  (200..300).include? response.code
end

#find(archive_id) ⇒ Archive

Gets an Archive object for the given archive ID.

Parameters:

  • archive_id (String) —

    The archive ID.

Returns:

  • (Archive) —

    The Archive object.

Raises:



130
131
132
133
134
 
# File 'lib/opentok/archives.rb', line 130

def find(archive_id)
  raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
  archive_json = @client.get_archive(archive_id.to_s)
  Archive.new self, archive_json
end

#layout(archive_id, options = {}) ⇒ Object

Sets the layout type for a composed archive. For a description of layout types, see Customizing the video layout for composed archives.

Parameters:

  • archive_id (String) —

    The archive ID.

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :type (String) —

    The layout type. Set this to “bestFit”, “pip”, “verticalPresentation”, “horizontalPresentation”, “focus”, or “custom”.

  • :stylesheet (String) —

    The stylesheet for a custom layout. Set this parameter if you set type to "custom". Otherwise, leave it undefined.

  • :screenshare_type (String) —

    The screenshare layout type. Set this to “bestFit”, “pip”, “verticalPresentation” or “horizonalPresentation”. If this is defined, then the type parameter must be set to "bestFit".

Raises:

  • (ArgumentError) —

    The archive_id or options parameter is empty. Or the “custom” type was specified without a stylesheet option. Or a stylesheet was passed in for a type other than custom. Or an invalid type was passed in.

  • (OpenTokAuthenticationError) —

    Authentication failed.

  • (ArgumentError) —

    The archive_id or options parameter is empty.

  • (ArgumentError) —

    The “custom” type was specified without a stylesheet option.

  • (ArgumentError) —

    A stylesheet was passed in for a type other than custom. Or an invalid type was passed in.

  • (ArgumentError) —

    An invalid layout type was passed in.

  • (OpenTokError) —

    OpenTok server error.

  • (OpenTokArchiveError) —

    Setting the layout failed.



240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/opentok/archives.rb', line 240

def layout(archive_id, options = {})
  raise ArgumentError, "option parameter is empty" if options.empty?
  raise ArgumentError, "archive_id not provided" if archive_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_layouts = ["bestFit","horizontalPresentation","pip", "verticalPresentation", ""]
  valid_non_custom_type = valid_non_custom_layouts.include? type
  raise ArgumentError, "type is not valid" if !valid_non_custom_type && !(type.eql? "custom")
  raise ArgumentError, "type is not valid or stylesheet not needed" if valid_non_custom_type and options.key? :stylesheet
  raise ArgumentError, "screenshare_type is not valid" if options[:screenshare_type] && !valid_non_custom_layouts.include?(options[:screenshare_type])
  raise ArgumentError, "type must be set to 'bestFit' if screenshare_type is defined" if options[:screenshare_type] && type != 'bestFit'
  response = @client.layout_archive(archive_id, options)
  (200..300).include? response.code
end

#remove_stream(archive_id, stream_id) ⇒ Object

Removes a stream from a currently running composed archive that was started with the streamMode set to “manual”. For a description of the feature, see https://tokbox.com/developer/rest/#selecting-archive-streams.

Parameters:

  • archive_id (String) —

    The archive ID.

  • stream_id (String) —

    The ID for the stream to be removed from the archive

Raises:

  • (ArgumentError) —

    The archive_id parameter id is empty.

  • (ArgumentError) —

    The stream_id parameter is empty.



315
316
317
318
319
320
321
322
 
# File 'lib/opentok/archives.rb', line 315

def remove_stream(archive_id, stream_id)
  raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
  raise ArgumentError, "stream_id not provided" if stream_id.to_s.empty?
  options = {}
  options['remove_stream'] = stream_id

  @client.select_streams_for_archive(archive_id, options)
end

#stop_by_id(archive_id) ⇒ Archive

Stops an OpenTok archive that is being recorded.

Archives automatically stop recording after 120 minutes or when all clients have disconnected from the session being archived.

Parameters:

  • archive_id (String) —

    The archive ID of the archive you want to stop recording.

Returns:

  • (Archive) —

    The Archive object corresponding to the archive being stopped.

Raises:



170
171
172
173
174
 
# File 'lib/opentok/archives.rb', line 170

def stop_by_id(archive_id)
  raise ArgumentError, "archive_id not provided" if archive_id.to_s.empty?
  archive_json = @client.stop_archive(archive_id)
  Archive.new self, archive_json
end