Vonage Video Transition Guide for Python

Transitioning from `Opentok-Python-SDK` to `vonage-python-sdk`

Introduction

Purpose

The goal of this document is to provide a starting point for transitioning from the OpenTok Python Server SDK to the Vonage Python Server SDK. There is a more specific and detailed migration guide available at this link.

Scope

This document assumes that you are using at least version 3.9.0 or later of the OpenTok Python SDK.

The Video API is fully supported in the Vonage Python SDK. You should use the latest full release version of the SDK, which can be found on GitHub or PyPI.

Assumptions

This guide is intended to be followed by a professional software engineer. At least a basic level of competency with Python, common Python developer tools, build systems and Git (or other version control system) is assumed.

You should be comfortable reading and writing Python code, managing project dependencies and deploying and executing a Python project. It is recommended to use a virtual Python environment.

An introduction to the Python language and associated tooling is well beyond the scope of this document.

Resources

The following links are useful for further reading to accompany this document and for reference to anything not covered in this document:

Vonage

TokBox

Planning Your Migration

Before transitioning from OpenTok to Vonage Video, you should consider the scale of the task to set realistic expectations.

Evaluate Impact

The first question to ask is: how much of your application's code depends on the OpenTok SDK?

Make a list of all the files in which the SDK is directly used. That is, any .py file which contains an import opentok or from opentok import... statement. You can search through the files in your project using an IDE or command-line tool to identify the affected files.

Timeline

Take into account the time required to complete the transition. This will depend on your experience with the project and its impact, as well as testing. It is crucial to have a good test suite in place so that you can verify equivalence between the OpenTok and Vonage Video SDKs. The time it will take to complete the transition is roughly proportional to the number of places where the OpenTok SDK is used in your code, as well as the variety of features used. Some API calls will be simpler to replace than others.

Versioning

OpenTok and Vonage Video are two different products - This makes a progressive migration impossible.

You should create a new branch in your version control system for the transition, so that you can make changes gradually and frequently without breaking the existing project. You can also use the existing project's tests as an oracle for correctness, if they're comprehensive. Ideally, you should only merge the transition branch into the main branch once you have completed the conversion.

Key Changes and Considerations

Package Update

Firstly, you'll need to install or update the Vonage Python SDK in your project. You can do that by running pip install -U vonage.

For a gradual migration, you can include both OpenTok and Vonage dependencies in your project, however we strongly recommend that this should be for testing only rather than deployments to production.

Authentication Changes

Authentication in both OpenTok and Vonage Python Server SDKs are handled for you, so you only need to provide your account credentials once upon initialisation. The difference is that OpenTok requires an API key and secret, whilst for Vonage Python SDK, you need to provide an application ID and its private key. Whilst both Vonage and OpenTok use token-based authentication, Vonage's tokens are JWTs whilst OpenTok uses a custom format. Whilst you can provide an API key and secret to the vonage.Client object just as with OpenTok, this is used for other Vonage APIs, not Video. Therefore, you will need to create or use an existing Vonage application.

You can create an application from the Vonage Dashboard. Ensure that your application has the Video capability enabled. Click 'Edit' for an existing application to view its capabilities and credentials. From here, click 'Generate public and private key'. This should only be done once, as every time you do this, the credentials change and so will break the existing key pair. Clicking this will trigger a download of your private key. You should place this file somewhere secure for testing. NEVER SHARE OR EXPOSE YOUR PRIVATE KEY!

The private key is effectively the "password" to your application, so should be treated carefully. It is recommended that you store your private key in a secure file. Use a package such as dotenv to create a .env file, then store the path to your private key file as an environment variable so that you can refer to it when setting up the client, calling the variable something like VONAGE_PRIVATE_KEY_PATH. The same should be done for your application ID (which can be found on the dashboard or in the URL when editing it).

For further guidance on setting up an application, see the Getting Started guide.

Use of Pydantic Models

The Vonage Python SDK uses Pydantic data models for taking in user options and returning API data. Most API requests with the Video API require a Pydantic model as input.

You can access data models for the Video API, e.g. as arguments for Video package methods, by importing them from the vonage_video.models package, e.g.

Usage

Instantiating a Client

See the Python SDK README for instructions on how to use this SDK.

Replace references to opentok.Client and opentok.OpenTok with the Video class accessed via vonage.Vonage.video.

Instead of this, with OpenTok:

Do the following:

Once you have access to a vonage.Vonage instance, you can use the Video API. To call methods related to the Video API, use this syntax:

For more detailed usage instructions, see the Python Server SDK video guide.

Method Changes Between OpenTok and Vonage SDKs

There are some changes to methods between the OpenTok SDK and the Video API implementation in the Vonage SDKs.

Any positional parameters in method signatures in opentok have been replaced with key-value parameters in the vonage package.
Methods now return the response as a Python dictionary.
Some methods have been renamed, for clarity and/or to better reflect what the method does. These are listed below:

OpenTok Method Name	Vonage Video Method Name
`opentok.generate_token`	`video.generate_client_token`
`opentok.add_archive_stream`	`video.add_stream_to_archive`
`opentok.remove_archive_stream`	`video.remove_stream_from_archive`
`opentok.set_archive_layout`	`video.change_archive_layout`
`opentok.add_broadcast_stream`	`video.add_stream_to_broadcast`
`opentok.remove_broadcast_stream`	`video.remove_stream_from_broadcast`
`opentok.set_broadcast_layout`	`video.change_broadcast_layout`
`opentok.set_stream_class_lists`	`video.change_stream_layout`
`opentok.force_disconnect`	`video.disconnect_client`
`opentok.mute_all`	`video.mute_all_streams`
`opentok.disable_force_mute`	`video.disable_mute_all_streams`
`opentok.dial`	`video.initiate_sip_call`
`opentok.start_render`	`video.start_experience_composer`
`opentok.list_renders`	`video.list_experience_composers`
`opentok.get_render`	`video.get_experience_composer`
`opentok.stop_render`	`video.stop_experience_composer`
`opentok.connect_audio_to_websocket`	`video.start_audio_connector`

Migration Strategies

Incremental Migration

We would recommend an incremental migration, moving from one use case to another, committing every time you end up in a "stable" state. Note that this approach would require both OpenTok and Vonage Video API to temporarily coexist.

Please note that, during such incremental process, your application as a whole would not be fully functional anymore as OpenTok and Vonage Video API are two fully different systems.

You should start by creating a specific "Video Adapter" that would regroup all current interactions with OpenTok, and then replace one by one the use of OpenTok with Vonage Video API.

Another approach could be to duplicate that "Video Adapter" into a new "Vonage Video Adapter", dedicated to that migration, before swapping those two adapters together. See more with the Strangler Fig Pattern.

Testing Recommendations

Thorough testing is essential for a smooth transition, both during and after the migration. This includes not only unit tests but also integration and regression testing. It is also worth manually testing your application flow at least once before and after the migration to ensure that your automated tests do what you think they do, or to pick up on any issues that the tests may not have caught. You may even consider creating equivalence tests.

The idea is to create a suite which asserts that both the OpenTok and Vonage Video versions of your application do the same thing. These can then be discarded once your transition is complete and the OpenTok version of your application is removed.

Troubleshooting & Support

The Vonage Python Server SDK endeavours to provide helpful exception messages in stack traces should you encounter runtime errors. Examine these carefully to determine the cause.

Support Channels

For general help and discussion on transitioning to Vonage Video, check out the #video-api channel on our Community Slack, where you can get answers from Vonage staff and fellow users. You can also get in touch with us on X @VonageDev.

The primary contact for any issues with the Video API itself is support@api.vonage.com. If you find a bug with the SDK, please file an issue with steps to reproduce on GitHub.