Skip to content

C# WebSocket SDK

Koldan.WebSocket.Sdk is a standalone C# SDK for the real-time speech recognition WebSocket API. It is separate from the generated REST SDK and focuses on streaming audio, receiving partial/final transcripts, and discovering streaming-capable models.

Install

Download and extract the SDK archive:

Download koldan-websocket-sdk-csharp-9.0.4.zip

Expand-Archive .\koldan-websocket-sdk-csharp-9.0.4.zip -DestinationPath .\koldan-websocket-sdk-csharp
dotnet add package Koldan.WebSocket.Sdk --source .\koldan-websocket-sdk-csharp\nuget

unzip koldan-websocket-sdk-csharp-9.0.4.zip -d koldan-websocket-sdk-csharp
dotnet add package Koldan.WebSocket.Sdk --source ./koldan-websocket-sdk-csharp/nuget

The archive contains a local NuGet package folder with the SDK package and its dependencies.

Configure

$env:KOLDAN_BASE_URL = "https://koldan.dixilang.com"
$env:KOLDAN_API_KEY = "YOUR_API_KEY"
$env:KOLDAN_MODEL = "medical-streaming"
$env:KOLDAN_PCM_FILE = "C:\path\to\example-16kHz-S16LE-mono.pcm"

export KOLDAN_BASE_URL="https://koldan.dixilang.com"
export KOLDAN_API_KEY="YOUR_API_KEY"
export KOLDAN_MODEL="medical-streaming"
export KOLDAN_PCM_FILE="/path/to/example-16kHz-S16LE-mono.pcm"

KOLDAN_MODEL is optional. When it is not set, examples call ListStreamingModelsAsync() and use the first model whose capabilities include supportsStreaming: true. KOLDAN_PCM_FILE should point to a raw PCM file you provide.

Stream Raw PCM Audio

The SDK sends authentication inside the session.start WebSocket message, matching the Koldan protocol. Model discovery uses a small REST call to GET /api/v1/speech-services/models and filters to streaming-capable aliases.

using Koldan.WebSocket.Sdk;

using var client = new KoldanStreamingClient(new KoldanStreamingClientOptions
{
    BaseUrl = new Uri(Environment.GetEnvironmentVariable("KOLDAN_BASE_URL")!),
    ApiKey = Environment.GetEnvironmentVariable("KOLDAN_API_KEY")
});

var model = Environment.GetEnvironmentVariable("KOLDAN_MODEL")
    ?? (await client.ListStreamingModelsAsync()).First().Id;

await using var session = await client.StartSessionAsync(new StreamingSessionOptions
{
    Model = model,
    Language = "he",
    EnableEndpointDetection = true
});

var reader = Task.Run(async () =>
{
    await foreach (var message in session.Messages.ReadAllAsync())
    {
        switch (message)
        {
            case PartialResultMessage partial:
                Console.WriteLine($"Partial: {partial.Transcript}");
                break;
            case FinalResultMessage final:
                Console.WriteLine($"Final[{final.SegmentIndex}]: {final.Transcript}");
                break;
            case SessionCompletedMessage:
                return;
            case ErrorMessage error:
                throw new KoldanStreamingProtocolException($"{error.Code}: {error.Message}");
        }
    }
});

var pcmFile = Environment.GetEnvironmentVariable("KOLDAN_PCM_FILE")
    ?? "example-16kHz-S16LE-mono.pcm";

await foreach (var frame in ReadPcmFramesAsync(pcmFile))
{
    await session.SendAudioAsync(frame);
    await Task.Delay(TimeSpan.FromMilliseconds(100));
}

await session.CompleteAsync();
await reader;

static async IAsyncEnumerable<byte[]> ReadPcmFramesAsync(string path)
{
    var buffer = new byte[3200]; // 100 ms at 16 kHz, 16-bit, mono
    await using var file = File.OpenRead(path);

    int read;
    while ((read = await file.ReadAsync(buffer)) > 0)
    {
        var frame = new byte[read];
        Buffer.BlockCopy(buffer, 0, frame, 0, read);
        yield return frame;
    }
}

Audio Requirements

Send audio as binary WebSocket frames:

Property Value
Encoding Raw PCM, signed 16-bit little-endian
Channels Mono
Sample rate Usually 16 kHz
Recommended frame size 20-100 ms
Maximum frame size 65,536 bytes

Provide your own raw PCM input file that matches these requirements. The SDK archive does not include audio files.

Microphone Example With NAudio

The SDK archive includes a Windows microphone sample at:

koldan-websocket-sdk-csharp/examples/NAudioMicrophone

Run it with:

dotnet run --project .\koldan-websocket-sdk-csharp\examples\NAudioMicrophone\Koldan.WebSocket.Sdk.Examples.NAudioMicrophone.csproj

The sample uses WaveInEvent with:

new WaveFormat(16000, 16, 1)

and BufferMilliseconds = 100, which produces 3,200-byte frames for real-time streaming.

Error Handling

The SDK exposes typed messages and typed exceptions:

Type When it appears
ErrorMessage Server-side protocol, quota, auth, engine, or bandwidth error sent over WebSocket
KoldanStreamingConfigurationException Invalid SDK options, missing model/auth, invalid diarization options, oversized audio frame
KoldanStreamingProtocolException Unexpected protocol state or invalid server message
KoldanStreamingRestException Model discovery REST call failed; includes HTTP status and response body
KoldanStreamingWebSocketException WebSocket connect/send/receive failure