Python-Server-SDK

Das Vonage Video Python SDK bietet Methoden für:

Erstellen von Sitzungen
Erzeugen von Token für Vonage Video-Anwendungen
Senden von Signalen an Clients, die mit einer Sitzung verbunden sind
Erstellen und Verwalten Archiv von Vonage Video-Sitzungen
Benutzer in Sitzungen moderieren
Arbeiten mit SIP Interconnect
Erstellen und Verwalten Live-Streaming-Übertragungen von Vonage Video-Sitzungen
Arbeiten mit Beschriftungen
Rendering mehrerer Objekte in einen Videostrom (mit der Option Experience Composer API)
Audio-Streaming zu einem WebSocket

Anforderungen

Sie müssen eine Anwendung in der Vonage Dashboard für Entwickler und laden Sie den privaten Schlüssel herunter. Diese Elemente werden für die Authentifizierung Ihrer Anfragen verwendet.

Erstellen einer virtuellen Python-Umgebung

Es wird dringend empfohlen, eine virtuelle Python-Umgebung für die Arbeit mit dem Vonage Python SDK zu verwenden.

Sie können dies tun mit

# 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 mit pip (empfohlen)

pip hilft bei der Verwaltung von Abhängigkeiten für Python-Projekte unter Verwendung des Python Package Index. Mehr Informationen finden Sie hier: http://www.pip-installer.org/en/latest.

Fügen Sie die vonage Paket als Abhängigkeit für Ihr Projekt, indem Sie es zu Ihrem requirements.txt Datei:

vonage>=4.0.0

Als nächstes installieren Sie die Abhängigkeiten:

pip install -r requirements.txt

Verwendung

Um die Vonage Video API verwenden zu können, müssen Sie eine Top-Level vonage.Vonage Client, über den Sie auf Video API-Methoden zugreifen können.

Die meisten Methoden der Video API erfordern einige Eingabedaten. Sie stellen diese bereit, indem Sie in Pydantisch Datenmodelle, die Sie aus vonage_video.models. Lesen Sie weiter, um Beispiele aus der Praxis zu sehen.

Alle API-Methoden und Datenmodelle haben Dokumentationen, in denen die erforderlichen und optionalen Argumente erläutert werden. Methoden beschreiben auch Rückgabetypen.

Initialisierung

Importieren und initialisieren Sie eine vonage.Vonage Objekt am Anfang einer jeden Datei, in der Sie die Vonage Video API verwenden möchten.

Erstellen Sie eine Instanz der Vonage Klasse und übergeben Sie eine Instanz der Auth Klasse. Initialisieren Sie die Vonage Objekt mit Ihrer Anwendungs-ID und Ihrem privaten Schlüssel.

from vonage import Auth, Vonage

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

Die Instanziierung der Vonage Klasse erzeugt auch eine Video Klasseninstanz. Sie können auf Methoden der Video API zugreifen, indem Sie pydantische Modelle wie folgt übergeben:

from vonage_video.models import VonageVideoRequestModel

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

Sitzungen erstellen

Um eine Vonage-Videositzung zu erstellen, verwenden Sie die vonage_client.video.create_session Methode. Für diese Methode gibt es optionale Schlüsselwortparameter, die Sie über eine SessionOptions Objekt, das jeweils einen erläuternden Dokumentationsstrang enthält.

Diese Methode gibt ein vonage_video.models.VideoSession Objekt. Sein session_id Attribut ist nützlich beim Speichern in einem dauerhaften Speicher (z. B. einer Datenbank).

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

Token generieren

Sobald eine Sitzung erstellt ist, können Sie damit beginnen, Token zu erzeugen, die die Clients bei der Verbindung mit der Sitzung verwenden können. Sie können ein Token erzeugen, indem Sie die Funktion vonage_client.video.generate_client_token(session_id) Methode. Es gibt eine Reihe von optionalen Parametern: scope, role, connection_data, initial_layout_class_list, jti, subject, iat, exp und acl.

Um diese zu verwenden, fügen Sie sie zu einer TokenOptions Modell und übergeben es an die generate_client_token Methode.

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

Arbeiten mit Archiven

Das ist wichtig: Sie können nur Sitzungen archivieren, die den Vonage Video Media Router verwenden (Sitzungen, bei denen der Medienmodus auf geroutet eingestellt ist).

Sie können die Aufzeichnung einer Vonage-Videositzung mit der Taste vonage_client.video.start_archive Methode. Sie können der Methode optionale Schlüsselwortargumente mitgeben, z. B. name um dem Archiv einen Namen zu geben. Diese Methode gibt ein Pydantic-Datenmodell zurück. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, mit der bereits Clients verbunden sind.

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

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Option has_audio oder has_video Attribut des CreateArchiveRequest Modell zu False:

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

Standardmäßig werden alle Streams in einer einzigen (zusammengesetzten) Datei aufgezeichnet. Sie können die verschiedenen Streams in der Sitzung in einzelnen Dateien aufzeichnen (statt in einer einzigen zusammengesetzten Datei), indem Sie den Parameter output_mode Parameter des CreateArchiveRequest Modell zu 'individual'.

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

Zusammengestellte Archive (output_mode='composed') haben eine optionale resolution Parameter. Wenn kein Wert angegeben wird, verwendet die Vonage Video-Plattform die Standardauflösung "640x480". Sie können dies einstellen auf "1280x720" durch Einstellung der resolution Parameter des CreateArchiveRequest Methode.

Warnung: Dieser Wert kann nicht eingestellt werden für 'individual' Ausgabemodus, wird ein Fehler ausgelöst.

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

Sie können die Aufzeichnung eines gestarteten Archivs mit der Taste vonage_client.video.stop_archive(archive_id) Methode.

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)

Um alle Informationen über ein Archiv anhand einer Archiv-ID zu erhalten, verwenden Sie die vonage_client.video.get_archive(archive_id) Methode.

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

Um ein Archiv zu löschen, können Sie die Funktion vonage_client.video.delete_archive(archive_id) Methode.

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

Sie können auch eine Liste aller Archive, die Sie erstellt haben (bis zu 1000), mit Ihrer Applications-ID abrufen. Dies geschieht mit der Funktion vonage_client.video.list_archives() Methode. Sie können optional nach Parametern filtern, was Ihnen helfen kann, die Ergebnisse zu paginieren. Diese Methode gibt ein Tupel zurück, das eine Liste von Archivobjekten, die Gesamtzahl der Archive und ggf. den gewünschten Offset-Wert für die nächste Seite enthält, d.h. (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)

Beachten Sie, dass Sie auch eine automatisch archivierte Sitzung erstellen können, indem Sie in 'archive_mode': 'always' zum SessionOptions Objekt, wenn Sie die Funktion vonage_client.video.create_session Methode (siehe "Sitzungen erstellen" oben).

Bei zusammengesetzten Archiven können Sie das Layout dynamisch ändern, indem Sie die vonage_client.video.change_archive_layout Methode:

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

Die Festlegung des Layouts von zusammengestellten Archiven ist optional. Standardmäßig verwenden zusammengestellte Archive das best fit Layout. Andere gültige Werte sind: custom, horizontalPresentation, pip und verticalPresentationobwohl sie mit dem LayoutType enum. Wenn Sie eine custom Layout-Typ, setzen Sie die 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%;}'
    )
)

Für andere Layouttypen setzen Sie die Eigenschaft Stylesheet nicht. Für weitere Informationen siehe Anpassen des Videolayouts für zusammengestellte Archive.

Sie können einen Stream manuell zu einem Archiv hinzufügen, indem Sie den Befehl vonage_client.video.add_stream_to_archive Methode:

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

Sie können auch bestimmte Datenströme aus einem Archiv entfernen, indem Sie den Befehl vonage_client.video.remove_stream_from_archive Methode:

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

Weitere Informationen zur Archivierung finden Sie in der Vonage Videoarchivierung Entwicklerhandbuch.

Senden von Signalen

Sobald eine Sitzung erstellt ist, können Sie Signale an alle Teilnehmer der Sitzung oder an eine bestimmte Verbindung senden. Sie können ein Signal senden, indem Sie die Funktion send_signal Methode der Video Klasse. Sie können die Methode mit dem Parameter connection_id um ein Signal an eine bestimmte Verbindung zu senden, z. B. 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',

Arbeiten mit Strömen

Sie können Informationen über einen Stream erhalten, indem Sie die get_stream(session_id, stream_id) Methode der Video Klasse.

Die Methode gibt ein StreamInfo Modell, das Informationen über einen Vonage Video-Stream enthält.

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)

Sie können Informationen über alle Streams in einer Sitzung erhalten, indem Sie die list_streams(session_id) Methode der Video Klasse. Die Methode gibt eine Liste von StreamInfo Objekte.

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

Sie können die Layout-Klassen für einen Vonage Video-Stream (wie der Stream in einem Vonage Video-Archiv angezeigt wird) mit dem Befehl change_stream_layout Methode der Video Klasse:

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

Sie können auch einen bestimmten Stream stummschalten mit der video.mute_stream Methode der Video Klasse:

vonage_client.video.mute_stream(session_id, stream_id)

Oder schalten Sie alle Streams stumm (mit Ausnahme der angegebenen Streams, die von dem Vorgang ausgeschlossen sind) mit der Option video.mute_all_streams Methode der Video Klasse:

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

Deaktivieren Sie Streams durch Aufruf der Funktion vonage_client.video.disable_mute_all_streams Methode:

vonage_client.video.disable_mute_all_streams(session_id)

Moderation der Sitzung

Ihr Anwendungsserver kann die Verbindung eines Clients zu einer Vonage Video-Sitzung trennen, indem er die Funktion disconnect_client(session_id, connection_id) Methode der Video Klasse.

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

Arbeiten mit SIP Interconnect

Sie können Ihre SIP-Plattform mit einer Vonage Video-Sitzung verbinden. Das Audio von Ihrem Ende des SIP-Anrufs wird der Vonage Video-Sitzung als reiner Audio-Stream hinzugefügt. Der Vonage Video Media Router mischt Audio aus anderen Streams in der Sitzung und sendet das gemischte Audio an Ihren SIP-Endpunkt.

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)

Die Methode unterstützt auch zusätzliche Optionen für den Aufbau des SIP-Anrufs. Übergeben Sie diese an die Methode SipOptions Modell mit dem 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)

Weitere Informationen, einschließlich technischer Details und Sicherheitsüberlegungen, finden Sie in der Vonage Video-SIP-ZusammenschaltungLeitfaden für Entwickler.

Arbeiten mit Broadcasts

Mit Vonage Video Broadcast können Sie Live-Sitzungen von Vonage Video mit vielen Zuschauern teilen.

Sie können die vonage_client.video.start_broadcast Methode, um eine Live-Streaming-Übertragung für eine Vonage Video-Sitzung zu starten. Damit wird die Sitzung an einen HLS (HTTP-Livestream) oder an RTMP-Streams übertragen.

Um die Übertragung einer Sitzung erfolgreich zu starten, muss mindestens ein Client mit der Sitzung verbunden sein.

Die Live-Streaming-Übertragung kann einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig für eine Sitzung ansteuern.

Sie können Live-Streaming nur für Sitzungen starten, die den Vonage Video Media Router verwenden; Sie können Live-Streaming nicht mit Sitzungen verwenden, deren Medienmodus auf 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())

Sie können einen gestarteten Broadcast mit dem Befehl vonage_client.video.stop_broadcast(broadcast_id) Methode.

# Stop a broadcast
from vonage_video.models import Broadcast

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

Details zu einer laufenden Sendung erhalten Sie mit der Methode 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

Sie können den Layouttyp einer Live-Streaming-Übertragung dynamisch ändern.

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

Arbeiten mit Untertiteln

Sie können Untertitel in einer Vonage Video API-Sitzung aktivieren mit

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

Sie können Beschriftungen wie folgt deaktivieren:

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

Arbeiten mit der Experience Composer-API

Mit der Experience Composer-API ist es möglich, mehrere Objekte in einen Videostream zu rendern. Auf diese Weise können Sie das gesamte Erlebnis Ihrer Webanwendung erfassen. Sie können die Experience Composer-API für zusammengesetzte Aufnahmen, Übertragungen und synchronisierte Gruppenanzeigen verwenden.

Starten Sie eine Experience Composer-Sitzung mit

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

Sie können eine Experience Composer-Sitzung beenden mit

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

und erhalten Sie Informationen über eine Experience Composer-Sitzung mit

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

Sie können auch eine Liste aller Experience Composer-Objekte abrufen:

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

Audio-Streaming zu einem WebSocket

Die Audio-Connector-API startet einen Audio-Connector in einer Vonage Video API-Sitzung, der Audioströme mit einem angegebenen WebSocket-URI verbindet.

Starten Sie einen Audio Connector wie folgt:

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)

Anmerkungen zur Veröffentlichung

Siehe die Änderungsprotokoll zum Python SDK Seite für Details zu jeder Version.