Vonage Video API Python-SDK

• SDK-Übersicht
• API-Referenz
• Herunterladen
• Beispiele
• GitHub

Mit dem OpenTok Python SDK können Sie Sitzungen und Token für OpenTok-Applications und Archiv OpenTok-Sitzungen.

Installation mit Pip (empfohlen):

Pip unterstützt die Verwaltung von Abhängigkeiten für Python-Projekte mithilfe des PyPI-Index. Weitere Informationen finden Sie hier: http://www.pip-installer.org/en/latest/.

Fügen Sie die opentok Paket als Abhängigkeit in Ihr Projekt einbinden. Am häufigsten wird es zu Ihrer requirements.txt Datei:

opentok>=3.0

Als nächstes installieren Sie die Abhängigkeiten:

$ pip install -r requirements.txt

Verwendung

Initialisierung

Importieren Sie das Paket am Anfang einer beliebigen Datei, in der Sie es verwenden möchten. Sie benötigen zumindest das Client Klasse. Initialisieren Sie anschließend eine Instanz des OpenTok-Clients mit Ihrem eigenen API-Schlüssel und API-Geheimnis.

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

Sitzungen erstellen

Um eine OpenTok-Sitzung zu erstellen, verwenden Sie die opentok.create_session() Methode. Für diese Methode gibt es optionale Schlüsselwortparameter:

• location die auf eine Zeichenkette gesetzt werden kann, die eine IP-Adresse enthält.
• media_mode das ist ein String (definiert durch die Klasse „MediaModes“). Dieser bestimmt, ob die Sitzung den OpenTok Media Router oder versuchen, Streams direkt zwischen Clients zu übertragen. Für einige OpenTok-Funktionen (wie beispielsweise die Archivierung) ist eine geroutete Sitzung erforderlich.
• archive_mode die angibt, ob die Sitzung automatisch archiviert wird (always) oder nicht (manual).
• archive_name Dieser Parameter gibt den Archivnamen für alle Archive in einer automatisch archivierten Sitzung an. Eine Sitzung, die mit dem Archivierungsmodus „always“ beginnt, verwendet diesen Archivnamen für alle Archive dieser Sitzung. Die Übergabe von „archive_name“ bei Verwendung des Archivierungsmodus „manual“ führt zu einer Fehlermeldung.
• archive_resolution die die Archivauflösung für alle Archive in der automatisch archivierten Sitzung angibt. Gültige Werte sind „640x480“, „480x640“, „1280x720“, „720x1280“, „1920x1080“ und „1080x1920“. Eine Sitzung, die mit dem Archivierungsmodus „always“ beginnt, verwendet diese Auflösung für alle Archive dieser Sitzung. Die Übergabe von „archive_resolution“ bei einem Archivierungsmodus von „manual“ führt zu einer Fehlermeldung.
• e2ee das ein boolescher Wert ist. Damit wird festgelegt, ob End-to-End-Verschlüsselung für die OpenTok-Sitzung.

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

# 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

Token generieren

Sobald eine Sitzung erstellt wurde, können Sie damit beginnen, Token zu generieren, die Clients bei der Verbindung zu dieser Sitzung verwenden können. Sie können ein Token entweder durch Aufruf der opentok.generate_token(session_id) Methode oder durch Aufruf der session.generate_token() Methode auf eine Session Instanz nach deren Erstellung. Es gibt eine Reihe optionaler Schlüsselwortparameter: role, expire_time, dataund 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'])

Arbeiten mit Archiven

Das ist wichtig: Sie können nur Sitzungen archivieren, die den OpenTok Media Router verwenden (Sitzungen, bei denen der Medienmodus auf „routed“ eingestellt ist).

Sie können die Aufzeichnung einer OpenTok-Sitzung über die opentok.start_archive(session_id) Methode. Diese Methode akzeptiert ein optionales Schlüsselwortargument name um dem Archiv einen Namen zuzuweisen. Diese Methode gibt einen Archive Beispiel. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, mit der Clients verbunden sind.

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

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

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Option has_audio oder has_video Eigenschaft der options Parameter zu 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

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 opentok.start_archive() Methode zu 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

Zusammengesetzte Archive (output_mode=OutputModes.composed) verfügen über eine optionale resolution Parameter. Wird kein Wert angegeben, verwendet die OpenTok-Plattform die Standardauflösung „640x480“. Sie können diese auf „1280x720“ festlegen, indem Sie den resolution Parameter des opentok.start_archive() Methode.

Warnung: Dieser Wert kann im Modus „Einzelausgabe“ nicht festgelegt werden; es wird ein Fehler ausgegeben.

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

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

Sie können die Aufzeichnung eines gestarteten Archivs mit der Taste opentok.stop_archive(archive_id) Methode. Sie können dies auch mithilfe der archive.stop() Methode eines Archive Instanz.

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

Um eine Archive Instanz (und alle zugehörigen Informationen) aus einer Archiv-ID zu erhalten, verwenden Sie die opentok.get_archive(archive_id) Methode.

archive = opentok.get_archive(archive_id)

Um ein Archiv zu löschen, können Sie die Funktion opentok.delete_archive(archive_id) Methode oder die archive.delete() Methode eines Archive Instanz.

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

Sie können sich außerdem eine Liste aller von Ihnen mit Ihrem API-Schlüssel erstellten Archive (bis zu 1000) anzeigen lassen. Dies geschieht mithilfe der opentok.list_archives() Methode. Es gibt zwei optionale Schlüsselwortparameter: count und offset; damit können Sie die Ergebnisse paginieren. Diese Methode gibt eine Instanz der ArchiveList Klasse.

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

Beachten Sie, dass Sie auch eine automatisch archivierte Sitzung erstellen können, indem Sie in ArchiveModes.always als die archive_mode Parameter, wenn Sie die opentok.create_session() Methode (siehe „Sitzungen erstellen“ weiter oben).

Bei zusammengesetzten Archiven können Sie das Layout dynamisch ändern, indem Sie die opentok.set_archive_layout(archive_id, type, stylesheet) Methode:

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

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 verticalPresentation. Wenn Sie einen custom Layout-Typ, setzen Sie die stylesheet Parameter:

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

Weitere Informationen zur Archivierung finden Sie in der OpenTok-Entwicklerhandbuch zur Archivierung.

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 signal(session_id, payload) Methode der OpenTok Klasse. Die Website payload „parameter“ ist ein Wörterbuch, das zum Festlegen der type, data Felder. Sie können die Methode auch mit dem Parameter aufrufen connection_id um ein Signal an eine bestimmte Verbindung zu senden 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)

Arbeiten mit Strömen

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

Die Methode gibt ein Stream-Objekt zurück, das Informationen zu einem OpenTok-Stream enthält:

id: Die Stream-ID

videoType: „Kamera“ oder „Bildschirm“

name: Der Name des Streams (sofern dieser beim Veröffentlichen des Streams durch den Client festgelegt wurde)

layoutClassList: Es handelt sich um ein Array der Layout-Klassen für den Stream

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

Außerdem können Sie Informationen zu allen Streams einer Sitzung abrufen, indem Sie die Funktion list_streams(session_id) Methode der OpenTok Klasse.

Die Methode gibt ein StreamList-Objekt zurück, das eine Liste aller Streams enthält.

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

Erzwungene Trennung

Ihr Anwendungsserver kann einen Client von einer OpenTok-Sitzung trennen, indem er die force_disconnect(session_id, connection_id) Methode der OpenTok Klasse oder die force_disconnect(connection_id) Methode der Session Klasse.

session_id = 'SESSIONID'
connection_id = 'CONNECTIONID'

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

Arbeiten mit SIP Interconnect

Sie können Ihre SIP-Plattform mit einer OpenTok-Sitzung verbinden; der Ton von Ihrer Seite des SIP-Anrufs wird der OpenTok-Sitzung als reiner Audio-Stream hinzugefügt. Der OpenTok Media Router mischt den Ton aus anderen Streams in der Sitzung und sendet den gemischten Ton an Ihren SIP-Endpunkt.

  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)

Weitere Informationen, einschließlich technischer Details und Sicherheitsüberlegungen, finden Sie in der OpenTok SIP-Anbindung Leitfaden für Entwickler.

Arbeiten mit Broadcasts

Mit OpenTok Broadcast können Sie Live-OpenTok-Sitzungen mit vielen Zuschauern teilen.

Sie können die opentok.start_broadcast() Methode zum Starten eines Live-Streams für eine OpenTok-Sitzung. Damit wird die Sitzung als HLS-Stream (HTTP Live Streaming) oder als RTMP-Stream übertragen.

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

Die Live-Streaming-Übertragung kann pro Sitzung auf einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig ausgerichtet werden. Sie können Live-Streaming nur für Sitzungen starten, die den OpenTok Media Router verwenden; bei Sitzungen, bei denen der Medienmodus auf „relayed“ eingestellt ist, ist Live-Streaming nicht möglich.

  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)

Sie können für einen Stream entweder nur Audio oder nur Video übertragen, indem Sie folgende Einstellung vornehmen: hasAudio oder hasVideo zu False sofern erforderlich. Diese Felder sind True standardmäßig.

  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)

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

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

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

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

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

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

Weitere Informationen zu Live-Streaming-Übertragungen mit OpenTok finden Sie unter Leitfaden für Entwickler im Bereich Rundfunk.

Audio mit einem WebSocket verbinden

Sie können Audiodaten über einen WebSocket senden, und zwar mit dem opentok.connect_audio_to_websocket Methode. Weitere Informationen finden Sie in der Audio Connector Entwicklerhandbuch.

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

Darüber hinaus können Sie nur die spezifischen Streams auflisten, die Sie an den WebSocket senden möchten, und/oder die zusätzlichen Header, die gesendet werden, indem Sie diese Felder zum websocket_options Objekt.

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

Zeitlimit konfigurieren

Das Timeout wird im Konstruktor von „Client“ übergeben:

  self.timeout = timeout
  

Um das Timeout zu konfigurieren, erstellen Sie zunächst eine Instanz:

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

Und ändern Sie anschließend den Wert mit

  opentok.timeout = value
  

Streams stummschalten

Sie können alle Streams in einer Sitzung stummschalten, indem Sie die opentok.mute_all() Methode:

  opentok.mute_all(session_id)
  

Zusätzlich zu den bereits bestehenden Streams werden alle Streams, die nach dem Aufruf dieser Methode veröffentlicht werden, mit stummgeschaltetem Ton veröffentlicht. Sie können den Stummschaltungsstatus einer Sitzung aufheben, indem Sie die Methode opentok.disableForceMute() Methode:

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

Nachdem der opentok.disableForceMute() Mit dieser Methode werden neue Streams, die in der Sitzung veröffentlicht werden, nicht stummgeschaltet.

  
opentok.disable_force_mute(session_id)

Sie können einen einzelnen Stream mithilfe der opentok.mute_stream() Methode:

  
opentok.mute_stream(session_id, stream_id)

DTMF

Sie können DTMF-Ziffern (Dual-Tone Multi-Frequency) an SIP-Endpunkte senden. Sie können DTMF-Töne an alle mit der Sitzung verbundenen Clients oder an eine bestimmte Verbindung senden:

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

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

Ergänzung zum User-Agent

Sie können dem User-Agent, der mit den Anfragen gesendet wird, eine Zeichenfolge anhängen:

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

Anforderungen

Sie benötigen einen OpenTok-API-Schlüssel und ein API-Geheimnis, die Sie erhalten, indem Sie sich bei Ihrem Konto anmelden. Vonage Video API-Konto.

Für das OpenTok Python SDK ist Python 3.5 oder höher erforderlich.

Wichtige Änderungen seit Version 2.2.0

Änderungen in Version 2.2.1:

Die Standardeinstellung für die create_session() Die Vorgehensweise besteht darin, eine Sitzung zu erstellen, bei der der Medienmodus auf „relayed“ eingestellt ist. In früheren Versionen des SDK war die Standardeinstellung die Verwendung des OpenTok Media Routers (Medienmodus auf „routed“ eingestellt). In einer „relayed“-Sitzung versuchen die Clients, Streams direkt untereinander zu übertragen (Peer-to-Peer); können die Clients aufgrund von Firewall-Einschränkungen keine Verbindung herstellen, nutzt die Sitzung den OpenTok-TURN-Server, um Audio- und Videostreams weiterzuleiten.

Änderungen in Version 2.2.0:

Diese Version des SDK bietet Unterstützung für die Arbeit mit OpenTok-2-Archiven.

Die Client.create_session() Die Methode enthält nun eine media_mode Parameter, anstelle eines p2p Parameter.