# What is Amazon Kinesis Video Streams with WebRTC? WebRTC is an open technology specification for enabling real-time communication (RTC) across browsers and mobile applications via simple APIs. It uses peering techniques for real-time data exchange between connected peers and provides low latency media streaming required for human-to-human interaction. The WebRTC specification includes a set of IETF protocols including [Interactive Connectivity Establishment](https://www.ietf.org/rfc/rfc5245.txt), [Traversal Using Relay around NAT (TURN)](https://tools.ietf.org/html/rfc5766), and [Session Traversal Utilities for NAT (STUN)](https://www.ietf.org/rfc/rfc5389.txt) for establishing peer-to-peer connectivity, in addition to protocol specifications for reliable and secure real-time media and data streaming. [Amazon Kinesis Video Streams](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/what-is-kinesis-video.html) 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. Using Kinesis Video Streams with WebRTC, you can easily build applications for live peer-to-peer media streaming, or real-time audio or video interactivity between camera IoT devices, web browsers, and mobile devices for a variety of use cases. Such applications can help parents keep an eye on their baby’s room, enable homeowners to use a video doorbell to check who’s at the door, enable owners of camera-enabled robot vacuums to remotely control the robot by viewing the live camera stream on a mobile phone, and so on. If you're a first-time user of Kinesis Video Streams with WebRTC, we recommend that you read the following sections: + [How it works](kvswebrtc-how-it-works.md) + [Amazon Kinesis Video Streams with WebRTC SDK in C for embedded devices](kvswebrtc-sdk-c.md) + [Amazon Kinesis Video Streams with WebRTC SDK in JavaScript for web applications](kvswebrtc-sdk-js.md) + [Amazon Kinesis Video Streams WebRTC SDK for Android](kvswebrtc-sdk-android.md) + [Amazon Kinesis Video Streams WebRTC SDK for iOS](kvswebrtc-sdk-ios.md) + [Control plane APIs](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_Operations_Amazon_Kinesis_Video_Streams.html) + [Data plane REST APIs](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_Operations_Amazon_Kinesis_Video_Signaling_Channels.html) + [Data plane Websocket APIs](https://docs.aws.amazon.com//kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-websocket-apis.html) # Region availability **Note** Amazon Kinesis Video Streams with WebRTC is not yet supported in the AWS GovCloud (US) Region. Amazon Kinesis Video Streams with WebRTC is available in the following regions: **** | Region Name | AWS Region Code | | --- | --- | | US East (Ohio) | us-east-2 | | US East (N. Virginia) | us-east-1 | | US West (Oregon) | us-west-2 | | Africa (Cape Town) | af-south-1 | | Asia Pacific (Hong Kong) | ap-east-1 | | Asia Pacific (Mumbai) | ap-south-1 | | Asia Pacific (Seoul) | ap-northeast-2 | | Asia Pacific (Singapore) | ap-southeast-1 | | Asia Pacific (Sydney) | ap-southeast-2 | | Asia Pacific (Malaysia) | ap-southeast-5 | | Asia Pacific (Tokyo) | ap-northeast-1 | | Canada (Central) | ca-central-1 | | Europe (Frankfurt) | eu-central-1 | | Europe (Ireland) | eu-west-1 | | Europe (London) | eu-west-2 | | Europe (Paris) | eu-west-3 | | Europe (Spain) | eu-south-2 | | South America (Sao Paulo) | sa-east-1 | | Middle East (Bahrain) | me-south-1 | # How it works Amazon Kinesis Video Streams with WebRTC enables real-time video communication between web browsers, mobile devices, and other WebRTC-enabled applications. It provides a secure and scalable infrastructure for building video streaming applications, handling tasks such as signaling, media streaming, and integration with other AWS services. This section explains the underlying architecture, components, and workflows of the service, helping explain its design principles and mechanisms. **Topics** + [ ## Key concepts ](#how-kvswebrtc-concepts) + [ ## Technology concepts ](#how-webrtc-concepts) + [ ## How STUN, TURN and ICE work together ](#how-webrtc-components-interwork) + [ ## Components ](#how-kvswebrtc-works) ## Key concepts The following are key terms and concepts specific to the Amazon Kinesis Video Streams with WebRTC. **Signaling channel** A resource that enables applications to discover, set up, control, and terminate a peer-to-peer connection by exchanging signaling messages. Signaling messages are metadata that two applications exchange with each other to establish peer-to-peer connectivity. This metadata includes local media information, such as media codecs and codec parameters, and possible network candidate paths for the two applications to connect with each other for live streaming. Streaming applications can maintain persistent connectivity with a signaling channel and wait for other applications to connect to them. Or, they can connect to a signaling channel only when they need to live stream media. A signaling channel enables applications to connect with each other in a one-to-few model, using the concept of one master connecting to multiple viewers. The application that initiates the connection assumes the responsibility of a master using the `ConnectAsMaster` API and waits for viewers. Up to 10 applications can then connect to that signaling channel by assuming the viewer responsibility by invoking the `ConnectAsViewer` API. After they're connected to a signaling channel, the master and viewer applications can send each other signaling messages to establish peer-to-peer connectivity for live media streaming. **Peer** Any device or application (for example, a mobile or web application, web cam, home security camera, baby monitor, etc.) that is configured for real-time, two-way streaming through a Kinesis Video Streams with WebRTC. **Master** A peer that initiates the connection and is connected to the signaling channel with the ability to discover and exchange media with any of the signaling channel's connected viewers. Currently, a signaling channel can only have one master. **Viewer** A peer that is connected to the signaling channel with the ability to discover and exchange media only with the signaling channel's master. A viewer cannot discover or interact with other viewers through a given signaling channel. A signaling channel can have up to 10 connected viewers. ## Technology concepts As you get started with Kinesis Video Streams with WebRTC, you can also benefit from learning about several interrelated protocols and APIs of which the WebRTC technology consists. **Session Traversal Utilities for NAT (STUN)** A protocol that is used to discover your public address and determine any restrictions in your router that would prevent a direct connection with a peer. **Traversal Using Relays around NAT (TURN)** A server that is used to bypass the Symmetric NAT restriction by opening a connection with a TURN server and relaying all information through that server. **Session Description Protocol (SDP)** A standard for describing the multimedia content of the connection such as resolution, formats, codecs, encryption, etc. so that both peers can understand each other once the data is transferring. **SDP Offer** An SDP message sent by an agent which generates a session description in order to create or modify a session. It describes the aspects of desired media communication. **SDP Answer** An SDP message sent by an answerer in response to an offer received from an offerer. The answer indicates the aspects that are accepted. For example, if all the audio and video streams in the offer are accepted. **Interactive Connectivity Establishment (ICE)** A framework that allows your web browser to connect with peers. **ICE Candidate** A method that the sending peer is able to use to communicate. ## How STUN, TURN and ICE work together Let's take the scenario of two peers, A and B, who are both using a WebRTC peer to peer two way media streaming (for example, a video chat application). What happens when A wants to call B? To connect to B's application, A's application must generate an SDP offer. An SDP offer contains information about the session A's application wants to establish, including what codecs to use, whether this is an audio or video session, etc. It also contains a list of ICE candidates, which are the IP and port pairs that B's application can attempt to use to connect to A. To build the list of ICE candidates, A's application makes a series of requests to a STUN server. The server returns the public IP address and port pair that originated the request. A's application adds each pair to the list of ICE candidates, in other words, it gathers ICE candidates. Once A's application has finished gathering ICE candidates, it can return an SDP. Next, A's application must pass the SDP to B's application through a signaling channel over which these applications communicate. The transport protocol for this exchange is not specified in the WebRTC standard. It can be performed over HTTPS, secure WebSocket, or any other communication protocol. Now, B's application must generate an SDP answer. B's application follows the same steps A used in the previous step: gathers ICE candidates, etc. B's application then needs to return this SDP answer to A's application. After A and B have exchanged SDPs, they then perform a series of connectivity checks. The ICE algorithm in each application takes a candidate IP/port pair from the list it received in the other party's SDP, and sends it a STUN request. If a response comes back from the other application, the originating application considers the check successful and marks that IP/port pair as a valid ICE candidate. After connectivity checks are finished on all of the IP/port pairs, the applications negotiate and decide to use one of the remaining, valid pairs. When a pair is selected, media begins flowing between the application. If either of the applications can't find an IP/port pair that passes connectivity checks, they'll make STUN requests to the TURN server to obtain a media relay address. A relay address is a public IP address and port that forwards packets received to and from the application to set up the relay address. This relay address is then added to the candidate list and exchanged via the signaling channel. ## Components Kinesis Video Streams with WebRTC includes the following components: + **Control plane** The control plane component is responsible for creating and maintaining the Kinesis Video Streams with WebRTC signaling channels. For more information, see the [Amazon Kinesis Video Streams API Reference](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_Operations_Amazon_Kinesis_Video_Streams.html). + **Signaling** The signaling component manages the WebRTC signaling endpoints that allow applications to securely connect with each other for peer-to-peer live media streaming. The signaling component includes the [Amazon Kinesis Video Signaling REST APIs](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_Operations_Amazon_Kinesis_Video_Signaling_Channels.html) and a set of [Websocket APIs](https://docs.aws.amazon.com//kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-websocket-apis.html). + **STUN** This component manages STUN endpoints that enable applications to discover their public IP address when they are located behind a NAT or a firewall. + **TURN** This component manages TURN endpoints that enable media relay via the cloud when applications can't stream media peer-to-peer. + **Kinesis Video Streams WebRTC SDKs** These are software libraries that you can download, install, and configure on your devices and application clients to enable your camera IoT devices with WebRTC capabilities to engage in low latency peer-to-peer media streaming. These SDKs also enable Android, iOS, and web application clients to integrate Kinesis Video Streams with WebRTC signaling, TURN, and STUN capabilities with any WebRTC-compliant mobile or web players. + [Amazon Kinesis Video Streams with WebRTC SDK in C for embedded devices](kvswebrtc-sdk-c.md) + [Amazon Kinesis Video Streams with WebRTC SDK in JavaScript for web applications](kvswebrtc-sdk-js.md) + [Amazon Kinesis Video Streams WebRTC SDK for Android](kvswebrtc-sdk-android.md) + [Amazon Kinesis Video Streams WebRTC SDK for iOS](kvswebrtc-sdk-ios.md) # System requirements This section covers basic system requirements for using Amazon Kinesis Video Streams with WebRTC, including network requirements and environment. It also includes information about debugging connections. ## Networking requirements The general networking requirements for the signaling channel service endpoints for Kinesis Video Streams with WebRTC are: + HTTPS calls to endpoints hosted at `https://*.kinesisvideo.{region}.amazonaws.com` + WebSocket integrations with endpoints `wss://*.kinesisvideo.{region}.amazonaws.com` + `STUN` servers at `stun:stun.kinesisvideo.{aws-region}.amazonaws.com:443` + `TURN` servers at `turn:_._.kinesisvideo.{aws-region}.amazonaws.com:443` and `turns:_._.kinesisvideo.{aws-region}.amazonaws.com:443` **Note** IPv6 addresses aren't currently supported for `STUN` and `TURN` servers. The protocols used between peers as part of the RTCPeerConnection can be either TCP or UDP based. Most applications attempt to establish direct, peer-to-peer connections by determining the IP addresses for each peer, as well as the ports and protocols to be exchanged as ICE candidates. These candidates are used to attempt to connect to one another using these candidates. They will attempt each pair until a connection can be established. ## Network environment If a message from the viewer has been sent to the master and a log such as `No valid ICE candidate` is recorded, then no valid connection route has been found. This can happen if there is a firewall that prevents direct connection, or if the network is not reachable. Do the following to troubleshoot the connectivity issue: + If you're not using `TURN` on the master side, be sure to enable `TURN`. `TURN` is enabled by default in the C SDK. In the JavaScript SDK, select `STUN/TURN` or `TURN only` in NAT Traversal. + For restricted networks, such as an enterprise network, try other available networks (wired or wireless). If you're connecting to a VPN, disconnect from it. **Note** You can disregard 403 `Forbidden IP` errors returned by Kinesis Video Streams TURN servers. The servers reject ICE candidate pairs that contain `localhost` IPs, such as `192.168.*` or `10.0.0.*`. This may cause some, but not all, ICE candidate pairs to fail. ## Debugging ongoing connections There are a few areas that can cause issues with an established, ongoing WebRTC connection, but networking is the most common. You can confirm a VERBOSE level log from the SDK by setting `export AWS_KVS_LOG_LEVEL=1` as an environment variable. **Note** If no candidate pair is found within the allotted timeout, the ICE agent returns error status `0x5a00000d`. For additional information about log levels, see [GitHub](https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-c/blob/master/README.md#setup-desired-log-level). ``` export AWS_KVS_LOG_LEVEL=1 ./kvsWebrtcClientMasterGstSample TestChannel ``` You will see logs like the following. From these logs, you can confirm the Interactive Connectivity Establishment (ICE) candidate (IP address and port) and the selected candidate pair. ``` 2023-02-13 05:57:16 DEBUG iceAgentReadyStateSetup(): Selected pair w1UdV9fE+_/CuBel1pl, local candidate type: srflx. Round trip time 7 ms. Local candidate priority: 1694498815, ice candidate pair priority: 7240977859836116990 2023-02-13 05:57:16 INFO onConnectionStateChange(): New connection state 3 2023-02-13 05:57:16 DEBUG rtcPeerConnectionGetMetrics(): ICE local candidate Stats requested at 16762678365731494 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate IP Address: XXX.XXX.XXX.XXX 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate type: srflx 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate port: 38563 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate priority: 1694498815 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate transport protocol: udp 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate relay protocol: N/A 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Local Candidate Ice server source: stun.kinesisvideo.ap-northeast-1.amazonaws.com 2023-02-13 05:57:16 DEBUG rtcPeerConnectionGetMetrics(): ICE remote candidate Stats requested at 16762678365732111 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Remote Candidate IP Address: XXX.XXX.XXX.XXX 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Remote Candidate type: srflx 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Remote Candidate port: 45867 2023-02-13 05:57:16 VERBOSE signalingClientGetCurrentState(): Signaling Client Get Current State 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Remote Candidate priority: 1685921535 2023-02-13 05:57:16 DEBUG logSelectedIceCandidatesInformation(): Remote Candidate transport protocol: udp ``` # Amazon Kinesis Video Streams with WebRTC service quotas Kinesis Video Streams with WebRTC has the following service quotas: **Important** The following service quotas are either soft **[s]**, which can be increased, or hard **[h]**, which can't be increased. You will see [s] and [h] next to individual service quota in the tables below. **Note** TPS stands for *transactions per second*. **Topics** + [ ## Control plane API service quotas ](#limits-control-plane) + [ ## Signaling API service quotas ](#limits-signaling-service) + [ ## TURN service quotas ](#limits-turn-service) + [ ## WebRTC ingestion service quotas ](#limits-ingestion) + [ ## Troubleshooting ](#troubleshooting) ## Control plane API service quotas The following section describes service quotas for the control plane APIs. | API | Maximum API request rate per AWS account | Maximum number of channels per AWS account per AWS Region | Maximum API request per channel | | --- | --- | --- | --- | | CreateSignalingChannel | 50 TPS [s] | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-limits.html) | N/A | | DeleteSignalingChannel | 50 TPS [h] | N/A | 5 TPS [h] | | DescribeMediaStorageConfiguration | 50 TPS [h] | N/A | 5 TPS [h] | | DescribeSignalingChannel | 300 TPS [h] | N/A | 5 TPS [h] | | GetSignalingChannelEndpoint | 300 TPS [h] | N/A | N/A | | ListSignalingChannels | 50 TPS [h] | N/A | N/A | | ListTagsForResource | 50 TPS [h] | N/A | 5 TPS [h] | | TagResource | 50 TPS [h] | N/A | 5 TPS [h] | | UntagResource | 50 TPS [h] | N/A | 5 TPS [h] | | UpdateMediaStorageConfiguration | 10 TPS [h] | N/A | 5 TPS [h] | | UpdateSignalingChannel | 50 TPS [h] | N/A | 5 TPS [h] | ## Signaling API service quotas The following section describes service quotas for the signaling component in Kinesis Video Streams with WebRTC. For more information, see [How it works](kvswebrtc-how-it-works.md). | API | Maximum GO\$1AWAY message grace period prior to terminating connection | Maximum API request rate per channel | Maximum number of concurrent connections per channel | Maximum connection duration | Maximum idle connection timeout period | | --- | --- | --- | --- | --- | --- | | ConnectAsMaster | 1 minute (h) | 3 TPS (h) | 1 (h) | 1 hour (h) | 10 minutes (h) | | ConnectAsViewer | 1 minute (h) | 3 TPS (h) | 10 (s) | 1 hour (h) | 10 minutes (h) | | API | Maximum API request rate | Maximum message payload size | | --- | --- | --- | | SendAlexaOffertoMaster | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-limits.html) | N/A | | SendICECandidate | 20 TPS per WebSocket connection (h) | 10k (h) | | SendSDPAnswer | 5 TPS per WebSocket connection (h) | 10k (h) | | SendSDPOffer | 5 TPS per WebSocket connection (h) | 10k (h) | ## TURN service quotas The following section describes service quotas for the Traversal Using Relays around NAT (TURN) component in Kinesis Video Streams with WebRTC. For more information, see [How it works](kvswebrtc-how-it-works.md). | API or parameter | Value | | --- | --- | | GetIceServerConfig | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/kinesisvideostreams-webrtc-dg/latest/devguide/kvswebrtc-limits.html) | | Bit Rate | 5Mbps (h) | | Credential Lifecycle | 5 minutes (h) | | Number of allocations | 50 per signaling channel (h) | ## WebRTC ingestion service quotas The following section describes service quotas for the media recording component in Amazon Kinesis Video Streams WebRTC. For more information, see [Use Amazon Kinesis Video Streams with WebRTC to ingest and store media](webrtc-ingestion.md). **JoinStorageSession** + API: + Per AWS account - 50 TPS (h) + Per channel - 2 TPS (h) + Streaming session quotas: + Bit rate - 1 Mbps (s) + Session duration - 1 hour (h) + Idle timeout - 3 minutes (h) **JoinStorageSessionAsViewer** + API: + Per AWS account - 50 TPS (h) + Per channel - 2 TPS (h) + Streaming session quotas: + Max concurrent clients in a session - 3 count (h) + Session duration - 1 hour (h) + Idle timeout - 1 minutes (h) ## Troubleshooting You can only connect **one** master and **one or more** viewers to a single signaling channel. It isn't possible to connect multiple masters to a single signaling channel. # Access Kinesis Video Streams with WebRTC You can work with Kinesis Video Streams with WebRTC in any of the following ways: **AWS Management Console** [Getting Started with the AWS Management Console](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/getting-started.html) The console is a browser-based interface to access and use AWS services, including Kinesis Video Streams with WebRTC. **AWS SDKs** AWS provides software development kits (SDKs) that consist of libraries and sample code for various programming languages and platforms (for example, Java, Python, Ruby, .NET, iOS, Android, and more). The SDKs provide a convenient way to create programmatic access to Kinesis Video Streams with WebRTC. For information about the AWS SDKs, including how to download and install them, see [Tools for Amazon Web Services](https://aws.amazon.com/tools/). **Kinesis Video Streams with WebRTC HTTPS API** You can access Kinesis Video Streams with WebRTC and AWS programmatically by using the Kinesis Video Streams with WebRTC APIs, which lets you issue API requests directly to the service. For more information, see the [Amazon Kinesis Video Streams API reference](https://docs.aws.amazon.com//kinesisvideostreams/latest/dg/API_Reference.html).