Streaming AudioFlow over Ktor

The Ktor extension adds adapters between Kodio's AudioFlow and Ktor's WebSocket plumbing so you can stream live mic capture to a backend (or pull a remote stream into a Player) without reinventing the framing.

Wire format

The protocol is intentionally minimal:

Format header: the AudioFormat is encoded with AudioFormat.encodeToByteArray(), prefixed with the four ASCII bytes KDIO, and sent as the first binary frame.
Chunks: every subsequent binary frame is one raw PCM byte chunk in the declared format.

The constants live in AudioFlowWireFormat.

Send a recorder over WebSocket

Stream a live recording from a mobile/desktop client to a server endpoint:

val client = HttpClient(CIO) { install(WebSockets) }
val recorder = Kodio.recorder(quality = AudioQuality.Voice)

recorder.start()
recorder.audioFlow!!.sendOverWebSocket(client, "wss://my-app.example.com/api/audio")
recorder.stop()
client.close()

AudioFlow.sendOverWebSocket opens the socket, sends the format header, forwards every chunk as a binary frame, and closes cleanly.

For an already-open session, use AudioFlow.sendInto(session).

Receive an AudioFlow on the server

A Ktor server can read the same protocol with one call:

embeddedServer(CIO, port = 8080) {
    install(WebSockets)
    routing {
        webSocket("/api/audio") {
            val flow = receiveAudioFlow()
            println("Receiving ${flow.format}")
            flow.collect { chunk -> /* persist, transcribe, ... */ }
        }
    }
}.start(wait = true)

WebSocketSession.receiveAudioFlow() is for server-side handlers that already manage the session lifecycle.

Pull an AudioFlow from a server

Fetch a server-pushed AudioFlow and play it:

val client = HttpClient(CIO) { install(WebSockets) }
val flow = client.receiveAudioFlowFromWebSocket("wss://my-app.example.com/api/audio/play")

Kodio.play(flow)

To collect the stream into a recording first:

val recording = AudioRecording.fromAudioFlow(flow)
Kodio.play(recording)

Or use the block overload for manual control:

Kodio.play(recording) { player ->
    player.start()
    player.awaitComplete()
}

SSE fallback

The current release ships WebSocket support only. SSE-based delivery (for environments where WebSockets are blocked) is planned as a follow-up and will re-use the same KDIO-prefixed header. Track GitHub issue #6 for status.

Maven coordinates

dependencies {
    implementation("space.kodio.extensions:ktor:0.2.0")
}

This module declares kodio-core, ktor-client-core, and ktor-client-websockets as api dependencies. Bring your own engine (ktor-client-cio, ktor-client-darwin, ktor-client-js, and so on).

Last modified: 03 July 2026