RICOH Live Streaming Client SDK API 外部仕様

RICOH Live Streaming API のクライアント SDK の外部仕様を説明する。

基本

  • RICOH Live Streaming API のクライアントとなるクラス Client を提供する。
  • Client App は Client をインスタンス化し、メソッドを呼んで使う。
  • Cilent は接続状態に応じた状態を持つ。
  • Client は EventTarget クラスのサブクラスであり、イベントハンドラを登録できる。
    • 接続状態の変化や、トラックの追加/削除がイベントとして通知される。
  • MediaStreamTrackへのアクセスインタフェースとなるクラス LSTrack を提供する。
  • LSTrack はアプリが生成したMediaStreamTrackをClient に渡す際に使用する。

状態

Client は以下の状態を持つ。状態は getState() メソッドで取得できる。

名前 状況
Idle インスタンス化もしくは切断が完了し接続準備ができている。connect() メソッドを呼ぶことで Connecting に遷移する。
Connecting Server との接続確立中 (WebSocket 接続中、 SDP 交換中、経路情報交換中) 。
Open 経路情報の交換が完了し、Server との接続 (SFU では PeerConnection 、 P2P は WebSocket) を確立できた。
Closing 切断要求を受け付けたか、エラーが発生して、切断処理をしている。
Closed 切断処理が完了した。

状態遷移

状態遷移

メソッド

メソッド名 概要
connect 指定された Room に接続・参加する
disconnect 参加中の Room から退出する
getState Client の状態を取得する
getStats PeerConnection の stats を取得する
updateMeta Connection Metadata を更新する
(Roomの種類がSFUの時のみ利用可能)
updateTrackMeta Track Metadata を更新する
(Roomの種類がSFUの時のみ利用可能)
replaceMediaStreamTrack MediaStreamTrackを置き換える
changeMute track の MuteType を変更する
getHeadReport 開始数分のログを取得する
getTailReport 直近数分のログを取得する
getStatsReport 直近数分の stats を取得する

connect

指定された Room に接続・参加する。

引数 (*必須) 概要 未指定時
client_id * IDString Client ID -
access_token * JwtAccessToken アクセストークン -
option * object オプション -
option.localLSTracks * LSTrack[] 初期 Local LSTrack の配列 -
option.meta Meta Connection Metadata オブジェクト
(Roomの種類がSFUの時のみ有効)
{}
option.signalingURL string シグナリングURL
(通常は既定URLが設定されるため指定不要)
既定URL
option.sending SendingOption Sending Option
(Roomの種類がSFUの時のみ有効)
SendingOption未指定時動作に準拠
option.receiving ReceivingOption Receiving Option
(Roomの種類がSFUの時のみ有効)
ReceivingOption未指定時動作に準拠
option.iceTransportPolicy "all" | "relay" P2Pの際のiceTransportPolicy all

SendingOption

Roomの種類がSFUの時のみ有効

引数 (*必須) 概要 未指定時
video SendingVideoOption Video送信オプション SendingVideoOption未指定時動作に準拠

ReceivingOption

Roomの種類がSFUの時のみ有効

引数 (*必須) 概要 未指定時
enabled boolean 受信するかどうか true

SendingVideoOption

引数 (*必須) 概要 未指定時
codec "h264" |
"vp8" |
"vp9" |
"h265" |
"av1"
codec 種別 (*1) "h264"
priority "normal" |
"high"
送信優先度 (*2) "normal"
maxBitrateKbps number ビットレート上限 (*2)
(100 以上 20000 以下)
priority:normalのとき500
priority:highのとき2000

(*1): 実際に利用可能なcodecはプラットフォームとブラウザによって異なります。未対応のcodecを指定した場合には接続時にエラーが発生し接続に失敗します。
(*2): 設定の詳細はSFU利用時のAPIへの設定方法及びRICOH Live Streaming Service 利用料金を参照ください。

disconnect

参加中の Room から退出し、Server 及びすべてのピアから切断する。

getState

Client の状態を返す。

getStats

PeerConnection毎の getStats() の結果を返す。
mediaStreamTrackオプション指定で当該MediaStreamTrackのみのgetStats()に限定できる

引数 (*必須) 概要 未指定時
mediaStreamTrack MediaStreamTrack getStats() 対象の
MediaStreamTrack
全MediaStreamTrackを対象とする

updateMeta

Connection Metadata を更新する。connect時に設定したキーのvalueしか更新できない。
受信先でupdateremoteconnectionイベントが発生する。
Roomの種類がSFUの時のみ利用可能

引数 (*必須) 概要 未指定時
meta* Meta 新たに設定するmeta -

updateTrackMeta

指定したLSTrackの Track Metadata を更新する。connect時に設定したキーのvalueしか更新できない。
受信先でupdateremotetrackイベントが発生する。
Roomの種類がSFUの時のみ利用可能

引数 (*必須) 概要 未指定時
lsTrack* LSTrack 更新対象の LSTrack -
meta* Meta 新たに設定するmeta -

replaceMediaStreamTrack

指定したLSTrackのMediaStreamTrackを更新する。

引数 (*必須) 概要 未指定時
lsTrack* LSTrack 更新対象の LSTrack -
mediaStreamTrack* MediaStreamTrack 更新するMediaStreamTrack -

changeMute

指定したLSTrackのMuteTypeを更新する。
受信先でupdatemuteイベントが発生する。

引数 (*必須) 概要 未指定時
lsTrack* Track 更新対象の LSTrack -
nextMuteType* MuteType 更新するmute type -

getHeadReport

開始数分のログを取得する
※ 接続中に呼び出すとメディア送受信のログも併せて取得できます

getTailReport

直近数分のログを取得する
※ 接続中に呼び出すとメディア送受信のログも併せて取得できます

getStatsReport

直近数分のstatsを取得する

イベント

イベントハンドラーはon()及びaddEventListener()を介して登録する。

// イベントハンドラーを登録する例
client.addEventListener('connecting', () => {
  console.log('connecting...');
});
イベント名
(プロパティ名)
イベントの型 発生タイミングと状態遷移の関係 状況・概要
connecting {
  type: string
}
Idle ->
Connecting
接続を開始した
(connect() メソッドが呼ばれた)
open {
  type: string
}
Connecting -> Open シグナリングサーバとの接続が確立した
closing {
  type: string
}
* -> Closing 切断が開始された
close {
  type: string
}
Closing -> Closed 切断された
error SDKErrorEvent Connected エラーが発生した
addremoteconnection {
  connection_id: string,
  meta: Meta
}
Connected Client に Remote
Connection が追加された
meta は Connection の
connect()時に指定した meta オブジェクト
meta は Roomの種類がSFUの時のみ有効
updateremoteconnection {
  connection_id: string,
  meta: Meta
}
Connected Remote Connection の
Connection Metadata が更新された
Room の種類がSFUの時のみ発火
removeremoteconnection {
  connection_id: string,
  meta: Meta,
  mediaStreamTrack?: MediaStreamTrack
}
Connected Client から Remote
Connection が削除された
meta は Remote
Connection の Connection Metadata オブジェクト
meta は Room の種類がSFUの時のみ有効
addremotetrack {
  connection_id:string,
  meta?: Meta,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
Connected Client に RemoteTrack が追加された
meta は RemoteTrack の
Track option で指定した
meta オブジェクト
meta は Roomの種類がSFUの時のみ有効
updateremotetrack {
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  meta: Meta
}
Connected Remote Connection の
Track Metadata が更新された
Room の種類がSFUの時のみ発火
changestability {
  connection_id: string,
  stability: string
}
Connected 通信の安定性が変化した
stability は("icestable" | "iceunstable")
addlocaltrack {
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream
}
Connected Client に LocalTrack が追加された
updatemute {
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
Connected Remote Track の MuteType が更新された
Room の種類がSFUの時のみ発火

エラー

状況 通知方法
状態で許可されていないメソッド呼び出し Connected 状態で connect を呼んだ メソッドが例外を投げる
間違った引数によるメソッド呼び出し 必須の引数が不足している メソッドが例外を投げる
サーバーからの明示的な切断 ネットワークエラー error イベント発火
その他の接続失敗、切断 予期しないエラー error イベント発火

詳細はエラー仕様を参照

Client

export class Client extends ET {
    public connect(client_id: ClientID, access_token: JwtAccessToken, option: Object): void;
    public disconnect(): void;        
    public getState(): StateType;
    public getStats(): Object;    
    public updateMeta(meta: Object): void;
    public updateTrackMeta(lsTrack: LSTrack, meta: Object): void;
    public replaceMediaStreamTrack(lsTrack: LSTrack, mediaStreamTrack: MediaStreamTrack): Promise<void>;    
    public changeMute(lsTrack: LSTrack, nextMuteType: MuteType): Promise<void>;
    public getHeadReport(): string;
    public getTailReport(): string;
    public getStatsReport(): string;
}

State

type StateType = "idle" | "connecting" | "open" | "closing" | "closed";

LSTrack

export class LSTrack {
    Track(mediaStreamTrack: MediaStreamTrack, stream: MediaStream, option: LSTrackOption): void;
}
LSTrackOption
field
meta object 任意のオブジェクト { "k1" : "v1", "k2": "v2" }
mute MuteType "unmute" | "softmute" | "hardmute"

connectに渡す際のLSTrackのmuteにより初期のミュート状態を設定することができる

MuteType

概要
unmute ミュートなし
hardmute videoもaudioも送らない
※ trackをnullにした際のブラウザ挙動に準拠
softmute videoは黒画面を送り、audioは送らない
※ trackをdisabledにした際のブラウザ挙動に準拠

softmuteでは受信側に最後のフレーム表示が残ることを避けることができるが、hardmuteに比べ、黒画面送受信に伴うエンコード/デコード/帯域負荷が追加で発生する。
※ ブラウザ規定 参考( https://w3c.github.io/webrtc-pc/#dom-rtcrtpsender-track )
MediaStreamTrackをVideoタグで表示中の場合、hardmute/softmute共に表示映像は黒画面となる。
(hardmuteの際にもローカルトラックはdisabledになる)

IDString

Meta

すべてのkeyがIDStringであるobject
valueはJSON にエンコードされて 0 文字以上 1024 文字以下となるUTF-8でエンコードできる全ての文字が使用できる
使用できるkeyの数は最大32