RICOH Live Streaming 共通仕様

用語定義

Client

本 API にリクエストするブラウザや Android 等のネイティブアプリなどのクライアントを表す。

Server

本 API のサーバ。

ClientApp

本サービスを利用するアプリケーションやクライアントの単位。ClientApp ごとに認可範囲は独立する。

ClientID

ClientApp を一意に特定するための識別子。認証などに利用される。

Room

いわゆるルーム型会議のためのルーム。Room には以下の 2 種類がある。

• P2P Room
  • 各 Connection が別の Connection に Track を送信する

• SFU Room
  • SFU Server を介して Track を送信する

RoomID

Room を一意に特定するための識別子。

ClientApp 単位で管理される。

ClientApp(ClientID)が一致、かつ RoomID が一致する場合に同じルームに接続される。

RoomInstance

本サービス内で管理される Room の生死単位。RoomInstance はある RoomID に対して、 Connection の入室数が 0→1 になったタイミングで生成され、 1→0 になったタイミングで消滅する。

Connection

Room に参加する Client の単位。アプリケーション上では同一アカウントとして認証される端末でもブラウザのタブが違えば別の Connection となる。

ConnectionInstance

本サービス内で管理される Connection の生死単位。ConnectionInstance はある Server で認証成功した時点で生成され、Server から切断した時点で消滅する。

Track

WebRTC のMediaStreamTrack と、それに紐づく Metadata を持つオブジェクト。いわゆる映像トラックや音声トラック。Track には以下の 2 種類がある。

• LocalTrack
  • ある Connection から見て自らが生成した Track。主に自映像。
• RemoteTrack
  • 自らが生成していない Track。主に相手の映像。

Metadata

Track や Connection に付与されるメタ情報を表す。例として、拠点名、アプリケーション内の User ID、ブラウザ名、360 映像の射影形式、などが考えられる。

用語間の関係

ある単位時間では Room に紐づく RoomInstance および Connection に紐づく ConnectionInstance は 0 か 1。連続した時間で見ると関連度が*になる。

Room や Connection は本サービスでは関与しない ClientApp 側のライフサイクルで生死が決まるエンティティを想定している。例としてこれらのライフサイクルをシーケンスで示すと以下のようになる。

データ定義

データ型

IDString

RICOH Live Streaming で使用する ID の型。

以下の形式である必要があります。

• 1 文字以上 255 文字以下
• ASCII
• 以下の文字のみ許可
  • 英数字
  • 次の記号: .%+^_"`{|}~<>\-
• 正規表現の例
  • JavaScript: /^[a-zA-Z0-9.%+^_"`{|}~<>\-]{1,255}$/
  • Ruby: /\A[a-zA-Z0-9.%+^_"`{|}~<>\-]{1,255}\z/

属性

• Room#room_id
  • IDString
  • ClientApp 内ユニーク
• Room#classification_label
  • IDString
  • ClientApp 内ユニーク
• Connection#connection_id
  • IDString
  • Room 内ユニーク
• Metadata: {[key: IDString]: any}
  • キーバリューの組数は 0 以上 32 以下
  • キー: IDString
  • バリュー:
    • データ構造や型は JSON にシリアライズできる全てが許容される
    • UTF-8 でエンコードできる全ての文字が許容される
    • JSON にエンコードされて 0 文字以上 1024 文字以下

RoomInstance 制約

• 最大継続時間: 24 時間
• 最大接続数
  • RoomSpecの type が sfu_large 以外のとき: 50
  • RoomSpecの type が sfu_large のとき: 300

ConnectionInstance 制約

• 最大継続時間: RoomInstance が継続しているまで

Web API 後方互換性

提供する Web API において以下の変更は互換性が維持されるものとする。互換性が維持される変更は予告なく実施される場合がある。

• リクエスト
  • サーバが受け付けるパスの追加
  • サーバが受け付ける HTTP メソッドの追加
  • クライアントが任意で追加できる HTTP ヘッダの追加
  • クライアントが任意で追加できる JSON オブジェクト属性の追加
  • サーバが受け付ける範囲を拡大する数値や文字列や配列長のバリデーション変更
• レスポンス
  • JSON オブジェクト属性の追加
  • 仕様として明記されていない HTTP ヘッダの追加変更削除
  • 返却する範囲を縮小する数値や文字列や配列の形式の変更
  • リクエスト要素が追加された際にその追加要素をリクエストに直接的および間接的に含む場合のみ発生する変更
    • 追加要素をリクエストに間接的に含む例: リソース/a の属性 b を新規列挙要素"c"で PUT で更新した後に、リソース/a を GET で取得するとレスポンスの属性 b が"c"になっている