SDK de Python para la Video API de Vonage

El SDK de OpenTok para Python te permite generar sesiones y fichas para las aplicaciones de OpenTok, y archivo Sesiones de OpenTok.

Instalación mediante Pip (recomendada):

Pip ayuda a gestionar las dependencias de los proyectos de Python utilizando el índice PyPI. Para más información, consulta aquí: http://www.pip-installer.org/en/latest/.

Añade el opentok Incluye el paquete como dependencia en tu proyecto. La forma más habitual es añadirlo a tu requirements.txt archivo:

opentok>=3.0

A continuación, instale las dependencias:

$ pip install -r requirements.txt

Uso

Inicialización de

Importa el paquete al principio de cualquier archivo en el que vayas a utilizarlo. Como mínimo, necesitarás el Client clase. A continuación, inicializa una instancia del cliente OpenTok con tu propia clave API y tu propio secreto API.

from opentok import Client
opentok = Client(api_key, api_secret)

Creación de sesiones

Para crear una sesión de OpenTok, utiliza el opentok.create_session() método. Este método admite parámetros de palabra clave opcionales:

  • location que se puede configurar con una cadena que contenga una dirección IP.
  • media_mode que es una cadena (definida por la clase MediaModes). Esto determina si la sesión utilizará el OpenTok Media Router o intentar enviar transmisiones directamente entre clientes. Para algunas funciones de OpenTok (como el archivado) es necesaria una sesión enrutada.
  • archive_mode que especifica si la sesión se archivará automáticamente (always) o no (manual).
  • archive_name que indica el nombre del archivo para todos los archivos de una sesión con archivado automático. Una sesión que comience con el modo de archivado «always» utilizará este nombre de archivo para todos los archivos de dicha sesión. Si se pasa «archive_name» con el modo de archivado «manual», se generará una respuesta de error.
  • archive_resolution que indica la resolución de todos los archivos de una sesión de archivado automático. Los valores válidos son «640x480», «480x640», «1280x720», «720x1280», «1920x1080» y «1080x1920». Una sesión que comience con el modo de archivo «always» utilizará esta resolución para todos los archivos de dicha sesión. Si se pasa «archive_resolution» con el modo de archivo «manual», se producirá una respuesta de error.
  • e2ee que es un valor booleano. Esto especifica si se debe habilitar cifrado de extremo a extremo para la sesión de OpenTok.

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

# Create a session that attempts to send streams directly between clients (falling back
# to use the OpenTok TURN server to relay streams if the clients cannot connect):
session = opentok.create_session()

from opentok import MediaModes
# A session that uses the OpenTok Media Router, which is required for archiving:
session = opentok.create_session(media_mode=MediaModes.routed)

# An automatically archived session:
session = opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.always)

# An automatically archived session with the archive name and resolution specified:
session = opentok.create_session(
  media_mode=MediaModes.routed,
  archive_mode=ArchiveModes.always,
  archive_name='my_archive',
  archive_resolution='1920x1080'
)

# A session with a location hint
session = opentok.create_session(location=u'12.34.56.78')

# Store this session ID in the database
session_id = session.session_id

Generación de fichas

Una vez creada una sesión, puedes empezar a generar tokens para que los clientes los utilicen al conectarse a ella. Puedes generar un token llamando a la función opentok.generate_token(session_id) método o llamando a la session.generate_token() en un Session instancia tras crearla. Hay un conjunto de parámetros opcionales de palabra clave: role, expire_time, datay initial_layout_class_list.

# Generate a Token from just a session_id (fetched from a database)
token = opentok.generate_token(session_id)
# Generate a Token by calling the method on the Session (returned from create_session)
token = session.generate_token()

from opentok import Roles
# Set some options in a token
token = session.generate_token(role=Roles.moderator,
                               expire_time=int(time.time()) + 10,
                               data=u'name=Johnny'
                               initial_layout_class_list=[u'focus'])

Trabajar con archivos

Importante: Solo puedes archivar las sesiones que utilicen el OpenTok Media Router (sesiones cuyo modo multimedia esté configurado como «routed»).

Puedes iniciar la grabación de una sesión de OpenTok utilizando el opentok.start_archive(session_id) método. Este método admite un argumento de palabra clave opcional name para asignar un nombre al archivo. Este método devolverá un Archive Por ejemplo. Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga clientes conectados.

archive = opentok.start_archive(session_id, name=u'Important Presentation')

# Store this archive_id in the 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 propiedad del options parámetro a false:

archive = opentok.start_archive(session_id, name=u'Important Presentation', has_video=False)

# Store this archive_id in the database
archive_id = archive.id

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 opentok.start_archive() método para OutputModes.individual.

archive = opentok.start_archive(session_id, name=u'Important Presentation', output_mode=OutputModes.individual)

# Store this archive_id in the database
archive_id = archive.id

Los archivos compuestos (output_mode=OutputModes.composed) tienen un parámetro opcional resolution parámetro. Si no se especifica ningún valor, la plataforma OpenTok utilizará la resolución predeterminada «640x480». Puedes establecerla en «1280x720» configurando el resolution del opentok.start_archive() método.

Advertencia: Este valor no se puede configurar en el modo de salida «Individual»; se producirá un error.

archive = opentok.start_archive(session_id, name=u'Important Presentation', resolution="1280x720")

# Store this archive_id in the database
archive_id = archive.id

Puede detener la grabación de un Archivo iniciado utilizando la tecla opentok.stop_archive(archive_id) método. También puedes hacerlo utilizando el archive.stop() método de un Archive instancia.

# Stop an Archive from an archive_id (fetched from database)
opentok.stop_archive(archive_id)
# Stop an Archive from an instance (returned from opentok.start_archive)
archive.stop()

Para obtener un Archive (y toda su información) a partir de un ID de archivo, utilice la función opentok.get_archive(archive_id) método.

archive = opentok.get_archive(archive_id)

Para eliminar un archivo, puedes llamar a la función opentok.delete_archive(archive_id) o el método archive.delete() método de un Archive instancia.

# Delete an Archive from an archive ID (fetched from database)
opentok.delete_archive(archive_id)
# Delete an Archive from an Archive instance (returned from opentok.start_archive or
opentok.get_archive)
archive.delete()

También puedes obtener una lista de todos los archivos que hayas creado (hasta 1000) con tu clave API. Para ello, utiliza la opentok.list_archives() método. Hay dos parámetros de palabra clave opcionales: count y offset; te permiten paginar los resultados. Este método devuelve una instancia de la ArchiveList clase.

archive_list = opentok.list_archive()

# Get a specific Archive from the list
archive = archive_list.items[i]

# Iterate over items
for archive in iter(archive_list):
  pass

# Get the total number of Archives for this API Key
total = archive_list.total

Tenga en cuenta que también puede crear una sesión archivada automáticamente, pasando en ArchiveModes.always como el archive_mode parámetro al llamar a la función opentok.create_session() método (véase «Creación de sesiones», más arriba).

En el caso de los archivos compuestos, puede cambiar el diseño dinámicamente, utilizando la función opentok.set_archive_layout(archive_id, type, stylesheet) método:

opentok.set_archive_layout('ARCHIVEID', 'horizontalPresentation')

Configurar el diseño de los archivos compuestos es opcional. Por defecto, los archivos compuestos utilizan el best fit diseño. Otros valores válidos son: custom, horizontalPresentation, pip y verticalPresentation. Si se especifica un custom tipo de diseño, establezca el stylesheet parámetro:

opentok.set_archive_layout(
    'ARCHIVEID',
    'custom',
    '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 los archivos compuestos.

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

Envío de señales

Una vez creada una sesión, puedes enviar señales a todos los participantes de la sesión o a una conexión concreta. Para enviar una señal, debes llamar a la función signal(session_id, payload) método del OpenTok clase. En payload El parámetro es un diccionario que se utiliza para configurar el type, data campos. También puedes llamar al método con el parámetro connection_id para enviar una señal a una conexión concreta signal(session_id, data, connection_id).

# payload structure
payload = {
    'type': 'type', #optional
    'data': 'signal data' #required
}

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

# To send a signal to everyone in the session:
opentok.signal(session_id, payload)

# To send a signal to a specific connection in the session:
opentok.signal(session_id, payload, 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 OpenTok clase.

El método devuelve un objeto Stream que contiene información sobre una transmisión de OpenTok:

id: El identificador de la transmisión

videoType: «cámara» o «pantalla»

name: El nombre de la transmisión (si se había establecido alguno cuando el cliente publicó la transmisión)

layoutClassList: Es una matriz que contiene las clases de diseño para el flujo

session_id = 'SESSIONID'
stream_id = '8b732909-0a06-46a2-8ea8-074e64d43422'

# To get stream info:
stream = opentok.get_stream(session_id, stream_id)

# Stream properties:
print stream.id #8b732909-0a06-46a2-8ea8-074e64d43422
print stream.videoType #camera
print stream.name #stream name
print stream.layoutClassList #['full']

Además, puedes obtener información sobre todas las transmisiones de una sesión llamando a la función list_streams(session_id) método del OpenTok clase.

El método devuelve un objeto StreamList que contiene una lista de todas las secuencias

# To get all streams in a session:
stream_list = opentok.list_streams(session_id)

# Getting the first stream of the list
stream = stream_list.items[0]

# Stream properties:
print stream.id #8b732909-0a06-46a2-8ea8-074e64d43422
print stream.videoType #camera
print stream.name #stream name
print stream.layoutClassList #['full']

Desconexión forzada

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de OpenTok llamando a la función force_disconnect(session_id, connection_id) método del OpenTok clase, o el force_disconnect(connection_id) método del Session clase.

session_id = 'SESSIONID'
connection_id = 'CONNECTIONID'

# To send a request to disconnect a client:
opentok.force_disconnect(session_id, connection_id)

Trabajar con la interconexión SIP

Puedes conectar tu plataforma SIP a una sesión de OpenTok; el audio de tu extremo de la llamada SIP se añade a la sesión de OpenTok como una transmisión de solo audio. El OpenTok Media Router mezcla el audio de otras transmisiones de la sesión y envía el audio mezclado a tu terminal SIP.

  session_id = u('SESSIONID')
  token = u('TOKEN')
  sip_uri = u('sip:user@sip.partner.com;transport=tls')

  # call the method with the required parameters
  sip_call = opentok.dial(session_id, token, sip_uri)

  # the method also support aditional options to establish the sip call

  options = {
      'from': 'from@example.com',
      'headers': {
          'headerKey': 'headerValue'
      },
      'auth': {
          'username': 'username',
          'password': 'password'
      },
      'secure': True
  }

  # call the method with aditional options
  sip_call = opentok.dial(session_id, token, sip_uri, options)

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

Trabajar con emisiones

La función de retransmisión de OpenTok te permite compartir sesiones de OpenTok en directo con numerosos espectadores.

Puedes utilizar el opentok.start_broadcast() Método para iniciar una retransmisión en directo de una sesión de OpenTok. Esto permite retransmitir la sesión mediante HLS (HTTP Live Streaming) o RTMP.

Para poder iniciar correctamente la retransmisión de una sesión, debe haber al menos un cliente conectado a ella.

La retransmisión en directo puede dirigirse a un punto final HLS y a un máximo de cinco servidores RTMP simultáneamente durante una sesión. Solo se puede iniciar la retransmisión en directo en sesiones que utilicen el OpenTok Media Router; no es posible utilizar la retransmisión en directo en sesiones cuyo modo multimedia esté configurado como «relayed».

  session_id = 'SESSIONID'
  options = {
    'layout': {
      'type': 'custom',
      'stylesheet': 'the layout stylesheet (only used with type == custom)'
    },
    'maxDuration': 5400,
    'hasAudio': True
    'hasVideo': True
    'outputs': {
      'hls': {},
      'rtmp': [{
        'id': 'foo',
        'serverUrl': 'rtmp://myfooserver/myfooapp',
        'streamName': 'myfoostream'
      }, {
        'id': 'bar',
        'serverUrl': 'rtmp://mybarserver/mybarapp',
        'streamName': 'mybarstream'
      }]
    },
    'resolution': '640x480'
  }

  broadcast = opentok.start_broadcast(session_id, options)

Puedes transmitir solo audio o solo vídeo en una retransmisión configurando hasAudio o hasVideo a False según sea necesario. Estos campos son True por defecto.

  session_id = 'SESSIONID'
  options = {
    'layout': {
      'type': 'custom',
      'stylesheet': 'the layout stylesheet (only used with type == custom)'
    },
    'maxDuration': 5400,
    'hasAudio': True
    'hasVideo': False
    'outputs': {
      'hls': {},
      'rtmp': [{
        'id': 'foo',
        'serverUrl': 'rtmp://myfooserver/myfooapp',
        'streamName': 'myfoostream'
      }, {
        'id': 'bar',
        'serverUrl': 'rtmp://mybarserver/mybarapp',
        'streamName': 'mybarstream'
      }]
    },
    'resolution': '640x480'
  }
  broadcast = opentok.start_broadcast(session_id, options)

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

  # getting the ID from a broadcast object
  broadcast_id = broadcast.id

  # stop a broadcast
  broadcast = opentok.stop_broadcast(broadcast_id)

Puede obtener información detallada sobre una emisión en curso utilizando el método opentok.get_broadcast(broadcast_id).

  broadcast_id = '1748b7070a81464c9759c46ad10d3734'

  # get broadcast details
  broadcast = opentok.get_broadcast(broadcast_id)

  print broadcast.json()

  # print result
  # {
  #   "createdAt": 1437676551000,
  #   "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  #   "projectId": 100,
  #   "resolution": "640x480",
  #   "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  #   "status": "started",
  #   "updatedAt": 1437676551000,
  #   "broadcastUrls": {
  #       "hls": "http://server/fakepath/playlist.m3u8",
  #       "rtmp": {
  #           "bar": {
  #               "serverUrl": "rtmp://mybarserver/mybarapp",
  #               "status": "live",
  #               "streamName": "mybarstream"
  #           },
  #           "foo": {
  #               "serverUrl": "rtmp://myfooserver/myfooapp",
  #               "status": "live",
  #               "streamName": "myfoostream"
  #           }
  #       }
  #   }
  # }

Puedes cambiar dinámicamente el tipo de diseño de una retransmisión en directo.

  # Valid values to 'layout_type' are: 'custom', 'horizontalPresentation',
  # 'pip' and 'verticalPresentation' 
  opentok.set_broadcast_layout('BROADCASTID', 'horizontalPresentation')

  # if you specify a 'custom' layout type, set the stylesheet parameter:
  opentok.set_broadcast_layout(
      'BROADCASTID',
      'custom',
      'stream.instructor {position: absolute; width: 100%;  height:50%;}'
  )

Para obtener más información sobre las retransmisiones en directo de OpenTok, consulta la Guía para desarrolladores de retransmisiones.

Conectar el audio a un WebSocket

Puedes enviar audio a un WebSocket con el opentok.connect_audio_to_websocket método. Para obtener más información, consulta el Guía del desarrollador del Conector de audio.

  websocket_options = {"uri": "wss://service.com/ws-endpoint"}
  websocket_audio_connection = opentok.connect_audio_to_websocket(session_id, opentok_token, websocket_options)

Además, puedes especificar únicamente los flujos concretos que deseas enviar al WebSocket y/o los encabezados adicionales que se envían, añadiendo estos campos al websocket_options objeto.

  websocket_options = {
    "uri": "wss://service.com/ws-endpoint",
    "streams": [
      "streamId-1",
      "streamId-2"
    ],
    "headers": {
      "headerKey": "headerValue"
    }
  }

Configuración del tiempo de espera

El tiempo de espera se pasa en el constructor de Client:

  self.timeout = timeout

Para configurar el tiempo de espera, primero crea una instancia:

  opentok = Client(...., timeout=value)

A continuación, cambia el valor con

  opentok.timeout = value

Silenciar transmisiones

Puedes silenciar todas las transmisiones de una sesión utilizando el opentok.mute_all() método:

  opentok.mute_all(session_id)

Además de las transmisiones existentes, cualquier transmisión que se publique tras la llamada a este método se publicará con el audio silenciado. Puedes desactivar el estado de silencio de una sesión llamando al método opentok.disableForceMute() método:

  
excluded_stream_ids = ['1234', '5678']
opentok.mute_all(session_id, excluded_stream_ids)

Tras llamar al opentok.disableForceMute() Con este método, las nuevas transmisiones que se publiquen en la sesión no se silenciarán.

  
opentok.disable_force_mute(session_id)

Puedes silenciar una sola transmisión utilizando el opentok.mute_stream() método:

  
opentok.mute_stream(session_id, stream_id)

DTMF

Puedes enviar dígitos DTMF (multifrecuencia de dos tonos) a terminales SIP. Puedes reproducir tonos DTMF para todos los clientes conectados a la sesión o para una conexión específica:

  
digits = '12345'
opentok.play_dtmf(session_id, digits)

# To a specific connection
opentok.play_dtmf(session_id, connection_id, digits)

Añadir información al agente de usuario

Puedes añadir una cadena al agente de usuario que se envía con las solicitudes:

  
  opentok.append_to_user_agent('my-appended-string')

Requisitos

Necesitas una clave API y un secreto API de OpenTok, que puedes obtener iniciando sesión en tu Cuenta API de Video de Vonage.

El SDK de OpenTok para Python requiere Python 3.5 o una versión superior

Cambios importantes desde la versión 2.2.0

Cambios en la versión 2.2.1:

La configuración predeterminada para el create_session() El método consiste en crear una sesión con el modo multimedia configurado en «relayed». En versiones anteriores del SDK, la configuración predeterminada era utilizar el OpenTok Media Router (modo multimedia configurado en «routed»). En una sesión de retransmisión, los clientes intentarán enviar flujos directamente entre sí (punto a punto); si los clientes no pueden conectarse debido a restricciones del cortafuegos, la sesión utiliza el servidor TURN de OpenTok para retransmitir los flujos de audio y vídeo.

Cambios en la versión 2.2.0:

Esta versión del SDK incluye compatibilidad para trabajar con archivos de OpenTok 2.

El Client.create_session() El método ahora incluye un media_mode parámetro, en lugar de un p2p parámetro.