Kurento WebRTC is the combination of the Kurento Media Server (KMS) and the WebRTC protocol that lets developers process, record, and route real-time audio and video on the server side. Kurento exposes a WebRtcEndpoint that negotiates SDP offers and answers with browsers, while its media pipeline model lets you add filters, recorders, and mixers to live streams. If you need server-side media control rather than raw peer-to-peer calls, Kurento is one of the most established open-source options, and managed alternatives like VideoSDK remove the infrastructure burden entirely.
Real-time video has moved from a nice-to-have to a core feature. Telehealth consultations, live tutoring, remote support, and social apps all depend on sub-second audio and video delivery, and users notice anything less. Building that experience from scratch with raw WebRTC means handling signaling, NAT traversal, media routing, and reconnection logic yourself.
Kurento takes a different approach: it brings WebRTC to the server side. Instead of browsers exchanging media directly, each browser connects to the Kurento Media Server, which can then process, record, filter, or redistribute that media. This article walks through what Kurento is, how its WebRTC architecture works, how to set it up and configure endpoints, and the pitfalls and performance practices that separate a working demo from a production deployment.
What Is Kurento?
Kurento is defined as an open-source WebRTC media server that receives, processes, and delivers real-time media streams on the server. It is developed by the Kurento project and hosted on GitHub, where you can inspect the source, read the documentation, and follow release activity.
Kurento works by exposing a graph-based media processing model. The core building block is the MediaPipeline, a container that holds a chain of MediaElements. Each element performs one media function: a WebRtcEndpoint terminates a WebRTC connection, a RecorderEndpoint writes streams to disk, filters apply computer vision or audio effects, and dispatchers route media between participants. You connect elements together, and media flows through the resulting pipeline.
The element you will interact with most is the WebRtcEndpoint. It is the bridge between a browser's WebRTC stack and Kurento's internal pipeline. Every participant in a Kurento-based call connects through their own WebRtcEndpoint, which handles SDP negotiation, ICE candidate exchange, and the encryption that WebRTC requires.
Understanding WebRTC Basics
WebRTC is a peer-to-peer protocol: two browsers can, in principle, exchange audio, video, and data directly without any server touching the media. To establish that direct connection, three things must happen.
First, signaling. Browsers exchange session descriptions using the SDP offer/answer model. One side creates an offer describing what codecs and media it wants to send and receive, and the other side answers with its own description. WebRTC does not define how these descriptions travel; your application does, typically over WebSockets.
Second, connectivity. Browsers sit behind NATs and firewalls, so they exchange ICE candidates, which are potential network addresses and ports for reaching each other. ICE tries direct host-to-host routes first, then STUN-assisted routes, and finally falls back to a TURN relay when direct paths fail.
Third, media transport. Once a route is found, audio and video flow over encrypted SRTP channels.
The catch is that pure peer-to-peer WebRTC gives you no server-side control. You cannot record a stream, mix multiple participants into one view, apply a filter, or broadcast to many viewers without a media server in the path. That is exactly the gap Kurento fills, and it is also the gap that managed SDKs like VideoSDK's video calling API fill with hosted infrastructure, recording, and transcription built in.
Understanding Kurento WebRTC Architecture
Kurento WebRTC architecture follows a clear division of labor: the browser handles capture and playback, your signaling server brokers messages, and Kurento handles all media processing. The browser never talks to Kurento directly for control purposes; it talks to your application server, which in turn talks to Kurento over its WebSocket-based API using client libraries such as the Kurento JavaScript client for Node.js.
The flow works like this. A browser joins a session and sends an SDP offer to your signaling server. The signaling server asks Kurento to create a MediaPipeline and a WebRtcEndpoint, then forwards the offer to that endpoint. Kurento processes the offer, generates an answer, and returns it through the signaling server back to the browser. Meanwhile, both sides exchange ICE candidates through the same signaling path. Once connectivity is established, media flows directly between the browser and Kurento over SRTP, bypassing your signaling server entirely.
Inside Kurento, the WebRtcEndpoint can be connected to other media elements. Connect it to a RecorderEndpoint and the session is recorded. Connect two endpoints to each other and you have a one-to-one call. Connect many endpoints through a mixer or dispatcher and you have multi-party conferencing.
This separation matters in production. Your signaling server can fail and be restarted without dropping established media flows, because media never passes through it. Kurento instances can be scaled horizontally, with each instance handling a slice of your media load.
Setting Up Kurento Media Server
Kurento Media Server runs natively on Ubuntu, which is the officially supported and recommended platform. The standard installation path uses the operating system's package manager: you add the Kurento repository, install the Kurento Media Server package, and enable the service so it starts automatically. On other operating systems, or when you want reproducible deployments, the official Kurento Docker image is the cleaner option; you run a container that exposes Kurento's WebSocket port and mount a volume for any recordings.
Before installing, confirm your environment. You need a supported Ubuntu version, network access to the Kurento package repository, and open ports for the Kurento WebSocket API (typically port 8888) plus a range of UDP ports for RTP media. If you plan to build the client side with the Kurento JavaScript client, you also need Node.js installed on your application server.
After installation, verify the server is healthy. The Kurento service exposes a WebSocket endpoint, and a successful connection handshake to that endpoint confirms the server is up and listening. The Kurento project also provides a set of demo applications, including the well-known loopback tutorial, which streams your camera back to you through the server. Getting the loopback working end to end is the fastest confidence check that your installation, signaling, and media path are all functional.
One detail that trips people up immediately: Kurento's API port should not be exposed to the public internet. It belongs behind your application server on a private network or localhost, with your signaling server as the only client that connects to it.
Configuring Kurento WebRTC Endpoints
Configuring a Kurento WebRTC connection means orchestrating three conversations at once: pipeline creation, SDP negotiation, and ICE candidate exchange. All of it happens through the Kurento client library from your application server.
The process starts when a user joins. Your server asks Kurento to create a MediaPipeline, then creates a WebRtcEndpoint inside that pipeline. The browser generates its SDP offer and sends it over your signaling channel. Your server passes that offer to the endpoint, which processes it and returns an SDP answer. That answer travels back to the browser, and both sides now agree on codecs, directions, and transport parameters.
In parallel, ICE candidates flow. The browser discovers its own candidates and sends them through signaling; your server forwards each one to the Kurento endpoint. Kurento discovers its own candidates and emits an event for each one, which your server forwards back to the browser. This is Trickle ICE in action: candidates are exchanged as they are discovered rather than waiting for the full set, which shortens connection setup time.
The Kurento client exposes distinct methods depending on which side initiates. When the browser offers first, the endpoint processes the offer and generates the answer. When Kurento initiates, the endpoint generates an offer that the browser must answer. Getting these roles mixed up is a classic source of failed negotiations.
SDP Offer/Answer Flow
Every WebRTC session has exactly one offerer and one answerer, and in Kurento the roles are explicit. If your browser starts the session, the browser is the offerer: it describes the media it wants to send, and the Kurento WebRtcEndpoint acts as the answerer, accepting the codecs it supports and rejecting the rest. If your application design has Kurento initiate, the endpoint generates the offer and the browser answers.
The practical rule is to pick one direction and stay consistent across your application. Most Kurento tutorials have the browser offer first, because the browser knows its local media state at join time. Whichever direction you choose, the offer must be processed before candidates are applied, and the answer must reach the browser before it finalizes its remote description. Sequencing violations here produce sessions that negotiate successfully but never carry media.
ICE Candidate Management
ICE candidate management in Kurento follows the Trickle ICE pattern. As the endpoint gathers candidates, it raises a candidate-found event for each one, and your signaling server must relay each event to the browser. In the other direction, every candidate the browser sends must be added to the Kurento endpoint.
A common mistake is assuming candidate exchange is optional because the connection sometimes works without it. On a same-machine loopback test, host candidates may connect immediately. In real networks behind NAT, relay candidates through a TURN server are often the only working path, and dropping candidate events means those users simply never connect. Configure a STUN server for public deployments and a TURN server for restrictive networks, and make sure the UDP media port range on the Kurento host is open in any firewall or security group.
Common Pitfalls and Troubleshooting
Most Kurento WebRTC failures cluster around four issues, and all of them have well-understood fixes.
The first and most frequent is missing HTTPS and secure WebSockets. Browsers only allow camera and microphone access on secure contexts, meaning your pages must load over HTTPS and your signaling must run over secure WebSocket connections in production. A setup that works on localhost over plain HTTP will fail the moment you deploy it, with permission errors that look like Kurento problems but are not. Provision a TLS certificate for both your web server and your signaling endpoint before testing anything else.
The second is mismatched or malformed SDP. If your signaling layer accidentally mutates the session description, for example by serializing it twice or truncating it, the endpoint will reject the offer. Keep SDP blobs opaque in your signaling code: receive them, pass them through, never parse or modify them.
The third is ICE failure. Symptoms include a session that negotiates but shows no media, or connections that work on some networks and not others. Check that the Kurento media port range is open, that STUN and TURN servers are configured, and that the endpoint's ICE state transitions are being observed. Kurento raises events for ICE state changes, and logging them on the server side tells you immediately whether connectivity failed or media failed.
The fourth is silent event loss. If your signaling server does not forward every ICE candidate event or every media state event, failures become invisible. Instrument both sides: log the endpoint's media-state and ICE-state events in Kurento, and log the browser's connection state on the client. The Kurento server also writes detailed logs that reveal pipeline errors, codec negotiation failures, and port binding problems, and reading those logs before changing code will save you hours.
Real-World Use Cases
Kurento's pipeline model supports a wide range of applications beyond basic calling.
One-to-one video chat is the canonical starting point, and the loopback demo (your own stream returned to you through the server) is the simplest possible pipeline: one endpoint in, the same endpoint out. Extend it to two endpoints connected to each other and you have a two-person call with the server in the middle, which also gives you a natural recording point.
Multi-party conferencing is where server-side media earns its keep. Because every participant connects to Kurento, the server can mix multiple audio streams, composite video into a grid, or selectively forward only the active speaker. This is impossible with pure peer-to-peer WebRTC at scale, since each participant would need a separate connection to every other participant.
Media recording and playback is a first-class use case. A RecorderEndpoint attached to a pipeline writes the session to storage, which powers lecture capture, interview recording, and compliance archiving. Data channels round out the picture: WebRTC data channels carry chat messages, file transfer, or application state alongside the media, all through the same connection.
If your use case is primarily standard video calling and you would rather not operate media servers at all, VideoSDK's Prebuilt UI Kit delivers a complete calling interface without any server-side media infrastructure, and the REST APIs handle recording and room management for you.
Best Practices and Performance Tips
Production Kurento deployments live or die on network configuration and capacity planning.
Enable DSCP Quality of Service marking when your traffic crosses private networks you control. Kurento supports DSCP marking on its media streams, which lets routers prioritize real-time audio and video over bulk traffic. On the public internet this has no effect, since ISPs strip or ignore the markings, but inside a corporate or campus network it measurably reduces jitter.
Always deploy STUN and TURN servers. A significant fraction of real-world users sit behind symmetric NATs or restrictive firewalls where direct media paths fail. Without a TURN relay, those users simply cannot connect. Budget TURN capacity, since relayed media consumes bandwidth on the TURN host.
Tune codecs and bitrate to your scenario. Limit the negotiated codecs to the ones you actually want, cap bitrates per endpoint based on resolution targets, and remember that every simultaneous HD stream multiplies server load. Kurento's CPU usage scales with the number of streams and any processing elements in the pipeline, so filters and mixing are the first things to profile.
Finally, plan for scale from day one. A single Kurento instance has finite capacity, so run multiple instances behind a load balancer or a session-aware router, keep signaling stateless so any application server can serve any user, and monitor per-instance CPU and bandwidth so you can add capacity before quality degrades. For teams that want conferencing, recording, and adaptive streaming without operating this stack, VideoSDK's interactive live streaming and calling SDKs provide a managed alternative with network-adaptive streaming built in.
Definitions Glossary
Kurento Media Server (KMS): The open-source server process that receives, processes, and delivers WebRTC media streams. It exposes a WebSocket API that application servers use to build media pipelines.
MediaPipeline: A container in Kurento that holds a chain of connected media elements. Media flows through the pipeline from one element to the next, enabling processing, recording, and routing.
WebRtcEndpoint: The Kurento media element that terminates a WebRTC connection. It performs SDP offer/answer negotiation and ICE candidate exchange on behalf of the server.
SDP Offer/Answer: The session negotiation model in WebRTC where one side describes the media it wants to exchange and the other side responds with a matching description.
ICE Candidates: Potential network addresses and ports that WebRTC peers exchange to find a working media route, including host, server-reflexive, and relayed candidates discovered via STUN and TURN.
Trickle ICE: The practice of sending ICE candidates as they are discovered rather than waiting for gathering to complete, which speeds up connection setup.
Key Takeaways
- Kurento WebRTC places a media server between participants, enabling server-side recording, mixing, filtering, and broadcasting that pure peer-to-peer WebRTC cannot do.
- The WebRtcEndpoint is the bridge between the browser and Kurento, handling SDP negotiation and ICE candidate exchange through your signaling server.
- HTTPS and secure WebSockets are mandatory in production; browsers block camera and microphone access on insecure origins.
- Most connection failures trace back to ICE problems, so deploy STUN and TURN servers and open the Kurento media port range in every firewall.
- Scaling Kurento means multiple instances behind a load balancer with stateless signaling, or choosing a managed platform like VideoSDK that handles infrastructure, recording, and adaptive streaming for you.
Conclusion
Kurento WebRTC gives you a powerful, open-source path to server-side media processing: a pipeline model for composing endpoints, filters, and recorders, and a WebRtcEndpoint that handles the messy details of SDP and ICE negotiation. The trade-off is operational ownership, from HTTPS and TURN configuration to multi-instance scaling and capacity planning.
If you want to ship real-time video faster, VideoSDK's video calling SDKs cover ten-plus platforms with recording, transcription, and network-adaptive streaming built in, and you can start free at app.videosdk.live. Explore the Kurento GitHub repository for tutorials and demos, and check the VideoSDK code samples for ready-to-run calling examples. What are you building with real-time video? Drop a comment, I'd love to hear about your Kurento WebRTC use case.
Free $20 Balance for AI Voice Agents & Video Calls
FAQ