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 に遷移する。
ConnectingServer との接続確立中 (WebSocket 接続中、 SDP 交換中、経路情報交換中) 。
Open経路情報の交換が完了し、Server との接続 (SFU では PeerConnection 、 P2P は WebSocket) を確立できた。
Closing切断要求を受け付けたか、エラーが発生して、切断処理をしている。
Closed切断処理が完了した。

状態遷移

状態遷移

メソッド

メソッド名概要
connect指定された Room に接続・参加する
disconnect参加中の Room から退出する
getStateClient の状態を取得する
getStatsPeerConnection の stats を取得する
updateMetaConnection Metadata を更新する
updateTrackMetaTrack Metadata を更新する
(Room の種類が SFU の時のみ利用可能)
changeMediaRequirementsConnection に関する Media の要件を変更する
replaceMediaStreamTrackMediaStreamTrack を置き換える
changeMutetrack の MuteType を変更する
changeVideoSendBitrateVideo の送信ビットレートを更新する
changeVideoSendFramerateVideo の送信フレームレートを更新する
getHeadReport開始数分のログを取得する
getTailReport直近数分のログを取得する
getStatsReport直近数分の stats を取得する
getTrackReportMediaStreamTrack に関するログを取得する
setLibWebrtcLogOptionlibwebrtc ログオプションを設定する
changeAdaptiveSendingMode適応的送信モードを設定する(β 版)
setAdaptiveSendingCapturer適応的送信用の Capturer を設定する(β 版)

connect

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

引数 (*必須)概要未指定時
client_id *IDStringClient ID-
access_token *JwtAccessTokenアクセストークン-
option *objectオプション-
option.localLSTracks *LSTrack[]初期 Local LSTrack の配列-
option.metaMetaConnection Metadata オブジェクト{}
option.signalingURLstringシグナリング URL
(通常は既定 URL が設定されるため指定不要)
既定 URL
option.sendingSendingOptionSending Option
(Room の種類が SFU の時のみ有効)
SendingOption 未指定時動作に準拠
option.receivingReceivingOptionReceiving Option
(Room の種類が SFU の時のみ有効)
ReceivingOption 未指定時動作に準拠
option.iceTransportPolicy"all" | "relay"P2P の際の iceTransportPolicyall
option.iceServersProtocol"all" | "udp" | "tcp" | "tls" | "tcp_tls"iceServers に使用する TURN Protocol (tcp_tls は tcp か tls のいずれかで接続)all
option.proxyProxyOptionProxy OptionAndroid SDK のみ対応。未指定時は proxy 不使用

SendingOption

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

引数 (*必須)概要未指定時
videoSendingVideoOptionVideo 送信オプションSendingVideoOption 未指定時動作に準拠
enabledboolean送信するかどうかtrue

※ 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 の時のみ有効

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

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

SendingVideoOption

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

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

ProxyOption

引数 (*必須)概要未指定時
urlstringproxy 指定文字列””

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()に限定できる

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

updateMeta

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

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

updateTrackMeta

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

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

changeMediaRequirements

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

引数 (*必須)概要未指定時
connection_id*string対象の相手 Connection-
videoRequirement*"required" | "unrequired"video を要求するかどうか-

replaceMediaStreamTrack

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

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

changeMute

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

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

changeVideoSendBitrate

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

引数 (*必須)概要未指定時
maxBitrateKbps*number送信ビットレート上限-

changeVideoSendFramerate

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

引数 (*必須)概要未指定時
maxFramerate*number送信フレームレート上限
(0 以上 10000 以下)
-

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

setLibWebrtcLogOption

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

引数 (*必須)概要未指定時
option*LibWebrtcLogOptionログオプション-

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

LibWebrtcLogOption

引数 (*必須)概要未指定時
path*string保存先ファイル名のフルパス----
maxTotalFileSizenumberログファイルの最大合計サイズ(MByte)
(4 以上 32 以下)
4
logLevel"VERBOSE" |
"INFO"
ログレベル("VERBOSE":全てのログ、"INFO":重要なログのみ)"INFO"

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

changeAdaptiveSendingMode

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

引数 (*必須)概要未指定時
option*AdaptiveSendingOption適応的送信オプション----

※ Android SDK (Theta のみ) に対応

AdaptiveSendingOption

引数 (*必須)概要未指定時
mode*"NONE" |
"BALANCED"
"NONE":sdk 独自の自動制御なし(libwebrtc によるメディア制御のみ行う)、"BALANCED":解像度/フレームレートの優先度を sdk に任せる"NONE"

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

setAdaptiveSendingCapturer

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

引数 (*必須)概要未指定時
capturer*VideoCapturercapturer----

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

※ Android SDK (Theta のみ) に対応

イベント

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

// イベントハンドラーを登録する例
client.addEventListener('connecting', () => {
  console.log('connecting...');
});
イベント名
(プロパティ名)
イベントの型発生タイミングと状態遷移の関係状況・概要
connecting{}Idle ->
Connecting
接続を開始した
(connect() メソッドが呼ばれた)
open{access_token_json: string}Connecting -> Openシグナリングサーバとの接続が確立した
access_token_json は Connection の
connect()時に指定した access_token の中身
closing{}* -> Closing切断が開始された
close{}Closing -> Closed切断された
errorSDKErrorEventOpenエラーが発生した
mediaopen{}Openサーバとの Media 接続が確立した(Room の種類が SFU の時のみ利用可能)
addremoteconnection{
  connection_id: string,
  meta: Meta
}
OpenClient に Remote
Connection が追加された
meta は Connection の
connect()時に指定した meta オブジェクト
updateremoteconnection{
  connection_id: string,
  meta: Meta
}
OpenRemote Connection の
Connection Metadata が更新された
removeremoteconnection{
  connection_id: string,
  meta: Meta,
  mediaStreamTrack?: MediaStreamTrack
}
OpenClient から Remote
Connection が削除された
meta は Remote
Connection の Connection Metadata オブジェクト
addremotetrack{
  connection_id:string,
  meta?: Meta,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
OpenClient に RemoteTrack が追加された
meta は RemoteTrack の
Track option で指定した
meta オブジェクト
meta 及び mute は Room の種類が SFU の時のみ有効
updateremotetrack{
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  meta: Meta
}
OpenRemote Connection の
Track Metadata が更新された
Room の種類が SFU の時のみ発火
[deprecated]changestability{
  connection_id: string,
  stability: string
}
Open※将来廃止予定のため changemediastability に移行して下さい。
通信の安定性が変化した
stability は("icestable" | "iceunstable")
changemediastability{
  connection_id: string,
  stability: string
}
OpenMedia 接続の通信の安定性が変化した
stability は("stable" | "unstable")
addlocaltrack{
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream
}
OpenClient に LocalTrack が追加された
updatemute{
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
OpenRemote Track の MuteType が更新された
Room の種類が SFU の時のみ発火
updateconnectionsstatus{
  connections_status: Object
}
OpenConnectionsStatus が更新された
room の種類が SFU の時のみ発火
log{
  msg: string,
  category:
string,
  subcategory: string,
  date: Date
}
Connectedログが発生した

エラー

状況通知方法
状態で許可されていないメソッド呼び出し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;
  public getTrackRepeort(): string;
}

State

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

LSTrack

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

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

MuteType

概要
unmuteミュートなし
hardmutevideo も audio も送らない
※ track を null にした際のブラウザ挙動に準拠
softmutevideo は黒画面を送り、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

ConnectionsStatus

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

field説明
video.receiver_existenceboolean自クライアントの映像が他クライアントから使用されているかどうかを示す※

※ 他クライアントの入退室や、他クライアントによる 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 互換性のないバージョン更新。アプリケーションに実装変更が必要となる。

この情報は役に立ちましたか?