deepgram-dotnet-text-to-speech

用途

该技能适用于在本仓库中编写或审查调用 Deepgram 文本转语音（Text-to-Speech）的 C# 代码。它覆盖 ClientFactory.CreateSpeakRESTClient() 及 ToStream / ToFile 等方法的用法。

主要能力

提供两种将文本转换为音频的方式：

REST：合成完整文本，并保存或处理返回的音频。
WebSocket：将文本流式发送给 Deepgram，并增量接收音频分块。

需要注意：如果需要在一个会话中完成“听、思考、说”的智能体，应改用 deepgram-dotnet-voice-agent 技能。

安装与认证

dotnet add package Deepgram

using Deepgram;

Library.Initialize();
var client = ClientFactory.CreateSpeakRESTClient();

SDK 默认读取 DEEPGRAM_API_KEY，同时也支持通过 DeepgramHttpClientOptions / DeepgramWsClientOptions 使用 bearer 访问令牌。

使用方式

REST 快速开始

using Deepgram;
using Deepgram.Models.Speak.v1.REST;

Library.Initialize();

var client = ClientFactory.CreateSpeakRESTClient();
var response = await client.ToFile(
    new TextSource("Hello World!"),
    "output.mp3",
    new SpeakSchema()
    {
        Model = "aura-2-thalia-en",
    });

Console.WriteLine(response);

如果希望在内存中获取字节，调用 ToStream(...) 并读取 response.Stream。

WebSocket 快速开始

using Deepgram;
using Deepgram.Models.Speak.v2.WebSocket;

Library.Initialize();

var speakClient = ClientFactory.CreateSpeakWebSocketClient();

await speakClient.Subscribe(new EventHandler<AudioResponse>((sender, e) =>
{
    if (e.Stream != null)
    {
        // Streaming Speak (Encoding = "linear16") delivers raw PCM — no WAV header.
        // Save as .raw, or prepend a valid WAV header (see examples/text-to-speech/websocket/simple/Program.cs).
        using (var writer = new BinaryWriter(File.Open("output.raw", FileMode.Append)))
        {
            writer.Write(e.Stream.ToArray());
        }
    }
}));

bool connected = await speakClient.Connect(new SpeakSchema()
{
    Encoding = "linear16",
    SampleRate = 48000,
});

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

speakClient.SpeakWithText("Hello World!");
speakClient.Flush();
Console.ReadKey();
await speakClient.Stop();

关键参数

REST SpeakSchema：Model、BitRate、CallBack、CallBackMethod、Container、Encoding、SampleRate。
WebSocket SpeakSchema：Model、BitRate、Encoding、SampleRate。
流式控制：SpeakWithText、Flush、Clear、Close、SendMessageImmediately。

适用场景与限制

REST 适合合成完整文本并保存或处理音频；WebSocket 适合流式输入与增量接收音频。
需要同一会话内完成听、思考、说的智能体场景，请使用 deepgram-dotnet-voice-agent。

注意事项

方法名是 ToStream / ToFile，而不是 GenerateAsync，请使用实际的 .NET 名称。
REST 会返回音频元数据以及一个 MemoryStream。ToFile 会替你写出文件，然后清空 response.Stream。
WebSocket 输出通过 AudioResponse.Stream 到达，需要自行写出或播放这些字节。
Flush 很重要。如果从不调用 Flush()，可能会无限等待缓冲文本被合成。
自动刷新可配置。DeepgramWsClientOptions.AutoFlushSpeakDelta 可为逐 token 输入自动刷新。
输出格式需与输出目标匹配。如果请求 linear16 + 48000，WAV 头 / 播放路径必须与之匹配。
回调流程是独立的。使用 StreamCallBack(...) 进行异步 REST 回调处理。

参考

仓库内：Deepgram/Clients/Speak/v1/REST/Client.cs、Deepgram/Clients/Speak/v2/WebSocket/Client.cs、Deepgram/Models/Speak/v1/REST/SpeakSchema.cs、Deepgram/Models/Speak/v2/WebSocket/SpeakSchema.cs
OpenAPI（REST）：https://developers.deepgram.com/openapi.yaml
AsyncAPI（WSS）：https://developers.deepgram.com/asyncapi.yaml
产品文档：https://developers.deepgram.com/reference/text-to-speech/speak-request、https://developers.deepgram.com/docs/tts-models

仓库内示例文件

examples/text-to-speech/rest/file/hello-world/Program.cs
examples/text-to-speech/rest/file/woodchuck/Program.cs
examples/text-to-speech/websocket/simple/Program.cs
tests/edge_cases/tts_v1_client_example/

跨语言产品知识

API 参考、示例配方、MCP 设置：npx skills add deepgram/skills。