Method: OpenTok::OpenTok#create_session

Defined in:

lib/opentok/opentok.rb

#create_session(opts = {}) ⇒ Session

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 www.tokbox.com/opentok/api/#session_id_production) or at your OpenTok account page.

Parameters:

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

  (Optional) This hash defines options for the session.

Options Hash (opts):

• :media_mode (Symbol) —

  Determines whether the session will transmit streams the using OpenTok Media Router (:routed) or not (:relayed). By default, this property is set to :relayed.

  With the media_mode property set to :relayed, 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 media_mode property set to :routed, the session will use the OpenTok Media Router. The OpenTok Media Router provides the following benefits:

  • The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the media_mode property is set to :relayed, 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 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 archiving feature, which lets you record, save, and retrieve OpenTok sessions.

• :location (String) —

  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.

• :archive_mode (Symbol) —

  Determines whether the session will be archived automatically (:always) or not (:manual). When using automatic archiving, the session must use the :routed media mode.

• :archive_name (Symbol) —

  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.

• :archive_resolution (Symbol) —

  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.

• :e2ee (true, false) — default: 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 / documentation for more information.

Returns:

• (Session) —

  The Session object. The session_id property of the object is the session ID.

Raises:

• (ArgumentError)

# File 'lib/opentok/opentok.rb', line 165

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