deepgram-dotnet-speech-to-text

name

deepgram-dotnet-speech-to-text

description

Use when writing or reviewing C# code in this repo that calls Deepgram Speech-to-Text for prerecorded or live transcription. Covers `ClientFactory.CreateListenRESTClient()` with `TranscribeUrl` / `TranscribeFile`, and `ClientFactory.CreateListenWebSocketClient()` with `Connect`, `Subscribe`, and `Send`. Use `deepgram-dotnet-audio-intelligence` for summaries/sentiment/topics overlays, `deepgram-dotnet-conversational-stt` for Flux-specific work, and `deepgram-dotnet-voice-agent` for full-duplex assistants.

Using Deepgram Speech-to-Text (.NET SDK)

Basic transcription for prerecorded audio (REST) or live audio (WebSocket).

When to use this product

• REST — one-shot transcription of a file, stream, or hosted URL.
• WebSocket — continuous live transcription for microphone, file streaming, or relay streams.

Use a different skill when:

• You want summaries, sentiment, topics, intents, redaction, or diarization guidance on /listen → deepgram-dotnet-audio-intelligence.
• You need Flux / conversational turn-taking semantics → deepgram-dotnet-conversational-stt.
• You need STT + LLM + TTS over one socket → deepgram-dotnet-voice-agent.

Authentication

dotnet add package Deepgram

using Deepgram;

Library.Initialize();

// Reads DEEPGRAM_API_KEY by default.
var client = ClientFactory.CreateListenRESTClient();

The SDK also accepts DEEPGRAM_ACCESS_TOKEN via DeepgramHttpClientOptions / DeepgramWsClientOptions. In this repo, async methods return Task<T> but do not use an Async suffix.

Quick start — REST (URL)

using Deepgram;
using Deepgram.Models.Listen.v1.REST;

Library.Initialize();

var client = ClientFactory.CreateListenRESTClient();
var response = await client.TranscribeUrl(
    new UrlSource("https://dpgr.am/bueller.wav"),
    new PreRecordedSchema()
    {
        Model = "nova-3",
        SmartFormat = true,
        Punctuate = true,
        Keyterm = new List<string> { "Bueller" },
    });

Console.WriteLine(response.Results.Channels[0].Alternatives[0].Transcript);

Quick start — REST (file)

using Deepgram.Models.Listen.v1.REST;

var client = ClientFactory.CreateListenRESTClient();
var audioData = File.ReadAllBytes("audio.wav");

var response = await client.TranscribeFile(
    audioData,
    new PreRecordedSchema()
    {
        Model = "nova-3",
        Punctuate = true,
    });

You can also call TranscribeFile(Stream source, ...) when you already have a Stream.

Quick start — WebSocket (live)

using Deepgram;
using Deepgram.Microphone;
using Deepgram.Models.Listen.v2.WebSocket;

Library.Initialize();

var liveClient = ClientFactory.CreateListenWebSocketClient();

await liveClient.Subscribe(new EventHandler<ResultResponse>((sender, e) =>
{
    var transcript = e.Channel.Alternatives[0].Transcript;
    if (!string.IsNullOrWhiteSpace(transcript))
    {
        Console.WriteLine(transcript);
    }
}));

bool connected = await liveClient.Connect(new LiveSchema()
{
    Model = "nova-3",
    Encoding = "linear16",
    SampleRate = 16000,
    InterimResults = true,
    UtteranceEnd = "1000",
    VadEvents = true,
});

if (!connected)
{
    Console.Error.WriteLine("WebSocket connection failed — check API key and network.");
    return;
}

var microphone = new Microphone(liveClient.Send);
microphone.Start();
Console.ReadKey();
microphone.Stop();
await liveClient.Stop();

Key params

REST PreRecordedSchema: Model, Language, Encoding, SampleRate, Punctuate, SmartFormat, Keyterm, Utterances, Paragraphs. Full list in Deepgram/Models/Listen/v1/REST/PreRecordedSchema.cs.

WebSocket LiveSchema: Model, Encoding, SampleRate, InterimResults, UtteranceEnd, VadEvents, Endpointing, Keyterm. Full list in Deepgram/Models/Listen/v2/WebSocket/LiveSchema.cs.

References

• In-repo: Deepgram/Clients/Listen/v1/REST/Client.cs, Deepgram/Clients/Listen/v2/WebSocket/Client.cs
• OpenAPI (REST): https://developers.deepgram.com/openapi.yaml
• AsyncAPI (WSS): https://developers.deepgram.com/asyncapi.yaml
• Product docs: https://developers.deepgram.com/reference/speech-to-text/listen-pre-recorded, https://developers.deepgram.com/reference/speech-to-text/listen-streaming

Gotchas

1. Use the real .NET surface. This SDK uses await client.TranscribeUrl(...), not TranscribeUrlAsync(...).
2. REST and streaming use different model namespaces. REST is Deepgram.Models.Listen.v1.REST; live is Deepgram.Models.Listen.v2.WebSocket.
3. Streaming events are subscription-based. Register Subscribe(...) handlers before Connect(...).
4. Raw audio must match Encoding + SampleRate. Wrong declarations produce bad transcripts or server errors.
5. Keyterm is guarded. Listen.v2.WebSocket.Client.Connect throws if you use Keyterm with a non-nova-3 model.
6. Callback flows are separate methods. Use TranscribeUrlCallBack / TranscribeFileCallBack; sync methods reject CallBack in PreRecordedSchema.
7. Deepgram.Microphone is optional. It is a helper package/project, not required for file or URL transcription.

Example files in this repo

• examples/speech-to-text/rest/url/Program.cs
• examples/speech-to-text/rest/file/Program.cs
• examples/speech-to-text/websocket/file/Program.cs
• examples/speech-to-text/websocket/http/Program.cs
• examples/speech-to-text/websocket/microphone/Program.cs
• tests/edge_cases/stt_v1_client_example/

Cross-language product knowledge (API reference, recipes, MCP setup): npx skills add deepgram/skills.