SDK Python de la Video API Vonage

• Présentation du SDK
• Référence API
• Télécharger
• Exemples
• GitHub

Le SDK Python d'OpenTok vous permet de générer sessions et jetons pour les applications OpenTok, et archives Sessions OpenTok.

Installation à l'aide de Pip (recommandée) :

Pip permet de gérer les dépendances des projets Python à l'aide de l'index PyPI. Pour en savoir plus, rendez-vous ici : http://www.pip-installer.org/en/latest/.

Ajouter le opentok ce package en tant que dépendance dans votre projet. La méthode la plus courante consiste à l'ajouter à votre requirements.txt fichier :

opentok>=3.0

Ensuite, installez les dépendances :

$ pip install -r requirements.txt

Utilisation

Initialisation

Importez le package en début de tout fichier dans lequel vous comptez l'utiliser. Vous aurez au minimum besoin de la commande Client classe. Initialisez ensuite une instance du client OpenTok à l'aide de votre propre clé API et de votre secret API.

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

Création de sessions

Pour créer une session OpenTok, utilisez la commande opentok.create_session() méthode. Cette méthode dispose de paramètres par mot-clé facultatifs :

• location qui peut être défini sur une chaîne de caractères contenant une adresse IP.
• media_mode qui est une chaîne de caractères (définie par la classe MediaModes). Cela détermine si la session utilisera le Routeur multimédia OpenTok ou tenter d'envoyer des flux directement entre clients. Une session acheminée est requise pour certaines fonctionnalités d'OpenTok (telles que l'archivage).
• archive_mode qui précise si la session sera automatiquement archivée (always) ou non (manual).
• archive_name qui indique le nom d'archive pour toutes les archives de la session à archivage automatique. Une session qui démarre avec le mode d'archivage « always » utilisera ce nom d'archive pour toutes les archives de cette session. Le fait de passer le paramètre « archive_name » avec le mode d'archivage « manual » entraînera une réponse d'erreur.
• archive_resolution qui indique la résolution d'archivage pour toutes les archives de la session d'archivage automatique. Les valeurs valides sont « 640x480 », « 480x640 », « 1280x720 », « 720x1280 », « 1920x1080 » et « 1080x1920 ». Une session démarrant en mode d’archivage « always » utilisera cette résolution pour toutes les archives de cette session. Le fait de passer le paramètre « archive_resolution » avec le mode d’archivage « manual » entraînera une réponse d’erreur.
• e2ee qui est une valeur booléenne. Elle permet de spécifier s'il faut activer chiffrement de bout en bout pour la session OpenTok.

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

# 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

Générer des jetons

Une fois la session créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour s'y connecter. Vous pouvez générer un jeton soit en appelant la méthode opentok.generate_token(session_id) méthode ou en appelant la session.generate_token() sur un Session instance après sa création. Il existe un ensemble de paramètres facultatifs sous forme de mots-clés : role, expire_time, dataet 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'])

Travailler avec les archives

Important : Vous ne pouvez archiver que les sessions qui utilisent OpenTok Media Router (c'est-à-dire celles dont le mode multimédia est défini sur « routed »).

Vous pouvez lancer l'enregistrement d'une session OpenTok à l'aide de la commande opentok.start_archive(session_id) méthode. Cette méthode prend un argument de mot-clé facultatif name pour attribuer un nom à l'archive. Cette méthode renverra un Archive Par exemple. Notez que vous ne pouvez lancer une archive que sur une session à laquelle des clients sont connectés.

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

# Store this archive_id in the 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 la propriété options au paramètre 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

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 opentok.start_archive() à la méthode 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

Les archives composées (output_mode=OutputModes.composed) comportent un paramètre facultatif resolution paramètre. Si aucune valeur n'est fournie, la plateforme OpenTok utilisera la résolution par défaut « 640x480 ». Vous pouvez la définir sur « 1280x720 » en configurant le resolution du paramètre opentok.start_archive() méthode.

Avertissement : Cette valeur ne peut pas être définie en mode de sortie « Individuel » ; une erreur sera générée.

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

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

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche opentok.stop_archive(archive_id) méthode. Vous pouvez également le faire à l'aide de la archive.stop() méthode d'un Archive instance.

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

Pour obtenir un Archive (et toutes les informations la concernant) à partir d'un ID d'archive, utilisez la commande opentok.get_archive(archive_id) méthode.

archive = opentok.get_archive(archive_id)

Pour supprimer une archive, vous pouvez appeler le opentok.delete_archive(archive_id) ou la méthode archive.delete() méthode d'un Archive instance.

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

Vous pouvez également obtenir la liste de toutes les archives que vous avez créées (jusqu'à 1 000) à l'aide de votre clé API. Pour ce faire, utilisez la opentok.list_archives() méthode. Il existe deux paramètres de mot-clé facultatifs : count et offset; elles vous permettent de parcourir les résultats par pages. Cette méthode renvoie une instance de la 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

Notez que vous pouvez également créer une session automatiquement archivée, en passant le paramètre ArchiveModes.always en tant que archive_mode paramètre lorsque vous appelez la fonction opentok.create_session() méthode (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 opentok.set_archive_layout(archive_id, type, stylesheet) méthode :

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

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 verticalPresentation. Si vous spécifiez un custom définir le type de mise en page stylesheet paramètre :

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

Pour plus d'informations sur l'archivage, voir la page Guide du développeur sur l'archivage OpenTok.

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 signal(session_id, payload) de la méthode OpenTok classe. Les payload Le paramètre est un dictionnaire utilisé pour définir le type, data champs. Vous pouvez également appeler la méthode avec le paramètre connection_id pour envoyer un signal à une connexion spécifique 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)

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 OpenTok classe.

Cette méthode renvoie un objet Stream contenant les informations relatives à un flux OpenTok :

id: L'identifiant du flux

videoType: « caméra » ou « écran »

name: Le nom du flux (s'il a été défini lors de la publication du flux par le client)

layoutClassList: Il s'agit d'un tableau contenant les classes de mise en page pour le flux

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

Vous pouvez également obtenir des informations sur tous les flux d'une session en appelant la fonction list_streams(session_id) de la méthode OpenTok classe.

La méthode renvoie un objet StreamList contenant la liste de tous les flux.

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

Déconnexion forcée

Votre serveur d'applications peut déconnecter un client d'une session OpenTok en appelant la méthode force_disconnect(session_id, connection_id) de la méthode OpenTok classe, ou le force_disconnect(connection_id) de la méthode Session classe.

session_id = 'SESSIONID'
connection_id = 'CONNECTIONID'

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

Travailler avec SIP Interconnect

Vous pouvez connecter votre plateforme SIP à une session OpenTok ; le flux audio provenant de votre côté de l'appel SIP est alors ajouté à la session OpenTok sous la forme d'un flux audio uniquement. Le routeur multimédia OpenTok mélange ce flux audio avec ceux des autres participants à la session, puis envoie le flux audio mixé vers votre 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)

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

Travailler avec des diffusions

La fonctionnalité de diffusion d'OpenTok vous permet de partager des sessions OpenTok en direct avec un large public.

Vous pouvez utiliser le opentok.start_broadcast() méthode permettant de lancer une diffusion en direct pour une session OpenTok. Cela permet de diffuser la session via un flux HLS (HTTP Live Streaming) ou 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 de terminaison HLS et jusqu'à cinq serveurs RTMP simultanément pour une même session. Vous ne pouvez lancer la diffusion en direct que pour les sessions utilisant OpenTok Media Router ; vous ne pouvez pas utiliser la diffusion en direct avec les sessions dont le mode multimédia est défini sur « 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)

Vous pouvez diffuser uniquement le son ou uniquement la vidéo d'un flux en configurant hasAudio ou hasVideo à False si nécessaire. Ces champs sont les suivants : True par défaut.

  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)

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

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

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

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

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

  # 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%;}'
  )

Pour plus d'informations sur les diffusions en direct avec OpenTok, consultez la Guide du développeur pour la diffusion.

Connexion audio à un WebSocket

Vous pouvez envoyer des données audio vers un WebSocket à l'aide de la commande opentok.connect_audio_to_websocket méthode. Pour plus d'informations, voir la page Guide du développeur Audio Connector.

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

De plus, vous pouvez n'indiquer que les flux spécifiques que vous souhaitez envoyer au WebSocket, et/ou les en-têtes supplémentaires qui sont envoyés, en ajoutant ces champs au websocket_options objet.

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

Configuration du délai d'expiration

Le délai d'expiration est transmis au constructeur du client :

  self.timeout = timeout
  

Pour configurer le délai d'expiration, commencez par créer une instance :

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

Puis modifiez la valeur à l'aide de

  opentok.timeout = value
  

Désactiver le son des flux

Vous pouvez couper le son de tous les flux d'une session à l'aide de la commande opentok.mute_all() méthode :

  opentok.mute_all(session_id)
  

Outre les flux existants, tous les flux publiés après l'appel de cette méthode sont publiés avec le son désactivé. Vous pouvez désactiver la mise en sourdine d'une session en appelant la méthode opentok.disableForceMute() méthode :

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

Après avoir appelé le opentok.disableForceMute() Avec cette méthode, les nouveaux flux publiés dans la session ne seront pas mis en sourdine.

  
opentok.disable_force_mute(session_id)

Vous pouvez couper le son d'un flux à l'aide de la commande opentok.mute_stream() méthode :

  
opentok.mute_stream(session_id, stream_id)

DTMF

Vous pouvez envoyer des chiffres DTMF (Dual-Tone Multi-Frequency) à des terminaux SIP. Vous pouvez diffuser des tonalités DTMF à tous les clients connectés à une session ou à une connexion spécifique :

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

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

Ajout à l'agent utilisateur

Vous pouvez ajouter une chaîne de caractères à l'agent utilisateur envoyé avec les requêtes :

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

Exigences

Vous avez besoin d'une clé API OpenTok et d'un secret API, que vous pouvez obtenir en vous connectant à votre Compte Video API de Vonage.

Le SDK Python d'OpenTok nécessite Python 3.5 ou une version ultérieure

Modifications importantes depuis la version 2.2.0

Modifications apportées à la version 2.2.1 :

Le paramètre par défaut pour le create_session() La méthode consiste à créer une session avec le mode multimédia défini sur « relayed ». Dans les versions précédentes du SDK, le paramètre par défaut consistait à utiliser le routeur multimédia OpenTok (mode multimédia défini sur « routed »). Dans une session en mode « relayed », les clients tentent d'échanger des flux directement entre eux (peer-to-peer) ; si les clients ne parviennent pas à se connecter en raison de restrictions de pare-feu, la session utilise le serveur TURN d'OpenTok pour relayer les flux audio et vidéo.

Nouveautés de la version 2.2.0 :

Cette version du SDK prend en charge l'utilisation des archives OpenTok 2.

Les Client.create_session() Cette méthode inclut désormais un media_mode paramètre, au lieu d'un p2p paramètre.