Vonage Video API Ruby SDK

OpenTok Ruby SDK には、以下の機能を実現するためのメソッドが用意されています：

生成セッションそしてトークン～のためにオープントーク Applications
OpenTokとの連携アーカイブ
OpenTokとの連携ライブ・ストリーミング放送
OpenTokとの連携 SIP相互接続
セッションに接続しているクライアントにシグナルを送る
セッションからのクライアントの切断
セッション内のクライアントに、公開されたオーディオを強制的に切断またはミュートさせる
OpenTokとの連携経験豊富な作曲家たち
OpenTokとの連携オーディオ・コネクター

インストール

バンドラー（推奨）：

BundlerはRubyプロジェクトの依存関係を管理するのに役立ちます。詳細はこちら： http://bundler.io

この逸品をあなたの Gemfile:

gem "opentok", "~> 4.0.0"

Bundlerに変更内容をインストールさせます。

$ bundle install

RubyGems：

$ gem install opentok

使用方法

初期化

そのgemを使用するファイルの先頭に読み込んでください。その後、 OpenTok::OpenTok OpenTokのAPIキーとAPIシークレットを指定してください。

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret

初期化オプション

カスタムタイムアウト

新しいものを初期化する際に、HTTPリクエストのタイムアウト値を独自に指定することができます。 OpenTok::OpenTok オブジェクト：

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret, :timeout_length => 10

の値は :timeout_length HTTP リクエストが完了するまで待機する秒数を表す整数です。デフォルトは2秒に設定されています。

UA 補遺

また、 User-Agent 新しいものを初期化する際の、HTTPリクエストのヘッダー値 OpenTok::OpenTok オブジェクト：

require "opentok"

opentok = OpenTok::OpenTok.new api_key, api_secret, :ua_addendum => 'FOO'

上記を実行すると、次のような出力が得られます。 User-Agent ヘッダーは次のようなものです：

User-Agent: OpenTok-Ruby-SDK/4.6.0-Ruby-Version-3.1.2-p20 FOO

セッションの作成

OpenTokセッションを作成するには、次の OpenTok#create_session(properties) メソッドを使用する。その properties parameter は、以下を指定するために使用されるオプションのハッシュです：

そのセッションで OpenTok Media ルーター, これは、OpenTokの一部の機能（アーカイブなど）を利用するために必要です
OpenTokサーバーの設置場所に関するヒント。
セッションを自動的にアーカイブするかどうか。

について session_id 返されるメソッド OpenTok::Session このインスタンスは、永続ストア（データベースなど）に保存できるセッションIDを取得するのに役立ちます。

# Create a session that will attempt to transmit streams directly between clients.
# If clients cannot connect, the session uses the OpenTok TURN server:
session = opentok.create_session

# A session that will use the OpenTok Media Server:
session = opentok.create_session :media_mode => :routed

# A session with a location hint:
session = opentok.create_session :location => '12.34.56.78'

# A session with automatic archiving (must use the routed media mode):
session = opentok.create_session :archive_mode => :always, :media_mode => :routed

# A session with end-to-end encryption (must use the routed media mode):
session = opentok.create_session :e2ee => true, :media_mode => :routed

# Store this sessionId in the database for later use:
session_id = session.session_id

トークンの生成

セッションが作成されると、クライアントがセッションに接続する際に使用するトークンの生成を開始できます。トークンを生成するには opentok.generate_token(session_id, options) メソッド、または Session#generate_token(options) インスタンスを作成した後、そのインスタンスに対してメソッドを呼び出します。その options parameter は、トークンのロール、有効期限、および接続データを設定するために使用されるオプションのハッシュです。アーカイブやブロードキャストにおけるレイアウト制御のため、このトークンを使用して接続から公開されるストリームの初期レイアウトクラス一覧も設定できます。

## 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 createSession)
token = session.generate_token

# Set some options in a token
token = session.generate_token({
    :role        => :moderator,
    :expire_time => Time.now.to_i+(7 * 24 * 60 * 60), # in one week
    :data        => 'name=Johnny',
    :initial_layout_class_list => ['focus', 'inactive']
});

ストリームを使う

このメソッドを使用すると、OpenTok ストリームまたはセッション内のすべてのストリームに関する情報を取得できます。たとえば、このメソッドを呼び出すことで、 OpenTok ストリームで使用されているレイアウトクラスに関する情報を取得できます。

セッション内の特定のストリームに関する情報を取得するには、次の関数を呼び出します。 opentok.streams.find(session_id, stream_id). 返されるオブジェクトは Stream オブジェクト、そして次の例（RSpecの表記法を使用）に示すように、さまざまなストリームのプロパティにアクセスできます：

expect(stream).to be_an_instance_of OpenTok::Stream
expect(stream.videoType).to eq 'camera'
expect(stream.layoutClassList.count).to eq 1
expect(stream.layoutClassList.first).to eq "full"

セッション内のすべてのストリームに関する情報を取得するには、次のコマンドを実行します。 opentok.streams.all(session_id). 戻り値は StreamList オブジェクトがある：

expect(all_streams).to be_an_instance_of OpenTok::StreamList
expect(all_streams.total).to eq 2
expect(all_streams[0].layoutClassList[1]).to eq "focus"

アーカイブとの取り組み

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

OpenTokセッションの録画は、以下の方法を使用して開始できます。 opentok.archives.create(session_id, options) メソッド。これにより、 OpenTok::Archive インスタンス。パラメータ options は、～を設定するために使用されるオプションのハッシュです。 has_audio, has_videoそして name オプション。なお、アーカイブを開始できるのは、クライアントが接続しているセッションのみであることに注意してください。

# Create an Archive
archive = opentok.archives.create session_id

# Create a named Archive
archive = opentok.archives.create session_id :name => "Important Presentation"

# Create an audio-only Archive
archive = opentok.archives.create session_id :has_video => false

# Store this archive_id in the database for later use
archive_id = archive.id

セッティング :output_mode オプションで :individual この設定により、アーカイブ内の各ストリームがそれぞれ個別のファイルに記録されるようになります：

archive = opentok.archives.create session_id :output_mode => :individual

について :output_mode => :composed この設定（デフォルト）では、アーカイブ内のすべてのストリームが 1つの（結合された）ファイルに記録されます。

作成するアーカイブについては、アーカイブの解像度を「640x480」（SD 横向き、デフォルト）、「1280x720」（HD 横向き）、「1920x1080」（FHD 横向き）、「480x640」（SD 縦向き）、「720x1280」（HD 縦向き）、または「1080x1920」（FHD 縦向き）から選択できます。この resolution このパラメータは省略可能であり、のオプションハッシュ（第2引数）に含めることができます。 opentok.archives.create() メソッドを使用する。

opts = {
    :output_mode => :composed,
    :resolution => "1280x720"
}

archive = opentok.archives.create session_id, opts

構成されたアーカイブの初期レイアウトをカスタマイズするには :layout オプション。これを、2つのキーを含むハッシュに設定してください： :type そして :stylesheet. の有効な値は :type 「bestFit」（最適フィット）、「custom」（カスタム）、「horizontalPresentation」（横向き表示）、「pip」（ピクチャー・イン・ピクチャー）、および「verticalPresentation」（縦向き表示）です。「custom」レイアウトタイプを指定する場合は、 :stylesheet スタイルシート（CSS）のキー。（その他のレイアウトタイプの場合は、 :stylesheet キー)

opts = {
    :output_mode => :composed,
    :resolution => "1280x720",
    :layout => {
      :type => "custom",
      :stylesheet => "stream:last-child{display: block;margin: 0;top: 0;left: 0;width: 1px;height: 1px;}stream:first-child{display: block;margin: 0;top: 0;left: 0;width: 100%;height: 100%;}"
    }
}

archive = opentok.archives.create session_id, opts

初期レイアウトタイプを指定しない場合、アーカイブは最適なレイアウトタイプを使用します。詳細については、以下を参照してください。構成されたビデオのレイアウトをカスタマイズするアーカイブ.

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

# Stop an Archive from an archive_id (fetched from database)
opentok.archives.stop_by_id archive_id

# Stop an Archive from an instance (returned from opentok.archives.create)
archive.stop

を得るには OpenTok::Archive インスタンス（とそれに関するすべての情報）を archive_id, 以下のを使用してください opentok.archives.find(archive_id) メソッドを使用する。

archive = opentok.archives.find archive_id

アーカイブを削除するには opentok.archives.delete_by_id(archive_id) メソッド、あるいは delete 〜の方法 OpenTok::Archive インスタンスだ。

# Delete an Archive from an archive_id (fetched from database)
opentok.archives.delete_by_id archive_id

# Delete an Archive from an Archive instance (returned from archives.create, archives.find)
archive.delete

また、APIキーで作成したすべてのアーカイブ（最大1000件）のリストを取得することもできます。これはを使用します。 opentok.archives.all(options) メソッドを使用します。パラメータ options これはオプションのハッシュであり、以下を指定するために使用されます。 :offset そして :count 検索結果のページ分割を行うのに役立ちます。これにより、のインスタンスが返されます。 OpenTok::ArchiveList クラスである。

archive_list = opentok.archives.all

# Get an specific Archive from the list
archive_list[i]

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

を渡すことで、自動的にアーカイブされたセッションを作成することもできます。 :always として :archive_mode プロパティの options に渡しされたパラメータ OpenTok#create_session() メソッド（上記の「セッションの作成」を参照）。

を設定することができます。レイアウトアーカイブの：

opts = { :type => "verticalPresentation" }
opentok.archives.layout(archive_id, opts)

ハッシュ opts 2つのエントリがあります：

について type アーカイブのレイアウトタイプです。有効な値は「bestFit」（ベストフィット）「custom」（カスタム）、「horizontalPresentation」（横向き表示）、「pip」（ピクチャー・イン・ピクチャー）、および「verticalPresentation」（縦向き表示）です。
カスタム」レイアウト・タイプを指定する場合は、次のように設定します。 stylesheet プロパティ。（その他のレイアウトタイプについては、スタイルシートプロパティを設定しないでください。）

参照構成されたアーカイブのビデオレイアウトをカスタマイズする詳細についてはこちらをご覧ください。

クライアントのストリームの初期レイアウトクラスは、クライアントのトークンを作成する際にレイアウトオプションを設定することで指定できます。その際は、 opentok.generate_token メソッド。また、次のようにしてストリームのレイアウトクラスを変更することもできます：

streams_list = {
    :items => [
        {
            :id => "8b732909-0a06-46a2-8ea8-074e64d43422",
            :layoutClassList => ["full"]
        },
        {
            :id => "8b732909-0a06-46a2-8ea8-074e64d43423",
            :layoutClassList => ["full", "focus"]
        }
    ]
}
response = opentok.streams.layout(session_id, streams_list)

ストリームレイアウトクラスの設定に関する詳細については、 OpenTok ストリームの構成済みアーカイブレイアウトクラスを変更する.

以下の点にご留意ください。 streams.layout このメソッドは、アーカイブおよび放送ストリームにのみ適用されます。

アーカイブに関する詳細については、以下の OpenTokのアーカイブ機能開発者ガイド

シグナリング

以下の方法を使って信号を送信できます。 opentok.signals.send(session_id, connection_id, opts) メソッド。もし connection_id がnilまたは空文字列の場合、そのシグナルはセッション内のすべての有効な接続に送信されます。

例として opts このフィールドは、次のように指定できます：

opts = { :type => "chat",
         :data => "Hello"
}

の最大長。 type 文字列は128バイトで、文字（A～Zおよびa～z）、Numbers（0～9）、'-'、'_'、'~'のみを含める必要があります。

について data 文字列は最大サイズ（8kB）を超えてはならない。

について connection_id そして opts パラメータは、デフォルトではいずれも省略可能です。したがって、以下のように使用することもできます opentok.signals.send(session_id)

シグナリングに関する詳細については、以下の OpenTokのシグナリングプログラミングガイド

放送

ストリームをHLSまたはRTMPサーバーに配信することができます。

セッションの配信を正常に開始するには、少なくとも1つのパブリッシングクライアントがそのセッションに接続されている必要があります。

ライブストリーミング配信では、1つのHLSエンドポイントと、最大5つのRTMPサーバーを、 1つのセッションで同時に配信先として指定できます。

ライブストリーミングを開始できるのは、OpenTok Media Router を使用しているセッション（メディアモードが「routed」に設定されているもの）のみです。メディアモードが「relayed」に設定されているセッションでは、ライブストリーミングを利用することはできません。

HLSのみの配信を作成するには：

opts = {
  :outputs => {
      :hls => {}
  }
}
broadcast = opentok.broadcasts.create(session_id, opts)

# HLS + RTMP
opts = {
   :outputs => {
       :hls => {},
       :rtmp => [
           {
               :id => "myOpentokStream",
               :serverUrl => "rtmp://x.rtmp.youtube.com/live123",
               :streamName => "66c9-jwuh-pquf-9x00"
           }
       ]
   }
}
broadcast = opentok.broadcasts.create(session_id, opts)

返されるBroadcastオブジェクトには、id、sessionId、projectId、 createdAt、updatedAt、resolution、status、およびbroadcastUrlsのハッシュといった、ブロードキャストに関する情報が含まれています。broadcastUrlsは、 HLS URLとRTMPオブジェクトの配列で構成されています。RTMPオブジェクトは、 rtmp 値 in opts 上記の例では。

放送に関する詳細については、以下の OpenTok 放送ガイドプログラミングガイド

放送ストリームに関する情報を取得するには

my_broadcast = opentok.broadcasts.find broadcast_id

返されるBroadcastオブジェクトには、id、sessionId、 projectId、createdAt、updatedAt、resolution、status、およびbroadcastUrlsのハッシュなど、ブロードキャストを記述するプロパティが含まれています。broadcastUrlsは、 HLS URLとRTMPオブジェクトの配列で構成されています。RTMPオブジェクトは、 rtmp 値 in opts 上記の例では。

ブロードキャストを停止するには：

 my_broadcast = opentok.broadcasts.stop broadcast_id

 # stop at a broadcast object level too
 #
 my_broadcast = opentok.broadcasts.find broadcast_id
 ret_broadcast =  my_broadcast.stop

 # Both the above returned objects has the "broadcastUrls" property as a nil value and the status
 # property value is "stopped"

放送のレイアウトを動的に変更するには

opentok.broadcasts.layout(started_broadcast_id, {
        :type => "verticalPresentation"
    })

  # On an object level
   my_broadcast = opentok.broadcasts.find broadcast_id
   my_broadcast.layout(
             :type => 'pip',
             )

   # the returned value is true if successful

上記のハッシュには2つのエントリがあります。

について type アーカイブのレイアウトタイプです。有効な値は、「bestFit」（最適フィット）、「custom」（カスタム）、「horizontalPresentation」（横向き表示）、「pip」（ピクチャー・イン・ピクチャー）、および「verticalPresentation」（縦向き表示）です。
カスタム」レイアウト・タイプを指定する場合は、次のように設定します。 stylesheet プロパティ。（その他のレイアウトタイプについては、スタイルシートプロパティを設定しないでください。）

参照構成されたビデオのレイアウトをカスタマイズするアーカイブ詳細についてはこちらをご覧ください。

個々のストリームのレイアウトを動的に変更することも可能です。詳しくは、以下を参照してください。 Streams の操作.

強制切断

以下の方法を使用することで、クライアントをセッションから強制的に切断させることができます。 opentok.connections.forceDisconnect(session_id, connection_id) メソッドを使用する。

セッション内のクライアントに公開音声のミュートを強制する

を使って、特定のストリームのパブリッシャーにオーディオのパブリッシングを停止させることができます。 opentok.streams.force_mute(session_id, stream_id) メソッドを使用する。

セッション内のすべてのストリームのパブリッシャーを強制的に停止することができます（オプションのストリームリストを除く）。を使って音声の公開を停止させることができます。 opentok.streams.force_mute_all(session_id, opts) メソッド。その後、 opentok.streams.disable_force_mute(session_id) メソッドを使用する。

詳細については、以下を参照してください。セッション内のストリームの音声をミュートする.

SIPコールの開始

以下の方法を使用して、SIP通話を開始できます。 opentok.sip.dial(session_id, token, sip_uri, opts) メソッド。これにはSIP URLが必要です。多くの場合、SIPプロバイダへの認証や、暗号化されたセッションの確立を指定するためのオプションを渡す必要があります。

opts = { "auth" => { "username" => sip_username,
                     "password" => sip_password },
         "secure" => "true"
}
response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.example.com;transport=tls", opts)

SIP相互接続に関する詳細については、以下の OpenTok SIP相互接続開発者ガイド

経験豊富な作曲家との協業

[...]を開始できます。エクスペリエンス・コンポーザーを呼び出すことで opentok.renders.start(session_id, options) メソッドを使用する。

Experience Composer は、 opentok.renders.stop(render_id, options) メソッドを使用する。

「エクスペリエンス・コンポーザー」に関する情報は、以下の電話番号にお問い合わせいただければご提供いたします。 opentok.renders.find(render_id) そして opentok.renders.list(options) のメソッドがある。

Audio Connector の使用方法

[...]を開始できます。オーディオ・コネクター WebSocket を呼び出すことで opentok.websocket.connect() メソッドを使用する。

必要条件

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

OpenTok Ruby SDK には、Ruby 2.1.0 以降が必要です。

リリースノート

参照リリース各リリースの詳細については、こちらのページをご覧ください。

v2.2.0以降の主な変更点

v4.0.0での変更点：

このSDKではRuby v2.7への対応が追加され、Ruby v2.1.0以降が必要となりました。 Ruby v2.0.0をご利用の場合は、引き続きOpenTok Ruby SDK v3.0.0をご利用ください。 Ruby v1.9.3をご利用の場合は、引き続きOpenTok Ruby SDK v2.5.0をご利用ください。

v3.0.0での変更点：

このSDKでは、Ruby v2.0.0以降が必要となりました。Ruby v1.9.3をご利用の場合は、引き続き OpenTok Ruby SDK v2.5.0をご利用ください。

v2.2.2での変更点：

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

v2.2.0での変更点：

このバージョンのSDKでは、OpenTokアーカイブの操作がサポートされています。

また、以下の点にも注意してください。 options パラメーターの OpenTok.create_session() このメソッドには media_mode a の代わりに property p2p 財産である。