No description or website provided.
Python HTML JavaScript CSS
Latest commit ed85869 Aug 2, 2016 @aoberoi aoberoi committed on GitHub Merge pull request #91 from davemun/update-test-lib
Update test lib from 'sure' to 'expects'
Failed to load latest commit information.
docs Minor docs edits. May 26, 2015
sample Minor docs correction. May 27, 2015
.gitignore Docs edits. May 26, 2015
.travis.yml run tests on python3.5 Oct 22, 2015 adds contributing and development guidelines, fixes #30 Feb 11, 2015
LICENSE.txt change travis badge repo url, fix TODOs in readme, add license May 23, 2014
README.rst Update to version v2.4.1 Apr 22, 2016
requirements.txt removes nose (what is it good for?) starts using pip for installing r… Mar 25, 2014
setup.cfg add metadata May 27, 2014 Initial implementation of REST API JWT header auth. Jul 13, 2016
test_requirements.txt Update tests Aug 1, 2016
tox.ini run tests on python3.5 Oct 22, 2015


OpenTok Python SDK

The OpenTok Python SDK lets you generate sessions and tokens for OpenTok applications, and archive OpenTok sessions.

Installation using Pip (recommended):

Pip helps manage dependencies for Python projects using the PyPI index. Find more info here:

Add the opentok package as a dependency in your project. The most common way is to add it to your requirements.txt file:


Next, install the dependencies:

$ pip install -r requirements.txt



Import the package at the top of any file where you will use it. At the very least you will need the OpenTok class. Then initialize an OpenTok instance with your own API Key and API Secret.

from opentok import OpenTok

opentok = OpenTok(api_key, api_secret)

Creating Sessions

The create an OpenTok Session, use the opentok.create_session() method. There are three optional keyword parameters for this method: location which can be set to a string containing an IP address, media_mode which is a String (defined by the MediaModes class) and archive_mode which specifies whether the session will be automatically archived (always) or not (manual). This method returns a Session object. Its session_id attribute is useful when saving to a persistent store (such as a database).

# Create a session that attempts to send streams directly between clients (falling back
# to use the OpenTok TURN server to relay streams if the clients cannot connect):
session = opentok.create_session()

from opentok import MediaModes
# A session that uses the OpenTok Media Router:
session = opentok.create_session(media_mode=MediaModes.routed)

# An automatically archived session:
session = opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.always)

# A session with a location hint
session = opentok.create_session(location=u'')

# Store this session ID in the database
session_id = session.session_id

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to it. You can generate a token either by calling the opentok.generate_token(session_id) method or by calling the session.generate_token() method on a Session instance after creating it. There is a set of optional keyword parameters: role, expire_time, and data.

# Generate a Token from just a session_id (fetched from a database)
token = opentok.generate_token(session_id)
# Generate a Token by calling the method on the Session (returned from create_session)
token = session.generate_token()

from opentok import Roles
# Set some options in a token
token = session.generate_token(role=Roles.moderator,
                               expire_time=int(time.time()) + 10,

Working with Archives

You can start the recording of an OpenTok Session using the opentok.start_archive(session_id) method. This method takes an optional keyword argument name to assign a name to the archive. This method will return an Archive instance. Note that you can only start an Archive on a Session that has clients connection.

archive = opentok.start_archive(session_id, name=u'Important Presentation')

# Store this archive_id in the database
archive_id =

You can also disable audio or video recording by setting the has_audio or has_video property of the options parameter to false:

archive = opentok.start_archive(session_id, name=u'Important Presentation', has_video=False)

# Store this archive_id in the database
archive_id =

By default, all streams are recorded to a single (composed) file. You can record the different streams in the session to individual files (instead of a single composed file) by setting the output_mode parameter of the opentok.start_archive() method OutputModes.individual.

archive = opentok.start_archive(session_id, name=u'Important Presentation', output_mode=OutputModes.individual)

# Store this archive_id in the database
archive_id =

You can stop the recording of a started Archive using the opentok.stop_archive(archive_id) method. You can also do this using the archive.stop() method of an Archive instance.

# Stop an Archive from an archive_id (fetched from database)
# Stop an Archive from an instance (returned from opentok.start_archive)

To get an Archive instance (and all the information about it) from an archive ID, use the opentok.get_archive(archive_id) method.

archive = opentok.get_archive(archive_id)

To delete an Archive, you can call the opentok.delete_archive(archive_id) method or the archive.delete() method of an Archive instance.

# Delete an Archive from an archive ID (fetched from database)
# Delete an Archive from an Archive instance (returned from opentok.start_archive or

You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is done using the opentok.list_archives() method. There are two optional keyword parameters: count and offset; they can help you paginate through the results. This method returns an instance of the ArchiveList class.

archive_list = opentok.list_archive()

# Get a specific Archive from the list
archive = archive_list.items[i]

# Iterate over items
for archive in iter(archive_list):

# Get the total number of Archives for this API Key
total =

Note that you can also create an automatically archived session, by passing in ArchiveModes.always as the archive_mode parameter when you call the opentok.create_session() method (see "Creating Sessions," above).

For more information on archiving, see the OpenTok archiving programming guide.


There are two sample applications included in this repository. To get going as fast as possible, clone the whole repository and follow the Walkthroughs:


Reference documentation is available at <> and in the docs directory of the SDK.


You need an OpenTok API key and API secret, which you can obtain at

The OpenTok Python SDK requires Python 2.6, 2.7, 3.2, 3.3, or 3.4

Release Notes

See the Releases page for details about each release.

Important changes since v2.2

Changes in v2.2.1:

The default setting for the create_session() method is to create a session with the media mode set to relayed. In previous versions of the SDK, the default setting was to use the OpenTok Media Router (media mode set to routed). In a relayed session, clients will attempt to send streams directly between each other (peer-to-peer); if clients cannot connect due to firewall restrictions, the session uses the OpenTok TURN server to relay audio-video streams.

Changes in v2.2.0:

This version of the SDK includes support for working with OpenTok archives.

The OpenTok.create_session() method now includes a media_mode parameter, instead of a p2p parameter.

For details, see the reference documentation at <>.

Development and Contributing

Interested in contributing? We ❤️ pull requests! See the Development and Contribution guidelines.


See for all our support options.

Find a bug? File it on the Issues page. Hint: test cases are really helpful!