OpenTokSDK.OpenTok

Creates an OpenTok object.

Parameters

apiKey	Your OpenTok API key. (See the Vonage Video API account page
apiSecret	Your OpenTok API secret. (See the Vonage Video API account page

For Vonage internal use.

Parameters

apiKey
apiSecret
apiUrl

Creates a new 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 or by logging in to your Vonage Video API account.

Parameters

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.
mediaMode	Whether the session will transmit streams using the OpenTok Media Router (MediaMode.ROUTED) or not (MediaMode.RELAYED). By default, the setting is MediaMode.RELAYED.

With the parameter set to MediaMode.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 streams.

The OpenTok Media Router provides the following benefits:

• The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the mediaMode parameter is set to MediaMode.ROUTED, 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.

Parameters

archiveMode

Whether the session is automatically archived (ArchiveMode.ALWAYS) or not (ArchiveMode.MANUAL). By default, the setting is ArchiveMode.MANUAL and you must call the StartArchive method of the OpenTok object to start archiving. To archive the session (either automatically or not), you must set the mediaMode parameter to MediaMode.ROUTED

Returns

A Session object representing the new session. The Session.Id property of the Session is the session ID, which uniquely identifies the session. You will use this session ID in the client SDKs to identify the session. For example, when using the OpenTok.js library, use the session ID when calling the OT.initSession() method (to initialize an OpenTok session).

Deletes an OpenTok archive.

You can only delete an archive which has a status of "available" or "uploaded". 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.

Parameters

archiveId

The archive ID of the archive you want to delete.

Connects a SIP platform to an OpenTok session.

For more information, including technical details and security considerations, see the the OpenTok SIP interconnect developer guide.

Parameters

sessionId	The session ID corresponding to the session to which the user will connect.
token	The token for the session ID with which the SIP user will use to connect.
sipUri	The SIP URI to be used as destination of the SIP call initiated from OpenTok to your SIP platform. If the SIP URI contains a ​transport=tls​ header, the negotiation between OpenTok and the SIP endpoint will be done securely. Note that this will only apply to the negotiation itself, and not to the transmission of audio. If you also audio transmission to be encrypted, set the Secure property of the of the DialOptions object passed into the options parameter to ​true​. This is an example of setting sipUri for a secure call negotiation: "sip:user@sip.partner.com;transport=tls". This is an example of insecure call negotiation: "sip:user@sip.partner.com".
options	Optional parameters for SIP dialing.

Connects a SIP platform to an OpenTok session.

For more information, including technical details and security considerations, see the the OpenTok SIP interconnect developer guide.

Also see OpenTok.Dial.

Parameters

sessionId	The session ID corresponding to the session to which the user will connect.
token	The token for the session ID with which the SIP user will use to connect.
sipUri	The SIP URI to be used as destination of the SIP call initiated from OpenTok to your SIP platform. If the SIP URI contains a ​transport=tls​ header, the negotiation between OpenTok and the SIP endpoint will be done securely. Note that this will only apply to the negotiation itself, and not to the transmission of audio. If you also audio transmission to be encrypted, set the Secure property of the of the DialOptions object passed into the options parameter to ​true​. This is an example of setting sipUri for a secure call negotiation: "sip:user@sip.partner.com;transport=tls". This is an example of insecure call negotiation: "sip:user@sip.partner.com".
options	Optional parameters for SIP dialing.

Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.

After you call the ForceMuteAll method, any streams published after the call are published with audio muted. Call the DisableForceMute() method automatically muted.

Also see the DisableForceMuteAsync method.

Parameters

sessionId

The session ID.

Exceptions

OpenTokArgumentException	Thrown when the session ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Disables the active mute state of the session. After you call this method, new streams published to the session will no longer have audio muted.

After you call the ForceMuteAllAsync method, any streams published after the call are published with audio muted. Call the DisableForceMuteAsync() method automatically muted.

Also see the DisableForceMutec method.

Parameters

sessionId

The session ID.

Exceptions

OpenTokArgumentException	Thrown when the session ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Force a specific client to disconnect from an OpenTok session.

Parameters

sessionId	The session ID corresponding to the session.
connectionId	The connectionId of the connection in a session.

Forces all streams (except for an optional list of streams) in a session to mute published audio.

In addition to existing streams, any streams that are published after the call to this method are published with audio muted. You can remove the mute state of a session by calling the DisableForceMute method.

Also see the ForceMuteAllAsync and ForceMuteStream methods.

Parameters

sessionId	The ID of session.
excludedStreamIds	The stream IDs of streams that will not be muted.

Exceptions

OpenTokArgumentException	Thrown when the session ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Forces all streams (except for an optional list of streams) in a session to mute published audio.

In addition to existing streams, any streams that are published after the call to this method are published with audio muted. You can remove the mute state of a session by calling the DisableForceMuteAsync method.

Also see the ForceMuteAll and ForceMuteStreamAsync methods.

Parameters

sessionId	The ID of session.
excludedStreamIds	The stream IDs of streams that will not be muted.

Exceptions

OpenTokArgumentException	Thrown when the session ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Force the publisher of a specific stream to mute its published audio.

Also see the ForceMuteAll and ForceMuteStreamAsync methods.

Parameters

sessionId	The session ID of the session that includes the stream.
streamId	The stream ID.

Exceptions

OpenTokArgumentException	Thrown when session or stream ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Force the publisher of a specific stream to mute its published audio.

Also see the ForceMuteAll and ForceMuteStream methods.

Parameters

sessionId	The session ID of the session that includes the stream.
streamId	The stream ID.

Exceptions

OpenTokArgumentException	Thrown when session or stream ID is invalid.
OpenTokWebException	Thrown when an HTTP error has occurred.

Creates a token for connecting to an OpenTok session. In order to authenticate a user connecting to an OpenTok session, the client passes a token when connecting to the session.

For testing, you can also generate test tokens by logging in to your Vonage Video API account.

Parameters

sessionId	The session ID corresponding to the session to which the user will connect.
role	The role for the token. Valid values are defined in the Role enum: Role.SUBSCRIBER (A subscriber can only subscribe to streams) Role.PUBLISHER (A publisher can publish streams, subscribe to streams, and signal. (This is the default value if you do not specify a role.)) Role.MODERATOR (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 Moderation developer guide.
expireTime	The expiration time of the token, 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	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.
initialLayoutClassList	A list of strings values containing the initial layout for the stream.

Returns

Gets an Archive object for the given archive ID.

Parameters

archiveId

The archive ID.

Returns

The Archive object.

Use this method to get a live streaming broadcast object of an OpenTok session.

For more information on broadcasting, see the Broadcast developer guide.

Parameters

broadcastId

The broadcast ID of the broadcasting session

Returns

The Broadcast object. This object includes properties defining the broadcast, including the broadcast ID.

Gets a Stream object for the given stream ID.

Parameters

sessionId	The session ID of the OpenTok session.
streamId	The stream ID.

Returns

The Stream object.

Returns a List of Archive objects, representing archives that are both both completed and in-progress, for your API key.

Parameters

offset	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.
count	The number of archives to be returned. The maximum number of archives returned is 1000.
sessionId	The session ID.

Returns

A List of Archive objects.

Returns a List of Stream objects, representing streams that are in-progress, for the session ID.

Parameters

sessionId

The session ID corresponding to the session.

Returns

A List of Stream objects.

Send DTMF digits to all participants in an active OpenTok session or to a specific client connected to that session.

Parameters

sessionId	The session ID corresponding to the session that will receive the DTMF string.
connectionId	The connection connection ID of the client you are sending the DTMF signal to. Leave this empty to send a DTMF signal to all clients connected to the session.
digits	This is the string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).

Send DTMF digits to all participants in an active OpenTok session or to a specific client connected to that session.

Parameters

sessionId	The session ID corresponding to the session that will receive the DTMF string.
connectionId	The connection connection ID of the client you are sending the DTMF signal to. Leave this empty to send a DTMF signal to all clients connected to the session.
digits	This is the string of DTMF digits to send. This can include 0-9, '*', '#', and 'p'. A p indicates a pause of 500ms (if you need to add a delay in sending the digits).

Allows you to Dynamically change the layout of a composed archive while it's being recorded see Customizing the video layout for composed archives for details regarding customizing a layout.

Parameters

archiveId
layout

Returns

Sets the layout type for the broadcast. For a description of layout types, see Configuring the video layout for OpenTok live streaming broadcasts.

Parameters

broadcastId	The broadcast ID of the broadcasting session.
layout	The BroadcastLayout that defines layout options for the broadcast.

Set's the default request timeout (in milliseconds) for all WebRequest's sent by the SDK

Parameters

timeout

Sets the layout class list for streams in a session. Layout classes are used in the layout for composed archives and live streaming broadcasts. For more information, see Customizing the video layout for composed archives and Configuring video layout for OpenTok live streaming broadcasts.

You can set the initial layout class list for streams published by a client when you generate used by the client. See the GenerateToken method.

Parameters

sessionId	The sessionId
streams	A list of StreamsProperties that defines class lists for one or more streams in the session.

Sends a signal to clients (or a specific client) connected to an OpenTok session.

Parameters

sessionId	The OpenTok sessionId where the signal will be sent.
signalProperties	This signalProperties defines the payload for the signal.
connectionId	An optional parameter used to send the signal to a specific connection in a session.

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 uses the OpenTok Media Router (sessions with the media mode set to routed); you cannot archive sessions with the media mode set to relayed.

Note that you can have the session be automatically archived by setting the archiveMode parameter of the CreateSession method to ArchiveMode.ALWAYS.

Parameters

sessionId	The session ID of the OpenTok session to archive.
name	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 libraries.
hasVideo	Whether the archive will record video (true) or not (false). The default value is true (video is recorded). If you set both hasAudio and hasVideo to false, the call to the StartArchive method results in an error.
hasAudio	Whether the archive will record audio (true) or not (false). The default value is true (audio is recorded). If you set both hasAudio and hasVideo to false, the call to the StartArchive method results in an error.
outputMode	Whether all streams in the archive are recorded to a single file (OutputMode.COMPOSED, the default) or to individual files (OutputMode.INDIVIDUAL).
resolution	The resolution for the archive. The default for OutputMode.COMPOSED is "640x480". You cannot specify the resolution for OutputMode.INDIVIDUAL.
layout	The layout that you want to use for your archive. If type is set to LayoutType.custom you must provide a StyleSheet string to Vonage how to layout your archive.

Returns

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

Use this method to start a live streaming for an OpenTok session. This broadcasts the session to an HLS (HTTP live streaming) or to RTMP streams.

To successfully start broadcasting a session, at least one client must be connected to the session.

The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simultaneously for a session. You can only start live streaming for sessions that use the OpenTok Media Router (with the media mode set to routed); you cannot use live streaming with sessions that have the media mode set to relayed OpenTok Media Router. See The OpenTok Media Router and media modes.

For more information on broadcasting, see the Broadcast developer guide.

Parameters

sessionId	The session ID corresponding to the session.
hls	Whether to include an HLS broadcast.
rtmpList	A list of Rtmp objects, defining RTMP streams to be broadcast (up to five).
resolution	The resolution of the broadcast video. This can be set to either "640x480" or "1280x720".
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 (7,200 seconds).
layout	Specify this BroadcastLayout object to assign the initial layout type for the broadcast.

Returns

The Broadcast object. This object includes properties defining the archive, including the archive ID.

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

archiveId

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

Returns

The Archive object corresponding to the archive being STOPPED.

Use this method to stop a live broadcast of an OpenTok session. Note that broadcasts automatically stop 120 minutes after they are started.

For more information on broadcasting, see the Broadcast developer guide.

Parameters

broadcastId

The broadcast ID of the broadcasting session

Returns

The Broadcast object. This object includes properties defining the broadcast, including the broadcast ID.

The OpenTok API key passed into the OpenTok() constructor.

The OpenTok API secret passed into the OpenTok() constructor.

For internal use

Enables writing request/response details to console. Don't use in a production environment.