SDK del servidor Python

Vonage Video Python SDK proporciona métodos para:

Requisitos

Deberá crear una aplicación en la sección Panel de control para desarrolladores de Vonage y descargar la clave privada. Estos elementos se utilizarán para autenticar sus solicitudes.

Crear un entorno virtual Python

Se recomienda encarecidamente utilizar un entorno virtual Python para trabajar con el SDK Python de Vonage.

Puede hacerlo con

# 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

Instalación mediante pip (recomendado)

pip ayuda a gestionar las dependencias de los proyectos Python mediante el índice de paquetes Python. Más información aquí: http://www.pip-installer.org/en/latest.

Añada el vonage como dependencia de su proyecto añadiéndolo a su paquete requirements.txt archivo:

vonage>=4.0.0

A continuación, instale las dependencias:

pip install -r requirements.txt

Utilización

Para utilizar la API de Video de Vonage, debes crear una instancia de nivel superior de vonage.Vonage a través del cual puede acceder a los métodos de la Video API.

La mayoría de los métodos de la Video API requieren algunos datos de entrada. Estos datos se introducen en Pydantic modelos de datos, que se importan desde vonage_video.models. Siga leyendo para ver ejemplos prácticos.

Todos los métodos y modelos de datos de la API tienen docstrings que explican los argumentos obligatorios y opcionales. Los métodos también describen los tipos de retorno.

Inicialización de

Importar e inicializar un vonage.Vonage al principio de cualquier archivo en el que desees utilizar la API de Video de Vonage.

Crear una instancia de Vonage y pasar una instancia de la clase Auth clase. Inicializar la clase Vonage con su ID de aplicación y su clave privada.

from vonage import Auth, Vonage

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

Instanciación del Vonage también crea una clase Video de la clase. Puede acceder a los métodos de la Video API, pasando modelos pydantic como este:

from vonage_video.models import VonageVideoRequestModel

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

Creación de sesiones

Para crear una sesión de vídeo de Vonage, utiliza el botón vonage_client.video.create_session método. Existen parámetros de palabra clave opcionales para este método, que se pasan mediante un parámetro SessionOptions que tiene un docstrip que explica cada uno.

Este método devuelve un vonage_video.models.VideoSession objeto. Su session_id es útil cuando se guarda en un almacén persistente (como una base de datos).

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

Generación de fichas

Una vez creada una Sesión, puede empezar a generar Tokens para que los clientes los utilicen cuando se conecten a ella. Puede generar un token llamando a la función vonage_client.video.generate_client_token(session_id) método. Hay una serie de parámetros opcionales: scope, role, connection_data, initial_layout_class_list, jti, subject, iat, exp y acl.

Para utilizarlos, añádalos a un TokenOptions y pasarlo al modelo generate_client_token método.

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

Trabajar con archivos

Importante: Sólo puedes archivar sesiones que utilicen el enrutador de medios de video de Vonage (sesiones con el modo de medios configurado como enrutado).

Puedes iniciar la grabación de una sesión de video de Vonage usando el botón vonage_client.video.start_archive método. Puede proporcionar argumentos de palabra clave opcionales al método, por ejemplo name para asignar un nombre al archivo. Este método devolverá un modelo de datos Pydantic. Tenga en cuenta que sólo puede iniciar un Archivo en una Sesión que tenga clientes conectados.

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

También puedes desactivar la grabación de audio o vídeo configurando la opción has_audio o has_video del atributo CreateArchiveRequest modelo a False:

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

Por defecto, todos los flujos se graban en un único archivo (compuesto). Puede grabar los distintos flujos de la sesión en archivos individuales (en lugar de en un único archivo compuesto) configurando la opción output_mode del CreateArchiveRequest modelo a 'individual'.

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

Archivos compuestos (output_mode='composed') tienen un resolution parámetro. Si no se proporciona ningún valor, la plataforma de vídeo de Vonage utilizará la resolución predeterminada. "640x480". Puede ajustarlo a "1280x720" estableciendo el resolution del CreateArchiveRequest método.

Advertencia: Este valor no puede establecerse para 'individual' se producirá un error.

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

Puede detener la grabación de un archivo iniciado mediante la tecla vonage_client.video.stop_archive(archive_id) método.

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)

Para obtener toda la información sobre un archivo a partir de un ID de archivo, utilice la función vonage_client.video.get_archive(archive_id) método.

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

Para eliminar un Archivo, puede llamar a la función vonage_client.video.delete_archive(archive_id) método.

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

También puede obtener una lista de todos los Archivos que ha creado (hasta 1000) con su ID de Aplicación. Para ello, utilice la función vonage_client.video.list_archives() método. Opcionalmente, puede filtrar los parámetros, lo que puede ayudarle a paginar los resultados. Este método devuelve una tupla que contiene una lista de objetos de archivo, el recuento total de archivos y el valor de desplazamiento requerido para la página siguiente, si procede, es decir (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)

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en 'archive_mode': 'always' a la SessionOptions cuando llame a la función vonage_client.video.create_session (véase "Crear sesiones" arriba).

En el caso de los archivos compuestos, puede cambiar el diseño dinámicamente, utilizando la función vonage_client.video.change_archive_layout método:

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 configuración del diseño de los archivos compuestos es opcional. Por defecto, los archivos compuestos utilizan el formato best fit diseño. Otros valores válidos son: custom, horizontalPresentation, pip y verticalPresentationaunque están vinculadas al LayoutType enum. Si especifica un custom tipo de diseño, establezca el stylesheet parámetro:

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

Para otros tipos de presentación, no establezca la propiedad de hoja de estilos. Para obtener más información, consulte Personalización del diseño de vídeo para archivos compuestos.

Puede añadir manualmente un flujo a un archivo con la función vonage_client.video.add_stream_to_archive método:

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

También puede eliminar flujos específicos de un archivo con la función vonage_client.video.remove_stream_from_archive método:

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

Para más información sobre el archivado, consulte el Guía para desarrolladores de Vonage Video archiving.

Envío de señales

Una vez creada una sesión, puede enviar señales a todos los miembros de la sesión o a una conexión específica. Puede enviar una señal llamando a la función send_signal método del Video clase. Puede llamar al método con el parámetro connection_id para enviar una señal a una conexión específica, por ejemplo 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',

Trabajar con flujos

Puede obtener información sobre un flujo llamando a la función get_stream(session_id, stream_id) método del Video clase.

El método devuelve un StreamInfo que contiene información sobre un flujo de Vonage Video.

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)

Puede obtener información sobre todos los flujos de una sesión llamando a la función list_streams(session_id) método del Video clase. El método devuelve una lista de StreamInfo objetos.

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

Puedes cambiar las clases de diseño para un flujo de Vonage Video (cómo se muestra el flujo en un archivo de Vonage Video) con la función change_stream_layout método del Video clase:

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

También puede silenciar un flujo específico con la tecla video.mute_stream método del Video clase:

vonage_client.video.mute_stream(session_id, stream_id)

O silenciar todos los flujos (excepto los especificados que se excluyen de la operación) con la opción video.mute_all_streams método del Video clase:

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

Desactiva los flujos llamando a la función vonage_client.video.disable_mute_all_streams método:

vonage_client.video.disable_mute_all_streams(session_id)

Moderación de la sesión

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de Vonage Video llamando a la función disconnect_client(session_id, connection_id) método del Video clase.

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

Trabajar con SIP Interconnect

Puedes conectar tu plataforma SIP a una sesión de Vonage Video, el audio de tu extremo de la llamada SIP se agrega a la sesión de Vonage Video como un flujo de sólo audio. El enrutador de medios de Vonage Video mezcla el audio de otras transmisiones en la sesión y envía el audio mezclado a tu punto final 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)

El método también admite opciones adicionales para establecer la llamada SIP. Páselas al método SipOptions con el 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)

Para más información, incluidos detalles técnicos y consideraciones de seguridad, consulte el Interconexión SIP de vídeo de Vonageguía del desarrollador.

Trabajar con emisiones

La transmisión de Vonage Video te permite compartir sesiones de Vonage Video en vivo con muchos espectadores.

Puede utilizar la función vonage_client.video.start_broadcast para iniciar una transmisión en vivo para una sesión de Vonage Video. Esto transmite la sesión a una transmisión en vivo HLS (HTTP) o a transmisiones RTMP.

Para iniciar correctamente la difusión de una sesión, al menos un cliente debe estar conectado a la sesión.

La retransmisión en directo puede dirigirse a un punto final HLS y hasta cinco servidores RTMP simultáneamente para una sesión.

Sólo puedes iniciar la transmisión en vivo para sesiones que utilicen el enrutador de medios de video de Vonage; no puedes utilizar la transmisión en vivo con sesiones que tengan el modo de medios configurado en 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())

Puede detener una emisión iniciada utilizando el botón vonage_client.video.stop_broadcast(broadcast_id) método.

# Stop a broadcast
from vonage_video.models import Broadcast

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

Puede obtener información detallada sobre una emisión en curso utilizando el método 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

Puede cambiar dinámicamente el tipo de presentación de una emisión en directo.

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

Trabajar con subtítulos

Puedes habilitar los subtítulos en una sesión de Video API de Vonage con

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

Puedes desactivar los subtítulos así:

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

Trabajar con la API de Experience Composer

Es posible renderizar varios objetos en un flujo de vídeo con la API Experience Composer. Puede utilizarla para capturar toda la experiencia de su aplicación web. Puede utilizar la API Experience Composer para grabaciones compuestas, retransmisiones y visualización sincronizada de grupos.

Inicie una sesión de Experience Composer con

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

Puede detener una sesión de Experience Composer con

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

e infórmese sobre una sesión de Experience Composer con

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

También puede obtener una lista de todos los objetos de 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)
)

Transmisión de audio a un WebSocket

La API del conector de audio inicia un conector de audio en una sesión de la Video API de Vonage que conecta transmisiones de audio a un URI de WebSocket especificado.

Inicia un Conector de Audio así:

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)

Notas de publicación

Véase el Cambios en el SDK de Python para obtener más información sobre cada versión.