こちらのページは旧SkyWayの情報です。新しいSkyWayに関する情報はこちら

# JavaScript SDK

# はじめに

SkyWay の開発が初めての方は、ドキュメント/はじめにをご確認ください。

# クラス一覧

  • Peer :P2P 接続、およびルーム接続機能を操作するためのクラス
  • MediaConnection :接続先 Peer へのメディアチャネル接続を管理するクラス
  • DataConnection :接続先 Peer へのデータチャネル接続を管理するクラス
  • MeshRoom :メッシュ接続でのルームを管理するクラス
  • SFURoom :SFU 接続でのルームを管理するクラス

# EventEmitterについて

すべてのクラスはEventEmitterを継承しています。

EventEmitter は直訳の通り、イベントを発火 or 受け取ることができる機能です。

例えば、着信などのイベントが発生した場合にはon()を利用します。

function onOpen() {
  console.log("着信しました!");
}
// 着信イベントを検知するイベントリスナを設置
peer.on("open", onOpen);

// イベントリスナを削除
peer.off("open", onOpen);

EventEmitterの詳しい使い方については、公式ドキュメント等をご確認ください。

TIP

エラー検知は、on('error', listener)にて確認するようにしてください。

# Peer

P2P 接続、およびルーム接続機能を操作するためのクラスです。

SkyWay を利用するためには、まず最初に Peer インスタンス生成が必要です。

# Constructor(id, options)

# Constructor(options)

新規に Peer インスタンスを生成します。 new Peer() により、SkyWay のシグナリングサーバと接続します。

# Sample

// デバッグ情報を最大(3)にして接続する場合
const peer = new Peer('some-peer-name', {
  key:   "<YOUR-API-KEY>"
  debug: 3,
});
// TURNサーバを強制利用する場合
const peer = new Peer({
  key:   "<YOUR-API-KEY>"
  config: {
    iceTransportPolicy: 'relay',
  },
});

# Parameter

Name Type Required Default Description
id string ユーザの Peer ID です。値を与えなかった場合、Peer ID はシグナリングサーバから与えられます。
options options object 接続に関するパラメータを指定するオプションです。
# options object
Name Type Required Default Description
key string SkyWay の API キーです。
debug number 0 ログレベルは NONE: 0, ERROR: 1, WARN: 2, FULL: 3 から選択できます。
turn boolean true SkyWay で提供する TURN を使うかどうかのフラグです。TURN 利用が有効の場合のみ使えます。
credential credential object Peer を認証するためのクレデンシャルです。Peer認証が有効の場合のみ使えます。
config RTCConfiguration Default RTCConfiguration object RTCPeerConnectionに渡される RTCConfiguration です。発展的なオプションのため、内容を理解している場合のみご利用ください。
# credential object

Peer認証の詳細はPeer認証のサンプルをご確認ください。

Name Type Required Default Description
timestamp number 現在の UNIX タイムスタンプです。
ttl number Time to live(ttl)。タイムスタンプ + ttl の時間でクレデンシャルが失効します。ttlの取りうる値は600~90,000です。
authToken string HMAC を利用して生成する認証用トークンです。
# Default RTCConfiguration object
const defaultConfig = {
  iceServers: [
    {
      urls: "stun:stun.webrtc.ecl.ntt.com:3478",
      url: "stun:stun.webrtc.ecl.ntt.com:3478",
    },
  ],
  iceTransportPolicy: "all",
  sdpSemantics: "unified-plan",
};

# Members

Name Type Description
id string ユーザーが指定した Peer ID、もしくはサーバが生成した Peer ID です。
open boolean シグナリングサーバへの接続状況を保持します。
connections Object 全てのコネクションを保持するオブジェクトです。
rooms Object 全てのルームを保持するオブジェクトです。
options Object Constructor()での指定と、SDK のデフォルト設定を反映したオブジェクトです。

# Methods

# call(peerId[, stream][, options])

指定した Peer にメディアチャネル(音声・映像)で接続して、MediaConnectionを作成します。 オプションを指定することで、帯域幅・コーデックなどを指定できます。

# Parameters
Name Type Required Default Description
peerId string 接続先の Peer ID です。
stream MediaStream 接続先の Peer へ送るメディアストリームです。 設定されていない場合は、受信のみモードで発信します。
options call options object 発信時に付与するオプションです。帯域幅・コーデックなどを指定します。
# call options object
Name Type Required Default Description
metadata Object コネクションに関連付けされる任意のメタデータで、接続先の Peer に渡されます。
videoBandwidth number 接続先から受信する映像の最大帯域幅(kbps)です。
audioBandwidth number 接続先から受信する音声の最大帯域幅(kbps)です。
videoCodec string 映像コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'H264' 'VP8' 'VP9'
audioCodec string 音声コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'opus' 'ISAC' 'G722' 'PCMU' 'PCMA'
videoReceiveEnabled boolean 映像を受信のみで使う場合のフラグです。この値がtrueかつstreamに映像トラックが含まれない場合、受信のみで映像の通信を行います。
audioReceiveEnabled boolean 音声を受信のみで使う場合のフラグです。この値がtrueかつstreamに音声トラックが含まれない場合、受信のみで音声の通信を行います。
connectionId string コネクションを識別する ID です。
label string Deprecated コネクションを識別するのに利用するラベルです。代わりにconnectionIdを使用してください。
# Return value

MediaConnectionのインスタンス

# Sample
// 自身のlocalStreamを設定して、相手に発信する場合
const call = peer.call("peerID", localStream);
// 自身のlocalStreamおよびmetadataを設定して、相手に発信する場合
const call = peer.call("peerID", localStream, {
  metadata: {
    foo: "bar",
  },
});
// 映像コーデックとしてH264を利用する場合
const call = peer.call("peerID", localStream, {
  videoCodec: "H264",
});
// 音声のみ接続先から受信する設定で、相手に発信する場合
const call = peer.call("peerID", null, {
  audioReceiveEnabled: true,
});

# connect(peerId[, options])

指定した Peer にデータチャネルで接続して、DataConnectionインスタンスを生成します。

# Parameters
Name Type Required Default Description
peerId string 接続先の Peer ID です。
options connect options object 接続時に付与するオプションです。
# connect options object
Name Type Required Default Description
metadata Object コネクションに関連付けされる任意のメタデータで、接続先の Peer に渡されます。
serialization string 'binary' 送信時のシリアライズ方法を指定します。'binary', 'json', 'none'のいずれかとなります。
dcInit RTCDataChannelInit {} DataChannel 利用時に信頼性の有無を指定するためのオプションです。デフォルトでは信頼性有で動作します。
connectionId string コネクションを識別する ID です。
label string Deprecated コネクションを識別するのに利用するラベルです。代わりにconnectionIdを使用してください。
# Return value

DataConnectionのインスタンス

# Sample
// 単にDataChannelを接続する場合(デフォルトで信頼性有り)
peer.connect("peerId");
// metadata付きでconnectする場合
peer.connect("peerId", {
  metadata: {
    hoge: "foobar",
  },
});
// 信頼性無しモードでDataChannelを接続する場合
peer.connect("peerId", {
  dcInit: {
    // 最大2回、再送する
    maxRetransmits: 2,
  },
});

# destroy()

シグナリングサーバとの接続、および、接続済みのmediaConnection, dataConnectionを切断します。

# Return value

undefined

# disconnect()

Deprecated 代わりに destroy() を使用してください。

シグナリングサーバとの接続を切断します。なお、接続済みのmediaConnection, dataConnectionは継続されます。

# Return value

undefined

# reconnect()

Deprecated 代わりに Peer インスタンスを再度生成してください。

シグナリングサーバへ再接続します。再接続の際には割り当て済みのPeer IDを使用します。

# Return value

undefined

# joinRoom(roomName[, roomOptions])

メッシュ接続のルーム、または SFU 接続のルームに参加します。 メッシュ接続および SFU 接続についてはこちらを確認ください。

# Parameters
Name Type Rquired Default Description
roomName string 参加先のルームの名前です。
roomOptions room options object {} 接続時に選択・付与するオプションです。
# room options object
Name Type Required Default Description
mode string 'mesh' 'sfu'または'mesh'を指定します。
stream MediaStream ユーザーが送信するメディアストリームです。
videoBandwidth number 映像の最大帯域幅(kbps)です。メッシュ接続のみ使用可能です。
audioBandwidth number 音声の最大帯域幅(kbps)です。 メッシュ接続のみ使用可能です。
videoCodec string 映像コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'H264' 'VP8' 'VP9' メッシュ接続のみ使用可能です。
audioCodec string 音声コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'opus' 'ISAC' 'G722' 'PCMU' 'PCMA' メッシュ接続のみ使用可能です。
videoReceiveEnabled boolean 映像を受信のみで使う場合のフラグです。メッシュ接続のみ使用可能です。
audioReceiveEnabled boolean 音声を受信のみで使う場合のフラグです。メッシュ接続のみ使用可能です。
# Return value

SFURoom または MeshRoom のインスタンス

# Sample
// Mesh接続を利用する場合
const room = peer.joinRoom("roomName", {
  mode: "mesh",
  stream: localStream,
});
// SFU接続を利用する場合
const room = peer.joinRoom("roomName", {
  mode: "sfu",
  stream: localStream,
});

# fetchPeerExists(peerId)

REST API を利用して、API キーに紐づく指定した Peer ID が存在するかを取得します。 1秒に1回利用することが可能です。 利用するためには、ダッシュボードで listAllPeers API の利用が許可されている必要があります。

# Parameters
Name Type Required Default Description
peerId string 取得する対象の Peer ID です。
# Return value

Promise<boolean>

# Sample
const isExist = await peer.fetchPeerExists(peerId);
console.log(isExist);
// => true or false

# listAllPeers(callback)

REST API を利用して、API キーに紐づく Peer ID 一覧を取得します。 特定の Peer ID について存在確認をするにはfetchPeerExists()が利用できます。

# Parameters
Name Type Required Default Description
callback Function Peer ID 一覧を受け取る関数です。
# Return value

undefined

# Sample
peer.listAllPeers((peers) => {
  console.log(peers);
  // => ["yNtQkNyjAojJNGrt", "EzAmgFhCKBQMzKw9"]
});

# getConnection(peerId, connectionId)

作成した MediaConnection および DataConnection を取得します。

# Parameters
Name Type Required Default Description
peerId string Peer ID です。
connectionId string コネクションの ID です。
# Return value

MediaConnectionのインスタンス、またはDataConnectionのインスタンス、またはnull

# updateCredential(credential)

Peer 認証のクレデンシャルの TTL を延長するための更新リクエストの送付します。 Peer 認証については、コチラをご確認ください。

# Parameters
Name Type Required Default Description
credential credential object ユーザー側で作成する新しいクレデンシャルです。
# Return value

undefined

# Events

それぞれのイベント名は、PeerクラスのEVENTSプロパティからも参照できます。

// これらは同じ意味
peer.on("open", () => {});
peer.on(Peer.EVENTS.open, () => {});

# Event: 'open'

シグナリングサーバへ正常に接続できたときのイベントです。

Name Type Description
id string Peer ID
peer.on("open", (id) => {
  // ...
});

# Event: 'call'

接続先の Peer からメディアチャネル(音声・映像)の接続を受信したときのイベントです。

Name Type Description
call MediaConnection MediaConnectionのインスタンスです。
peer.on("call", (call) => {
  // ...
});

# Event: 'close'

peer.destroy()を実行したときに発生するイベントです。 本イベント発生後は、シグナリングサーバとの接続、およびすべてのmediaConnection, dataConnectionが切断され、さらにすべてのRoomから退出させられます。

peer.on("close", () => {
  // ...
});

# Event: 'connection'

接続先の Peer から DataChannel の接続を受信したときのイベントです。

Name Type Description
conn DataConnection DataConnectionのインスタンスです。
peer.on("connection", (conn) => {
  // ...
});

# Event: 'disconnected'

Deprecated 代わりに'close' イベントを使用してください。

シグナリングサーバから切断したときのイベントです。

Name Type Description
id string Peer ID
peer.on("disconnected", (id) => {
  // ...
});

# Event: 'expiresin'

クレデンシャルが失効する前に発生するイベントです。

Name Type Description
sec number クレデンシャルが失効するまでの時間(秒)です。
peer.on("expiresin", (sec) => {
  // ...
});

# Event: 'error'

エラーが発生した場合のイベントです。

Name Type Description
error Error エラーオブジェクトです。

typeプロパティから以下を判別できます。

Type Description
room-error ルーム名が指定されていません。
そのルーム名は別のタイプのルームで使用されています。他の名前で再度試してください。
SFU 機能が該当の API キーで Disabled です。利用するには、Dashboard から enable にしてください。
ルームへの入室中に不明なエラーが発生しました。少し待って、リトライしてください。
ルームログ取得時に不明なエラーが発生しました。少し待って、リトライしてください。
ルーム内のユーザー一覧の取得中に不明なエラーが発生しました。少し待って、リトライしてください。
offer のリクエスト中に不明なエラーが発生しました。少し待って、リトライしてください。
answer の処理中に不明なエラーが発生しました。少し待って、リトライしてください。
SFU ルームは 1000 回までしか入室できません。
permission 該当のルームの利用が許可されてません。
list-error listAllPeers API が Disabled です。
disconnected SkyWay のシグナリングサーバに接続されていません。
socket-error SkyWay のシグナリングサーバとの接続が失われました。
SkyWay のシグナリングサーバと接続ができません。
SkyWay の dispatcher へのリクエストが失敗しました。ネットワーク接続を確認してください。
SkyWay の dispatcher へのリクエストが中断されました。
SkyWay の dispatcher へのリクエストがタイムアウトしました。ファイアウォールの設定やインターネット設定・SkyWay の障害情報を確認してください。
SkyWay のシグナリングサーバーから予期せぬレスポンスを受け取りました。
SkyWay のシグナリングサーバからドメインを含まない不正な JSON を受け取りました。
SkyWay のシグナリングサーバから不正な JSON を受け取りました。
invalid-id peerid が無効です。peerid は 1~63 文字である必要があります。
unavailable-id その peerid はすでに使われています。違う peerid を使用してください。
invalid-key API キーが無効です。
invalid-domain この API キーではそのドメインは登録されていません。
authentication タイムスタンプを現在時刻より将来の時刻にすることはできません。
クレデンシャルが期限切れになっています。
認証トークンが期限切れになっています。
認証トークンが不正です。
TTL に制限よりも大きい数値が設定されています。
TTL に制限よりも小さい数値が設定されています。
server-error SkyWay のシグナリングサーバとの接続中に問題がありました。 少し待って、リトライしてください。
sfu-client-not-supported このクライアントは SFU の使用をサポートしていません。最新の Google Chrome を使用してください。
peer-unavailable 対向の peer へ送信できませんでした。peerid が正しいことを確認してください。
signaling-limited シグナリング回数が Community Edition の無償利用枠を超過しているため、全ての機能が利用できません。(Community Edition のみ)
sfu-limited SFU サーバの利用量が Community Edition の無償利用枠を超過しているため、SFU の機能が利用できません。(Community Edition のみ)
turn-limited TURN サーバの利用量が Community Edition の無償利用枠を超過しているため、TURN の機能が利用できません。(Community Edition のみ)
// 仮にRoom名を指定せずにjoinRoomを呼んだ場合
peer.on("error", (error) => {
  console.log(`${error.type}: ${error.message}`);
  // => room-error: Room name must be defined.
});

WARNING

「xxxx-limited」エラーが発生している場合、利用量が Community Edition の無償利用枠を超過しているため、当月中は該当機能を利用できません。翌月 1 日 0:00 に無償利用枠がリセットされ、利用が再開されます。

# MediaConnection

接続先 Peer へのメディアチャネル接続を管理するクラスです。

SDK 内部の利用のみで、コンストラクタは通常利用しません。 MediaConnectionインスタンスは、Peer#call() およびPeercallイベント で生成されます。

# Sample

// 発信側
const mediaConnection = peer.call("peerID", mediaStream);

// 着信側
peer.on("call", (mediaConnection) => {
  // MediaStreamで応答する
  mediaConnection.answer(mediaStream);
});

# Members

Name Type Description
type string コネクションタイプを示す文字列です。MediaConnection では、この値は'media' です。
metadata Object 発信側がPeer#call()実行時に指定したmetadataです。着信側では、発信側が指定した値になります。
localStream MediaStream Peer#call()あるいはMediaConnection#answer()で指定した自身の MediaStream です。
open boolean コネクションがオープンしているかどうかを示します。MediaConnectionstreamイベントまたは MediaConnection#answer() が呼び出された際にオープンし、 MediaConnection#close()が呼び出されたまたはMediaConnectioncloseイベントが発生した際にクローズします。
remoteId string 接続先 Peer の Peer ID です。
peer string Deprecated 接続先 Peer の Peer ID です。remoteId を使ってください。
id string コネクションを識別する ID です。

# Methods

# answer(stream[, options])

発信側からのメディアチャネル接続の接続要求に対して応答します。

# Parameters
Name Type Required Default Description
stream MediaStream 発信側の Peer へ送る MediaStream オブジェクトです。
options answer options object 応答時に付与するオプションです。
# answer options object
Name Type Required Default Description
videoBandwidth number 接続先 Peer から受信する映像の最大帯域幅(kbps)です。
audioBandwidth number 接続先 Peer から受信する音声の最大帯域幅(kbps)です。
videoCodec string 映像コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'H264' 'VP8' 'VP9'
audioCodec string 音声コーデックです。対応コーデックはブラウザにより異なります。取りうる値は次のとおりです。'opus' 'ISAC' 'G722' 'PCMU' 'PCMA'
# Return value

undefined

# Sample
peer.on("call", (mediaConnection) => {
  const answerOption = {
    videoCodec: "H264",
  };

  mediaConnection.answer(mediaStream, answerOption);
});

# close(forceClose)

接続先 Peer との MediaConnection の接続を切断します。

# Parameters
Name Type Required Default Description
forceClose boolean false この値がtrueの場合、相手の MediaConnection も即座に close します。falseの場合相手は、ブラウザによる ice 再接続が失敗してからコネクションを close します。

Deprecated
false は非推奨です。将来のバージョンからtrueに変更される可能性があります。
# Return value

undefined

# replaceStream(stream)

送信中の MediaStream を変更します。 例えば、カメラ・マイクデバイスの変更や、画質や音質の変更などに用います。

注意

MediaStream を送信しない状態から送信する状態に変更することはできません。その逆の変更もできません。

また、「映像か音声のどちらかのみを持つ MediaStream」と「映像・音声の両方を持つ MediaStream」を入れ替えることはできません。

# Parameters
Name Type Required Default Description
stream MediaStream 変更対象となる新しい MediaStream です。
# Return value

undefined

# getPeerConnection()

接続先 Peer との MediaConnection が内部的に使用している RTCPeerConnection を取得します。 コネクションのopenプロパティがfalseの場合は、 null が返ります。

注意

RTCPeerConnectionを直接操作すると、SDK は正しく動作しなくなる可能性があります。

# Return value

RTCPeerConnection のインスタンス または null

# Sample
if (mediaConnection.open) {
  const pc = mediaConnection.getPeerConnection();

  // ...
}

# Events

# Event: 'stream'

MediaStream を受信したときに発生します。

Name Type Description
stream MediaStream MediaStream のインスタンスです。
mediaConnection.on("stream", (stream) => {
  // ...
});

# Event: 'close'

MediaConnection#close()が呼ばれたとき、または接続先 Peer とのメディアチャネル接続が切断されたときに発生します。

mediaConnection.on("close", () => {
  // ...
});

# DataConnection

接続先 Peer へのデータチャネル接続を管理するクラスです。

SDK 内部の利用のみで、コンストラクタは通常利用しません。 DataConnectionインスタンスは、Peer#connect() およびPeerconnectionイベント で生成されます。

# Sample

// 発信側
const dataConnection = peer.connect("peerID");

// 着信側
peer.on("connection", (dataConnection) => {
  // ...
});

# Members

Name Type Description
type string コネクションタイプを示す文字列です。DataConnection では、この値は'data' です。
metadata Object 発信側がPeer#connect()実行時に指定したmetadataです。着信側では、発信側が指定した値になります。
serialization string 発信側がPeer#connect()実行時に指定したserializationです。着信側では、発信側が指定した値になります。
dcInit RTCDataChannelInit 発信側がPeer#connect()実行時に指定したdcInitです。着信側では、発信側が指定した値になります。
open boolean コネクションがオープンしているかどうかを示します。DataConnectionopenイベントが発生した際にオープンし、DataConnection#close()が呼び出されたまたはデータチャネル接続が切断された際にクローズします。
remoteId string 接続先 Peer の Peer ID です。
peer string Deprecated 接続先 Peer の Peer ID です。remoteId を使ってください。
id string コネクションを識別する ID です。

# Methods

# send(data)

接続先 Peer にデータを送信します。シリアライズ方法が'binary'である場合は、送信前に分割します。

# Parameters
Name Type Required Default Description
data * 接続先の Peer へ送るデータです。
# Return value

undefined

# Sample
// データを送信する
dataConnection.on("open", () => {
  const data = {
    name: "SkyWay",
    msg: "Hello, World!",
  };
  dataConnection.send(data);
});

// データを受信する
dataConnection.on("data", ({ name, msg }) => {
  console.log(`${name}: ${msg}`);
  // => 'SkyWay: Hello, World!'
});

# getPeerConnection()

接続先 Peer との DataConnection が内部的に使用している RTCPeerConnection を取得します。 コネクションのopenプロパティがfalseの場合は、 null が返ります。

注意

RTCPeerConnectionを直接操作すると、SDK は正しく動作しなくなる可能性があります。

# Return value

RTCPeerConnection のインスタンス または null

# Sample
if (dataConnection.open) {
  const pc = dataConnection.getPeerConnection();

  // ...
}

# close(forceClose)

接続先 Peer との DataConnection の接続を切断します。

# Parameters
Name Type Required Default Description
forceClose boolean false この値がtrueの場合、相手の DataConnection も即座に close します。

Deprecated
false は非推奨です。将来のバージョンからtrueに変更される可能性があります。
# Return value

undefined

# Events

# Event: 'open'

データチャネルが接続されたときに発生します。

dataConnection.on("open", () => {
  // ...
});

# Event: 'data'

接続先の Peer からデータを受信したときに発生します。 シリアライズ方法が'binary'である場合は、分割されたデータすべてを受信し、再結合が完了したときに発生します。

Name Type Description
data * 受信したデータです。
dataConnection.on("data", (data) => {
  // ...
});

# Event: 'close'

DataConnection#close()が呼ばれたとき、または接続先 Peer とのデータチャネル接続が切断されたときに発生します。

dataConnection.on("close", () => {
  // ...
});

# Event: 'error'

DataConnection#send()が呼ばれたが、まだデータチャネルが接続されていなかったときに発生します。

dataConnection.on("error", () => {
  // ...
});

# MeshRoom

メッシュ接続でのルームを管理するクラスです。

SDK 内部の利用のみで、コンストラクタは通常利用しません。 MeshRoom のインスタンスは、Peer#joinRoom() で生成されます。

# Sample

const meshRoom = peer.joinRoom("roomName", {
  mode: "mesh",
  stream: localStream,
});
meshRoom.on("open", () => {});

# Members

Name Type Description
name string ルーム名です。
connections Object Peer ID をキーに、ルーム内のコネクションを保持するオブジェクトです。

# Methods

# close()

ルームを退出し、ルーム内のすべてのユーザーとのコネクションを切断します。

# Return value

undefined

# getLog()

シグナリングサーバにルームのログ取得を要求します。 シグナリングサーバからログを受信すると、logイベントが発火します。

# Return value

undefined

# Sample
room.once("log", (log) => {
  // ...
});
room.getLog();

# replaceStream(stream)

送信中の MediaStream を変更します。 例えば、カメラ・マイクデバイスの変更や、画質や音質の変更などに用います。

注意

MediaStream を送信しない状態から送信する状態に変更することはできません。その逆の変更もできません。

また、「映像か音声のどちらかのみを持つ MediaStream」と「映像・音声の両方を持つ MediaStream」を入れ替えることはできません。

# Parameters
Name Type Required Default Description
stream MediaStream 更新対象となる新しい MediaStream です。
# Return value

undefined

# send(data)

WebSocket を使用してルーム内の全てのユーザーにデータを送信します。

注意

  • 送信可能なデータサイズの上限は 20MB です。

  • 送信頻度は 100msec に 1 回に制限されています。 送信頻度の制限を超えた送信データはキューに入り、100msec 毎に順次送信されます。

# Parameters
Name Type Required Default Description
data * 送信するデータです。
# Return value

undefined

# getPeerConnections()

自身のPeerとルーム内に存在する各Peerとの間のRTCPeerConnectionを取得します。

# Return value

キーがpeerId、値がRTCPeerConnectionのオブジェクト

# Sample
const pcs = room.getPeerConnections();

for ([peerId, pc] of Object.entries(pcs)) {
  console.log(peerId, pc);
}

# Events

# Event: 'open'

新規に Peer がルームへ入室したときに発生します。

room.on("open", () => {
  // ...
});

# Event: 'peerJoin'

ルームに新しい Peer が参加したときに発生します。

Name Type Description
peerId string 参加した Peer の ID です。
room.on("peerJoin", (peerId) => {
  // ...
});

# Event: 'peerLeave'

新規に Peer がルームを退出したときに発生します。

Name Type Description
peerId string 退出した Peer の ID です。
room.on("peerLeave", (peerId) => {
  // ...
});

# Event: 'log'

ルームのログを受信したときに発生します。

Name Type Description
logs string[] ログ(JSON 文字列)の配列です。
room.once("log", (logs) => {
  for (const logStr of logs) {
    const { messageType, message, timestamp } = JSON.parse(logStr);
    // ...
  }
});

# Event: 'stream'

ルームに Join している他のユーザのストリームを受信した時に発生します。 ストリーム送信元の Peer ID はstream.peerIdで取得できます。

Name Type Description
stream MediaStream MediaStream のインスタンスです。
room.on("stream", (stream) => {
  // ...
});

# Event: 'data'

他のユーザーから送信されたデータを受信した時に発生します。

Name Type Description
data object data object形式のオブジェクトです。
# data object
Name Type Description
src string データを送信した Peer の ID です。
data * 受信したデータです。
room.on("data", ({ src, data }) => {
  // ...
});

# Event: 'close'

現在のルームから自分が退室したときに発生します。

room.on("close", () => {
  // ...
});

# SFURoom

SFU 接続でのルームを管理するクラスです。

SDK 内部の利用のみで、コンストラクタは通常利用しません。 SFURoom のインスタンスは、Peer#joinRoom() で生成されます。

# Sample

const sfuRoom = peer.joinRoom("roomName", {
  mode: "sfu",
  stream: localStream,
});
sfuRoom.on("open", () => {});

# Members

Name Type Description
name string ルーム名です。
remoteStreams Object MediaStream.id をキーに、ルーム内のストリームを保持するオブジェクトです。
members string[] ルーム内に参加している Peer ID の配列です。

# Methods

# close()

ルームを退出し、SFU サーバーとのコネクションを切断します。

# Return value

undefined

# getLog()

シグナリングサーバにルームのログ取得を要求します。 シグナリングサーバからログを受信すると、logイベントが発火します。

# Return value

undefined

# Sample
room.once("log", (log) => {
  // ...
});
room.getLog();

# replaceStream(stream)

送信中の MediaStream を変更します。 例えば、カメラ・マイクデバイスの変更や、画質や音質の変更などに用います。

注意

MediaStream を送信しない状態から送信する状態に変更することはできません。その逆の変更もできません。

また、「映像か音声のどちらかのみを持つ MediaStream」と「映像・音声の両方を持つ MediaStream」を入れ替えることはできません。

# Parameters
Name Type Required Default Description
stream MediaStream 更新対象となる新しい MediaStream です。
# Return value

undefined

# send(data)

WebSocket を使用してルーム内の全てのユーザーにデータを送信します。

注意

  • 送信可能なデータサイズの上限は 20MB です。

  • 送信頻度は 100msec に 1 回に制限されています。 送信頻度の制限を超えた送信データはキューに入り、100msec 毎に順次送信されます。

# Parameters
Name Type Required Default Description
data * 送信するデータです。
# Return value

undefined

# getPeerConnection()

自身のPeerとSFUサーバとの間のRTCPeerConnectionを取得します。

# Return value

RTCPeerConnectionのインスタンス または null

# Events

# Event: 'open'

新規に Peer がルームへ入室したときに発生します。

room.on("open", () => {
  // ...
});

# Event: 'peerJoin'

ルームに新しい Peer が参加したときに発生します。

Name Type Description
peerId string 参加した Peer の ID です。
room.on("peerJoin", (peerId) => {
  // ...
});

# Event: 'peerLeave'

新規に Peer がルームを退出したときに発生します。

Name Type Description
peerId string 退出した Peer の ID です。
room.on("peerLeave", (peerId) => {
  // ...
});

# Event: 'log'

ルームのログを受信したときに発生します。

Name Type Description
logs string[] ログ(JSON 文字列)の配列です。
room.once("log", (logs) => {
  for (const logStr of logs) {
    const { messageType, message, timestamp } = JSON.parse(logStr);
    // ...
  }
});

# Event: 'stream'

ルームに Join している他のユーザのストリームを受信した時に発生します。 ストリーム送信元の Peer ID はstream.peerIdで取得できます。

Name Type Description
stream MediaStream MediaStream のインスタンスです。
room.on("stream", (stream) => {
  // ...
});

# Event: 'data'

他のユーザーから送信されたデータを受信した時に発生します。

Name Type Description
data object data object形式のオブジェクトです。
# data object
Name Type Description
src string データを送信した Peer の ID です。
data * 受信したデータです。
room.on("data", ({ src, data }) => {
  // ...
});

# Event: 'close'

現在のルームから自分が退室したとき、および SFU サーバーから切断されたときに発生します。

room.on("close", () => {
  // ...
});

# TIPS

WARNING

このページの内容はその動作を保証するものではありません。ブラウザの実装によっては動作しない・挙動が異なるなどの可能性があります。

# MediaStream の取得

Peer#call()Peer#joinRoom()には、引数としてMediaStreamを渡せますが、SkyWay ではそのMediaStreamの取得方法を規定していません。

一般的な JavaScript の API では、次の方法で取得できます。

  • navigator.mediaDevices.getUserMedia(options)
  • navigator.mediaDevices.getDisplayMedia(options)
(async function() {
  // ..

  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const call = peer.call("remote-peerId", stream);

  // ...
})();

指定できるoptionsの詳細・挙動については、各ブラウザの実装状況に依存します。

そのほか、HTMLVideoElementHTMLAudioElement、およびHTMLCanvasElementcaptureStream()からも取得できます。

# 画面共有

端末の画面自体をMediaStreamとして取得することができます。

取得したMediaStreamを使うことで、画面共有機能が実現できます。

(async function() {
  // ..

  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const call = peer.call("remote-peerId", stream);

  // ...
})();

# 使用するデバイスの選択

端末に複数の USB カメラ・マイクが接続されている場合、それらを選択して使用できます。

(async function() {
  // ..

  const defaultVideoStream = await navigator.mediaDevices.getUserMedia({
    video: true,
  });

  // デバイスの一覧を取得
  const devices = await navigator.mediaDevices.enumerateDevices();

  // 任意のデバイスを指定
  const newVideoInputDevice = devices.find(
    (device) => device.kind === "videoinput"
  );
  const newVideoStream = await navigator.mediaDevices.getUserMedia({
    video: {
      deviceId: newVideoInputDevice.deviceId,
    },
  });

  // ...
})();

navigator.mediaDevices.enumerateDevices()を使うことで、利用可能なデバイスの一覧を取得できます。 その中から任意のデバイスを参照し、そのdeviceIdgetUserMedia()に渡すことで、入力ソースを指定できます。

# MediaStreamをミュートする

一時的に動画や音声をミュートしたい場合は、MediaStreamTrackenabledプロパティを設定することで実現できます。

(async function() {
  // ..

  const stream = await navigator.mediaDevices.getUserMedia({
    video: true,
    audio: true,
  });
  const call = peer.call("remote-peerId", stream);

  // 音声のみミュート
  stream.getAudioTracks().forEach((track) => (track.enabled = false));

  // ...
})();

# マルチストリーム

複数のMediaStreamを送りたい場合についてです。

現状、SkyWay では SDK としてマルチストリームの機能を提供していません。

アプリケーション側で、MediaConnectionを複数用意するなど、実現することはできます。

# sdpSemantics

Peerクラスのコンストラクタ引数として、RTCPeerConnectionのコンストラクタに渡されるRTCConfigurationを指定できます。

Chrome ではsdpSemanticsというプロパティを指定できますが、SkyWay では常にunified-planを使用します。

# 統計情報の取得

RTCPeerConnectiongetStats()を用いることで、送受信データ量やパケットロス率などの各種統計情報を取得することが可能です。

参考:MDN RTCPeerConnection.getStats()

RTCPeerConnectionは以下の方法で取得できます。

  • MediaConnectionクラスのgetPeerConnection()メソッド
  • MeshRoomクラスのgetPeerConnections()メソッド
  • SFURoomクラスのgetPeerConnection()メソッド