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 client application 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

This application uses HTTPS. It will work fine is you run it in localhost and accept a security exception in the browser, but you should secure your application if running remotely. For more info, check Configure Java applications to use HTTPS.

Quick start

Follow these steps to run this demo application:

  1. Install Kurento Media Server: Installation Guide.

  2. Run these commands:

    git clone https://github.com/Kurento/kurento-tutorial-java.git
    cd kurento-tutorial-java/kurento-hello-world
    git checkout 6.7.1
    mvn clean compile exec:java -Dkms.url=ws://localhost:8888/kurento
    
  3. Open the demo page with a WebRTC-compliant browser (Chrome, Firefox): https://localhost:8443/

  4. Click on Start to begin the demo.

  5. Copy the KMS IP and Port information to the external streaming program.

  6. 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.

  7. 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 later is used to show the incoming 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 server application 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. WebSocket is created between the browser client and the application server to implement a custom signaling protocol.
  2. Another WebSocket is used to perform the communication between the Kurento Java Client and the Kurento Media Server.

This communication takes place using the Kurento Protocol. For further information, see Kurento Protocol.

The following sections analyze in depth the server (Java) and client-side (JavaScript) code of this application. The complete source code 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 client application:

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 = "record";
    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 client application

Client-Side Logic

We use a specific Kurento JavaScript library called kurento-utils.js to simplify the WebRTC interaction between browser and server application. 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.