Warning

Kurento is a low-level platform to create WebRTC applications from scratch. You will be responsible of managing STUN/TURN servers, networking, scalability, etc. If you are new to WebRTC, we recommend using OpenVidu instead.

OpenVidu is an easier to use, higher-level, Open Source platform based on Kurento.

Kurento Java Tutorial - RTP Receiver

This web application consists of a simple RTP stream pipeline: an RtpEndpoint is configured in KMS to listen for one incoming video stream. This stream must be generated by an external program. Visual feedback is provided in this page, by connecting the RtpEndpoint to a WebRtcEndpoint in receive-only mode.

The Java Application Server connects to all events emitted from KMS and prints log messages for each one, so this application is also a good reference to understand what are those events and their relationship with how KMS works. Check Endpoint Events for more information about events that can be emitted by KMS.

Note

Web browsers require using HTTPS to enable WebRTC, so the web server must use SSL and a certificate file. For instructions, check Configure a Java server to use HTTPS.

For convenience, this tutorial already provides dummy self-signed certificates (which will cause a security warning in the browser).

Quick start

Follow these steps to run this demo application:

  1. Install and run Kurento Media Server: Installation Guide.

  2. Install Java JDK and Maven:

    sudo apt-get update
    sudo apt-get install default-jdk maven
    
  3. Run these commands:

    git clone https://github.com/Kurento/kurento.git
    cd kurento/tutorials/java/rtp-receiver/
    git checkout 7.0.0
    mvn -U clean spring-boot:run \
        -Dspring-boot.run.jvmArguments="-Dkms.url=ws://{KMS_HOST}:8888/kurento"
    
  4. Open the demo page with a WebRTC-compliant browser (Chrome, Firefox): https://localhost:8443/

  5. Click on Start to begin the demo.

  6. Copy the KMS IP and Port values to the external streaming program.

  7. As soon as the external streaming program starts sending RTP packets to the IP and Port where KMS is listening for incoming data, the video should appear in the page.

  8. Click on Stop to finish the demo.

Understanding this example

To implement this behavior we have to create a Media Pipeline, composed of an RtpEndpoint and a WebRtcEndpoint. The former acts as an RTP receiver, and the latter is used to show the video in the demo page.

This is a web application, and therefore it follows a client-server architecture. At the client-side, the logic is implemented in JavaScript. At the server-side, we use a Spring-Boot based application server consuming the Kurento Java Client API, to control Kurento Media Server capabilities. All in all, the high level architecture of this demo is three-tier.

To communicate these entities, two WebSockets channels are used:

  1. A WebSocket is created between the Application Server and the browser client, to implement a custom signaling protocol.

  2. Another WebSocket is used to perform the communication between the Application Server and the Kurento Media Server. For this, the Application Server uses the Kurento Java Client library. This communication takes place using the Kurento Protocol (see Kurento Protocol).

The complete source code for this tutorial can be found in GitHub.

Application Server Logic

This demo has been developed using Java in the server side, based on the Spring Boot framework, which embeds a Tomcat web server within the resulting program, and thus simplifies the development and deployment process.

Note

You can use whatever Java server side technology you prefer to build web applications with Kurento. For example, a pure Java EE application, SIP Servlets, Play, Vert.x, etc. Here we chose Spring Boot for convenience.

This graph shows the class diagram of the Application Server:

digraph tutorial_kurento_rtp_receiver {
  bgcolor = "transparent";
  fontname = "Bitstream Vera Sans";
  fontsize = 8;
  size = "12,8";

  node [
    fillcolor = "#E7F2FA";
    fontname = "Bitstream Vera Sans";
    fontsize = 8;
    shape = "rect";
    style = "filled";
  ]

  edge [
    arrowhead = "vee";
    fontname = "Bitstream Vera Sans";
    fontsize = 8;
  ]

  "PlayerApp" -> "PlayerHandler";
  "PlayerApp" -> "KurentoClient";
  "PlayerHandler" -> "KurentoClient" [constraint = false];
  "PlayerHandler" -> "UserSession";
}

Server-side class diagram of the Application Server

Client-Side Logic

We use a specific Kurento JavaScript library called kurento-utils.js to simplify the WebRTC interaction between browser and application server. This library depends on adapter.js, which is a JavaScript WebRTC utility maintained by Google that abstracts away browser differences.

These libraries are linked in the index.html page, and are used in the index.js file.