Kurento API Reference¶
In the following sections we will describe the Kurento API in a high level way. We will show the media capabilities exposed by Kurento Media Server to clients. If you want see working demos using Kurento, please refer to Tutorials section.
Media elements and media pipelines¶
Kurento is based on two concepts that act as building blocks for application developers:
- Media Elements. A Media element is a functional unit performing a
specific action on a media stream. Media elements are a way of every
capability is represented as a self-contained “black box” (the media
element) to the application developer, who does not need to understand the
low-level details of the element for using it. Media elements are capable of
receiving media from other elements (through media sources) and of
sending media to other elements (through media sinks). Depending on their
function, media elements can be split into different groups:
- Input Endpoints: Media elements capable of receiving media and injecting it into a pipeline. There are several types of input endpoints. File input endpoints take the media from a file, Network input endpoints take the media from the network, and Capture input endpoints are capable of capturing the media stream directly from a camera or other kind of hardware resource.
- Filters: Media elements in charge of transforming or analyzing media. Hence there are filters for performing operations such as mixing, muxing, analyzing, augmenting, etc.
- Hubs: Media Objects in charge of managing multiple media flows in a pipeline. A Hub has several hub ports where other media elements are connected. Depending on the Hub type, there are different ways to control the media. For example, there are a Hub called Composite that merge all input video streams in a unique output video stream with all inputs in a grid.
- Output Endpoints: Media elements capable of taking a media stream out of the pipeline. Again, there are several types of output endpoints specialized in files, network, screen, etc.
- Media Pipeline: A Media Pipeline is a chain of media elements, where the output stream generated by one element (source) is fed into one or more other elements input streams (sinks). Hence, the pipeline represents a “machine” capable of performing a sequence of operations over a stream.
Kurento API is an object oriented API. That is, there are classes that can be instantiated. This classes define operations that can be invoked over objects of this classes. The classes can have an inheritance relationship with other classes, inheriting operations from parent classes to children ones.
The following class diagram shows some of the relationships of the main classes in the Kurento API.
Let us discuss briefly the different Endpoints offered by kurento.
A WebRtcEndpoint is an output and input endpoint that provides media streaming for Real Time Communications (RTC) through the web. It implements WebRTC technology to communicate with browsers.
A RtpEndpoint is an output and input endpoint. That is, provides bidirectional content delivery capabilities with remote networked peers through RTP protocol. As you can imagine, to send and receive media through the network it uses RTP protocol and SDP for media negotiation.
An HttpPostEndpoint is an input endpoint that accepts media using http POST requests like HTTP file upload function.
A PlayerEndpoint is an input endpoint that retrieves content from file system, http URL or RTSP url and inject it into the media pipeline.
A RecorderEndpoint is an output endpoint that provides function to store
contents in reliable mode (doesn’t discard data). It contains
pads for audio and video.
The following class diagram shows the relationships of the main endpoint classes.
Filters are MediaElements that perform media processing, computer vision, augmented reality, and so on. Let see the available filters in Kurento:
The ZBarFilter filter detects QR and bar codes in a video stream. When a
code is found, the filter raises a
CodeFoundEvent. Clients can add a
listener to this event to execute some action.
The FaceOverlayFilter filter detects faces in a video stream and overlaid it with a configurable image.
GStreamerFilter is a generic filter interface that allow use GStreamer filter in Kurento Media Pipelines.
The following class diagram shows the relationships of the main filter classes.
Hubs are media objects in charge of managing multiple media flows in a pipeline. A Hub has several hub ports where other media elements are connected. Let’s see the available hubs in Kurento:
Composite is a hub that mixes the audio stream of its connected inputs and constructs a grid with the video streams of them.
DispatcherOneToMany is a Hub that sends a given input to all the connected output HubPorts.
Dispatcher is a hub that allows routing between arbitrary input-output HubPort pairs.
The following class diagram shows the relationships of the hubs.
You see the details of the Kurento Clients see the JavaDoc/JsDoc: