Module: OpenTok

Defined in:
lib/opentok.rb,
lib/opentok/sip.rb,
lib/opentok/client.rb,
lib/opentok/render.rb,
lib/opentok/stream.rb,
lib/opentok/archive.rb,
lib/opentok/opentok.rb,
lib/opentok/renders.rb,
lib/opentok/session.rb,
lib/opentok/signals.rb,
lib/opentok/streams.rb,
lib/opentok/version.rb,
lib/opentok/archives.rb,
lib/opentok/captions.rb,
lib/opentok/broadcast.rb,
lib/opentok/constants.rb,
lib/opentok/websocket.rb,
lib/opentok/broadcasts.rb,
lib/opentok/exceptions.rb,
lib/opentok/connections.rb,
lib/opentok/render_list.rb,
lib/opentok/stream_list.rb,
lib/opentok/archive_list.rb,
lib/opentok/broadcast_list.rb,
lib/opentok/extensions/hash.rb,
lib/opentok/token_generator.rb

Overview

An object that lets you work with Audio Connector WebSocket connections.

Defined Under Namespace

Modules: HashExtensions Classes: Archive, ArchiveList, Archives, Broadcast, BroadcastList, Broadcasts, Captions, Connections, OpenTok, OpenTokArchiveError, OpenTokAuthenticationError, OpenTokBroadcastError, OpenTokCaptionsError, OpenTokConnectionError, OpenTokError, OpenTokRenderError, OpenTokSipError, OpenTokStreamLayoutError, OpenTokWebSocketError, Render, RenderList, Renders, Session, Signals, Sip, Stream, StreamList, Streams, WebSocket

Constant Summary collapse

API_URL = 
"https://api.opentok.com"
TOKEN_SENTINEL = 
"T1=="
ROLES = 
{ subscriber: "subscriber", publisher: "publisher", moderator: "moderator", publisheronly: "publisheronly" }
ARCHIVE_MODES = 
::Set.new([:manual, :always])
AUTH_EXPIRE = 
300

Instance Method Summary collapse

Instance Method Details

#generate_token(options) ⇒ String

Generates a token.

Parameters:

  • options (Hash)

Options Hash (options):

  • :role (Symbol) —

    The role for the token. Set this to one of the following values:

    • :subscriber – A subscriber can only subscribe to streams.

    • :publisher – A publisher can publish streams, subscribe to streams, and signal. (This is the default value if you do not specify a role.)

    • :moderator – n 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 / Moderation developer guide.

  • :expire_time (integer) —

    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.

  • :data (String) —

    A string containing connection metadata describing the end-user. For example, you can pass the user ID, name, or other data describing the end-user. The length of the string is limited to 1000 characters. This data cannot be updated once it is set.

  • :initial_layout_class_list (Array) —

    An array of class names (strings) to be used as the initial layout classes for streams published by the client. Layout classes are used in customizing the layout of videos in / live streaming broadcasts and composed archives.

Returns:

  • (String) —

    The token string.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/opentok/opentok.rb', line 63

class OpenTok

  include TokenGenerator
  generates_tokens({
    :api_key => ->(instance) { instance.api_key },
    :api_secret => ->(instance) { instance.api_secret }
  })

  # @private
  # don't want these to be mutable, may cause bugs related to inconsistency since these values are
  # cached in objects that this can create
  attr_reader :api_key, :api_secret, :timeout_length, :api_url, :ua_addendum

  ##
  # Create a new OpenTok object.
  #
  # @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 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()
    @api_secret = api_secret
    @timeout_length = opts[:timeout_length] || 2
    @api_url = opts[:api_url] || API_URL
    @ua_addendum = opts[:ua_addendum]
  end

  # Creates a new OpenTok session and returns the session ID, which uniquely identifies
  # the session.
  #
  # For example, when using the OpenTok JavaScript library, use the session ID when calling the
  # OT.initSession()</a> method (to initialize an OpenTok session).
  #
  # OpenTok sessions do not expire. However, authentication tokens do expire (see the
  # generateToken() method). Also note that sessions cannot explicitly be destroyed.
  #
  # A session ID string can be up to 255 characters long.
  #
  # Calling this method results in an OpenTokException in the event of an error.
  # Check the error message for details.
  #
  # You can also create a session using the OpenTok REST API (see
  # http://www.tokbox.com/opentok/api/#session_id_production) or at your
  # {https://tokbox.com/account OpenTok account page}.
  #
  # @param [Hash] opts (Optional) This hash defines options for the session.
  #
  # @option opts [Symbol] :media_mode Determines whether the session will transmit streams the
  #   using OpenTok Media Router (<code>:routed</code>) or not (<code>:relayed</code>).
  #   By default, this property is set to <code>:relayed</code>.
  #
  #   With the <code>media_mode</code> property set to <code>:relayed</code>, the session
  #   will attempt to transmit streams directly between clients. If clients cannot connect due to
  #   firewall restrictions, the session uses the OpenTok TURN server to relay audio-video
  #   streams.
  #
  #   With the <code>media_mode</code> property set to <code>:routed</code>, the session will use
  #   the {https://tokbox.com/opentok/tutorials/create-session/#media-mode OpenTok Media Router}.
  #   The OpenTok Media Router provides the following benefits:
  #
  #   * The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
  #     (When the <code>media_mode</code> property is set to <code>:relayed</code>,
  #     each client must send a separate audio-video stream to each client subscribing to
  #     it.)
  #   * The OpenTok Media Router can improve the quality of the user experience through
  #     {https://tokbox.com/platform/fallback audio fallback and video recovery}. With
  #     these features, if a client's connectivity degrades to a degree that
  #     it does not support video for a stream it's subscribing to, the video is dropped on
  #     that client (without affecting other clients), and the client receives audio only.
  #     If the client's connectivity improves, the video returns.
  #   * The OpenTok Media Router supports the
  #     {https://tokbox.com/opentok/tutorials/archiving archiving}
  #     feature, which lets you record, save, and retrieve OpenTok sessions.
  #
  # @option opts [String] :location  An IP address that the OpenTok servers will use to
  #     situate the session in its global network. If you do not set a location hint,
  #     the OpenTok servers will be based on the first client connecting to the session.
  #
  # @option opts [Symbol] :archive_mode Determines whether the session will be archived
  #     automatically (<code>:always</code>) or not (<code>:manual</code>). When using automatic
  #     archiving, the session must use the <code>:routed</code> media mode.
  #
  # @option opts [Symbol] :archive_name The name to use for archives in auto-archived sessions.
  #     When setting this option, the :archive_mode option must be set to :always or an error will result.
  #     The length of the archive name can be up to 80 chars.
  #     Due to encoding limitations the following special characters are translated to a colon (:) character: ~, -, _.
  #     If you do not set a name and the archiveMode option is set to always, the archive name will be empty.
  #
  # @option opts [Symbol] :archive_resolution The resolution of archives in an auto-archived session.
  #     Valid values are "480x640", "640x480" (the default), "720x1280", "1280x720", "1080x1920", and "1920x1080".
  #     When setting this option, the :archive_mode option must be set to :always or an error will result.
  #
  # @option opts [true, false] :e2ee
  #     (Boolean, optional) — Whether the session uses end-to-end encryption from client to client (default: false).
  #     This should not be set to `true` if `:media_mode` is `:relayed`.
  #     See the {https://tokbox.com/developer/guides/end-to-end-encryption/ documentation} for more information.
  #
  # @return [Session] The Session object. The session_id property of the object is the session ID.
  def create_session(opts={})

    # normalize opts so all keys are symbols and only include valid_opts
    valid_opts = [ :media_mode, :location, :archive_mode, :archive_name, :archive_resolution, :e2ee ]
    opts = opts.inject({}) do |m,(k,v)|
      if valid_opts.include? k.to_sym
        m[k.to_sym] = v
      end
      m
    end

    # keep opts around for Session constructor, build REST params
    params = opts.clone

    # validate input combinations
    raise ArgumentError, "A session with always archive mode must also have the routed media mode." if (params[:archive_mode] == :always && params[:media_mode] == :relayed)

    raise ArgumentError, "A session with relayed media mode should not have e2ee set to true." if (params[:media_mode] == :relayed && params[:e2ee] == true)

    raise ArgumentError, "A session with always archive mode must not have e2ee set to true." if (params[:archive_mode] == :always && params[:e2ee] == true)

    # anything other than :relayed sets the REST param to "disabled", in which case we force
    # opts to be :routed. if we were more strict we could raise an error when the value isn't
    # either :relayed or :routed
    if params.delete(:media_mode) == :routed
      params["p2p.preference"] = "disabled"
    else
      params["p2p.preference"] = "enabled"
      opts[:media_mode] = :relayed
    end
    # location is optional, but it has to be an IP address if specified at all
    unless params[:location].nil?
      raise "location must be an IPv4 address" unless params[:location] =~ Resolv::IPv4::Regex
    end
    # archive mode is optional, but it has to be one of the valid values if present
    unless params[:archive_mode].nil?
      raise "archive mode must be either always or manual" unless ARCHIVE_MODES.include? params[:archive_mode].to_sym
      raise ArgumentError, "archive name and/or archive resolution must not be set if archive mode is manual" if params[:archive_mode] == :manual && (params[:archive_name] || params[:archive_resolution])
    end

    response = client.create_session(params)
    Session.new api_key, api_secret, response['sessions']['Session']['session_id'], opts
  end

  # An Archives object, which lets you work with OpenTok archives.
  def archives
    @archives ||= Archives.new client
  end

  # A Broadcasts object, which lets you work with OpenTok live streaming broadcasts.
  def broadcasts
    @broadcasts ||= Broadcasts.new client
  end

  # A Captions object, which lets you start and stop live captions for an OpenTok session.
  def captions
    @captions ||= Captions.new client
  end

  # A Connections object, which lets you disconnect clients from an OpenTok session.
  def connections
    @connections ||= Connections.new client
  end

  # A Renders object, which lets you work with OpenTok Experience Composer renders.
  def renders
    @renders ||= Renders.new client
  end

  # A Sip object, which lets you use the OpenTok SIP gateway.
  def sip
    @sip ||= Sip.new client
  end

  # A Streams object, which lets you work with OpenTok live streaming broadcasts.
  def streams
    @streams ||= Streams.new client
  end

  # A Signals object, which lets you send signals to OpenTok sessions.
  def signals
    @signals ||= Signals.new client
  end

  # A WebSocket object, which lets you connect OpenTok streams to a WebSocket URI.
  def websocket
    @websocket ||= WebSocket.new client
  end

  protected
  def client
    @client ||= Client.new api_key, api_secret, api_url, ua_addendum, timeout_length: @timeout_length
  end

end