# Deepgram Dotnet Speech To Text

> 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.

- Skill: `deepgram/deepgram-dotnet-speech-to-text` (Agent Skill)
- Install (CLI): `npx skillmds@latest add deepgram/deepgram-dotnet-speech-to-text`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deepgram/deepgram-dotnet-speech-to-text/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: deepgram (https://skillmd.com/u/deepgram)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deepgram/deepgram-dotnet-speech-to-text

---


# 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

```bash
dotnet add package Deepgram
```

```csharp
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)

```csharp
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)

```csharp
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)

```csharp
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`.