Suggestions

close search

OpenTok 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 milliseconds.
  • 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)
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

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

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.
  • 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.
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.
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, in clients using the OpenTok.js 2.2 library, a moderator can call the forceUnpublish() and forceDisconnect() method of the Session object.
  • 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_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’

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.

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.
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, in clients using the OpenTok.js 2.2 library, a moderator can call the forceUnpublish() and forceDisconnect() method of the Session object.

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, in clients using the OpenTok.js 2.2 library, a moderator can call the forceUnpublish() and forceDisconnect() method of the Session object.
  • 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()