Python Server SDK

The Vonage Video Python SDK provides methods for:

• Creating sessions
• Generating tokens for Vonage Video applications
• Sending signals to clients connected to a session
• Creating and managing archives of Vonage Video sessions
• Moderating users in sessions
• Working with SIP Interconnect
• Creating and managing live streaming broadcasts of Vonage Video sessions
• Working with captions
• Rendering multiple objects into one video stream (with the Experience Composer API)
• Streaming audio to a WebSocket

Requirements

You'll need to create an application in the Vonage Developer Dashboard and download the private key. These items will be used to authenticate your requests.

Create a Python Virtual Environment

It's strongly recommended to use a Python Virtual Environment for working with the Vonage Python SDK.

You can do this with

Installation using pip (recommended)

pip helps manage dependencies for Python projects using the Python Package Index. Find more info here: http://www.pip-installer.org/en/latest.

Add the vonage package as a dependency for your project by adding it to your requirements.txt file:

Next, install the dependencies:

Usage

In order to use the Vonage Video API, you need to instantiate a top-level vonage.Vonage client through which you can access Video API methods.

Most Video API methods require some input data. You provide this by passing in Pydantic data models, which you import from vonage_video.models. Read on to see examples of this in practice.

All API methods and data models have docstrings which explain required and optional arguments. Methods also describe return types.

Initializing

Import and initialize a vonage.Vonage object at the top of any file where you want to use the Vonage Video API.

Create an instance of the Vonage class and pass in an instance of the Auth class. Initialise the Vonage object with your application ID and private key.

Instantiating the Vonage class also creates a Video class instance. You can access Video API methods, passing in pydantic models like this:

Creating Sessions

To create a Vonage Video Session, use the vonage_client.video.create_session method. There are optional keyword parameters for this method, which you pass in via a SessionOptions object, which has a docstring explaining each.

This method returns a vonage_video.models.VideoSession object. Its session_id attribute is useful when saving to a persistent store (such as a database).

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 by calling the vonage_client.video.generate_client_token(session_id) method. There is a set of optional parameters: scope, role, connection_data, initial_layout_class_list, jti, subject, iat, exp and acl.

To use these, add them to a TokenOptions model and pass it into the generate_client_token method.

Working with Archives

You can start the recording of a Vonage Video Session using the vonage_client.video.start_archive method. You can supply optional keyword arguments to the method, e.g. name to assign a name to the archive. This method will return a Pydantic data model. Note that you can only start an Archive on a Session that has clients connected to it.

You can also disable audio or video recording by setting the has_audio or has_video attribute of the CreateArchiveRequest model to False:

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 CreateArchiveRequest model to 'individual'.

Composed archives (output_mode='composed') have an optional resolution parameter. If no value is supplied the Vonage Video platform will use the default resolution "640x480". You can set this to "1280x720" by setting the resolution parameter of the CreateArchiveRequest method.

You can stop the recording of a started archive using the vonage_client.video.stop_archive(archive_id) method.

To get all the information about an archive from an archive ID, use the vonage_client.video.get_archive(archive_id) method.

To delete an Archive, you can call the vonage_client.video.delete_archive(archive_id) method.

You can also get a list of all the Archives you've created (up to 1000) with your Application ID. This is done using the vonage_client.video.list_archives() method. You can optionally filter on parameters, which can help you paginate through the results. This method returns a tuple containing a list of archive objects, the total count of archives and the required offset value for the next page, if applicable. i.e. (archives: list[Archive], count: int, next_page_offset: Optional[int]).

Note that you can also create an automatically archived session, by passing in 'archive_mode': 'always' to the SessionOptions object when you call the vonage_client.video.create_session method (see "Creating Sessions" above).

For composed archives, you can change the layout dynamically, using the vonage_client.video.change_archive_layout method:

Setting the layout of composed archives is optional. By default, composed archives use the best fit layout. Other valid values are: custom, horizontalPresentation, pip and verticalPresentation, though they are tied to the LayoutType enum. If you specify a custom layout type, set the stylesheet parameter:

For other layout types, do not set the stylesheet property. For more information see Customizing the video layout for composed archives.

You can manually add a stream to an archive with the vonage_client.video.add_stream_to_archive method:

You can also remove specific streams from an archive with the vonage_client.video.remove_stream_from_archive method:

For more information on archiving, see the Vonage Video archiving developer guide.

Sending Signals

Once a Session is created, you can send signals to everyone in the session or to a specific connection. You can send a signal by calling the send_signal method of the Video class. You can call the method with the parameter connection_id to send a signal to a specific connection, e.g. video.send_signal(session_id, data, connection_id='some_connection_id').

Working with Streams

You can get information about a stream by calling the get_stream(session_id, stream_id) method of the Video class.

The method returns a StreamInfo model that contains information about a Vonage Video stream.

You can get information about all the streams in a session by calling the list_streams(session_id) method of the Video class. The method returns a list of StreamInfo objects.

You can change the layout classes for a Vonage Video stream (how the stream is displayed in a Vonage Video archive) with the change_stream_layout method of the Video class:

You can also mute a specific stream with the video.mute_stream method of the Video class:

Or mute all streams (except specified streams that are excluded from the operation) with the video.mute_all_streams method of the Video class:

Unmute streams by calling the vonage_client.video.disable_mute_all_streams method:

Session Moderation

Your application server can disconnect a client from a Vonage Video session by calling the disconnect_client(session_id, connection_id) method of the Video class.

Working with SIP Interconnect

You can connect your SIP platform to a Vonage Video session, the audio from your end of the SIP call is added to the Vonage Video session as an audio-only stream. The Vonage Video Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint.

The method also supports additional options to establish the SIP call. Pass them in to the SipOptions model with the URI:

For more information, including technical details and security considerations, see the Vonage Video SIP interconnectdeveloper guide.

Working with Broadcasts

Vonage Video broadcast lets you share live Vonage Video sessions with many viewers.

You can use the vonage_client.video.start_broadcast method to start a live streaming broadcast for a Vonage Video session. This broadcasts the session to an HLS (HTTP live stream) 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 Vonage Video Media Router; you cannot use live streaming with sessions that have the media mode set to relayed.

You can stop a started Broadcast using the vonage_client.video.stop_broadcast(broadcast_id) method.

You can get details on a broadcast that is in-progress using the method vonage_client.video.get_broadcast(broadcast_id).

You can dynamically change the layout type of a live streaming broadcast.

Working with Captions

You can enable captions in a Vonage Video API session with

You can disable captions like this:

Working with the Experience Composer API

It is possible to render multiple objects into one video stream with the Experience Composer API. You can use this to capture the entire experience of your web application. You can use the Experience Composer API for composite recordings, broadcasts and synchronized group viewing.

Start an Experience Composer session with

You can stop an Experience Composer session with

and get information about an Experience Composer session with

You can also get a list of all Experience Composer objects:

Streaming Audio to a WebSocket

The Audio Connector API starts an audio connector in a Vonage Video API session that connects audio streams to a specified WebSocket URI.

Start an Audio Connector like this:

Release Notes

See the Python SDK changelog page for details about each release.