SDK em Python da Video API da Vonage

• Visão geral do SDK
• Referência da API
• Baixar
• Amostras
• GitHub

O SDK do OpenTok para Python permite que você gere sessões e fichas para aplicativos OpenTok, e arquivo Sessões do OpenTok.

Instalação usando o Pip (recomendado):

O Pip ajuda a gerenciar dependências para projetos em Python usando o índice PyPI. Saiba mais aqui: http://www.pip-installer.org/en/latest/.

Adicione o opentok inclua o pacote como dependência no seu projeto. A maneira mais comum é adicioná-lo ao seu requirements.txt arquivo:

opentok>=3.0

Em seguida, instale as dependências:

$ pip install -r requirements.txt

Uso

Inicializando

Importe o pacote no início de qualquer arquivo em que você for usá-lo. No mínimo, você precisará do Client classe. Em seguida, inicialize uma instância do OpenTok Client com sua própria chave de API e seu segredo de API.

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

Criação de sessões

Para criar uma sessão do OpenTok, use o opentok.create_session() método. Existem parâmetros de palavra-chave opcionais para este método:

• location que pode ser definido como uma sequência de caracteres contendo um endereço IP.
• media_mode que é uma String (definida pela classe MediaModes). Isso determina se a sessão utilizará o Roteador de mídia OpenTok ou tentar enviar transmissões diretamente entre clientes. É necessária uma sessão roteada para alguns recursos do OpenTok (como o arquivamento).
• archive_mode que especifica se a sessão será arquivada automaticamente (always) ou não (manual).
• archive_name que indica o nome do arquivo para todos os arquivos da sessão com arquivamento automático. Uma sessão que inicie com o modo de arquivamento “always” utilizará esse nome de arquivo para todos os arquivos dessa sessão. Passar o parâmetro “archive_name” com o modo de arquivamento “manual” resultará em uma resposta de erro.
• archive_resolution que indica a resolução de arquivamento para todos os arquivos na sessão de arquivamento automático. Os valores válidos são '640x480', '480x640', '1280x720', '720x1280', '1920x1080' e '1080x1920'. Uma sessão que inicie com o modo de arquivamento “always” utilizará essa resolução para todos os arquivos dessa sessão. Passar o parâmetro “archive_resolution” com o modo de arquivamento “manual” resultará em uma resposta de erro.
• e2ee que é um valor booleano. Isso especifica se deve ser ativado criptografia de ponta a ponta para a sessão do OpenTok.

Este método retorna um Session objeto. Seu session_id O atributo é útil ao salvar em um armazenamento persistente (como um banco de dados).

# 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

Geração de tokens

Depois que uma sessão for criada, você poderá começar a gerar tokens para que os clientes os utilizem ao se conectarem a ela. É possível gerar um token chamando o método opentok.generate_token(session_id) método ou chamando o session.generate_token() método em um Session instância após criá-la. Há um conjunto de parâmetros opcionais de palavra-chave: role, expire_time, data, e 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'])

Trabalhando com arquivos

Importante: É possível arquivar apenas as sessões que utilizam o OpenTok Media Router (sessões com o modo de mídia definido como “routed”).

Você pode iniciar a gravação de uma sessão do OpenTok usando o opentok.start_archive(session_id) método. Esse método recebe um argumento de palavra-chave opcional name para atribuir um nome ao arquivo. Esse método retornará um Archive instância. Observe que só é possível iniciar um Arquivo em uma Sessão que tenha clientes conectados.

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

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

Você também pode desativar a gravação de áudio ou vídeo configurando o has_audio ou has_video propriedade do options parâmetro para 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 padrão, todos os fluxos são gravados em um único arquivo (composto). É possível gravar os diferentes fluxos da sessão em arquivos individuais (em vez de um único arquivo composto) definindo a output_mode parâmetro do 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

Arquivos compostos (output_mode=OutputModes.composed) possuem um resolution parâmetro. Se nenhum valor for fornecido, a plataforma OpenTok utilizará a resolução padrão “640x480”. Você pode definir esse valor como “1280x720” configurando o resolution parâmetro do opentok.start_archive() método.

Aviso: Esse valor não pode ser definido no modo de saída “Individual”; será gerado um erro.

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

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

Você pode interromper a gravação de um arquivo já iniciado usando o opentok.stop_archive(archive_id) método. Você também pode fazer isso usando o archive.stop() método de um Archive instância.

# 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 obter um Archive instância (e todas as informações a respeito dela) a partir de um ID de arquivo, use o opentok.get_archive(archive_id) método.

archive = opentok.get_archive(archive_id)

Para excluir um arquivo, você pode chamar a função opentok.delete_archive(archive_id) método ou o archive.delete() método de um Archive instância.

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

Você também pode obter uma lista de todos os arquivos que criou (até 1.000) com sua chave de API. Isso é feito usando o opentok.list_archives() método. Existem dois parâmetros de palavra-chave opcionais: count e offset; eles podem ajudar você a paginar os resultados. Esse método retorna uma instância do ArchiveList classe.

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

Observe que você também pode criar uma sessão arquivada automaticamente, passando ArchiveModes.always como o archive_mode parâmetro ao chamar o opentok.create_session() método (consulte “Criação de sessões”, acima).

Para arquivos compostos, é possível alterar o layout dinamicamente, usando o opentok.set_archive_layout(archive_id, type, stylesheet) método:

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

A configuração do layout dos arquivos compostos é opcional. Por padrão, os arquivos compostos utilizam o best fit layout. Outros valores válidos são: custom, horizontalPresentation, pip e verticalPresentation. Se você especificar um custom tipo de layout, defina o stylesheet parâmetro:

opentok.set_archive_layout(
    'ARCHIVEID',
    'custom',
    'stream.instructor {position: absolute; width: 100%;  height:50%;}'
)

Para outros tipos de layout, não defina a propriedade da folha de estilo. Para obter mais informações, consulte Personalização do layout do vídeo para arquivos compostos.

Para obter mais informações sobre arquivamento, consulte o Guia do desenvolvedor sobre arquivamento do OpenTok.

Enviando sinais

Depois que uma sessão for criada, você poderá enviar sinais para todos os participantes da sessão ou para uma conexão específica. Para enviar um sinal, basta chamar a função signal(session_id, payload) método do OpenTok classe. A payload O parâmetro é um dicionário usado para definir o type, data campos. Você também pode chamar o método com o parâmetro connection_id para enviar um sinal a uma conexão específica 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)

Trabalhando com fluxos

É possível obter informações sobre um fluxo chamando a função get_stream(session_id, stream_id) método do OpenTok classe.

O método retorna um objeto Stream que contém informações de um stream do OpenTok:

id: O ID da transmissão

videoType: “câmera” ou “tela”

name: O nome do stream (caso tenha sido definido quando o cliente publicou o stream)

layoutClassList: É uma matriz das classes de layout para o fluxo

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']

Além disso, é possível obter informações sobre todos os fluxos de uma sessão chamando a função list_streams(session_id) método do OpenTok classe.

O método retorna um objeto StreamList que contém uma lista de todos os fluxos

# 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']

Desconexão forçada

Seu servidor de aplicativos pode desconectar um cliente de uma sessão do OpenTok chamando a função force_disconnect(session_id, connection_id) método do OpenTok classe, ou o force_disconnect(connection_id) método do Session classe.

session_id = 'SESSIONID'
connection_id = 'CONNECTIONID'

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

Trabalhando com interconexão SIP

Você pode conectar sua plataforma SIP a uma sessão do OpenTok; o áudio da sua extremidade da chamada SIP é adicionado à sessão do OpenTok como um fluxo apenas de áudio. O OpenTok Media Router mixa o áudio de outros fluxos na sessão e envia o áudio mixado para o seu 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 obter mais informações, incluindo detalhes técnicos e considerações de segurança, consulte o Interconexão SIP da OpenTok guia do desenvolvedor.

Trabalhando com transmissões

A transmissão do OpenTok permite que você compartilhe sessões ao vivo do OpenTok com muitos espectadores.

Você pode usar o opentok.start_broadcast() método para iniciar uma transmissão ao vivo para uma sessão do OpenTok. Isso transmite a sessão para um fluxo HLS (HTTP Live Streaming) ou para um fluxo RTMP.

Para iniciar com sucesso a transmissão de uma sessão, é necessário que pelo menos um cliente esteja conectado à sessão.

A transmissão ao vivo pode ser direcionada a um ponto de extremidade HLS e a até cinco servidores RTMP simultaneamente por sessão. Só é possível iniciar a transmissão ao vivo para sessões que utilizem o OpenTok Media Router; não é possível usar a transmissão ao vivo com sessões cujo modo de mídia esteja definido 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)

Você pode transmitir apenas áudio ou apenas vídeo em uma transmissão, configurando hasAudio ou hasVideo para False conforme necessário. Esses campos são True por padrão.

  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)

É possível interromper uma transmissão já iniciada usando o 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)

É possível obter detalhes sobre uma transmissão em andamento usando o 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"
  #           }
  #       }
  #   }
  # }

É possível alterar dinamicamente o tipo de layout de uma transmissão ao vivo.

  # 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 obter mais informações sobre as transmissões ao vivo do OpenTok, consulte o Guia do desenvolvedor de transmissões.

Conectando áudio a um WebSocket

Você pode enviar áudio para um WebSocket usando o opentok.connect_audio_to_websocket método. Para obter mais informações, consulte o Guia do desenvolvedor do Audio Connector.

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

Além disso, você pode listar apenas os fluxos específicos que deseja enviar para o WebSocket e/ou os cabeçalhos adicionais que são enviados, adicionando esses campos ao websocket_options objeto.

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

Configuração do tempo limite

O tempo limite é passado no construtor do Cliente:

  self.timeout = timeout
  

Para configurar o tempo limite, primeiro crie uma instância:

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

Em seguida, altere o valor com

  opentok.timeout = value
  

Silenciar transmissões

Você pode silenciar todas as transmissões em uma sessão usando o opentok.mute_all() método:

  opentok.mute_all(session_id)
  

Além das transmissões existentes, todas as transmissões publicadas após a chamada a este método são publicadas com o áudio silenciado. É possível desativar o silenciamento de uma sessão chamando o método opentok.disableForceMute() método:

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

Depois de ligar para o opentok.disableForceMute() Com esse método, os novos streams publicados na sessão não serão silenciados.

  
opentok.disable_force_mute(session_id)

Você pode silenciar uma única transmissão usando o opentok.mute_stream() método:

  
opentok.mute_stream(session_id, stream_id)

DTMF

É possível enviar dígitos DTMF (Dual-Tone Multi-Frequency) para terminais SIP. É possível reproduzir tons DTMF para todos os clientes conectados à sessão ou para uma conexão específica:

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

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

Adicionando informações ao User Agent

Você pode acrescentar uma sequência de caracteres ao agente do usuário que é enviado junto com as solicitações:

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

Requisitos

Você precisa de uma chave de API e de um segredo de API do OpenTok, que podem ser obtidos fazendo login na sua Account da Video API da Vonage.

O SDK do OpenTok para Python requer o Python 3.5 ou uma versão superior

Alterações importantes desde a versão 2.2.0

Alterações na versão 2.2.1:

A configuração padrão para o create_session() O método consiste em criar uma sessão com o modo de mídia definido como “relayed”. Nas versões anteriores do SDK, a configuração padrão era utilizar o OpenTok Media Router (modo de mídia definido como “routed”). Em uma sessão retransmitida, os clientes tentarão enviar fluxos diretamente entre si (ponto a ponto); se os clientes não conseguirem se conectar devido a restrições de firewall, a sessão utiliza o servidor TURN do OpenTok para retransmitir os fluxos de áudio e vídeo.

Alterações na versão 2.2.0:

Esta versão do SDK inclui suporte para trabalhar com arquivos do OpenTok 2.

O Client.create_session() O método agora inclui um media_mode parâmetro, em vez de um p2p parâmetro.