# 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	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	Description
peerId	string	✔	接続先の Peer ID です。
stream	MediaStream		接続先の Peer へ送るメディアストリームです。設定されていない場合は、受信のみモードで発信します。
options	call options object		発信時に付与するオプションです。帯域幅・コーデックなどを指定します。

# call options object

Name	Type	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	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	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() およびPeerのcallイベントで生成されます。

# 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	コネクションがオープンしているかどうかを示します。`MediaConnection`の`stream`イベントまたは `MediaConnection#answer()` が呼び出された際にオープンし、 `MediaConnection#close()`が呼び出されたまたは`MediaConnection`の`close`イベントが発生した際にクローズします。
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	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() およびPeerのconnectionイベントで生成されます。

# 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	コネクションがオープンしているかどうかを示します。`DataConnection`の`open`イベントが発生した際にオープンし、`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の詳細・挙動については、各ブラウザの実装状況に依存します。

そのほか、HTMLVideoElementやHTMLAudioElement、およびHTMLCanvasElementの captureStream()からも取得できます。

# 画面共有

端末の画面自体を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()を使うことで、利用可能なデバイスの一覧を取得できます。その中から任意のデバイスを参照し、そのdeviceIdをgetUserMedia()に渡すことで、入力ソースを指定できます。

# `MediaStream`をミュートする

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

(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を使用します。

# `統計情報の取得`

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

参考：MDN RTCPeerConnection.getStats()

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

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

← 管理API iOS SDK →

# JavaScript SDK

# はじめに

# クラス一覧

# EventEmitterについて

# Peer

# Constructor(id, options)

# Constructor(options)

# Sample

# Parameter

# options object

# credential object

# Default RTCConfiguration object

# Members

# Methods

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

# Parameters

# call options object

# Return value

# Sample

# connect(peerId[, options])

# Parameters

# connect options object

# Return value

# Sample

# destroy()

# Return value

# disconnect()

# Return value

# reconnect()

# Return value

# joinRoom(roomName[, roomOptions])

# Parameters

# room options object

# Return value

# Sample

# fetchPeerExists(peerId)

# Parameters

# Return value

# Sample

# listAllPeers(callback)

# Parameters

# Return value

# Sample

# getConnection(peerId, connectionId)

# Parameters

# Return value

# updateCredential(credential)

# Parameters

# Return value

# Events

# Event: 'open'

# Event: 'call'

# Event: 'close'

# Event: 'connection'

# Event: 'disconnected'

# Event: 'expiresin'

# Event: 'error'

# MediaConnection

# Sample

# Members

# Methods

# answer(stream[, options])

# Parameters

# answer options object

# Return value

# Sample

# close(forceClose)

# Parameters

# Return value

# replaceStream(stream)

# Parameters

# Return value

# getPeerConnection()

# Return value

# Sample

# Events

# Event: 'stream'

# Event: 'close'

# DataConnection

# Sample

# `EventEmitter`について

# `Constructor(id, options)`

# `Constructor(options)`

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

# `connect(peerId[, options])`

# `destroy()`

# `disconnect()`

# `reconnect()`

# `joinRoom(roomName[, roomOptions])`

# `fetchPeerExists(peerId)`

# `listAllPeers(callback)`

# `getConnection(peerId, connectionId)`

# `updateCredential(credential)`

# Event: `'open'`

# Event: `'call'`

# Event: `'close'`

# Event: `'connection'`

# Event: `'disconnected'`

# Event: `'expiresin'`

# Event: `'error'`

# `answer(stream[, options])`

# `close(forceClose)`

# `replaceStream(stream)`

# `getPeerConnection()`

# Event: `'stream'`

# Event: `'close'`

# `send(data)`

# `getPeerConnection()`

# `close(forceClose)`

# Event: `'open'`

# Event: `'data'`

# Event: `'close'`

# Event: `'error'`

# `close()`

# `getLog()`

# `replaceStream(stream)`

# `send(data)`

# `getPeerConnections()`

# Event: `'open'`

# Event: `'peerJoin'`

# Event: `'peerLeave'`

# Event: `'log'`

# Event: `'stream'`

# Event: `'data'`

# Event: `'close'`

# `close()`

# `getLog()`

# `replaceStream(stream)`

# `send(data)`

# `getPeerConnection()`

# Event: `'open'`

# Event: `'peerJoin'`

# Event: `'peerLeave'`

# Event: `'log'`

# Event: `'stream'`

# Event: `'data'`

# Event: `'close'`