Vonage Video API Python SDK

OpenTok Python SDK を使用すると、以下を生成できますセッションそしてトークン OpenTok Applications向け、およびアーカイブ OpenTokのセッション。

Pip を使用したインストール（推奨）：

Pipは、PyPIインデックスを利用してPythonプロジェクトの依存関係管理を支援します。詳細はこちらをご覧ください： http://www.pip-installer.org/en/latest/.

を追加する。 opentok プロジェクトの依存関係としてこのパッケージを追加します。最も一般的な方法は、これを requirements.txt ファイル：

opentok>=3.0

次に、依存関係をインストールする：

$ pip install -r requirements.txt

使用方法

初期化

そのパッケージを使用するファイルの先頭に、そのパッケージをインポートしてください。少なくとも、以下の Client クラス。次に、独自のAPIキーとAPIシークレットを使用して、OpenTokクライアントのインスタンスを初期化します。

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

セッションの作成

OpenTokセッションを作成するには、次の opentok.create_session() メソッド。このメソッドには、オプションのキーワード引数があります：

location これは、IPアドレスを含む文字列に設定することができます。
media_mode これは（MediaModes クラスで定義された）文字列です。これにより、セッションで OpenTok メディアルーターあるいは、クライアント間で直接ストリームを送信しようとしないでください。OpenTokの一部の機能（アーカイブなど）を利用するには、ルーティングされたセッションが必要です。
archive_mode セッションが自動的にアーカイブされるかどうかを指定する（always)または(manual).
archive_name これは、自動アーカイブセッション内のすべてのアーカイブのアーカイブ名を示します。アーカイブモードが「always」で開始されたセッションでは、そのセッションのすべてのアーカイブに対してこのアーカイブ名が使用されます。アーカイブモードが「manual」の場合に「archive_name」を指定すると、エラー応答が返されます。
archive_resolution これは、自動アーカイブセッション内のすべてのアーカイブの解像度を示します。有効な値は、「640x480」、「480x640」、「1280x720」、「720x1280」、「1920x1080」、および「1080x1920」です。アーカイブモードが「always」で開始されたセッションでは、そのセッションのすべてのアーカイブにこの解像度が使用されます。アーカイブモードが「manual」の状態で「archive_resolution」を指定すると、エラー応答が返されます。
e2ee これはブール値です。これは、有効にするかどうかを指定します。エンドツーエンドの暗号化 OpenTokセッションについて。

このメソッドは Session オブジェクトのことである。その session_id 属性は、永続ストア（データベースなど）に保存するときに便利です。

# 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

トークンの生成

セッションが作成されると、クライアントがそのセッションに接続する際に使用するトークンの生成を開始できます。トークンは、 opentok.generate_token(session_id) メソッドを使用するか、または session.generate_token() メソッドを Session インスタンスを作成した後。一連のオプションのキーワードパラメータがあります： role, expire_time, dataそして 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'])

アーカイブとの取り組み

重要だ： OpenTok Media Router を使用しているセッション（メディアモードが「routed」に設定されているセッション）のみをアーカイブできます。

OpenTokセッションの録画は、以下の方法を使用して開始できます。 opentok.start_archive(session_id) メソッド。このメソッドは、オプションのキーワード引数を受け取ります。 name アーカイブに名前を付ける。このメソッドは Archive 例。アーカイブを開始できるのは、クライアントが接続されているセッションのみである点に注意してください。

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

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

を設定することで、オーディオまたはビデオ録画を無効にすることもできます。 has_audio または has_video プロパティの options パラメータを 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

デフォルトでは、すべてのストリームは1つの（合成された）ファイルに記録されます。を設定することで、セッション内のさまざまなストリームを（1つの合成ファイルではなく）個別のファイルに記録することができます。 output_mode パラメーターの opentok.start_archive() メソッドを使用します。 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

構成済みアーカイブ（output_mode=OutputModes.composed）には、オプションの resolution パラメータ。値が指定されない場合、OpenTokプラットフォームはデフォルトの解像度「640x480」を使用します。これを「1280x720」に設定するには、 resolution パラメーターの opentok.start_archive() メソッドを使用する。

警告だ： この値は「個別出力モード」では設定できません。設定しようとするとエラーが発生します。

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

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

を使用して、開始したアーカイブの録画を停止することができます。 opentok.stop_archive(archive_id) メソッド。また、次の方法でもこれを行うことができます。 archive.stop() 〜の方法 Archive インスタンスだ。

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

を得るには Archive インスタンス(とそれに関するすべての情報)をアーカイブIDから取得するには opentok.get_archive(archive_id) メソッドを使用する。

archive = opentok.get_archive(archive_id)

アーカイブを削除するには opentok.delete_archive(archive_id) メソッドまたは archive.delete() 〜の方法 Archive インスタンスだ。

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

また、APIキーを使用して、自分が作成したすべてのアーカイブ（最大1000件）の一覧を取得することもできます。これを行うには、 opentok.list_archives() メソッド。2つのオプションのキーワード引数があります： count そして offset; これらを使えば、検索結果のページ分割を行うことができます。このメソッドは、 ArchiveList クラスである。

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

を渡すことで、自動的にアーカイブされたセッションを作成することもできます。 ArchiveModes.always として archive_mode を呼び出す際のパラメータ opentok.create_session() メソッド（上記の「セッションの作成」を参照）。

構成されたアーカイブの場合、レイアウトを動的に変更するには opentok.set_archive_layout(archive_id, type, stylesheet) メソッドを使用する：

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

構成済みアーカイブのレイアウトの設定は任意です。デフォルトでは、構成済みアーカイブは best fit レイアウトを指定します。その他の有効な値は以下の通り： custom, horizontalPresentation, pip そして verticalPresentation. もし custom レイアウト・タイプを設定します。 stylesheet パラメータが必要だ：

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

その他のレイアウト・タイプの場合は、stylesheetプロパティを設定しないでください。詳細については構成されたアーカイブのビデオレイアウトをカスタマイズする.

アーカイブの詳細については OpenTok アーカイブ開発者ガイド.

シグナルの送信

セッションが作成されると、セッション内の全員、または特定の接続にシグナルを送ることができます。シグナルを送るには signal(session_id, payload) のメソッドを使用する。 OpenTok クラスである。その payload parameter は、以下を設定するために使用される辞書です。 type, data フィールド。また、パラメータを指定してこのメソッドを呼び出すこともできます。 connection_id 特定の接続に信号を送信する 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)

ストリームを使う

ストリームに関する情報は get_stream(session_id, stream_id) のメソッドを使用する。 OpenTok クラスである。

このメソッドは、OpenTok ストリームの情報を含む Stream オブジェクトを返します：

id: ストリームID

videoType: 「カメラ」または「画面」

name: ストリーム名（クライアントがストリームを公開した際に設定されていた場合）

layoutClassList: これは、ストリームのレイアウトクラスの配列です

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

また、以下の関数を呼び出すことで、セッション内のすべてのストリームに関する情報を取得できます。 list_streams(session_id) のメソッドを使用する。 OpenTok クラスである。

このメソッドは、すべてのストリームのリストを含む StreamList オブジェクトを返します。

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

強制切断

アプリケーションサーバーは、 force_disconnect(session_id, connection_id) のメソッドを使用する。 OpenTok クラス、あるいは force_disconnect(connection_id) のメソッドを使用する。 Session クラスである。

session_id = 'SESSIONID'
connection_id = 'CONNECTIONID'

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

SIPインターコネクトでの作業

SIPプラットフォームをOpenTokセッションに接続すると、SIP通話のユーザー側からの音声が、音声のみのストリームとしてOpenTokセッションに追加されます。OpenTok Media Routerは、セッション内の他のストリームからの音声をミックスし、そのミックスされた音声を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)

技術的な詳細やセキュリティ上の注意点などの詳細については、以下を参照してください。 OpenTok SIP相互接続開発者ガイド

ブロードキャストでの作業

OpenTokの放送機能を使えば、OpenTokのライブセッションを多くの視聴者と共有できます。

を使用することができます。 opentok.start_broadcast() OpenTokセッションのライブストリーミングを開始する方法です。これにより、セッションがHLS（HTTPライブストリーミング）またはRTMPストリームに配信されます。

セッションのブロードキャストを成功裏に開始するには、少なくとも1人のクライアントがセッションに接続していなければならない。

ライブストリーミング配信では、1つのHLSエンドポイントと、最大5つのRTMPサーバーを1つのセッションで同時に指定できます。ライブストリーミングを開始できるのは、OpenTok Media Routerを使用しているセッションのみです。メディアモードが「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)

以下の設定を行うことで、ストリームについて音声のみ、または動画のみを配信することができます。 hasAudio または hasVideo への False 必要に応じて。これらのフィールドは True デフォルトで

  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)

開始したブロードキャストは opentok.stop_broadcast(broadcast_id) メソッドを使用する。

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

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

メソッドを使って、進行中の放送の詳細を得ることができる。 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"
  #           }
  #       }
  #   }
  # }

ライブストリーミング放送のレイアウトタイプを動的に変更できます。

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

OpenTokのライブ配信に関する詳細については、以下を参照してください。放送開発者ガイド.

WebSocketへのオーディオ接続

以下の方法で、WebSocketにオーディオを送信できます。 opentok.connect_audio_to_websocket メソッドを使用します。詳細についてはオーディオコネクタ開発者ガイド.

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

さらに、WebSocket に送信したい特定のストリームや、送信される追加のヘッダーのみを指定するには、これらのフィールドを websocket_options オブジェクトがある。

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

タイムアウトの設定

タイムアウトは、Clientのコンストラクタで渡されます：

  self.timeout = timeout

タイムアウトを設定するには、まずインスタンスを作成します：

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

そして、次のようにして値を変更します。

  opentok.timeout = value

ストリームのミュート

セッション内のすべてのストリームをミュートするには、 opentok.mute_all() メソッドを使用する：

  opentok.mute_all(session_id)

既存のストリームに加え、このメソッドの呼び出し後に公開されるすべてのストリームは、音声がミュートされた状態で公開されます。セッションのミュート状態を解除するには、 opentok.disableForceMute() メソッドを使用する：

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

を呼び出した後、 opentok.disableForceMute() このメソッドを使用すると、セッションに公開される新しいストリームはミュートされません。

  
opentok.disable_force_mute(session_id)

以下の方法を使って、個別のストリームの音声をミュートすることができます。 opentok.mute_stream() メソッドを使用する：

  
opentok.mute_stream(session_id, stream_id)

DTMF

SIPエンドポイントに対して、デュアルトーン多周波数（DTMF）の数字を送信することができます。セッションに接続されているすべてのクライアント、または特定の接続に対して、DTMFトーンを再生することができます。

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

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

ユーザーエージェントへの追加

リクエストとともに送信されるユーザーエージェントに、文字列を追加することができます：

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

必要条件

OpenTokのAPIキーとAPIシークレットが必要です。これらは、アカウントにログインすることで取得できます。 Vonage Video API アカウント.

OpenTok Python SDK には、Python 3.5 以降が必要です。

v2.2.0以降の主な変更点

v2.2.1での変更点：

のデフォルト設定は create_session() この方法では、メディアモードを「relayed」に設定してセッションを作成します。以前のバージョンのSDKでは、デフォルト設定としてOpenTok Media Routerを使用していました（メディアモードは「routed」に設定されていました）。リレー方式のセッションでは、クライアント同士が直接（ピアツーピア）でストリームを送信しようとします。ファイアウォールの制限によりクライアント同士が接続できない場合、セッションでは OpenTok TURN サーバーを使用して音声・動画ストリームを中継します。

v2.2.0での変更点：

このバージョンのSDKでは、OpenTok 2のアーカイブを扱う機能がサポートされています。

について Client.create_session() このメソッドには現在、 media_mode パラメータの代わりに、 p2p パラメータが必要だ。