PeerJS docsSkyWay対応版

PeerJSは、WebRTCを利用したピア·ツー·ピアのデータ、ビデオ、オーディオ通信を簡単に実現することができます。このドキュメントでは、PeerJS APIの基本的な使い方を紹介します。PeerJSを用いた実装例をご覧になりたい方は, サンプル ページを御覧ください。

このドキュメントは、NTTコミュニケーションズが提供するクラウドサービス「SkyWay」にて利用できるようにカスタマイズしたPeerJSを対象としています。

セットアップ

1. PeerJSのクライアントライブラリをインクルード

PeerJSクライアントライブラリをあなたのアプリケーションにインクルードしてください。

<script src="https://skyway.io/dist/0.3/peer.js"></script>

PeerJSライブラリ（peer.js, peer.min.js）はあなたのサーバ上に設置することができます。 ソースコードはGithubからforkする事ができます。

2. Peerオブジェクトを作成

Peerオブジェクトは、Peerコネクションを生成、受信する為に利用します。

var peer = new Peer({key: 'APIKEY'});

Peerのコンストラクタに渡す'APIKEY'は、SkyWayのAPIキーです。APIキーの申し込みを行うことで無料で取得することができます。APIキー申込時には利用ドメインを申請していただきます。APIキーは申請したドメインからのみ利用可能です。

PeerJSのセッション情報交換やシグナリングに利用するサーバを、自身で構築することもできます。 詳しくはpeerjs-serverをご覧ください。

これで利用するための準備はすべて整いました！

使い方

Peerオブジェクトは生成時、ランダムなID（以下、PeerID）が付与されます。

peer.on('open', function(id) {
  console.log('My peer ID is: ' + id);
});

他のPeerと接続したい場合は、接続先のPeerIDが必要になります。 RestAPIを利用して接続先のPeerIDを入手するか、何らかの仕組みでPeerIDを交換してください。Peer constructorのオプションに自身のPeerIDを指定すると、この処理を省略することができます。

その他のオプション、メソッド、イベント、エラー処理などの詳細は、Peer API リファレンスをお読みください。

Data connections

相手のPeerIDを指定してpeer.connectを実行するとData connectionを開始します。相手から接続要求はいつでもconnection イベントを利用して受け取ることができます。

var conn = peer.connect('dest-peer-id');

peer.on('connection', function(conn) { ... });

peer.connectとconnectionイベントのコールバックではDataConnectionオブジェクトを提供します。このオブジェクトを使用してデータの送受信を行うことができます。

conn.on('open', function() {
  // メッセージを受信
  conn.on('data', function(data) {
    console.log('Received', data);
  });

  // メッセージを送信
  conn.send('Hello!');
});

メソッドとイベントの詳細は、DataConnection API リファレンスをご覧ください。

Video/audio calls

相手のPeerIDを指定してpeer.callを実行することで、その相手を呼び出すことができます。相手があなたを呼び出した場合、 callイベントが発生します。

callイベントを受信した時は、必ずそのイベントに応答する必要があります。応答しなければ接続は確立しません。

// Call a peer, providing our mediaStream
var call = peer.call('dest-peer-id',
  mediaStream);

peer.on('call', function(call) {
  // Answer the call, providing our mediaStream
  call.answer(mediaStream);
});

相手を呼び出す時、または、呼び出しに応答する時には、MediaStreamを提供する必要があります。 MediaStreamにはビデオストリーム（ウェブカメラの映像）やオーディオストリームなどがあり、navigator.getUserMediaによって取得することができます。取得できる内容はブラウザによってことなります。 尚、呼び出しに応答する時のMediaStreamは必須ではありません。もし応答時にMediaStreamをセットしなければ、一方向の通話が確立されます。 通話が確立されると、openプロパティにtrueがセットされます。

peer.call と call イベントのコールバックではMediaConnectionオブジェクトを提供します。 MediaConnectionオブジェクトはstream イベントをキャッチすることができます。streamイベントのコールバックには相手の映像／音声ストリームが含まれます。

call.on('stream', function(stream) {
  // `stream` is the MediaStream of the remote peer.
  // Here you'd add it to an HTML video/canvas element.
});

詳しくは MediaConnection API reference をご覧ください。

SkyWay RestAPIの使い方

/active/list/

APIキー毎のアクティブなPeerIDを取得します。

  Request : https://skyway.io/active/list/APIKEY
  Response : [peerid1,peerid2,peerid3,peerid4,.....]

/active/count/

APIキー毎のアクティブなPeerIDの数を取得します。

  Request : https://skyway.io/active/count/APIKEY
  Response : {"name":"active_session","count":0,"api_key":"APIKEY"}

SkyWay WebAPIはAPIキー申請時に申請していただいたドメインからのみアクセスが可能です。

FAQ

どのような種類のデータを送ることができますか？

PeerJSは BinaryPackシリアライゼーションフォーマットを利用しています。JSONやバイナリBlobs、ArrayBuffersなど様々なデータを簡単な手順で送受信することができます。

conn.send({
  strings: 'hi!',
  numbers: 150,
  arrays: [1,2,3],
  evenBinary: new Blob([1,2,3]),
  andMore: {bool: true}
});

PeerJSを利用することができないシーンはありますか？

シンメトリックNATの内側にいるクライアント同士はNATを超えることができないため、通信することができません。 ただし、TURNサーバを利用して接続を中継すれば回避することができます。TURNサーバは提供していないため必要であれば別途用意してください。 TURNサーバの情報は、Peerオブジェクトのオプションで指定することができます。

TURNサーバはどのようにして利用するのでしょうか？

Peerオブジェクトを生成する際、オプションのiceServersにURL等の情報を設定してください。

var peer = new Peer({
  config: {'iceServers': [
    { url: 'stun:stun.skyway.io:3478' },
    { url: 'turn:homeo@turn.bistri.com:80', credential: 'homeo' }
  ]} /* Sample servers, please use appropriate ones */
});

現在のブラウザ対応状況は?

WebRTC仕様との互換性並びにブラウザの対応状況はこちらをご覧ください。尚、SkyWay対応版のPeerJSについては、動作に差異がある可能性があります。

接続しようとしてるピアに接続できない場合はどうなりますか？

ピアに接続できない場合はPeerServerにて接続要求を5秒間保持します。ピアが一時的に再接続するような場合、コネクションを切らずに保持することができます。尚、SkyWayは現時点ではこの機能に対応していません。

ピアとつながらない場合は何を確認するべきでしょうか？

ピア同士がシンメトリックNATの内側にいる可能性があります。この場合はTURNサーバを利用してください。

ファイアウォール等でUDPのポート3478（STUNサーバへの問い合わせに必要）をブロックしているかもしれません。STUNサーバへの問い合わせが可能な状況でご利用ください。

遅延／帯域幅は?

ピア同士のデータのやり取りはサーバを経由しないため、それが原因となる遅延などは発生しません。ピア同士の処理性能やネットワーク環境に依存します。

ピア同士のコネクション確立に関する遅延は、セッション情報の中継（以下、シグナリング）とユーザの識別という2つに分類できます。PeerJSでは、シグナリングの時間を短縮するために、XHRストリーミングリクエストでデータを送った後、WebSocketで送ります。ユーザの識別に関しては手動でIDを指定することで、サーバ側にてIDを生成する際のRTT（Round-Trip delay Time）を短縮することができます。尚、SkyWayに関してはXHRでの接続に現時点では対応していません。

その他

PeerJS Google Group(英語のみ)

免責事項

本ドキュメントはhttp://peerjs.com/docs/を元に、NTTコミュニケーションズが提供するSkyWayを利用するための情報等を追記し公開しています。ドキュメント原本に関する個別問い合わせには応じることができませんので、予めご了承ください。