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

# Create the virtual environmentpython3 -m venv venv# Activate the virtual environment in Mac/Linux. ./venv/bin/activate# Or on Windows Command Promptvenv\Scripts\activate

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:

vonage>=4.0.0

Next, install the dependencies:

pip install -r requirements.txt

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.

from vonage import Auth, Vonage

vonage_client = Vonage(
    Auth(
        application_id=VONAGE_APPLICATION_ID,
        private_key=VONAGE_APPLICATION_PRIVATE_KEY_PATH,
    )
)

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

from vonage_video.models import VonageVideoRequestModel

vonage_client.video.name_of_video_api_method(VonageVideoRequestModel(...))

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

from vonage_video.models import VideoSession

# Create a session
session_info: VideoSession = vonage_client.video.create_session()

# A session that doesn't use the Vonage Media Router and instead sends 
# information between peers directly
from vonage_video.models import SessionOptions

options = SessionOptions(media_mode='relayed')
session_info = vonage_client.video.create_session(options)

# An automatically archived session:
options = SessionOptions(media_mode='routed', archive_mode='always')
session_info = vonage_client.video.create_session(options)

# A session with a location hint
options = SessionOptions(location='12.34.56.78')
session_info = vonage_client.video.create_session(options)

# Extract the session ID to be stored in a database
session_id = session_info.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 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.

from vonage_video.models import TokenOptions

# Generate a token from just a session_id (fetched from a database)
token = vonage_client.video.generate_client_token(TokenOptions(session_id=session_id))

# Specify some options and generate a token
token = vonage_client.video.generate_client_token(
    TokenOptions(
        session_id='session-id',
        role='moderator',
        connection_data='connection-data',
        initial_layout_class_list=['focus'],
        jti='4cab89ca-b637-41c8-b62f-7b9ce10c3971',
        subject='video',
        iat=123456789,
    )
)

Working with Archives

Important: You can only archive sessions that use the Vonage Video Media Router (sessions with the media mode set to routed).

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.

from vonage_video.models import Archive, CreateArchiveRequest

# All fields are optional except session_id!
archive_options = CreateArchiveRequest(session_id=session_id)

archive: Archive = vonage_client.video.start_archive(archive_options)

# Get the archive_id to store in a database
archive_id = archive.id

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

archive_options = CreateArchiveRequest(
    session_id=session_id,
    has_audio=False,
    has_video=True,
)

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

archive_options = CreateArchiveRequest(
    session_id=session_id,
    output_mode='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.

Warning: This value cannot be set for 'individual' output mode, an error will be thrown.

archive_options = CreateArchiveRequest(session_id=session_id, resolution='1280x720')

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

from vonage_video.models import Archive

# Stop an archive from an archive_id (fetched from database)
archive: Archive = vonage_client.video.stop_archive(archive_id)

print(archive.status)

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

archive: Archive = vonage_client.video.get_archive(archive_id)

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

# Delete an Archive from an archive ID (fetched from database)
vonage_client.video.delete_archive(archive_id)

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

from vonage_video.models import Archive
archive_list, count, next = vonage_client.video.list_archives()

# Get a specific Archive from the list
archive: Archive = archive_list[0]

# Get dict representations of all the archives
print([archive.model_dump() for archive in archives])


# Iterate over items
for archive in archive_list:
    ...

# Get the total number of Archives for this App ID
print(count)

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:

from vonage_video.models import Archive, ComposedLayout, LayoutType

archive: Archive = vonage_client.video.change_archive_layout(
    archive_id='archive-id',
    layout=ComposedLayout(type=LayoutType.BEST_FIT, screenshare_type=LayoutType.PIP),
)

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:

vonage_client.video.change_archive_layout(archive_id='archive-id',
    layout=ComposedLayout(
        type=LayoutType.CUSTOM,
        stylesheet='stream.instructor {position: absolute; width: 100%;  height:50%;}'
    )
)

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:

from vonage_video.models import AddStreamRequest
params = AddStreamRequest(stream_id='stream-id')
# Add a stream to the archive
vonage_client.video.add_stream_to_archive(archive_id='archive-id', params)

# Add a stream to the archive but specify audio only
vonage_client.video.add_stream_to_archive(
    archive_id='archive-id',
    AddStreamRequest(stream_id='stream-id', has_video=False)
)

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

archive_id = 'archive-id'
stream_id = 'stream-id'
vonage_client.video.remove_stream_from_archive(archive_id, stream_id)

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

connection_id = '2a84cd30-3a33-917f-9150-49e454e01572'

# To send a signal to everyone in the session:
from vonage_video.models import SignalData

vonage_client.video.send_signal(session_id, SignalData(type='msg', data='Hello, World!'))

# To send a signal to a specific connection in the session:
vonage_client.video.send_signal(
    session_id, 
    SignalData(
        type='msg',
        data='Hello, World!')
    ),
    connection_id='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.

session_id = 'session-id'
stream_id = 'stream-id'

# To get stream info:
from vonage_video.models import StreamInfo
stream: StreamInfo = vonage_client.video.get_stream(session_id, stream_id)

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.

# Get all streams in a session
from vonage_video.models import StreamInfo
 
stream_list: list[StreamInfo] = vonage_client.video.list_streams(session_id)

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:

from vonage_video.models.stream import StreamLayout, StreamLayoutOptions

layout = StreamLayoutOptions(
    items=[
        StreamLayout(
            id='stream_id-0', layout_class_list=['full'],
            id='stream_id-1', layout_class_list=['focus']
        )
    ]
)

vonage_client.video.change_stream_layout(
    session_id='session-id',
    stream_layout_options=layout,
)

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

vonage_client.video.mute_stream(session_id, stream_id)

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

vonage_client.video.mute_all_streams(session_id, excluded_stream_ids=['123', '456', '789'])

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

vonage_client.video.disable_mute_all_streams(session_id)

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.

vonage_client.video.disconnect_client('session-id', 'connection-id')

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.

from vonage_video.models import InitiateSipRequest, SipAuth, SipCall, SipOptions, TokenOptions

sip_request_params = InitiateSipRequest(
    session_id='session-id,
    token='token,
    sip=SipOptions(uri=f'sip:{vonage_number}@sip.nexmo.com;transport=tls'),
)

sip_call: SipCall = vonage_client.video.initiate_sip_call(sip_request_params)
print(sip_call)

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

sip_options = SipOptions(
    uri=f'sip:{vonage_number}@sip.nexmo.com;transport=tls',
    from_=f'test@vonage.com',
    headers={'header_key': 'header_value'},
    auth=SipAuth(username='asdfqwer', password='1234qwerasdf'),
    secure=False,
    video=False,
    observe_force_mute=True,
)

# Call the method with aditional options
sip_request_params = InitiateSipRequest(
    session_id='session-id,
    token='token,
    sip=sip_options
)

sip_call: SipCall = vonage_client.video.initiate_sip_call(sip_request_params)
print(sip_call)

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.

from vonage_video.models import (
    Broadcast,
    BroadcastHls,
    BroadcastOutputSettings,
    BroadcastRtmp,
    ComposedLayout,
    CreateBroadcastRequest,
    LayoutType,
    StreamMode,
    VideoResolution,
)

broadcast_options = CreateBroadcastRequest(
    session_id=session_id,
    layout=ComposedLayout(
        type=LayoutType.BEST_FIT, screenshare_type=LayoutType.HORIZONTAL_PRESENTATION
    ),
    max_duration=3600,
    outputs=BroadcastOutputSettings(
        hls=BroadcastHls(dvr=True, low_latency=False),
        rtmp=[
            BroadcastRtmp(
                id='test',
                server_url='rtmp://a.rtmp.youtube.com/live2',
                stream_name='stream-key',
            )
        ],
    ),
    resolution=VideoResolution.RES_1280x720,
    stream_mode=StreamMode.MANUAL,
    multi_broadcast_tag='test-broadcast',
    max_bitrate=1_000_000,
)


broadcast: Broadcast = vonage_client.video.start_broadcast(broadcast_options)
print(broadcast.model_dump())

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

# Stop a broadcast
from vonage_video.models import Broadcast

broadcast: Broadcast = vonage_client.video.stop_broadcast('BROADCAST_ID')
print(broadcast.model_dump())

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

broadcast_id = 'broadcast-id'

# Get broadcast details
broadcast: Broadcast = vonage_client.video.get_broadcast(broadcast_id)

broadcast_id = broadcast.id # All other attributes can be accessed from the broadcast model too

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

from vonage_video.models import Broadcast, ComposedLayout, LayoutType

# Valid values to 'type' are: 'bestFit', 'custom', 'horizontalPresentation',
# 'pip' and 'verticalPresentation' 
broadcast: Broadcast = vonage_client.video.change_broadcast_layout(
    'broadcast-id',
    layout=ComposedLayout(type=LayoutType.BEST_FIT),
)
print(response.model_dump())

# if you specify a 'custom' layout type, set the stylesheet parameter:
broadcast: Broadcast = vonage_client.video.change_broadcast_layout(
    'broadcast-id',
    layout=ComposedLayout(
        type=LayoutType.CUSTOM,
        stylesheet='stream.instructor {position: absolute; width: 100%;  height:50%;}'
    ),
)
print(response.model_dump())

Working with Captions

You can enable captions in a Vonage Video API session with

from vonage_video.models import CaptionsData, CaptionsOptions

options = CaptionsOptions(
        session_id='session-id',
        token='token-id,
    )

captions: CaptionsData = vonage_client.video.start_captions(options)
print(response.model_dump())

You can disable captions like this:

vonage_client.video.stop_captions(
    CaptionsData(captions_id='captions-id')
)

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

from vonage_video.models import (
    ExperienceComposerOptions,
    ExperienceComposerProperties,
    VideoResolution,
)

ec_options = ExperienceComposerOptions(
    session_id='session-id',
    token='token',
    url='https://developer.vonage.com',
    max_duration=3600,
    resolution=VideoResolution.RES_1280x720,
    properties=ExperienceComposerProperties(name='vonage experience composer'),
)

experience_composer: ExperienceComposer = (
    vonage_client.video.start_experience_composer(ec_options)
)
print(experience_composer.model_dump())

You can stop an Experience Composer session with

vonage_client.video.stop_experience_composer('experience-composer-id')

and get information about an Experience Composer session with

experience_composer: ExperienceComposer = vonage_client.video.get_experience_composer(
    'experience-composer-id'
)

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

experience_composers, count, next_page_offset = vonage_client.video.list_experience_composers()

print([ec.model_dump() for ec in experience_composers])

# Optionally, you can use a filter
from vonage_models import ListExperienceComposersFilter

experience_composers, count, next_page_offset = vonage_client.video.list_experience_composers(
    filter=ListExperienceComposersFilter(offset=0, page_size=3)
)

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:

from vonage_video.models import (
    AudioConnectorData,
    AudioConnectorOptions,
    AudioConnectorWebSocket,
)

options = AudioConnectorOptions(
    session_id='session-id',
    token='token',
    websocket=AudioConnectorWebSocket(
        uri='wss://example.com/websocket', audio_rate=16000
    ),
)
audio_connector: AudioConnectorData = vonage_client.video.start_audio_connector(options)

Release Notes

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