ewents-rtc

This document explains how to integrate and use the ewents-rtc library in your projects. ewents-rtc is a library that enables peer-to-peer communication, allowing you to send information from one end to another. From here on, we will refer to the two ends as Peer1 and Peer2 to describe both parties.

Demo: https://demo-rtc.ewents.io/

Demo code: https://github.com/TomasFleitas/rtc-example

NPM

To install the library using npm, run the following command in your terminal:

npm install ewents-rtc

Uso

To start using the library after installing it, you need to import it into your projects as follows:

import WebRTC from 'ewents-rtc';

Generate an instance for each peer you want to communicate with (keep in mind that if the user is communicating with N other users, you need to create 1 pair of peers for each user, meaning USERS = PEERS amount).

Example:

CurrentUser needs to connect with User1, User2, and User3. | Peer1 | Peer2 | |--------|--------| |CurrentUser|User1| |CurrentUser|User2| |CurrentUser|User3|

Initialization. (Peer1)

const webRTC = new WebRTC({
  peerId: peer1-id, // Unique identifier of current peer (Peer1) (optional)
  isSecure: true // if is true, the method startConnection will return a unique secure code to connect with the other peer (optional)
  clientKey: '66760d2b14813c0e8b53b4ff', // Default client key (it will be deleted in the future). (Mandatory)
  isLog: true, // Allows internal logs to be printed for debugging and monitoring. (optional)
  closeConnectionTimeout: 60000 // Close connection timeout in ms, max 60000 ms (1min) (optional)
  onReceiveData: (data) => {}, // Data from Peer2 (optional)
  onReceiveFile: ({ fileName, percentage, file }) => {}, // File from Peer2 (optional)
  onCommunicationState: (state) => {}, // Connection state from Peer2: can be 'none' (no connection), 'connecting' (waiting to connect), 'weak' (text only, no file or video), or 'full' (allows text, file, and video). (optional)
  onReceiveMediaStream: (stream) => {}, // Media streem from Peer2 (optional)
});

Starts a connection with Peer2. You can use `await` to retrieve the secure code if `isSecure` is set to `true` or you can pass a callback function as part of the `opts` object. The `opts` object allows you to configure various connection options, including:

- callback: (optional) A function that will be invoked once the secure code is generated, if `isSecure` is true. The function should accept a single argument `secureCode`.

- secureCode: (optional) A pre-generated secure code that will be used during the connection setup, if `isSecure` is true.

- peerId: (optional) The ID of the current peer initiating the connection.

- isSecure: (optional) A boolean flag indicating whether the connection should be secured with a secure code. When `true`, the secure code will be generated and returned.

- isLog: (optional) A boolean flag indicating whether to log the connection process for debugging purposes.

- closeConnectionTimeout: (optional) A number close connection timeout in ms.


const secureCode = await webRTC.startConnection(peer2Id, {
    callback: (secureCode?: string) => void,
    secureCode: secureCodeFrom,
    peerId: peer-id,
    isSecure: true,
    closeConnectionTimeout: 60000,
    isLog: true,
});

Initialization. (Peer2)

Same as Peer1, but you should change the peerId and the id that you pass to the startConnection method as shown below:

const webRTC = new WebRTC({
  peerId: peer2-id, // Unique identifier of current peer (Peer2)
  clientKey: '66760d2b14813c0e8b53b4ff', // Default client key (it will be deleted in the future).
  secureCode: "unique-code" // You can pass the value generated by the other peer either in the constructor or as an optional second parameter in the startConnection method.
  ... // same as Peer1
});
webRTC.startConnection(peer1Id, { secureCode: "unique-code" }); // Start connection with Peer1, optionally passing a secure code for validation.

Callbacks in another way (using the instance).

webRTC.onReceiveData((data) => {}); // Data from Peer2
webRTC.onReceivedFile(({ fileName, percentage, file }) => {}); // File from Peer2
webRTC.onCommunicationState((state) => {}); // Connection state from Peer2: can be 'none' (no connection), 'connecting' (waiting to connect), 'weak' (text only, no file or video), or 'full' (allows text, file, and video).
webRTC.onReceiveMediaStream((stream) => {}); // Media streem from Peer2

Interact with Peer2.

• sendData.

This method allows you to send data to Peer2.

webRTC.sendData(any); // Send any data.

You can add a callback as the second parameter in the sendData method to know the time in milliseconds when Peer2 receives the data.

webRTC.sendData(any, ({ ms }) => {}); // Send any data.

Additionally, if you use the await keyword with the sendData method, you will also get the time in milliseconds when Peer2 receives the data.

const { ms } = await webRTC.sendData(any); // Send any data.

• sendFile

This method allows you to send file data to Peer2.

webRTC.sendFile(File); // Send File object (directly from an input type="file")

You can add a callback as the second parameter in the sendFile method to receive multiple callbacks indicating the percentage of the file transfer, from 0 to 100%.

webRTC.sendFile(any, ({ percentage }) => {});

• setMediaTracks

The setMediaTracks method sets the audio and video tracks for peer-to-peer connection, following the below example:

webRTC.setMediaTracks({ audioTrack, videoTrack }, stream);

const startCall = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: true,
    audio: true,
  });
  const videoTrack = stream.getVideoTracks()[0];
  const audioTrack = stream.getAudioTracks()[0];
  webRTC.setMediaTracks({ audioTrack, videoTrack }, stream);
};

Then you can remove tracks using:

webRTC.removeMediaTrack('audio');
webRTC.removeMediaTrack('video');

or get tracks:

webRTC.getMediaTrack('audio');
webRTC.getMediaTrack('video');

• closeConnection

This method just closes the connection between peers.

webRTC.closeConnection();

• Miscellaneous methods:

webRTC.getChannelId(); // Retrieve the unique identifier of the peer connection
webRTC.peerType(); // Retrieve the peer type ('unknown' | 'answerer' | 'offerer')
webRTC.isConnected(); // true or false

Deprecated

⚠️ DEPRECATED: This method is no longer recommended for use.

Please use the onCommunicationState() instead of onConnectionStateChange(). The onCommunicationState() will be removed in a future release.