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() メソッドで取得できる。

状態遷移

メソッド

connect

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

SendingOption

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

※ enabled を false にする場合、enabled 非対応バージョンの SDK を使用した Client App が同一 Room に存在すると必ず OnTrackTimeout エラーが発生します
非対応バージョン SDK:

• Web: v1.2.0 以前
• Android: v1.5.0 以前
• Windows Unity: v1.2.0 以前

※ SendingOption と ReceivingOption の enabled は少なくともいずれかが true でなければならない

ReceivingOption

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

※ SendingOption と ReceivingOption の enabled は少なくともいずれかが true でなければならない

SendingVideoOption

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

ProxyOption

url: 経由する proxy サーバを設定するための文字列形式。WebSocket 接続及び、iceServers に使用する TURN Protocol が TCP/TLS の際に適用される。

http://<username>:<password>@<proxyhost>:<proxyport>/ 形式の文字列

username:password は認証 proxy 経由時のみ指定する

例) http://proxyhost:3128/
例) http://user:pass@proxyhost:3128/

※ proxy 経由を必須とする場合は、option.iceServersProtocol の設定により、UDP 通信が発生しないようにしてください。
※ 認証情報が誤っている場合は ParameterError が発生します。

disconnect

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

getState

Client の状態を返す。

getStats

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

updateMeta

Connection Metadata を更新する。connect 時に設定したキーの value しか更新できない。
受信先でupdateremoteconnectionイベントが発生する。

updateTrackMeta

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

changeMediaRequirements

指定した 相手 Connection に関する Media の要件を変更する。
サーバはこの指定に基づいて Media の送信をどう行うか、あるいは行わないかを決定する。 Room の種類が SFU の時のみ利用可能 ※ 指定した connection_id の相手が leave 済の場合、ConnectionNotFoundOnChangeMediaRequirements が発生します。

replaceMediaStreamTrack

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

changeMute

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

changeVideoSendBitrate

ビデオの送信ビットレートを変更する。
※ connect 時に指定した値(未指定時はデフォルト値)より大きな値や 100 未満を設定するとエラーになります。
※ AdaptiveSendingMode が NONE 以外に設定されている場合はエラーになります。

changeVideoSendFramerate

ビデオの送信フレームレートを変更する。
※ カメラの出力フレームレートを超えた値を設定しても、実効フレームレートはカメラの出力フレームレートに制限されます。
※ Web SDK は Google Chrome のみ有効。

getHeadReport

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

getTailReport

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

getStatsReport

直近数分の stats を取得する

getTrackReport

Client の open から API コール時点 までに発生した Track の追加削除ログが取得できます

※ Web SDK のみ対応

例)

[2023-04-17T01:08:42.334Z]	add(audio)	4CV8AMX26H07S5MXYSX4WV6J00	connection_id: WebDemoAppMC45NDMwNjUwMzAwMzQ2MzE3
[2023-04-17T01:08:42.336Z]	add(video)	NG2N02JT1X58SAD32XPBD6JREG	connection_id: WebDemoAppMC45NDMwNjUwMzAwMzQ2MzE3
[2023-04-17T01:08:42.347Z]	connect(audio)	4CV8AMX26H07S5MXYSX4WV6J00	codec: audio/opus
[2023-04-17T01:08:42.347Z]	connect(video)	NG2N02JT1X58SAD32XPBD6JREG	codec: video/VP8
[2023-04-17T01:08:47.884Z]	remove(audio)	4CV8AMX26H07S5MXYSX4WV6J00
[2023-04-17T01:08:47.884Z]	remove(video)	NG2N02JT1X58SAD32XPBD6JREG

getLocalTrackMid

Local LSTrack に対する mid が取得できます。
mid: WebRTC 規定における メディアストリームの識別子
※ 参考( https://w3c.github.io/webrtc-pc/#dfn-mid )

※ Web SDK のみ対応

setLibWebrtcLogOption

libwebrtc ログオプションを設定する。
※ Android SDK 及び Windows UnitySDK のみ対応

本 API を呼び出さなければ libwebrtc ログは出力されない。

LibWebrtcLogOption

ログファイルの出力仕様は libwebrtc に準じる。
基本的には、ログの先頭、末尾がそれぞれ maxTotalFileSize の半分のザイズずつ保存され、ファイル名の末尾には時系列の新しいものから順に連番が付与される。

changeAdaptiveSendingMode

適応的送信モードを設定する(β 版)

※ Android SDK (Theta のみ) に対応

AdaptiveSendingOption

いずれのモードでも libwebrtc によるメディア制御は行われるが、NONE 以外のモードでは、ネットワークの状況変化に応じた sdk 独自のビデオ解像度とフレームレート変更が行われる。 NONE 以外に設定する場合、事前に setAdaptiveSendingCapturer() を用いた capturer 設定が必要。

setAdaptiveSendingCapturer

適応的送信用の Capturer を設定する(β 版)

AdaptiveSendingMode を NONE 以外に設定する場合は、本 API を呼び出して事前に capturer を設定する必要がある。

※ Android SDK (Theta のみ) に対応

イベント

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

// イベントハンドラーを登録する例
client.addEventListener('connecting', () => {
  console.log('connecting...');
});

エラー

詳細はエラー仕様を参照

型

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;
  public getTrackRepeort(): string;
  public getLocalTracktMid(
    lsTrack: LSTrack,
    connection_id: ConnectionID,
  ): string;
}

State

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

LSTrack

export class LSTrack {
  Track(
    mediaStreamTrack: MediaStreamTrack,
    stream: MediaStream,
    option: LSTrackOption,
  ): void;
}

LSTrackOption

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

MuteType

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

IDString

• IDString

Meta

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

ConnectionsStatus

自クライアントのトラックの他クライアントからの利用状況を示すオブジェクト

※ 他クライアントの入退室や、他クライアントによる changeMediaRequirements 呼び出しで変化する

バージョニング

SDK バージョンはセマンティックバージョニング 2.0.0に準拠している。

バージョンナンバーは、メジャー.マイナー.パッチ の形式となる。

後方互換性があるバグ修正をした場合はパッチバージョン、
後方互換性がある機能追加をした場合はマイナーバージョン、
API 互換性のない変更をした場合はメジャーバージョンが上がる。

例)

• v1.5.0 -> v1.5.1: API 互換性のあるバグ修正。
• v1.5.0 -> v1.6.0: API 互換性のある機能追加。
• v1.5.0 -> v2.0.0: API 互換性のないバージョン更新。アプリケーションに実装変更が必要となる。