Kurento Documentation

1 .Kurento Documentation Release 6.9.0 Kurento Dec 12, 2018 

2 .

3 . User Documentation 1 About Kurento and WebRTC 3 1.1 WebRTC media servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Kurento Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Kurento Design Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 About OpenVidu 9 3 Getting Started 11 4 Installation Guide 13 4.1 Amazon Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2 Docker image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.3 Local Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.4 STUN and TURN servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.5 Check your installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5 Installing Pre-Release Builds 19 5.1 Kurento Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2 Kurento Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.3 Kurento JavaScript Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6 Kurento Tutorials 23 6.1 Hello World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.2 WebRTC Magic Mirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 6.3 RTP Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 6.4 WebRTC One-To-Many broadcast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 6.5 WebRTC One-To-One video call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 6.6 WebRTC One-To-One video call with recording and filtering . . . . . . . . . . . . . . . . . . . . . . 124 6.7 WebRTC Many-To-Many video call (Group Call) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 6.8 Media Elements metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 6.9 WebRTC Media Player . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 6.10 WebRTC outgoing Data Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 6.11 WebRTC incoming Data Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 6.12 WebRTC recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 6.13 WebRTC repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 6.14 WebRTC statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 i 

4 .7 Features 221 7.1 Kurento API, Clients, and Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 7.2 Kurento Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 7.3 RTP Streaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 7.4 Congestion Control / REMB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 8 Configuration Guide 227 8.1 Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 8.2 MediaElement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 8.3 SdpEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 8.4 WebRtcEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 8.5 HttpEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 8.6 Debug Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 8.7 Service Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 9 Writing Kurento Applications 229 9.1 Global Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 9.2 Application Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 9.3 Media Plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 10 Writing Kurento Modules 235 10.1 OpenCV module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 10.2 GStreamer module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 10.3 For both kind of modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 10.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 11 Frequently Asked Questions 239 11.1 When is STUN needed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 11.2 How To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 11.3 Why do I get the error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 12 Troubleshooting Issues 243 12.1 Media Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 12.2 Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 12.3 Element-specific info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 12.4 Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 13 Support 255 13.1 Usage Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 13.2 Community Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 13.3 Commercial Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 14 Kurento API 257 14.1 Media Elements and Media Pipelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 14.2 Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 14.3 Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 14.4 Hubs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 15 Kurento Client 265 15.1 Kurento Java Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 15.2 Kurento JavaScript Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 15.3 Reference Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 16 Kurento Protocol 267 16.1 JSON-RPC message format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 ii 

5 . 16.2 Kurento API over JSON-RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 16.3 Network issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 16.4 Example: WebRTC in loopback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 16.5 Creating a custom Kurento Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 17 Kurento Modules 279 17.1 Module Tutorial - Pointer Detector Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 17.2 Module Tutorial - Chroma Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 17.3 Module Tutorial - Crowd Detector Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 17.4 Module Tutorial - Plate Detector Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 18 Kurento Utils JS 349 18.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 18.2 How to use it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 18.3 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 18.4 Using data channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 18.5 Reference documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 18.6 Souce code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 18.7 Build for browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 19 Endpoint Events 357 19.1 MediaObject events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 19.2 MediaElement events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 19.3 BaseRtpEndpoint events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 19.4 WebRtcEndpoint events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 19.5 Sample sequence of events: WebRtcEndpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 20 NAT Traversal 365 20.1 WebRTC with ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 20.2 RTP without ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 21 Securing Kurento Applications 369 21.1 Securing Application Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 21.2 Securing server applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 22 WebRTC Statistics 373 22.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 22.2 API description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 22.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 23 Debug Logging 377 23.1 Logging levels and components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 23.2 Suggested levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 23.3 3rd-Party libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 24 Kurento Team 383 25 Contribution Guide 385 26 Code of Conduct 387 27 Release Notes 389 27.1 6.9.0 (Dec 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 27.2 6.8.1 (Oct 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 27.3 6.7.2 (May 2018) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 iii 

6 .28 Kurento Business Features 395 28.1 Commercial Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 29 Developer Guide 397 29.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 29.2 Code Repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 29.3 Development 101 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 29.4 Building from sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 29.5 Working on a forked library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 29.6 Debian packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 29.7 How-To . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 30 Continuous Integration 411 31 Release Procedures 413 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 31.2 General considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 31.3 Project Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 31.4 C/C++ modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 31.5 Java modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 32 Security Hardening 417 32.1 Hardening validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 32.2 Hardening in Kurento . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 32.3 PIC/PIE in GCC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 32.4 PIC/PIE in CMake . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 33 Writing this documentation 421 33.1 Building locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 33.2 Kurento documentation Style Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 33.3 Sphinx documentation generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 33.4 Read The Docs builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 34 Testing 425 34.1 E2E Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 34.2 Running Java tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 34.3 Kurento Testing Framework explained . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 35 Congestion Control (RMCAT) 441 35.1 Google Congestion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 35.2 Meaning of REMB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 36 NAT Types and NAT Traversal 443 36.1 Basic Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 36.2 Types of NAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 36.3 Types of NAT in the Real World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 36.4 NAT Traversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 37 RTP Streaming Commands 451 37.1 RTP sender examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 37.2 RTP receiver examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 37.3 SRTP examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 37.4 Additional Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459 38 Apple Safari 463 38.1 Codec issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 iv 

7 . 38.2 HTML policies for video playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 39 Glossary 465 40 Indices and tables 473 v 

8 .vi 

9 . Kurento Documentation, Release 6.9.0 Kurento is a WebRTC Media Server and a set of client APIs that simplify the development of advanced video applica- tions for web and smartphone platforms. Its features include group communications, transcoding, recording, mixing, broadcasting and routing of audiovisual flows. The code is open source, released under the terms of Apache License Version 2.0 and available on GitHub. You can read more on our page About Kurento and WebRTC. Check now how to get started with Kurento and take a look at our tutorials, which showcase some demo applications. The main documentation for the project is organized into different sections: • User Documentation • Feature Documentation • Project Documentation • Business Documentation Information about development of Kurento itself is also available: • Developer Documentation User Documentation 1 

10 .Kurento Documentation, Release 6.9.0 2 User Documentation 

11 . CHAPTER 1 About Kurento and WebRTC Kurento is a WebRTC Media Server and a set of client APIs that simplify the development of advanced video applica- tions for web and smartphone platforms. Its features include group communications, transcoding, recording, mixing, broadcasting and routing of audiovisual flows. Kurento offers a multimedia framework that eases the task of building multimedia applications with the following features: • Dynamic WebRTC Media pipelines: Kurento allows custom media pipelines connected to WebRTC peers like web browsers and mobile apps. These media pipelines are based on composable elements such as players, recorders, mixers, etc. that can be mix-and-matched, activated, or deactivated at any point in time, even when the media is already flowing. • Client/Server Architecture: Apps developed with Kurento follow a client/server architecture. Kurento Media Server (KMS) is the server and offers a WebSocket interface implementing the Kurento Protocol, which allows Client Applications to define pipeline topologies. • Java and JavaScript Client Applications: The typical use case of a KMS deployment consists of a three- layer architecture, where the user’s browser interacts with the KMS server by means of an intermediate Client Application. There are several official Kurento Client Libraries, supporting the use of Java and JavaScript for the Client Applications. Clients for other languages can be easily implemented following the WebSocket protocol. • Third party Modules: The Kurento Media Server has an extensible architecture based on plugins, which allows third parties to implement modules that can be added to their media pipelines. This allows integration of media processing algorithms to any WebRTC application, like integrating Computer Vision, Augmented Reality, video indexing, and speech analysis. All is needed is to create a new Kurento element, and use it in any already existing media pipeline. This document contains a high level explanation of how to become a KMS developer. Development of Kurento Client Applications is out of the scope for this document, and won’t be explained here. The code of Kurento Media Server is open source, released under the terms of Apache License Version 2.0 and available on GitHub. 3 

12 .Kurento Documentation, Release 6.9.0 1.1 WebRTC media servers WebRTC is a set of protocols, mechanisms and APIs that provide browsers and mobile applications with Real-Time Communications (RTC) capabilities over peer-to-peer connections. It has been conceived as a technology that allows browsers to communicate directly without the mediation of any kind of infrastructure. However, this model is only enough for creating basic web applications; features such as group communications, media stream recording, media broadcasting, or media transcoding are difficult to implement on top of it. For this reason, many applications end up requiring an intermediate media server. Fig. 1: Peer-to-peer WebRTC approach vs. WebRTC through a media server Conceptually, a WebRTC media server is just a multimedia middleware where media traffic passes through when moving from source to destinations. Media servers are capable of processing incoming media streams and offer different outcomes, such as: • Group Communications: Distributing among several receivers the media stream that one peer generates, i.e. acting as a Multi-Conference Unit (“MCU”). • Mixing: Transforming several incoming stream into one single composite stream. • Transcoding: On-the-fly adaptation of codecs and formats between incompatible clients. • Recording: Storing in a persistent way the media exchanged among peers. 1.2 Kurento Media Server Kurento’s main component is the Kurento Media Server (KMS), responsible for media transmission, processing, recording, and playback. KMS is built on top of the fantastic GStreamer multimedia library, and provides the following features: • Networked streaming protocols, including HTTP, RTP and WebRTC. • Group communications (MCU and SFU functionality) supporting both media mixing and media rout- ing/dispatching. • Generic support for filters implementing Computer Vision and Augmented Reality algorithms. 4 Chapter 1. About Kurento and WebRTC 

13 . Kurento Documentation, Release 6.9.0 Fig. 2: Typical WebRTC Media Server capabilities • Media storage that supports writing operations for WebM and MP4 and playing in all formats supported by GStreamer. • Automatic media transcoding between any of the codecs supported by GStreamer, including VP8, H.264, H.263, AMR, OPUS, Speex, G.711, and more. 1.3 Kurento Design Principles Kurento is designed based on the following main principles: Separate Media and Signaling Planes Signaling and Media are two separate planes and Kurento is de- signed so that applications can handle separately those facets of multimedia processing. Distribution of Media and Application Services Kurento Media Server and applications can be collo- cated, escalated or distributed among different machines. A single application can invoke the services of more than one Kurento Media Server. The opposite also applies, that is, a Kurento Media Server can attend the requests of more than one application. Suitable for the Cloud Kurento is suitable to be integrated into cloud environments to act as a PaaS (Platform as a Service) component. Media Pipelines Chaining Media Elements via Media Pipelines is an intuitive approach to challenge the complexity of multimedia processing. Application development Developers do not need to be aware of internal Kurento Media Server com- plexities: all the applications can deployed in any technology or framework the developer likes, from client to server. From browsers to cloud services. End-to-End Communication Capability Kurento provides end-to-end communication capabilities so developers do not need to deal with the complexity of transporting, encoding/decoding and rendering media on client devices. 1.3. Kurento Design Principles 5 

14 .Kurento Documentation, Release 6.9.0 Fig. 3: Kurento Media Server capabilities 6 Chapter 1. About Kurento and WebRTC 

15 . Kurento Documentation, Release 6.9.0 Fully Processable Media Streams Kurento enables not only interactive interpersonal communications (e.g. Skype-like with conversational call push/reception capabilities), but also human-to-machine (e.g. Video on Demand through real-time streaming) and machine-to-machine (e.g. remote video recording, multisensory data exchange) communications. Modular Processing of Media Modularization achieved through media elements and pipelines allows defining the media processing functionality of an application through a “graph-oriented” language, where the application developer is able to create the desired logic by chaining the appropriate func- tionalities. Auditable Processing Kurento is able to generate rich and detailed information for QoS monitoring, billing and auditing. Seamless IMS integration Kurento is designed to support seamless integration into the IMS infrastruc- ture of Telephony Carriers. Transparent Media Adaptation Layer Kurento provides a transparent media adaptation layer to make the convergence among different devices having different requirements in terms of screen size, power consumption, transmission rate, etc. possible. 1.3. Kurento Design Principles 7 

16 .Kurento Documentation, Release 6.9.0 8 Chapter 1. About Kurento and WebRTC 

17 . CHAPTER 2 About OpenVidu OpenVidu is a new project from the same team that created Kurento. It acts as a wrapper around an installation of Kurento Media Server and encapsulates most of its features, in order to greatly simplify some of the most typical use cases of WebRTC, such as conference rooms. An application developer using OpenVidu doesn’t need to worry about all the low-level technologies and protocols that form part of typical WebRTC communications. The main goal of this project is to provide a simple, effective, easy-to-use API; just include the OpenVidu client-side and OpenVidu Server for handling the media flows, and you’ll have a full-featured WebRTC-capable application. For more advanced needs, or for applications that require more versatile management of media processing pipelines, Kurento is still the go-to solution; however, if you are planning on building a service which matches one of the simplified use cases covered by OpenVidu, we strongly suggest to check it out as it will be easier and cheaper to go that route. Check out the OpenVidu project page, which contains all the relevant information: https://openvidu.io/ 9 

18 .Kurento Documentation, Release 6.9.0 10 Chapter 2. About OpenVidu 

19 . CHAPTER 3 Getting Started Generally speaking, these are the first steps that any user interested in Kurento should follow: 1. Know your use case Choose between Kurento and OpenVidu. Kurento Media Server has been designed as a general-purpose platform that can be used to create any kind of multimedia streaming applications. This makes KMS a powerful tool, however it also means that there is some unavoidable complexity that the developer must face. WebRTC is a complex standard with a lot of moving parts, and you need to know about each one of these components and how they work together to achieve the multimedia communications that the standard strives to offer. If your intended application consists of a complex setup with different kinds of sources and varied use cases, then Kurento is the best leverage you can use. However, if you intend to solve a simpler use case, such as those of video conference applications, the Open- Vidu project builds on top of Kurento to offer a simpler and easier to use solution that will save you time and development effort. 2. Install KMS The installation guide explains different ways in which Kurento can be installed in your system. The fastest and easiest one is to use our pre-configured template for Amazon AWS. 3. Configure KMS KMS is able to run as-is after a normal installation. However, there are several parameters that you might want to tune in the configuration files. 4. Write an Application Write an application that queries the Kurento API to make use of the capabilities offered by KMS. The easiest way of doing this is to build on one of the provided Kurento Clients. In general, you can use any programming language to write your application, as long as it speaks the Kurento Protocol. 11 

20 .Kurento Documentation, Release 6.9.0 Have a look at the features offered by Kurento, and follow any of the multiple tutorials that explain how to build basic applications. 5. Ask for help If you face any issue with Kurento itself or have difficulties configuring the plethora of mechanisms that form part of WebRTC, don’t hesitate to ask for help to our community of users. Still, there are times when the problems at hand require more specialized study. If you wish to get help from expert people with more inside knowledge of Kurento, we also offer the option of direct support contracts. 6. Enjoy! Kurento is a project that aims to bring the latest innovations closer to the people, and help connect them together. Make a great application with it, and let us know! We will be more than happy to find out about who is using Kurento and what is being built with it :-) 12 Chapter 3. Getting Started 

21 . CHAPTER 4 Installation Guide Kurento Media Server (KMS) can be installed in multiple ways • Using an EC2 instance in the Amazon Web Services (AWS) cloud service. Using AWS is suggested to users who don’t want to worry about properly configuring a server and all software packages, because the provided setup does all this automatically. • Using the Docker images provided by the Kurento team. Docker images allow to run Kurento in any host machine, so for example it’s possible to run KMS on top of a Fedora or CentOS system. In theory it could even be possible to run under Windows, but so far that possibility hasn’t been explored, so you would be at your own risk. • A local installation with apt-get install, in any Ubuntu machine. This method allows to have total control of the installation process. Besides installing KMS, a common need is to also install a STUN or TURN server, especially if KMS or any of its clients are located behind a NAT firewall. If you want to try pre-release builds of KMS, then head to the section Installing Pre-Release Builds. 4.1 Amazon Web Services The Kurento project provides an AWS CloudFormation template file. It can be used to create an EC2 instance that comes with everything needed and totally pre-configured to run KMS, including a Coturn server. Note that this template is specifically tailored to be deployed on the default Amazon Virtual Private Cloud (Amazon VPC) network. You need an Amazon VPC to deploy this template. Follow these steps to use it: 1. Access the AWS CloudFormation Console. 2. Click on Create Stack. 3. Look for the section Choose a template, and choose the option Specify an Amazon S3 template URL. Then, in the text field that gets enabled, paste this URL: https://s3-eu-west-1.amazonaws.com/aws. kurento.org/KMS-Coturn-cfn.yaml. 13 

22 .Kurento Documentation, Release 6.9.0 4. Follow through the steps of the configuration wizard: 4.1. Stack name: A descriptive name for your Stack. 4.2. InstanceType: Choose an appropriate size for your instance. Check the different ones. 4.3. KeyName: You need to create an RSA key beforehand in order to access the instance. Check AWS documentation on how to create one. 4.4. SSHLocation: For security reasons you may need to restrict SSH traffic to allow connections only from specific locations. For example, from your home or office. 4.5. TurnUser: User name for the TURN server. 4.6. TurnPassword: Password required to use the TURN server. Note: The template file includes Coturn as a TURN server. The default user/password for this server is kurento/kurento. You can optionally change the username, but make sure to change the default password. 5. Finish the Stack creation process. Wait until the status of the newly created Stack reads CREATE_COMPLETE. 6. Select the Stack and then open the Outputs tab, where you’ll find the instance’s public IP address, and the Kurento Media Server endpoint URL that must be used by Application Servers. 4.2 Docker image Kurento’s Docker Hub contains images built from each KMS Release. Just head to the kurento-media-server image page, and follow the instructions you’ll find there. 4.3 Local Installation With this method, you will install KMS from the native Ubuntu package repositories made available by the Kurento project. KMS has explicit support for two Long-Term Support (LTS) distributions of Ubuntu: Ubuntu 14.04 (Trusty) and Ubuntu 16.04 (Xenial). Only the 64-bits editions are supported. Currently, the main development environment for KMS is Ubuntu 16.04 (Xenial), so if you are in doubt, this is the preferred Ubuntu distribution to choose. However, all features and bug fixes are still being backported and tested on Ubuntu 14.04 (Trusty), so you can continue running this version if strictly required. Warning: Ubuntu 14.04 (Trusty) is in the path of deprecation and will stop receiving updates in the end of 2018. 1. Define what version of Ubuntu is in use. Open a terminal and copy only one of these commands: # KMS for Ubuntu 14.04 (Trusty) DISTRO="trusty" # KMS for Ubuntu 16.04 (Xenial) DISTRO="xenial" 14 Chapter 4. Installation Guide 

23 . Kurento Documentation, Release 6.9.0 2. Add the Kurento repository to your system configuration. Run these two commands in the same terminal you used in the previous step: sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 5AFA7A83 sudo tee "/etc/apt/sources.list.d/kurento.list" >/dev/null <<EOF # Kurento Media Server - Release packages deb [arch=amd64] http://ubuntu.openvidu.io/6.9.0 $DISTRO kms6 EOF 3. Install KMS: sudo apt-get update sudo apt-get install kurento-media-server This will install the KMS release version that was specified in the previous commands. The server includes service files which integrate with the Ubuntu init system, so you can use the following commands to start and stop it: sudo service kurento-media-server start sudo service kurento-media-server stop Log messages from KMS will be available in /var/log/kurento-media-server/. For more details about KMS logs, check Debug Logging. 4.4 STUN and TURN servers If Kurento Media Server, its Application Server, or any of the clients are located behind a NAT, you need to use a STUN or a TURN server in order to achieve NAT traversal. In most cases, STUN is effective in addressing the NAT issue with most consumer network devices (routers). However, it doesn’t work for many corporate networks, so a TURN server becomes necessary. Apart from that, you need to open all UDP ports in your system configuration, as STUN will use any random port from the whole [0-65535] range. Note: The features provided by TURN are a superset of those provided by STUN. This means that you don’t need to configure a STUN server if you are already using a TURN server. For more information about why and when STUN/TURN is needed, check out the FAQ: When is STUN needed? 4.4.1 STUN server To configure a STUN server in KMS, uncomment the following lines in the WebRtcEndpoint configuration file, located at /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini: stunServerAddress=<serverIp> stunServerPort=<serverPort> Note: Be careful since comments inline (with ;) are not allowed for parameters in the configuration files. Thus, the following line is not correct: 4.4. STUN and TURN servers 15 

24 .Kurento Documentation, Release 6.9.0 stunServerAddress=<serverIp> ; Only IP addresses are supported . . . and must be changed to something like this: ; Only IP addresses are supported stunServerAddress=<serverIp> The parameter serverIp should be the public IP address of the STUN server. It must be an IP address, not a domain name. It should be easy to find some public STUN servers that are made available for free. For example: 173.194.66.127:19302 173.194.71.127:19302 74.125.200.127:19302 74.125.204.127:19302 173.194.72.127:19302 74.125.23.127:3478 77.72.174.163:3478 77.72.174.165:3478 77.72.174.167:3478 77.72.174.161:3478 208.97.25.20:3478 62.71.2.168:3478 212.227.67.194:3478 212.227.67.195:3478 107.23.150.92:3478 77.72.169.155:3478 77.72.169.156:3478 77.72.169.164:3478 77.72.169.166:3478 77.72.174.162:3478 77.72.174.164:3478 77.72.174.166:3478 77.72.174.160:3478 54.172.47.69:3478 4.4.2 TURN server To configure a TURN server in KMS, uncomment the following lines in the WebRtcEndpoint configuration file, located at /etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini: turnURL=<user>:<password>@<serverIp>:<serverPort> The parameter serverIp should be the public IP address of the TURN server. It must be an IP address, not a domain name. See some examples of TURN configuration below: turnURL=kurento:kurento@WWW.XXX.YYY.ZZZ:3478 . . . or using a free access Numb TURN/STUN server: turnURL=user:password@66.228.45.110:3478 16 Chapter 4. Installation Guide 

25 . Kurento Documentation, Release 6.9.0 Note that it is somewhat easy to find free STUN servers available on the net, because their functionality is pretty limited and it is not costly to keep them working for free. However, this doesn’t happen with TURN servers, which act as a media proxy between peers and thus the cost of maintaining one is much higher. It is rare to find a TURN server which works for free while offering good performance. Usually, each user opts to maintain their own private TURN server instances. Coturn is an open source implementation of a TURN/STUN server. In the FAQ section there is a description about how to install and configure it. 4.5 Check your installation To verify that KMS is up and running, use this command and look for the kurento-media-server process: ps -ef | grep kurento-media-server > nobody 1270 1 0 08:52 ? 00:01:00 /usr/bin/kurento-media-server Unless configured otherwise, KMS will open the port 8888 to receive requests and send responses by means of the Kurento Protocol. Use this command to verify that this port is listening for incoming packets: sudo netstat -tupan | grep kurento > tcp6 0 0 :::8888 :::* LISTEN 1270/kurento-media-server 4.5. Check your installation 17 

26 .Kurento Documentation, Release 6.9.0 18 Chapter 4. Installation Guide 

27 . CHAPTER 5 Installing Pre-Release Builds Some components of KMS are built nightly, with the code developed during that same day. Other components are built immediately when code is merged into the source repositories. These builds end up being uploaded to Development repositories so they can be installed by anyone. Use these if you want to develop Kurento itself, or if you want to try the latest changes before they are officially released. Warning: Pre-release builds always represent the current state on the software development; 99% of the time this is stable code, very close to what will end up being released. However, it’s also possible (although unlikely) that these builds might include undocumented changes, regressions, bugs or deprecations. It’s safer to be conservative and avoid using pre-release builds in a production environment, unless you have a strong reason to do it. Note: If you are looking to build KMS from the source code, then you should check the section aimed at development of KMS itself : Building from sources. 5.1 Kurento Media Server The steps to install a pre-release version of KMS are pretty much the same as those explained in Local Installation, with the only change of using a different package repository. 1. Define what version of Ubuntu is installed in your system. Open a terminal and copy only one of these com- mands: # KMS for Ubuntu 14.04 (Trusty) DISTRO="trusty" 19 

28 .Kurento Documentation, Release 6.9.0 # KMS for Ubuntu 16.04 (Xenial) DISTRO="xenial" 2. Add the Kurento repository to your system configuration. Run these two commands in the same terminal you used in the previous step: sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 5AFA7A83 sudo tee "/etc/apt/sources.list.d/kurento.list" >/dev/null <<EOF # Kurento Media Server - Nightly packages deb [arch=amd64] http://ubuntu.openvidu.io/dev $DISTRO kms6 EOF 3. Install KMS: sudo apt-get update sudo apt-get install kurento-media-server This will install the latest KMS pre-release (potentially unstable) version. 5.2 Kurento Java Client The development builds of the Kurento Java Client are made available for Maven in https://maven.openvidu.io/index. action To use these, you need to add first this repository to your Maven configuration. Adding a repository to Maven can be done at three scope levels: • Project level. This will add access to development builds only for the project where the configuration is done. Open the project’s pom.xml and include this: <project> ... <repositories> <repository> <id>kurento-snapshots</id> <name>Kurento Snapshots</name> <url>https://maven.openvidu.io/repository/snapshots/</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>kurento-snapshots</id> <name>Kurento Snapshots</name> <url>https://maven.openvidu.io/repository/snapshots/</url> <releases> <enabled>false</enabled> </releases> (continues on next page) 20 Chapter 5. Installing Pre-Release Builds 

29 . Kurento Documentation, Release 6.9.0 (continued from previous page) <snapshots> <enabled>true</enabled> </snapshots> </pluginRepository> </pluginRepositories> ... </project> After this is included, there are two ways to use the updated versions: 1. In the same pom.xml, look for the desired <dependency> and change its version. For example: <dependency> <groupId>org.kurento</groupId> <artifactId>kurento-client</artifactId> <version>6.6.3-SNAPSHOT</version> </dependency> 2. If you have not specified a dependency version, use the -U switch in your next Maven run to force updating all dependencies. • User and System levels. The file settings.xml provides configuration for all projects, but its contents have a different reach depending on where it is located: – At $HOME/.m2/settings.xml, it defines the settings that will be applied for a single user. – At /etc/maven/settings.xml, it defines the settings that will be applied for all Maven users on a machine. To use this method, first edit the settings file at one of the mentioned locations, and include this: <settings> ... <profiles> <profile> <id>kurento</id> <repositories> <repository> <id>kurento-snapshots</id> <name>Kurento Snapshots</name> <url>https://maven.openvidu.io/repository/snapshots/</url> <releases> <enabled>false</enabled> </releases> <snapshots> <enabled>true</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>kurento-snapshots</id> <name>Kurento Snapshots</name> <url>https://maven.openvidu.io/repository/snapshots/</url> <releases> <enabled>false</enabled> (continues on next page) 5.2. Kurento Java Client 21