WebRTC client

Web Real-Time Communication (WebRTC) is a set of standards and APIs for real-time, peer-to-peer communication in browsers and native apps.

The WebRTC client in Ktor enables real-time peer-to-peer communication in multiplatform projects. With WebRTC, you can build features such as:

Video and voice calls
Multiplayer games
Collaborative applications, such as whiteboards and editors
Low-latency data exchange between clients

Add dependencies

To use WebRtcClient, you need to include the ktor-client-webrtc artifact in the build script:

implementation("io.ktor:ktor-client-webrtc:$ktor_version")

implementation "io.ktor:ktor-client-webrtc:$ktor_version"

        
                    <dependency>
                        <groupId>io.ktor</groupId>
                        <artifactId>ktor-client-webrtc-jvm</artifactId>
                        <version>${ktor_version}</version>
                    </dependency>
                    
        

Create a client

When creating a WebRtcClient, choose an engine based on your target platform:

JS/Wasm: JsWebRtc uses the browser WebRTC and Media Capture and Streams APIs.
Android: AndroidWebRtc uses the precompiled Stream WebRTC library for Android and Android media APIs.
iOS: IosWebRtc uses the WebRTC SDK and the native AVFoundation framework.
JVM: JvmWebRtc uses native WebRTC bindings provided by webrtc-java.

You can then provide platform-specific configuration similar to HttpClient. STUN/TURN servers are required for ICE to work correctly. You can use existing solutions such as coturn:

val jsClient = WebRtcClient(JsWebRtc) {
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}

val androidClient = WebRtcClient(AndroidWebRtc) {
    context = appContext // Required: provide Android context
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}

val iosClient = WebRtcClient(IosWebRtc) {
    // the same configuration, no extra context needed
}

val jvmClient = WebRtcClient(JvmWebRtc) {
    defaultConnectionConfig = {
        iceServers = listOf(WebRtc.IceServer("stun:stun.l.google.com:19302"))
    }
}

Create a connection and negotiate SDP

After creating a WebRtcClient, the next step is to create a peer connection. A peer connection is the core object that manages the real-time communication between two clients.

To establish a connection, WebRTC uses the Session Description Protocol (SDP). This involves three steps:

One peer (the caller) creates an offer.
The other peer (the callee) responds with an answer.
Both peers apply each other’s descriptions to complete the setup.

// Caller creates a connection and an offer
val caller = jsClient.createPeerConnection()
val offer = caller.createOffer()
caller.setLocalDescription(offer)
// send offer.sdp to the remote peer via your signaling mechanism

// Callee receives the offer and creates an answer
val callee = jsClient.createPeerConnection()
callee.setRemoteDescription(
    WebRtc.SessionDescription(WebRtc.SessionDescriptionType.OFFER, remoteOfferSdp)
)
val answer = callee.createAnswer()
callee.setLocalDescription(answer)
// send answer.sdp back to the caller via signaling

// Caller applies the answer
caller.setRemoteDescription(
    WebRtc.SessionDescription(WebRtc.SessionDescriptionType.ANSWER, remoteAnswerSdp)
)

Exchange ICE candidates

Once SDP negotiation is complete, peers still need to discover how to connect across networks. Interactive Connectivity Establishment (ICE) allows peers to find network paths to each other.

Each peer gathers its own ICE candidates.
These candidates must be sent to the other peer through your chosen signaling channel.
Once both peers add each other’s candidates, the connection can succeed.

// Collect and send local candidates
scope.launch {
    caller.iceCandidates.collect { candidate ->
        // send candidate.candidate, candidate.sdpMid, candidate.sdpMLineIndex to remote peer
    }
}

// Receive and add remote candidates
callee.addIceCandidate(WebRtc.IceCandidate(candidateString, sdpMid, sdpMLineIndex))

// Optionally wait until all candidates are gathered
callee.awaitIceGatheringComplete()

Use a data channel

WebRTC supports data channels, which let peers exchange arbitrary messages. This is useful for chat, multiplayer games, collaborative tools, or any low-latency messaging between clients.

Creating a channel

To create a channel on one side, use the .createDataChannel() method:

val channel = caller.createDataChannel("chat")

You can then listen for data channel events on the other side:

scope.launch {
    callee.dataChannelEvents.collect { event ->
        when (event) {
            is DataChannelEvent.Open -> println("Channel opened: ${event.channel}")
            is DataChannelEvent.Closing -> println("Channel closing: ${event.channel}")
            is DataChannelEvent.Closed -> println("Channel closed: ${event.channel}")
            is DataChannelEvent.BufferedAmountLow ->
                println("Buffered amount is low: ${event.channel}")
            is DataChannelEvent.Error ->
                println("Channel error: ${event.reason}")
        }
    }
}

DataChannelEvent can represent the following events:

Open: The channel is ready to send and receive data.
Closing: The channel has started closing.
Closed: The channel is closed.
BufferedAmountLow: The amount of buffered outgoing data has dropped to or below bufferedAmountLowThreshold.
Error: An error occurred on the channel. This event is not emitted on JVM. Send failures throw WebRtc.IOException instead.

To receive BufferedAmountLow set a threshold on the channel:

channel.setBufferedAmountLowThreshold(16 * 1024)

Sending and receiving messages

Channels use a Channel-like API, familiar to Kotlin developers:

// Send a message
scope.launch { channel.send("hello") }

// Receive messages
scope.launch { println("received: " + channel.receiveText()) }

Add and observe media tracks

In addition to data channels, WebRTC supports media tracks for audio and video. This allows you to build applications such as video calls or screen sharing.

Creating local tracks

You can request audio or video tracks from local devices (microphone, camera):

val audio = rtcClient.createAudioTrack {
    echoCancellation = true
}
val video = rtcClient.createVideoTrack {
    width = 1280
    height = 720
}

val pc = jsClient.createPeerConnection()
pc.addTrack(audio)
pc.addTrack(video)

Media capture is platform-specific:

On the web, it uses navigator.mediaDevices.getUserMedia.
On Android, it uses the Camera2 API. You need to request camera and microphone permissions separately.
On iOS, it uses the AVFoundation API. You also need to request the required permissions separately.
On JVM, it uses webrtc-java to access the system camera and microphone. The operating system may prompt the user for permission.

The client selects the most suitable media device based on the specified constraints. If no suitable device is available, it throws WebRtcMedia.DeviceException.

Receiving remote tracks

You can also listen for remote media tracks:

scope.launch {
    pc.trackEvents.collect { event ->
        when (event) {
            is TrackEvent.Add -> println("Remote track added: ${event.track.id}")
            is TrackEvent.Remove -> println("Remote track removed: ${event.track.id}")
        }
    }
}

Platform-specific logic

This API provides high-level abstractions, but there are use-cases that may require accessing platform-specific APIs. You can use the .getNative() extension functions to retrieve the underlying implementations. Platform-specific libraries are exposed as transitive libraries, except for WebRTC-SDK CocoaPod on iOS.

// DOM API is imported from `kotlin-wrappers`

val videoTrack = rtcClient.createVideoTrack()
val jsStream = MediaStream().apply {
    val nativeTrack: MediaStreamTrack = videoTrack.getNative()
    addTrack(nativeTrack)
}

// start rendering video
val videoElement = document.createElement("video") as HTMLVideoElement
videoElement.srcObject = jsStream
videoElement.autoplay = true

// stop rendering video
videoElement.srcObject = null

val eglBase = org.webrtc.EglBase.create() // should be unique in the app

val videoTrack = rtcClient.createVideoTrack()
val nativeTrack: org.webrtc.VideoTrack = videoTrack.getNative()

// create a surface to render incoming video frames
val renderer = org.webrtc.SurfaceViewRenderer()
renderer.init(eglBase.eglBaseContext, null)

// start rendering video
videoTrack.addSink(renderer)

// stop rendering video
videoTrack.removeSink(renderer)
renderer.release()

val videoTrack = rtcClient.createVideoTrack()
val nativeTrack: RTCVideoTrack = videoTrack.getNative()

// create a surface to render incoming video frames
val videoView = RTCMTLVideoView() // iOS UIKit View

// start rendering video
nativeTrack.addRenderer(videoView)

// stop rendering video
nativeTrack.removeRenderer(videoView)

To use the WebRTC-SDK API, you need to install it manually:

// build.gradle.kts
kotlin {
    cocoapods {
        pod("WebRTC-SDK") {
            version = "137.7151.04" // or newer
            // Default module name is `WebRTC-SDK`, you can change it for convenience
            moduleName = "WebRTC"
            packageName = "WebRTC"
        }
    }
}

val videoTrack = rtcClient.createVideoTrack()
val nativeTrack: dev.onvoid.webrtc.media.video.VideoTrack = videoTrack.getNative()

// There is no built-in video view. Attach a sink and render frames
// with Swing, JavaFX, Compose, or another UI toolkit.
nativeTrack.addSink { frame ->
    // draw frame.buffer to your UI, then frame.release()
}

// On Android, iOS, and JVM, audio track playback can be started/stopped without using `getNative()`
// In browser, you still should create an <audio/> element.

val audio = rtcClient.createAudioTrack()
// start playing audio
audio.enable(true)
// stop playing audio
audio.enable(false)

Limitations

The WebRTC client is experimental and has the following limitations:

Signaling: Signaling is not included. You need to implement it separately, for example, with WebSockets or HTTP.
Platform support: The client supports JavaScript/Wasm, Android, iOS, and JVM desktop. Kotlin/Native support is planned for a future release.
Permissions: Permissions must be handled by your application. Browsers prompt users for microphone and camera access. Android and iOS require runtime permission requests. On JVM, camera and microphone access are granted at the operating-system level.
JVM limitations: Candidate prefetching is not supported. iceCandidatePoolSize must be 0 or omitted. The facingMode, aspectRatio, and resizeMode video constraints are not supported and throw an exception if set. DataChannelEvent.Error is not emitted.
Media features: Only basic audio and video tracks are supported. Screen sharing, device selection, simulcast, and advanced RTP features are not yet available.
Connection statistics: Statistics are available but differ across platforms and do not follow a unified schema.

02 September 2026