Streaming AudioFlow over Ktor

The Ktor extension adds tiny adapters between Kodio's AudioFlow and Ktor's WebSocket / Server-Sent-Events 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.

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)

Or call WebSocketSession.receiveAudioFlow() from any custom handler that already manages the session lifecycle.

Pull an AudioFlow from a server

Symmetrically, fetch a server-pushed AudioFlow into a Kodio Player:

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

Kodio.play { player ->
    player.load(AudioRecording.fromAudioFlow(flow))
    player.start()
}

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.1.5")
}

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, …).

Last modified: 27 April 2026