Amazon Kinesis Video Streams WebRTC SDK for JavaScript

What is Amazon Kinesis Video Streams with WebRTC?

Amazon Kinesis Video Streams provides a standards-compliant WebRTC implementation as a fully managed capability. You can use Amazon Kinesis Video Streams with WebRTC to securely live stream media or perform two-way audio or video interaction between any camera IoT device and WebRTC-compliant mobile or web players. As a fully managed capability, you don't have to build, operate, or scale any WebRTC-related cloud infrastructure, such as signaling or media relay servers to securely stream media across applications and devices.

For more information about Amazon Kinesis Video Streams with WebRTC, check out the documentation.

This SDK is intended to be used along side the AWS SDK for JS (version 2.585.0+) to interface with the Amazon Kinesis Video Streams Signaling Service for WebRTC streaming.

Note: If you are looking to stream media from a Kinesis Video Stream (different from a Kinesis Video Streams Signaling Channel), check out the Kinesis Video Streams web media viewer.

Installing

In the Browser

To use the SDK in the browser, simply add the following script tag to your HTML pages:

<script src="https://unpkg.com/amazon-kinesis-video-streams-webrtc/dist/kvs-webrtc.min.js"></script>

The SDK classes are made available in the global window under the KVSWebRTC namespace. For example, window.KVSWebRTC.SignalingClient.

The SDK is also compatible with bundlers like Webpack. Follow the instructions in the next section to install the NodeJS module version for use with your bundler.

In NodeJS

The preferred way to install the SDK for NodeJS is to use the npm package manager. Simply type the following into a terminal window:

npm install amazon-kinesis-video-streams-webrtc

The SDK classes can then be imported like typical NodeJS modules:

// JavaScript
const SignalingClient = require('amazon-kinesis-video-streams-webrtc').SignalingClient;

// TypeScript / ES6 supported
import { SignalingClient } from 'amazon-kinesis-video-streams-webrtc';

Getting Started

You can start by trying out the SDK with a webcam on the example WebRTC test page.

It is also recommended to develop familiarity with the WebRTC protocols and KVS Signaling Channel APIs. See the following resources: * KVS WebRTC Developer Guide * KVS API Reference Guide

The first step in using the SDK in your own application is to follow the Installing instructions above to install the SDK.

From there, see the Usage section below for guidance on using the SDK to build a WebRTC application. Also refer to the examples directory for examples on how to write an end-to-end WebRTC application that uses the SDK.

Usage

This section demonstrates how to use this SDK along with the AWS SDK for JS (version 2.585.0+) to build a web-based viewer application. Refer to the examples directory for an example of a complete application including both a master and viewer role.

Note:

Codecs can be filtered in the sample application to selectively enable support for specific camera capabilities (e.g. H264 or H265).

Viewer Example With Audio/Video From Local Webcam

These code snippets demonstrate how to build a viewer application that receives audio and video and also sends audio and video from a webcam back to the master.

Set Up Variables

// DescribeSignalingChannel API can also be used to get the ARN from a channel name.
const channelARN = 'arn:aws:kinesisvideo:us-west-2:123456789012:channel/test-channel/1234567890';

// AWS Credentials
const accessKeyId = 'ACCESS_KEY_ID_GOES_HERE';
const secretAccessKey = 'SECRET_ACCESS_KEY_GOES_HERE';

// <video> HTML elements to use to display the local webcam stream and remote stream from the master
const localView = document.getElementsByTagName('video')[0];
const remoteView = document.getElementsByTagName('video')[1];

const region = 'us-west-2';
const clientId = 'RANDOM_VALUE';

See Managing Credentials for more information about managing credentials in a web environment.

Create KVS Client

const kinesisVideoClient = new AWS.KinesisVideo({
    region,
    accessKeyId,
    secretAccessKey,
    correctClockSkew: true,
});

Get Signaling Channel Endpoints

Each signaling channel is assigned an HTTPS and WSS endpoint to connect to for data-plane operations. These can be discovered using the GetSignalingChannelEndpoint API.

const getSignalingChannelEndpointResponse = await kinesisVideoClient
    .getSignalingChannelEndpoint({
        ChannelARN: channelARN,
        SingleMasterChannelEndpointConfiguration: {
            Protocols: ['WSS', 'HTTPS'],
            Role: KVSWebRTC.Role.VIEWER,
        },
    })
    .promise();
const endpointsByProtocol = getSignalingChannelEndpointResponse.ResourceEndpointList.reduce((endpoints, endpoint) => {
    endpoints[endpoint.Protocol] = endpoint.ResourceEndpoint;
    return endpoints;
}, {});

Create KVS Signaling Client

The HTTPS endpoint from the GetSignalingChannelEndpoint response is used with this client. This client is just used for getting ICE servers, not for actual signaling.

const kinesisVideoSignalingChannelsClient = new AWS.KinesisVideoSignalingChannels({
    region,
    accessKeyId,
    secretAccessKey,
    endpoint: endpointsByProtocol.HTTPS,
    correctClockSkew: true,
});

Get ICE server configuration

For best performance, we collect STUN and TURN ICE server configurations. The KVS STUN endpoint is always stun:stun.kinesisvideo.${region}.amazonaws.com:443 for legacy-IPv4 endpoint mode and stun:stun.kinesisvideo.${region}.api.aws:443 for dual-stack endpoint mode. To get TURN servers, the GetIceServerConfig API is used.

const getIceServerConfigResponse = await kinesisVideoSignalingChannelsClient
    .getIceServerConfig({
        ChannelARN: channelARN,
    })
    .promise();
const iceServers = [
    { urls: `stun:stun.kinesisvideo.${region}.amazonaws.com:443` }
];
getIceServerConfigResponse.IceServerList.forEach(iceServer =>
    iceServers.push({
        urls: iceServer.Uris,
        username: iceServer.Username,
        credential: iceServer.Password,
    }),
);

Create RTCPeerConnection

The RTCPeerConnection is the primary interface for WebRTC communications in the Web.

const peerConnection = new RTCPeerConnection({ iceServers });

Create WebRTC Signaling Client

This is the actual client that is used to send messages over the signaling channel.

signalingClient = new KVSWebRTC.SignalingClient({
    channelARN,
    channelEndpoint: endpointsByProtocol.WSS,
    clientId,
    role: KVSWebRTC.Role.VIEWER,
    region,
    credentials: {
        accessKeyId,
        secretAccessKey,
    },
    systemClockOffset: kinesisVideoClient.config.systemClockOffset,
});

Add Signaling Client Event Listeners

// Once the signaling channel connection is open, connect to the webcam and create an offer to send to the master
signalingClient.on('open', async () => {
    // Get a stream from the webcam, add it to the peer connection, and display it in the local view
    try {
        const localStream = await navigator.mediaDevices.getUserMedia({
            video: { width: { ideal: 1280 }, height: { ideal: 720 } },
            audio: true,
        });
        localStream.getTracks().forEach(track => peerConnection.addTrack(track, localStream));
        localView.srcObject = localStream;
    } catch (e) {
        // Could not find webcam
        return;
    }

    // Create an SDP offer and send it to the master
    // If there is no concern about browser compatibility, using `addTransceiver` would be better
    const offer = await viewer.peerConnection.createOffer({
        offerToReceiveAudio: true,
        offerToReceiveVideo: true,
    });
    await peerConnection.setLocalDescription(offer);
    signalingClient.sendSdpOffer(viewer.peerConnection.localDescription);
});

// When the SDP answer is received back from the master, add it to the peer connection.
signalingClient.on('sdpAnswer', async answer => {
    await peerConnection.setRemoteDescription(answer);
});

// When an ICE candidate is received from the master, add it to the peer connection.
signalingClient.on('iceCandidate', candidate => {
    peerConnection.addIceCandidate(candidate);
});

signalingClient.on('close', () => {
    // Handle client closures
});

signalingClient.on('error', error => {
    // Handle client errors
});

Add Peer Connection Event Listeners

// Send any ICE candidates generated by the peer connection to the other peer
peerConnection.addEventListener('icecandidate', ({ candidate }) => {
    if (candidate) {
        signalingClient.sendIceCandidate(candidate);
    } else {
        // No more ICE candidates will be generated
    }
});

// As remote tracks are received, add them to the remote view
peerConnection.addEventListener('track', event => {
    if (remoteView.srcObject) {
        return;
    }
    remoteView.srcObject = event.streams[0];
});

Open Signaling Connection

signalingClient.open();

Documentation

This section outlines all of the classes, events, methods, and configuration options for the SDK.

Class: SignalingClient

This class is the main class for interfacing with the KVS signaling service. It extends EventEmitter.

Constructor: new SignalingClient(config)

• config {object}
• role {Role} "MASTER" or "VIEWER".
• channelARN {string} ARN of a channel that exists in the AWS account.
• channelEndpoint {string} KVS Signaling Service endpoint. Should be the "WSS" endpoint from calling the GetSignalingChannel API.
• region {string} AWS region that the channel exists in.
• clientId {string} Identifier to uniquely identify this client when connecting to the KVS Signaling Service. Required if the role is "VIEWER". A value should not be provided if the role is "MASTER".
• credentials {object} Must be provided unless a requestSigner is provided. See Managing Credentials.
  • accessKeyId {string} AWS access key id.
  • secretAccessKey {string} AWS secret access key.
  • sessionToken {string} Optional. AWS session token.
• requestSigner {RequestSigner} Optional. A custom method for overriding the default SigV4 request signing.
• systemClockOffset {number} Optional. Applies the given offset when setting the date in the SigV4 signature. See systemClockOffset and correctClockSkew properties of the AWS SDK.
• enableEarlyIceCandidateBuffering {boolean} Optional. Default: false. When true, ICE candidates that arrive before the SDP offer/answer are buffered and not automatically emitted. The consumer must call drainPendingIceCandidates() after connecting this client's ice candidate listener to release the early ice candidates.
• logger {SignalingClientLogger} Optional. Logger object for diagnostic logging. If provided, the SDK logs ICE candidate buffering, draining, and SDP events through this logger. If not provided, no logging occurs. Pass console to log to the browser console, or provide a custom object with debug, log, and warn methods.

Event: 'open'

Emitted when the connection to the signaling service is open.

Event: 'sdpOffer'

• sdpOffer {RTCSessionDescription} The SDP offer received from the signaling service.
• senderClientId {string} The client id of the source of the SDP offer. The value will be null if the SDP offer is from the master.

Emitted when a new SDP offer is received over the channel. Typically only a master should receive SDP offers.

Event: 'sdpAnswer'

• sdpAnswer {RTCSessionDescription} The SDP answer received from the signaling service.