RubyサーバーSDK

Vonage Ruby SDKは、以下のメソッドを提供することで、Vonage Video APIとのやり取りを可能にします：

インストール

バンドラー（推奨）：

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

gemをプロジェクトの Gemfile:

gem "vonage"

bundler があなたのプロジェクトに gem をインストールすることを許可する。

$ bundle install

RubyGems：

または、RubyGems CLIを使用してコマンドラインから直接システムにGemをインストールすることもできます。 gem install 命令.

$ gem install vonage

使用方法

初期化

gemを使用するファイルの先頭にロードする。それから Vonage::Client オブジェクトの秘密鍵とアプリケーションIDを使用します。

require "vonage"

client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: File.read(ENV['VONAGE_PRIVATE_KEY_PATH'])
)

注意：上記の例では、Vonage アプリケーション ID と秘密鍵へのパスを環境変数として ENV キーを持つハッシュ VONAGE_APPLICATION_ID そして VONAGE_PRIVATE_KEY_PATH それぞれだ。

初期化オプション

Vonageクライアントは、異なるデータセンターを指す必要があるなど、特別なニーズが発生した場合、デフォルトの設定オプションを上書きすることができます。

require "vonage"

client = Vonage::Client.new(
  application_id: ENV['VONAGE_APPLICATION_ID'],
  private_key: File.read(ENV['VONAGE_PRIVATE_KEY_PATH']),
  video_host: 'country-specific-video.api.vonage.com'
)

この例では video_host: キーワード引数を指定すると、Video API のデフォルトのベース URL を上書きできます。これは、特定のデータセンターを選択したり、テスト目的で API のモックサーバーを指定したりする場合に便利である。

セッションの作成

へ Vonageビデオセッションを作成する をRuby SDKで使用するには Video#create_session メソッドを呼び出します。このメソッドは、いくつかのオプションのキーワード・パラメータを受け付ける：

  • :media_modeセッションが ビデオ・メディア・ルーターこれは Vonage Video の一部の機能（アーカイブなど）に必要です。有効なオプションは次のとおりです。 'routed' (メディア・ルーターを使用する場合は、これがデフォルト）または 'relayed' (ピアツーピアストリーミング用）
  • :archive_mode:セッションを自動的にアーカイブするかどうか。有効なオプションは 'always' (自動アーカイブ用）または 'manual' (手動で管理するアーカイブの場合、これがデフォルト)
  • :location:Vonage Videoサーバーのロケーションヒント。

以下は、異なる設定でセッションを作成する例です：

  • デフォルト設定を使用してセッションを作成する (media_mode デフォルトは 'routed'Vonage Media Routerを使用します。 archive_mode デフォルトは 'manual'これは はない。 自動的にアーカイブを作成する)：

    session = client.video.create_session

  • クライアント間でストリームを直接送信しようとするセッションを作成する。 archive_mode マスト・ビー 'manual'デフォルトは media_mode である。 'relayed'):

    session = client.video.create_session(media_mode: 'relayed')

  • ロケーションヒントを使ったセッションの作成

    session = client.video.create_session(location: '12.34.56.78')

  • 自動アーカイブ機能付きセッションの作成（必ず 'routed' メディアモード（デフォルト）：

    session = client.video.create_session(archive_mode: 'always')

を使用することができます。 session_id のアクセサー・メソッドを返します。 Vonage::Response インスタンスで、作成されたセッションのセッションIDを取得します。これは変数に代入したり、後で トークン生成:

session_id = session.session_id

トークンの生成

セッションが作成されると トークンの生成 セッションに接続するときにクライアントが使用する。

トークンを生成するには Video#generate_client_token メソッドを呼び出します。このメソッドは、1つの必須キーワード引数 :session_idこれは、トークンを作成したいセッションのIDです( セッションの作成 上記）。さらに、このメソッドはいくつかのオプションのキーワード・パラメータを受け付ける：

  • :scopeトークンのスコープ。これは 'session.connect'これはデフォルトである。
  • :roleクライアントの役割。有効なオプションは 'publisher' (これがデフォルト）、 'subscriber', 'moderator'そして 'publisher-only'.参照 役割
  • :data: クライアントを表すメタデータ（ユーザーIDや名前など）を含む文字列。参照 接続データ
  • :expire_time: トークンの有効期限（最大24時間。この期限を過ぎると、そのトークンを使用してセッションに接続することはできなくなる）。整数で指定する。 エポック秒. 指定がない場合のデフォルトは24時間です。
  • :initial_layout_class_list:

以下はトークン生成の例である：

  • デフォルト設定でトークンを生成する：

    token = client.video.generate_client_token(session_id: session_id)

  • 特定のオプションを指定してトークンを生成する

    token = client.video.generate_client_token(
  session_id: session_id,
  role: 'moderator',
  expire_time: Time.now.to_i+(24 * 60 * 60), # in 24 hours
  data: 'name=Johnny',
  initial_layout_class_list: ['focus', 'inactive']
)

ストリームを使う

Ruby SDK は、セッションに接続されている特定の Vonage Video ストリームに関する情報を取得したり、そのセッションのすべてのストリームに関する情報を取得したりするためのメソッドを提供します ( セッションの作成).

セッション内のすべてのストリームに関する情報を取得するには Streams#list メソッドを使用する：

streams = client.video.streams.list(session_id: session_id)

そして、返された Vonage::Streams::ListResponse インスタンスを使用して、ストリーム・リストに関する情報を取得する：

streams.count # => integer with the number of streams in the list
streams.items # => array of streams connected to the session

について items 配列は、セッションに接続された個々のストリームを Vonage::Entity オブジェクトのアクセッサ・メソッドを呼び出すことができます。例えば、ストリーム・リストの最初のストリームのIDを取得するには、以下のようにする：

stream_id = streams.items.first.id # => "af61926e-77dd-43ae-aa83-0b7e2835b3a0"

について Vonage::Streams::ListResponse クラスには以下が含まれる。 Enumerableを呼び出すことができます。 Enumerable メソッドを Vonage::Streams::ListResponse オブジェクトを取得する。たとえば、セッションに接続されているすべてのストリー ムのIDの配列を取得するには、次のようにする：

stream_ids_array = streams.map { |stream| stream.id }

セッション内の特定のストリームの情報を取得するには Streams#info メソッドを使用する：

stream = client.video.streams.info(session_id: session_id, stream_id: stream_id)

そして、返された Vonage::Response インスタンスを使用してストリームに関する情報を取得する：

stream.id # string with the stream ID
stream.video_type # string with the video type
stream.name # string with the name
stream.layout_class_list # array with the layout class list

アーカイブとの取り組み

Vonage Video APIを使用すると、次のことが可能になります。 セッションのアーカイブ、保存、検索.

アーカイブできるのは、Vonage Video Media Router を使用するセッションのみです。 メディアモード に設定する。 routed).

アーカイブ録画の開始

いつ セッションを作成するを設定することができます。 archive_mode への 'always' を設定すると、セッションのアーカイブ録音が自動的に作成されます。もし archive_mode への 'manual' を使うことで、セッションのアーカイブ録画を開始することができます。 Archives#start メソッドを使用する。

このメソッドはキーワード引数を必要とする、 :session_idまた、オプションのキーワード引数も取る。 :has_audio, :has_videoそして :name オプションを指定します。アーカイブを開始できるのは、既にクライアントが接続されているセッションのみです。

以下はアーカイブの作成例です：

  • アーカイブの作成

    archive = client.video.archives.start(session_id: session_id)

  • 名前付きアーカイブの作成

    archive = client.video.archives.start(session_id: session_id, name: 'Important Presentation')

  • 音声のみのアーカイブを作成する

    archive = client.video.archives.start(session_id: session_id, has_video: false)

を使用することができます。 id のアクセサー・メソッドを返します。 Vonage::Response インスタンスからアーカイブ ID を取得することができます。この ID を使用して、アーカイブの記録を停止したり、アーカイブの情報を取得したりすることができます。

archive_id = archive.id

セッティング output_mode オプションで 'individual' は、アーカイブ内の各ストリームを個別のファイルに記録する：

archive = client.video.archives.start(session_id: session_id, output_mode: 'individual')

セッティング output_mode オプションで 'composed' (デフォルト) は、アーカイブ内のすべてのストリームを単一の (構成された) ファイルに記録する。

構成済みアーカイブには resolution アーカイブの "640x480"（SDランドスケープ、デフォルト）、"1280x720"（HDランドスケープ）、"1920x1080"（FHDランドスケープ）、"480x640"（SDポートレート）、"720x1280"（HDポートレート）、または "1080x1920"（FHDポートレート）。

archive = client.video.archives.start(session_id: session_id, output_mode: 'composed', resolution: '1280x720')

構成されたアーカイブの初期レイアウトをカスタマイズするには layout オプションを指定する。2つのキーを含むハッシュに設定する： :type そして :stylesheet.

の有効な値 :type は "bestFit"（ベストフィット）、"custom"（カスタム）、"horizontalPresentation"（水平表示）、"pip"（ピクチャー・イン・ピクチャー）、"verticalPresentation"（垂直表示）。

カスタム」レイアウト・タイプを指定する場合は、次のように設定します。 :stylesheet キーをCSSスタイルの文字列に設定します。(他のレイアウト・タイプの場合は :stylesheet キー)

archive = client.video.archives.start(
  session_id: session_id
  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%;}'
  }
}

初期レイアウトのタイプを指定しない場合、アーカイブは 'bestFit' レイアウトの種類。詳しくは 構成されたアーカイブのビデオレイアウトをカスタマイズする.

を渡すことで、自動的にアーカイブされたセッションを作成することもできます。 'always' を値として :archive_mode キーワード引数 Video#create_session メソッド セッションの作成 上記）。

アーカイブ録画の停止

を使用して、開始したアーカイブの録画を停止することができます。 Archives#stop メソッドに :archive_id 停止するアーカイブの

client.video.archives.stop(archive_id: archive_id)

アーカイブに関する情報の入手

を使用して、特定のアーカイブ録画に関する情報を取得できます。 Archives#info メソッドに :archive_id アーカイブの

archive_info = client.video.archives.info(archive_id: archive_id)

また、作成したすべてのアーカイブ（最大1000）のリストを取得することもできます。これは Archives#list メソッドを使用します。このメソッドはオプションで :offset そして :count キーワード引数を指定することで、結果をページ分割することができます。これは Video::Archives::ListResponse クラスである。

archive_list = client.video.archives.list

アーカイブの削除

アーカイブを削除するには Archives#delete メソッドに archive_id 削除するアーカイブの

client.video.archives.delete(archive_id: archive_id)

アーカイブのレイアウトを設定する

アーカイブのレイアウトは Archives#change_layout メソッドを使用する：

client.video.archives.change_layout(
  archive_id: archive_id,
  type: 'verticalPresentation'
)

このメソッドは archive_id キーワード引数と3つのオプション引数 (type, stylesheetそして screenshare_type):

  • について type はアーカイブのレイアウトタイプです。有効な値は "bestFit"(ベストフィット) "custom"(カスタム) "horizontalPresentation"(水平表示) "pip"(ピクチャーインピクチャー) "verticalPresentation"(垂直表示)です。

  • カスタム」レイアウト・タイプを指定する場合は、次のように設定します。 stylesheet プロパティを設定します。(他のレイアウト・タイプの場合は、stylesheetプロパティを設定しないでください）。

  • について screenshare_type は、セッション内に画面共有ストリームがある場合に使用するレイアウト・タイプを示します。このプロパティを使用するには type プロパティを "bestFit "に設定する。 stylesheet プロパティは設定されていません。詳しくは 画面共有のためのレイアウトタイプ.

を設定することで、クライアントのストリームの初期レイアウト・クラスを設定できます。 layout オプションは、クライアントのトークン作成時に Video#generate_client_token メソッドを使用する。

構成済みアーカイブのレイアウトの設定は任意です。デフ ォル ト では、 構成 さ れたアーカ イ ブは 「最適な」 レ イ ア ウ ト を使用 し ます。参照 構成されたアーカイブのビデオレイアウトをカスタマイズする をご覧ください。

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

Vonage Video APIを使用すると、次のことが可能になります。 ブロードキャスト・セッション.

Vonage Video Media Routerを使用するセッションのみをブロードキャストすることができます。 メディアモード に設定する。 routed).

放送の開始

セッションのブロードキャストを開始するには Broadcasts#start メソッドを使用する。このメソッドはキーワード引数を必要とする、 :session_idまた、ブロードキャストの設定を指定するオプションのキーワード引数も取る：

  • layout放送のレイアウトをカスタマイズするために使用する。3つのキーを含むハッシュに設定する：
    • :type (必須）。有効な値は "bestFit" (ベストフィット）、 "custom" (カスタム）、 "horizontalPresentation" (水平プレゼンテーション）、 "pip" (ピクチャー・イン・ピクチャー）、そして "verticalPresentation" (縦型プレゼンテーション）。
    • :stylesheet: （以下の場合は必須 :type に設定されている。 'custom').カスタム」レイアウト・タイプを指定する場合は :stylesheet キーをCSSスタイルの文字列に設定します。(他のレイアウト・タイプの場合は :stylesheet キー)
    • :screenshareType: screenshareTypeプロパティを、セッション内に画面共有ストリームがある場合に使用するレイアウト・タイプに設定するために使用します。有効な値は "bestFit" (ベストフィット）、 "custom" (カスタム）、 "horizontalPresentation" (水平プレゼンテーション）、 "pip" (ピクチャー・イン・ピクチャー）、そして "verticalPresentation" (縦型プレゼンテーション）。
  • max_duration:ブロードキャストの最大時間（秒）。デフォルトは4時間。
  • outputs:開始したいブロードキャストストリームのタイプを定義するハッシュ（HLSとRTMPの両方）。ハッシュには2つのキーがあります、 :hls または rtmp:
    • :hlsこれは2つのキー（どちらもブール値）を持つハッシュである、 :dvr (DVR機能を有効にするかどうか）、および :lowLatency (HLSストリームの低遅延モードを有効にするかどうか）
    • :rtmp各ハッシュはRTMPブロードキャストストリームに関する情報を含む。各ハッシュには :id が必要です。 :serverUrl RTMPサーバーに必要な :streamName.
  • :resolution: ブロードキャストの解像度を指定する文字列。有効なオプションは 640x480, 1280x720, 1920x1080, 480x640, 720x1280, 1080x1920
  • :stream_modeどちらでも auto (デフォルト）、または manual
  • :multi_broadcast_tag同じセッションで複数のブロードキャストをサポートする場合は、同時ブロードキャストごとに一意の文字列を設定します。
  • :max_bitrate:ストリームの最大ビットレート

以下は放送の作成例である：

  • HLSブロードキャストの作成

    broadcast = client.video.archives.start(
  session_id: session_id,
  outputs: {
    hls: {
      dvr: true,
      lowLatency: true
    }
  }
)

  • RTMPブロードキャストの作成

    broadcast = client.video.archives.start(
  session_id: session_id,
  outputs: {
    rtmp: [
      {
        id: 'foo',
        serverURL: "rtmps://myfooserver/myfooapp",
        streamName: "myfoostream"
      }
    ]
  }
)

を使用することができます。 id のアクセサー・メソッドを返します。 Vonage::Response インスタンスを使用して、作成されたブロードキャストのブロードキャストIDを取得します。このIDを使用して、ブロードキャストを停止したり、ブロードキャストに関する情報を取得したりすることができます。

broadcast_id = broadcast.id

ブロードキャストの停止

ブロードキャストを停止するには Broadcasts#stop メソッドに :broadcast_id 放送を停止する。

client.video.broadcasts.stop(broadcast_id: broadcast_id)

放送に関する情報を得る

特定のブロードキャストに関する情報を取得するには Broadcast#info メソッドに :broadcast_id 放送の

broadcast_info = client.video.broadcasts.info(broadcast_id: broadcast_id)

また、作成したすべてのブロードキャストのリストを取得することもできます。これは Broadcasts#list メソッドを使用します。このメソッドはオプションで :offset そして :count キーワード引数を指定することで、結果をページ分割することができます。これは Video::Broadcasts::ListResponse クラスである。

broadcast_list = client.video.broadcasts.list

シグナリング

アクティブなVonage Videoセッションの特定の参加者、またはすべての参加者に信号を送信できます。

特定の参加者に送信するには Signals#send_to_one メソッドを使用する。

client.video.signals.send_to_one(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  connection_id: '909b9024-901d-11ed-a1eb-0242ac120002',
  type: 'chat',
  data: 'Hello'
)

すべての参加者に送信するには Signals#send_to_all メソッドを使用する。

client.video.signals.send_to_all(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  type: 'chat',
  data: 'Hello'
)

どちらの方法にも必要なのは session_id, typeそして data キーワード引数。キーワード引数の send_to_one メソッドはさらに connection_id キーワード引数は、シグナルを送信すべき特定の参加者を特定する。

の最大長。 type 文字列は128バイトであり、文字（A-Z、a-z）、 Numbers（0-9）、'-'、'_'、'~'のみを含まなければならない。

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

シグナリングの詳細については Vonageビデオ信号 プログラミングガイド

モデレーション

あなたは モデレート・セッション いろいろな意味で。

クライアントを強制的にセッションから切断させるには Moderation#force_disconnect メソッドに session_id アクティブなVonageビデオセッションの connection_id 切断されるクライアントの

client.video.moderation.force_disconnect(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  connection_id: '909b9024-901d-11ed-a1eb-0242ac120002'
)

アクティブなVonage Videoセッション内の特定のストリームをミュートしたり、そのセッション内の複数のストリームをミュートしたりできます。

特定のストリームをミュートするには Moderation#mute_single_stream メソッドに session_id アクティブなVonageビデオセッションの stream_id ミュートするストリームの

client.video.moderation.mute_single_stream(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  stream_id: '684d899a-901f-11ed-a1eb-0242ac120002'
)

セッション内の複数のストリームをミュートするには Moderation#mute_multiple_streams メソッドを使用する。

client.video.moderation.mute_multiple_streams(
  session_id: '80e87ab2-8dd3-11ed-a1eb-0242ac120002',
  active: true,
  excluded_stream_ids: [
    '2c2a905c-9029-11ed-a1eb-0242ac120002',
    '2c2a92f0-9029-11ed-a1eb-0242ac120002',
    '2c2a97c8-9029-11ed-a1eb-0242ac120002'
  ]
)

と同様である。 session_idその mute_multiple_streams メソッドは、さらに2つのキーワード引数を定義している：

  • について active 引数は必須で、次のいずれかに設定する。 true または false.への設定 true セッションのミュート状態を有効にすると、そのセッションにパブリッシュされている現在および将来のすべてのストリーム（ただし excluded_stream_ids 配列）がミュートされる。このメソッドを active プロパティを falseこの場合、セッションに将来公開されるストリームはミュートされない(ただし、 ミュートされている既存のストリームはミュートされたままである)。

  • について excluded_stream_ids キーワード引数はオプションで、ミュートから除外するストリームIDの配列を取る。

SIPでの作業

を開始することができる。 SIPコール を使用している。 SIP#dial メソッドを呼び出します。このメソッドには3つの必須キーワード引数がある：

  • :session_idダイヤルするセッションのID。
  • :tokenセッションのクライアントトークン ( クライアント・トークンの生成)
  • :sip_uriVonage Video からお客様の SIP プラットフォームに開始される SIP コールの宛先として使用される SIP URI。

以下は SIP#dial メソッドを使用する：

client.video.sip.dial(
  session_id: session_id,
  token: token,
  sip_uri: "sip:+15128675309@acme.pstn.example.com;transport=tls"
)

SIPインターコネクトの詳細については、以下を参照してください。 VonageビデオSIP相互接続 開発者ガイド

必要条件

Video対応Vonageアプリケーションには、アプリケーションIDと秘密鍵が必要です。Vonageアプリケーションは Vonageダッシュボード.

Vonage Video Ruby SDKはRuby 2.7.0以上をサポートしています。

リリースノート

ビデオ機能は Vonage Ruby SDK バージョンから 7.19.0.

参照 リリース ページに詳細を掲載している。