SDK serveur Python

Le SDK vidéo Python de Vonage fournit des méthodes pour :

Création sessions
Générer jetons pour les applications vidéo de Vonage
Envoi de signaux aux clients connectés à une session
Créer et gérer archives de sessions vidéo Vonage
Modérer les utilisateurs lors des sessions
Travailler avec SIP Interconnect
Créer et gérer diffusion en direct de sessions vidéo Vonage
Travailler avec des sous-titres
Rendu de plusieurs objets dans un flux vidéo (avec l'option Expérience Composer API)
Streaming audio vers une WebSocket

Exigences

Vous devrez créer une application dans la base de données Tableau de bord du développeur Vonage et téléchargez la clé privée. Ces éléments seront utilisés pour authentifier vos demandes.

Créer un environnement virtuel Python

Il est fortement recommandé d'utiliser un environnement virtuel Python pour travailler avec le SDK Python de Vonage.

Vous pouvez le faire avec

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

Installation à l'aide de pip (recommandé)

pip aide à gérer les dépendances pour les projets Python en utilisant le Python Package Index. Plus d'informations ici : http://www.pip-installer.org/en/latest.

Ajouter le vonage en tant que dépendance pour votre projet en l'ajoutant à votre fichier requirements.txt fichier :

vonage>=4.0.0

Ensuite, installez les dépendances :

pip install -r requirements.txt

Utilisation

Afin d'utiliser l'API Video de Vonage, vous devez instancier un fichier de niveau supérieur vonage.Vonage par l'intermédiaire duquel vous pouvez accéder aux méthodes de l'API Video.

La plupart des méthodes de la Video API nécessitent des données d'entrée. Vous les fournissez en transmettant Pydantique que vous importez à partir de vonage_video.models. Lisez la suite pour en voir des exemples concrets.

Toutes les méthodes et tous les modèles de données de l'API sont accompagnés d'une documentation expliquant les arguments obligatoires et facultatifs. Les méthodes décrivent également les types de retour.

Initialisation

Importer et initialiser un vonage.Vonage au début de tout fichier dans lequel vous souhaitez utiliser l'API Video de Vonage.

Créer une instance du Vonage et transmet une instance de la classe Auth classe. Initialiser le Vonage avec l'identifiant de l'application et la clé privée.

from vonage import Auth, Vonage

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

L'instanciation du Vonage crée également une classe Video de la classe. Vous pouvez accéder aux méthodes de Video API, en passant des modèles pydantiques comme ceci :

from vonage_video.models import VonageVideoRequestModel

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

Création de sessions

Pour créer une session vidéo Vonage, utilisez la fonction vonage_client.video.create_session et de la méthode. Cette méthode comporte des paramètres optionnels de type mot-clé, que vous transmettez par l'intermédiaire d'un mot-clé SessionOptions qui contient une docstring expliquant chacun d'entre eux.

Cette méthode renvoie un vonage_video.models.VideoSession objet. Son session_id est utile lors de l'enregistrement dans une mémoire persistante (telle qu'une base de données).

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

Générer des jetons

Une fois qu'une session est créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour se connecter à la session. Vous pouvez générer un jeton en appelant la fonction vonage_client.video.generate_client_token(session_id) méthode. Il existe une série de paramètres facultatifs : scope, role, connection_data, initial_layout_class_list, jti, subject, iat, exp et acl.

Pour les utiliser, ajoutez-les à un TokenOptions et le passer dans le modèle generate_client_token méthode.

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

Travailler avec les archives

Important : Vous ne pouvez archiver que les sessions qui utilisent le routeur vidéo de Vonage (sessions dont le mode média est réglé sur routé).

Vous pouvez démarrer l'enregistrement d'une session vidéo Vonage à l'aide du bouton vonage_client.video.start_archive méthode. Vous pouvez fournir des arguments facultatifs de type mot-clé à la méthode, par exemple name pour attribuer un nom à l'archive. Cette méthode renvoie un modèle de données Pydantic. Notez que vous ne pouvez démarrer une archive que sur une session à laquelle des clients sont connectés.

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

Vous pouvez également désactiver l'enregistrement audio ou vidéo en réglant le paramètre has_audio ou has_video de l'attribut CreateArchiveRequest modèle à False:

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

Par défaut, tous les flux sont enregistrés dans un seul fichier (composé). Vous pouvez enregistrer les différents flux de la session dans des fichiers individuels (au lieu d'un seul fichier composé) en définissant le paramètre output_mode du paramètre CreateArchiveRequest modèle à 'individual'.

archive_options = CreateArchiveRequest(
    session_id=session_id,
    output_mode='individual'
)

Archives composées (output_mode='composed') ont une option resolution paramètre. Si aucune valeur n'est fournie, la plateforme Vonage Video utilisera la résolution par défaut. "640x480". Vous pouvez régler ce paramètre sur "1280x720" en réglant le resolution du paramètre CreateArchiveRequest méthode.

Avertissement : Cette valeur ne peut pas être définie pour 'individual' un message d'erreur sera envoyé.

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

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche vonage_client.video.stop_archive(archive_id) méthode.

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)

Pour obtenir toutes les informations sur une archive à partir d'un ID d'archive, utilisez la commande vonage_client.video.get_archive(archive_id) méthode.

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

Pour supprimer une archive, vous pouvez appeler le vonage_client.video.delete_archive(archive_id) méthode.

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

Vous pouvez également obtenir une liste de toutes les Applications que vous avez créées (jusqu'à 1000) avec votre ID d'application. Cette opération s'effectue à l'aide de la fonction vonage_client.video.list_archives() méthode. Vous pouvez éventuellement filtrer sur des paramètres, ce qui peut vous aider à paginer dans les résultats. Cette méthode renvoie un tuple contenant une liste d'objets d'archives, le nombre total d'archives et la valeur de décalage requise pour la page suivante, le cas échéant. c.-à-d. (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)

Notez que vous pouvez également créer une session automatiquement archivée, en passant le paramètre 'archive_mode': 'always' à la SessionOptions lorsque vous appelez l'objet vonage_client.video.create_session (voir "Création de sessions" ci-dessus).

Pour les archives composées, vous pouvez modifier la mise en page de manière dynamique, en utilisant la fonction vonage_client.video.change_archive_layout méthode :

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

La définition de la mise en page des archives composées est facultative. Par défaut, les archives composées utilisent le format best fit la mise en page. Les autres valeurs valables sont les suivantes : custom, horizontalPresentation, pip et verticalPresentationbien qu'ils soient liés à la LayoutType enum. Si vous spécifiez un custom définir le type de mise en page stylesheet paramètre :

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

Pour les autres types de mise en page, ne définissez pas la propriété de feuille de style. Pour plus d'informations, voir Personnalisation de la présentation vidéo pour les archives composées.

Vous pouvez ajouter manuellement un flux à une archive à l'aide de la commande vonage_client.video.add_stream_to_archive méthode :

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

Vous pouvez également supprimer des flux spécifiques d'une archive à l'aide de la commande vonage_client.video.remove_stream_from_archive méthode :

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

Pour plus d'informations sur l'archivage, voir la page Guide du développeur pour l'archivage vidéo de Vonage.

Envoi de signaux

Une fois qu'une session est créée, vous pouvez envoyer des signaux à tous les participants à la session ou à une connexion spécifique. Vous pouvez envoyer un signal en appelant la fonction send_signal de la méthode Video de la classe. Vous pouvez appeler la méthode avec le paramètre connection_id pour envoyer un signal à une connexion spécifique, par exemple 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',

Travailler avec des flux

Vous pouvez obtenir des informations sur un flux en appelant la fonction get_stream(session_id, stream_id) de la méthode Video classe.

La méthode renvoie un StreamInfo qui contient des informations sur un flux vidéo Vonage.

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)

Vous pouvez obtenir des informations sur tous les flux d'une session en appelant la fonction list_streams(session_id) de la méthode Video de la classe. La méthode renvoie une liste de StreamInfo objets.

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

Vous pouvez modifier les classes de présentation d'un flux vidéo Vonage (comment le flux est affiché dans une archive vidéo Vonage) à l'aide de l'option change_stream_layout de la méthode Video classe :

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

Vous pouvez également couper le son d'un flux spécifique à l'aide de la fonction video.mute_stream de la méthode Video classe :

vonage_client.video.mute_stream(session_id, stream_id)

Ou mettre en sourdine tous les flux (à l'exception des flux spécifiés qui sont exclus de l'opération) à l'aide de la commande video.mute_all_streams de la méthode Video classe :

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

Rendre les flux muets en appelant la fonction vonage_client.video.disable_mute_all_streams méthode :

vonage_client.video.disable_mute_all_streams(session_id)

Modération de la session

Votre serveur d'application peut déconnecter un client d'une session vidéo Vonage en appelant la fonction disconnect_client(session_id, connection_id) de la méthode Video classe.

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

Travailler avec SIP Interconnect

Vous pouvez connecter votre plateforme SIP à une session Vonage Video, l'audio de votre côté de l'appel SIP est ajouté à la session Vonage Video en tant que flux audio uniquement. Le routeur média de Vonage Video mixe l'audio des autres flux de la session et envoie l'audio mixé à votre point d'extrémité SIP.

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)

La méthode prend également en charge des options supplémentaires pour établir l'appel SIP. Transmettez-les à la méthode SipOptions avec l'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)

Pour plus d'informations, y compris les détails techniques et les considérations relatives à la sécurité, voir le document Interconnexion vidéo SIP de Vonageguide du développeur.

Travailler avec des diffusions

La diffusion de Vonage Video vous permet de partager des sessions de Vonage Video en direct avec de nombreux spectateurs.

Vous pouvez utiliser le vonage_client.video.start_broadcast pour lancer une diffusion en direct d'une session Vonage Video. Cette méthode permet de diffuser la session vers un flux HLS (HTTP live stream) ou vers des flux RTMP.

Pour lancer avec succès la diffusion d'une session, au moins un client doit être connecté à la session.

La diffusion en direct peut cibler un point final HLS et jusqu'à cinq serveurs RTMP simultanément pour une session.

Vous ne pouvez démarrer la diffusion en direct que pour les sessions qui utilisent le routeur vidéo Vonage ; vous ne pouvez pas utiliser la diffusion en direct pour les sessions dont le mode média est réglé sur 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())

Vous pouvez arrêter une diffusion commencée à l'aide de la fonction vonage_client.video.stop_broadcast(broadcast_id) méthode.

# Stop a broadcast
from vonage_video.models import Broadcast

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

Vous pouvez obtenir des détails sur une diffusion en cours en utilisant la méthode 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

Vous pouvez modifier dynamiquement le type de mise en page d'une diffusion en direct.

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

Travailler avec des sous-titres

Vous pouvez activer les sous-titres dans une session Video API de Vonage avec

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

Vous pouvez désactiver les légendes comme suit :

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

Travailler avec l'API Experience Composer

Il est possible de rendre plusieurs objets dans un seul flux vidéo avec l'API Experience Composer. Vous pouvez l'utiliser pour capturer l'intégralité de l'expérience de votre application web. Vous pouvez utiliser l'API Experience Composer pour les enregistrements composites, les diffusions et la visualisation synchronisée de groupes.

Démarrer une session Experience Composer avec

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

Vous pouvez arrêter une session Experience Composer avec

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

et obtenir des informations sur une session Experience Composer avec

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

Vous pouvez également obtenir une liste de tous les objets Experience Composer :

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 vers une WebSocket

L'API Connecteur audio démarre un connecteur audio dans une session Video API de Vonage qui connecte des flux audio à une URI WebSocket spécifiée.

Commencez un connecteur audio comme ceci :

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)

Notes de mise à jour

Voir le Changements dans le SDK Python pour plus de détails sur chaque version.