Vonage Video API Python SDK Reference

opentok.archives module

class opentok.archives.Archive(sdk, values)

Bases: object

Represents an archive of an OpenTok session.

Variables:

created_at – The time at which the archive was created, in milliseconds since the UNIX epoch. duration – The duration of the archive, in seconds. has_audio – Boolean value set to true when the archive contains an audio track, and set to false otherwise. has_video – Boolean value set to true when the archive contains a video track, and set to false otherwise. id – The archive ID. name – The name of the archive. If no name was provided when the archive was created, this is set to null. output_mode – Whether all streams in the archive are recorded to a single file (OutputModes.composed) or to individual files (OutputModes.individual). partner_id – The API key associated with the archive. reason – For archives with the status “stopped” or “failed”, this string describes the reason the archive stopped (such as “maximum duration exceeded”) or failed. session_id – The session ID of the OpenTok session associated with this archive. size – The size of the MP4 file. For archives that have not been generated, this value is set to 0. status – The status of the archive, which can be one of the following: “available” – The archive is available for download from the OpenTok cloud. “expired” – The archive is no longer available for download from the OpenTok cloud. “failed” – The archive recording failed. “paused” – The archive is in progress and no clients are publishing streams to the session. When an archive is in progress and any client publishes a stream, the status is “started”. When an archive is paused, nothing is recorded. When a client starts publishing a stream, the recording starts (or resumes). If all clients disconnect from a session that is being archived, the status changes to “paused”, and after 60 seconds the archive recording stops (and the status changes to “stopped”). “started” – The archive started and is in the process of being recorded. “stopped” – The archive stopped recording. “uploaded” – The archive is available for download from the the upload target Amazon S3 bucket or Windows Azure container that you set at the OpenTok dashboard. url – The download URL of the available MP4 file. This is only set for an archive with the status set to “available”; for other archives, (including archives with the status “uploaded”) this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, call the Archive.listArchives() or OpenTok.getArchive() method.

attrs()

Returns a dictionary of the archive’s attributes.

delete()

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.

json()

Returns a JSON representation of the archive.

stop()

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.

class opentok.archives.ArchiveList(sdk, values)

Bases: object

attrs()

json()

class opentok.archives.OutputModes

Bases: enum.Enum

List of valid settings for the output_mode parameter of the OpenTok.start_archive() method.

composed = None

All streams in the archive are recorded to a single (composed) file.

individual = None

Each stream in the archive is recorded to an individual file.

opentok.archives.dthandler(obj)

opentok.endpoints module

class opentok.endpoints.Endpoints(api_url, api_key)

Bases: object

For internal use. Class that provides the endpoint urls

archive_url(archive_id=None)

broadcast_url(broadcast_id=None, stop=False, layout=False)

this method returns urls for working with broadcast

dial_url()

this method returns the url to initialize a SIP call

force_disconnect_url(session_id, connection_id)

this method returns the force disconnect url endpoint

get_stream_url(session_id, stream_id=None)

this method returns the url to get streams information

session_url()

set_archive_layout_url(archive_id)

this method returns the url to set the archive layout

set_stream_class_lists_url(session_id)

this method returns the url to set the stream class list

signaling_url(session_id, connection_id=None)

opentok.exceptions module

exception opentok.exceptions.ArchiveError

Bases: opentok.exceptions.OpenTokException

Indicates that there was a archive specific problem, probably the status of the requested archive is invalid.

exception opentok.exceptions.AuthError

Bases: opentok.exceptions.OpenTokException

Indicates that the problem was likely with credentials. Check your API key and API secret and try again.

exception opentok.exceptions.BroadcastError

Bases: opentok.exceptions.OpenTokException

Indicates that data in your request data is invalid JSON. It may also indicate that you passed in invalid layout options. Or you have exceeded the limit of five simultaneous RTMP streams for an OpenTok session. Or you specified and invalid resolution. Or The broadcast has already started for the session

exception opentok.exceptions.ForceDisconnectError

Bases: opentok.exceptions.OpenTokException

Indicates that there was a force disconnect specific problem: One of the arguments is invalid or the client specified by the connectionId property is not connected to the session

exception opentok.exceptions.GetStreamError

Bases: opentok.exceptions.OpenTokException

Indicates that the data in the request is invalid, or the session_id or stream_id are invalid

exception opentok.exceptions.NotFoundError

Bases: opentok.exceptions.OpenTokException

Indicates that the element requested was not found. Check the parameters of the request.

exception opentok.exceptions.OpenTokException

Bases: exceptions.Exception

Defines exceptions thrown by the OpenTok SDK.

exception opentok.exceptions.RequestError

Bases: opentok.exceptions.OpenTokException

Indicates an error during the request. Most likely an error connecting to the OpenTok API servers. (HTTP 500 error).

exception opentok.exceptions.SetStreamClassError

Bases: opentok.exceptions.OpenTokException

Indicates that there is invalid data in the JSON request. It may also indicate that invalid layout options have been passed

exception opentok.exceptions.SignalingError

Bases: opentok.exceptions.OpenTokException

Indicates that there was a signaling specific problem, one of the parameter is invalid or the type|data string doesn’t have a correct size

exception opentok.exceptions.SipDialError

Bases: opentok.exceptions.OpenTokException

Indicates that there was a SIP dial specific problem: The Session ID passed in is invalid or you attempt to start a SIP call for a session that does not use the OpenTok Media Router.

opentok.opentok module

class opentok.opentok.ArchiveModes

Bases: enum.Enum

List of valid settings for the archive_mode parameter of the OpenTok.create_Session() method.

always = None

The session will be automatically archived.

manual = None

The session will be manually archived.

class opentok.opentok.MediaModes

Bases: enum.Enum

List of valid settings for the mediaMode parameter of the OpenTok.create_session() method.

relayed = None

The session will attempt to transmit streams directly between clients. If two clients cannot send and receive each others’ streams, due to firewalls on the clients’ networks, their streams will be relayed using the OpenTok TURN Server.

routed = None

The session will transmit streams using the OpenTok Media Server.

class opentok.opentok.OpenTok(api_key, api_secret, api_url='https://api.opentok.com', timeout=None)

Bases: object

Use this SDK to create tokens and interface with the server-side portion of the Opentok API.

TOKEN_SENTINEL = 'T1=='

For internal use.

create_session(location=None, media_mode=<MediaModes.relayed: u'enabled'>, archive_mode=<ArchiveModes.manual: u'manual'>)

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() 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 or the OpenTok dashboard.

Parameters:

media_mode (String) – Determines 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 media_mode property 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 audio-video streams. The OpenTok Media Router provides the following benefits: The OpenTok Media Router can decrease bandwidth usage in multiparty sessions. (When the mediaMode property is set to MediaMode.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 (see https://tokbox.com/platform/fallback). 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 (see http://tokbox.com/platform/archiving). archive_mode (String) – Whether the session is automatically archived (ArchiveModes.always) or not (ArchiveModes.manual). By default, the setting is ArchiveModes.manual, and you must call the start_archive() method of the OpenTok object to start archiving. To archive the session (either automatically or not), you must set the media_mode parameter to MediaModes.routed. archive_name (String) – Indicates the archive name for all the archives in auto archived session. A session that begins with archive mode 'always' will be using this archive name for all archives of that session. Passing 'archive_name' with archive mode 'manual' will cause an error response. archive_resolution (String) – Indicates the archive resolution for all the archives in auto archived session. Valid values are '640x480', '480x640', '1280x720', '720x1280', '1920x1080' and '1080x1920'. A session that begins with archive mode 'always' will be using this resolution for all archives of that session. Passing 'archive_resolution' with archive mode 'manual' will cause an error response. 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. e2ee (Boolean) – Whether to enable end-to-end encryption for a routed session (see https://tokbox.com/developer/guides/end-to-end-encryption.

Return type:

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

delete_archive(archive_id)

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:	archive_id (String) – The archive ID of the archive to be deleted.

dial(session_id, token, sip_uri, options=[])

Use this method to connect a SIP platform to an OpenTok session. The audio from the end of the SIP call is added to the OpenTok session as an audio-only stream. The OpenTok Media Router mixes audio from other streams in the session and sends the mixed audio to the SIP endpoint

Parameters:	session_id (String) – The OpenTok session ID for the SIP call to join token (String) – The OpenTok token to be used for the participant being called sip_uri (String) – The SIP URI to be used as destination of the SIP call initiated from

OpenTok to the SIP platform

Parameters:

options optional (Dictionary) – Aditional options with the following properties: String ‘from’: The number or string that will be sent to the final SIP number as the caller Dictionary ‘headers’: Defines custom headers to be added to the SIP INVITE request initiated from OpenTok to the SIP platform Dictionary ‘auth’: Contains the username and password to be used in the the SIP INVITE request for HTTP digest authentication, if it is required by the SIP platform For example: ‘auth’: { ‘username’: ‘username’, ‘password’: ‘password’ } Boolean ‘secure’: A Boolean flag that indicates whether the media must be transmitted encrypted (true) or not (false, the default)

Return type:

A SipCall object, which contains data of the SIP call: id, connectionId and streamId

force_disconnect(session_id, connection_id)

Sends a request to disconnect a client from an OpenTok session

Parameters:	session_id (String) – The session ID of the OpenTok session from which the

client will be disconnected

Parameters:	connection_id (String) – The connection ID of the client that will be disconnected

generate_token(session_id, role=<Roles.publisher: u'publisher'>, expire_time=None, data=None, initial_layout_class_list=[])

Generates a token for a given session.

Parameters:

session_id (String) – The session ID of the session to be accessed by the client using the token. role (String) – The role for the token. Valid values are defined in the Role class: Roles.subscriber – A subscriber can only subscribe to streams. Roles.publisher – A publisher can publish streams, subscribe to streams, and signal. (This is the default value if you do not specify a role.) Roles.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. expire_time (int) – The expiration time of the token, in seconds since the UNIX epoch. The maximum expiration time is 30 days after the creation time. The default expiration time is 24 hours after the token 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 (list) – 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

Return type:

The token string.

get_archive(archive_id)

Gets an Archive object for the given archive ID.

Parameters:	archive_id (String) – The archive ID.
Return type:	The Archive object.

get_archives(offset=None, count=None, session_id=None)

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

Parameters:

int – offset 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. int – count Optional. The number of archives to be returned. The maximum number of archives returned is 1000. string – session_id Optional. Used to list archives for a specific session ID.

Return type:

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

get_broadcast(broadcast_id)

Use this method to get details on a broadcast that is in-progress.

Parameters:	broadcast_id (String) – The ID of the broadcast you want to stop
Rtype A Broadcast object, which contains information of the broadcast:
	id, sessionId

projectId, createdAt, updatedAt, resolution, broadcastUrls and status

get_stream(session_id, stream_id)

Returns an Stream object that contains information of an OpenTok stream:

-id: The stream ID -videoType: “camera” or “screen” -name: The stream name (if one was set when the client published the stream) -layoutClassList: It’s an array of the layout classes for the stream

headers()

For internal use.

json_headers()

For internal use.

list_archives(offset=None, count=None, session_id=None)

New method to get archive list, it’s alternative to ‘get_archives()’, both methods exist to have backwards compatible

list_streams(session_id)

Returns a list of Stream objects that contains information of all the streams in a OpenTok session, with the following attributes:

-count: An integer that indicates the number of streams in the session -items: List of the Stream objects

proxies

set_archive_layout(archive_id, layout_type, stylesheet=None)

Use this method to change the layout of videos in an OpenTok archive

Parameters:	archive_id (String) – The ID of the archive that will be updated layout_type (String) – The layout type for the archive. Valid values are:

‘bestFit’, ‘custom’, ‘horizontalPresentation’, ‘pip’ and ‘verticalPresentation’

Parameters:	stylesheet optional (String) – CSS used to style the custom layout.

Specify this only if you set the type property to ‘custom’

set_broadcast_layout(broadcast_id, layout_type, stylesheet=None)

Use this method to change the layout type of a live streaming broadcast

Parameters:	broadcast_id (String) – The ID of the broadcast that will be updated layout_type (String) – The layout type for the broadcast. Valid values are:

‘bestFit’, ‘custom’, ‘horizontalPresentation’, ‘pip’ and ‘verticalPresentation’

Parameters:	stylesheet optional (String) – CSS used to style the custom layout.

Specify this only if you set the type property to ‘custom’

set_stream_class_lists(session_id, payload)

Use this method to change layout classes for OpenTok streams. The layout classes define how the streams are displayed in the layout of a composed OpenTok archive

Parameters:	session_id (String) – The ID of the session of the streams that will be updated payload (List) – A list defining the class lists to apply to the streams.

Each element in the list is a dictionary with two properties: ‘id’ and ‘layoutClassList’. The ‘id’ property is the stream ID (a String), and the ‘layoutClassList’ is an array of class names (Strings) to apply to the stream. For example:

payload = [

{‘id’: ‘7b09ec3c-26f9-43d7-8197-f608f13d4fb6’, ‘layoutClassList’: [‘focus’]}, {‘id’: ‘567bc941-6ea0-4c69-97fc-70a740b68976’, ‘layoutClassList’: [‘top’]}, {‘id’: ‘307dc941-0450-4c09-975c-705740d08970’, ‘layoutClassList’: [‘bottom’]}

]

signal(session_id, payload, connection_id=None)

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

Parameters:	session_id (String) – The session ID of the OpenTok session that receives the signal payload (Dictionary) – Structure that contains both the type and data fields. These

correspond to the type and data parameters passed in the client signal received handlers

Parameters:	connection_id (String) – The connection_id parameter is an optional string used to

specify the connection ID of a client connected to the session. If you specify this value, the signal is sent to the specified client. Otherwise, the signal is sent to all clients connected to the session

start_archive(session_id, has_audio=True, has_video=True, name=None, output_mode=<OutputModes.composed: u'composed'>, resolution=None)

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. 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.js library. has_audio (Boolean) – if set to True, an audio track will be inserted to the archive. has_audio is an optional parameter that is set to True by default. If you set both has_audio and has_video to False, the call to the start_archive() method results in an error. has_video (Boolean) – if set to True, a video track will be inserted to the archive. has_video is an optional parameter that is set to True by default. output_mode (OutputModes) – Whether all streams in the archive are recorded to a single file (OutputModes.composed, the default) or to individual files (OutputModes.individual). resolution (Optional) (String) – The resolution of the archive, either “640x480” (the default) or “1280x720”. This parameter only applies to composed archives. If you set this parameter and set the output_mode parameter to OutputModes.individual, the call to the start_archive() method results in an error.

Return type:

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

start_broadcast(session_id, options)

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. 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

Parameters:	session_id (String) – The session ID of the OpenTok session you want to broadcast options, with the following properties (Dictionary) – Dictionary ‘layout’ optional: Specify this to assign the initial layout type for the broadcast. Valid values for the layout property are “bestFit”, “custom”, “horizontalPresentation”, “pip” and “verticalPresentation”. If you specify a “custom” layout type, set the stylesheet property of the layout object to the stylesheet. If you do not specify an initial layout type, the broadcast stream uses the Best Fit layout type Integer ‘maxDuration’ optional: 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 4 hours (14,400 seconds). Dictionary ‘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. For each RTMP stream, specify ‘serverUrl’ (the RTMP server URL), ‘streamName’ (the stream name, such as the YouTube Live stream name or the Facebook stream key), and (optionally) ‘id’ (a unique ID for the stream) String ‘resolution’ optional: The resolution of the broadcast, either “640x480” (SD, the default) or “1280x720” (HD)
Rtype A Broadcast object, which contains information of the broadcast:
	id, sessionId

projectId, createdAt, updatedAt, resolution, status and broadcastUrls

stop_archive(archive_id)

Stops an OpenTok archive that is being recorded.

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

@param [String] archive_id The archive ID of the archive you want to stop recording.

Return type:	The Archive object corresponding to the archive being stopped.

stop_broadcast(broadcast_id)

Use this method to stop a live broadcast of an OpenTok session

Parameters:	broadcast_id (String) – The ID of the broadcast you want to stop
Rtype A Broadcast object, which contains information of the broadcast:
	id, sessionId

projectId, createdAt, updatedAt and resolution

class opentok.opentok.Roles

Bases: enum.Enum

List of valid roles for a token.

moderator = None

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.

publisher = None

A publisher can publish streams, subscribe to streams, and signal

subscriber = None

A subscriber can only subscribe to streams.

opentok.session module

class opentok.session.Session(sdk, session_id, **kwargs)

Bases: object

Represents an OpenTok session.

Use the OpenTok.create_session() method to create an OpenTok session. Use the session_id property of the Session object to get the session ID.

Variables:	session_id (String) – The session ID.

generate_token(**kwargs)

Generates a token for the session.

Parameters:

role (String) – The role for the token. Valid values are defined in the Role class. Roles.subscriber – A subscriber can only subscribe to streams. Roles.publisher – A publisher can publish streams, subscribe to streams, and signal. (This is the default value if you do not specify a role.) Roles.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. expire_time (int) – The expiration time of the token, in seconds since the UNIX epoch. The maximum expiration time is 30 days after the creation time. The default expiration time is 24 hours after the token 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.

Return type:

The token string.

opentok.stream module

class opentok.stream.Stream(kwargs)

Bases: object

Represents an OpenTok stream

attrs()

Returns a dictionary of the Stream’s attributes.

json()

Returns a JSON representation of the Stream.

opentok.stream.dthandler(obj)

opentok.streamlist module

class opentok.streamlist.StreamList(values)

Bases: object

Represents a list of OpenTok stream objects

json()