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 を取得する

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"iceServers に使用する TURN Protocolall

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 利用料金を参照ください。

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 未満を設定するとエラーになります。

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

changeVideoSendFramerate

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

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

getHeadReport

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

getTailReport

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

getStatsReport

直近数分の stats を取得する

イベント

イベントハンドラーは 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切断された
errorSDKErrorEventConnectedエラーが発生した
addremoteconnection{
  connection_id: string,
  meta: Meta
}
ConnectedClient に Remote
Connection が追加された
meta は Connection の
connect()時に指定した meta オブジェクト
updateremoteconnection{
  connection_id: string,
  meta: Meta
}
ConnectedRemote Connection の
Connection Metadata が更新された
removeremoteconnection{
  connection_id: string,
  meta: Meta,
  mediaStreamTrack?: MediaStreamTrack
}
ConnectedClient から Remote
Connection が削除された
meta は Remote
Connection の Connection Metadata オブジェクト
addremotetrack{
  connection_id:string,
  meta?: Meta,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
ConnectedClient に RemoteTrack が追加された
meta は RemoteTrack の
Track option で指定した
meta オブジェクト
meta 及び mute は Room の種類が SFU の時のみ有効
updateremotetrack{
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  meta: Meta
}
ConnectedRemote Connection の
Track Metadata が更新された
Room の種類が SFU の時のみ発火
changestability{
  connection_id: string,
  stability: string
}
Connected通信の安定性が変化した
stability は("icestable" | "iceunstable")
addlocaltrack{
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream
}
ConnectedClient に LocalTrack が追加された
updatemute{
  connection_id: string,
  mediaStreamTrack:
MediaStreamTrack,
  stream: MediaStream,
  mute: MuteType
}
ConnectedRemote 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
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

バージョニング

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 互換性のないバージョン更新。アプリケーションに実装変更が必要となる。