mcpField
D
deepgram-speech

deepgram-speech

github.com/calesthio创意与媒体219101 次安装15 周前更新
代码仓库

关于 deepgram-speech

这是面向使用 Deepgram 进行语音转写、字幕、语音分析、语音 Agent 音频和文本转语音的制作技能。它按交付需求指导选择 API 路径、模型、功能与数据处理方案。

主要功能

  1. 01选择预录或实时转写
  2. 02生成带时间信息的字幕
  3. 03执行说话人区分与音频分析
  4. 04使用 Aura 生成语音
  5. 05配置实时语音 Agent

适用场景

  1. 01为播客或视频制作字幕
  2. 02为实时活动提供语音转写
  3. 03构建可打断对话的语音 Agent
  4. 04生成旁白或语音片段

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill deepgram-speech

安装后在 Claude Code 中输入/deepgram-speech确认已加载。

附带文件EVAL.md

详细介绍

Deepgram 语音生产

当 Deepgram 是转录、字幕制作、语音分析、语音 Agent 音频或文本转语音素材的候选服务商时，请使用此技能。应将 Deepgram 视为生产级语音平台，而不是通用的“生成音频”按钮：根据交付物对延迟、准确性、语言、隐私和产物的要求，选择端点、模型、功能和数据保管方案。

此技能中的事实已于 2026-07-10 根据 Deepgram 官方文档和定价信息核实。购买或发布前，请再次核实易变信息：公开模型 ID、语言支持、附加功能价格、并发量、区域可用性和早期访问控制。

使用的主要官方资料：

已记录的功能概览

语音转文字

Deepgram 提供 3 种 STT 路径：

  1. 通过 REST POST /v1/listen 处理预录制音频。适用于播客／视频转录、后期制作字幕、批量媒体档案、通话录音、编辑分析，以及任何完整文件处理时效比亚秒级中间结果更重要的任务。它接受本地二进制音频或托管 URL，支持回调，并且返回的转录结果是 Deepgram 唯一会提供的结果，除非你将其保存。
  2. 通过 WebSocket wss://api.deepgram.com/v1/listen 进行实时流式处理。适用于实时字幕、会议／活动转录、实时制作日志和 Agent 辅助转录。它可以输出中间和最终结果、语音事件、端点检测、话语事件和词级时间戳。
  3. 通过 Flux（当前文档中的 /v2/listen）进行轮次式对话 STT。适用于实时语音 Agent，以及需要关注轮次结束行为、对打断敏感的对话。Flux 通常不用于离线转录。

Deepgram 文档中的当前模型建议，已于 2026-07-10 核实：

  • nova-3 / Nova-3：性能最高的通用 ASR，但不支持模型原生轮次检测。适用于预录制媒体、实时字幕、会议、多语言／嘈杂／远场内容，以及大多数转录交付任务。
  • flux-*：面向 Agent 的对话式语音识别。当检测用户何时说完属于产品行为的一部分时使用。
  • nova-2：对于 Nova-3 尚不支持的语言／功能，以及 Deepgram 文档注明支持填充词识别的需求，可作为备用方案。
  • Whisper Cloud：仅适用于预录制音频；Deepgram 文档注明了额外的并发限制和长音频处理限制。不要将其用于实时流。
转录文本格式与增强

Deepgram 可以返回词级时间戳和置信度分数。适合生产环境使用的 STT 选项包括标点、智能格式、段落、话语、数字、脏话过滤、编辑遮盖、搜索／替换、关键词／关键术语、说话人分离、多声道、语言选择、语言检测和语码转换。

重要限制：

  • smart_format=true 通常用于提升可读性；Deepgram 文档说明，对于支持的语言，它至少包含标点和段落处理，并为英语提供更全面的日期、时间、货币、电话号码、电子邮件和 URL 格式处理。
  • 文档说明支持 diarize=true，但流式 API 参考将其标记为已弃用，建议改用 diarize_model；如有可用版本，请使用 diarize_model=latest 或固定到有文档说明的版本。当前参考文档中的流式处理不支持说话人分离 v2。
  • 说话人标签是数字形式的说话人聚类编号，并非经过验证的真人身份。
  • 每个说话人／音源单独占用一个声道时，使用多声道。说话人混在同一声道中时，使用说话人分离。如果两种方式都可行，在生产通话和讨论小组中优先采用清晰的声道分离。
  • 语言检测会识别／转录占主导地位的语言，并为支持的语言返回语言代码／置信度；当前语言检测文档明确指出，流式处理不支持此功能，并建议对实时多语言音频使用多语言模型。
  • language=multi 和 Flux 多语言支持的是语码转换转录，而非翻译。除非当前官方文档明确说明 Deepgram STT 支持所需工作流的翻译，否则不要承诺它能生成翻译后的字幕；应在转录后单独进行翻译。
字幕与字幕文件

Deepgram 可用于生成带时间信息的字幕文件，因为响应包含词级时间戳，且 Deepgram 提供 SRT／WebVTT 示例。但它不能替代视频编辑质量检查：

  • 根据单词或话语生成 SRT/VTT。
  • 根据平台要求调整换行、阅读速度和字幕时长。
  • 检查专有名称、数字、说话人变更、脏话政策和无障碍标签。
  • 如有需要，使用单独的合成器或视频工具将字幕压制到视频中。
音频智能

官方 STT／音频智能功能包括摘要、主题检测、意图识别、情感分析和实体检测。当前 Deepgram 文档列出了各功能的语言和流式处理限制，而且功能矩阵与某个单独功能页面之间至少存在一处明显不一致，因此在承诺支持的语言或流式处理能力之前，请立即核对相应功能页面。

经核实的安全生产解读（2026-07-10）：

  • 功能矩阵显示，情感分析、摘要和主题检测支持预录音频和英语。
  • 实体检测支持预录音频和部分流式使用；除非选择低延迟的 no_delay 行为（这可能会漏掉实体），否则流式处理可能要等到实体完整后才完成。
  • 官方文档显示，意图和主题基于上下文生成，并可接受自定义提示；应将其视为分析标签，而非确定性的分类体系。
  • 智能附加功能可能会降低实际并发能力。如果一次请求使用多项服务，Deepgram 的速率限制文档说明应以限制较低的服务为准。
文本转语音

Deepgram Aura 通过 REST POST /v1/speak 和 WebSocket wss://api.deepgram.com/v1/speak 提供 TTS。

经核实的 TTS 文档信息（2026-07-10）：

  • Aura 语音使用类似 aura-2-thalia-en 的模型 ID。
  • 官方 Aura 语言支持包括英语、西班牙语、德语、法语、荷兰语、意大利语和日语；语音模型文档列出了口音／变体。
  • REST 适合制作旁白文件、渲染语音片段、可供审核的录音和稳定的媒体资源。
  • TTS WebSocket 适合 LLM 令牌流式传输、IVR、语音 Agent 和即时播放。
  • Deepgram 说明，TTS 请求的输入上限为 2000 个字符，并提供了延迟参考：无流式传输时基准延迟约为 600 毫秒，示例模型中每 100 个字符约增加 40 毫秒。对于较长的旁白，为提高吞吐量，可将文本分块至接近上限；但为了提升性能和便于编辑，应在句子／节拍边界处分块。
  • Aura-2 控件包括英语和西班牙语 REST 与 WebSocket 接口中的语速和发音控制；文档规定语速范围为 0.7-1.5，Voice Agent 设置中另有一些早期访问限制说明。
  • Deepgram Aura TTS 提供预设语音生成。除非另行确认了官方合同／产品路径，否则不要暗示其支持自定义语音克隆或肖像复刻。
Voice Agent API 和实时音频

如果交付内容是交互式 Agent，而不只是转录文本或旁白文件，请使用 Deepgram Voice Agent。Voice Agent 通过 WebSocket 集成音频输入、STT、LLM 路由、TTS、工具／函数消息、对话文本和音频输出。连接后应立即发送 Settings 消息，以配置输入／输出音频、监听／思考／发言服务商、提示词、轮次管理和工具。

如果生产需求包括以下内容，应使用单独的 STT + LLM + TTS 组件，而不是 Voice Agent：

  • 确定性的离线资源；
  • 后期制作的配乐；
  • 独立的服务商评估；
  • 仅输出转录文本或字幕；
  • 播放语音前进行非实时的编辑审核。

经验性和运营观察

以下是运营模式，而非服务提供商的保证：

  • Deepgram 的实时体验通常在以小块、稳定且正确声明格式的方式发送音频时最佳。在流式集成中，“转录不佳”最常见的原因是 encoding、sample_rate、声道数错误，或容器格式与原始音频不匹配。
  • 低延迟设置可能降低编辑质量。中间转录结果、激进的端点检测、no_delay 和较小的 TTS 分块有助于提升响应速度，但会增加修订、误判为最终结果、实体遗漏和语音节奏不自然的情况。
  • 说话人分离质量容易受重叠发言、串音、背景音乐、房间回声和较短说话轮次影响。只要制作环节能够控制音频采集，干净的声道分配总是优于事后进行说话人分离。
  • 对于媒体制作，Deepgram 原始 JSON 的价值高于纯文本转录，因为它保留了词级时间戳、置信度、说话人／声道标签、请求 ID、警告和附加功能的输出。
  • TTS 旁白通常需要专为口语编写的文本，而不是直接照搬脚本中的书面语。标点、句子长度、发音提示和首字母缩写的拼写都会实质性影响 Aura 的输出。

生产启发式原则

除非用户要求另有规定，否则请遵循以下原则：

  • 完整转录和字幕选用 Nova-3；交互式 Agent 轮次交接选用 Flux。
  • 基于文件的媒体使用预录制 REST；只有在用户需要实时输出时才使用 WebSocket。
  • 即使交付格式为 SRT、VTT、TXT、CSV 或 EDL，也要保留完整的 JSON 响应文件。
  • 如果项目涉及人名、术语、口音、音乐或隐私敏感内容，在转录长项目之前先处理一个有代表性的短样本。
  • 将每项附加功能都视为一种权衡：它可能提升实用性，但也可能增加成本、降低并发能力、提高延迟，或引入故障／警告情况。
  • 对实时字幕，首先优化稳定性：确保音频格式正确，采用适度的端点检测，显示最终结果；如果显示中间结果，则应明确呈现修正过程。
  • 对 TTS，在确定使用长语音之前，先生成多个简短试听版本。批量合成前，固定语音 ID、语速、文本规范化规则、采样率／容器格式和发音覆盖项。

工作流方案

预录制转录和字幕
  1. 确认已取得处理音频的同意和相关权利。
  2. 检查媒体：时长、声道、采样率、语言、说话人、音乐／噪声和目标平台。
  3. 选择模型和功能：
    • 大多数生产音频使用 model=nova-3。
    • 使用 smart_format=true 获取易读的转录文本。
    • 使用 utterances=true 和／或 paragraphs=true 生成便于审核的片段。
    • 说话人混杂时，使用 diarize_model=latest 或当前文档中说明的说话人分离参数。
    • 声道可分离说话人时，使用 multichannel=true。
    • 必要时使用 redact=... 处理个人身份信息。
  4. 对于长任务或服务端工作流，使用回调；Deepgram 提供了有关异步处理和回调交付重试的文档。
  5. 保存原始响应、纯文本转录、SRT/VTT、警告、请求参数、模型、区域、请求 ID，以及源媒体的校验和。
  6. 对照音频进行质量检查。修正人名、数字、时间戳、说话人分离结果和字幕换行。
实时字幕
  1. 打开套接字之前，确认实时音频采集格式。对于原始音频，准确传递 encoding、sample_rate 和 channels。
  2. 除非需要类似 Agent 的轮次检测，否则实时流式处理使用 Nova-3。
  3. 仅当界面设计为支持文本修订时，才启用 interim_results=true；否则显示最终片段。
  4. 调整 endpointing、utterance_end_ms 和语音事件，以适应字幕节奏。
  5. 保留滚动转录缓冲区并持久化最终消息。网络中断在所难免；请实现重连行为并标记中断区段。
  6. 不要依赖实时说话人分离来按姓名识别人；应在审核后，或根据声道／来源元数据映射说话人。
语音 Agent
  1. 判断是否需要使用 Voice Agent。如果任务是“制作带旁白的视频”，请使用 TTS。如果任务是“构建交互式电话／网页 Agent”，Voice Agent 可能适用。
  2. WebSocket 连接后立即配置 Settings。
  3. 有意选择 listen／think／speak 提供商。Deepgram 文档显示，Deepgram TTS 是默认选项，并支持托管／自带 LLM／TTS 提供商；记录每项输出由哪个提供商生成。
  4. 在投入生产前，测试打断、插话、静音、端点检测、工具调用、错误／警告以及回退行为。
  5. 根据同意情况和隐私规则存储对话文本和事件日志；除非确有需要并获得授权，否则不要存储敏感的原始音频。
TTS 旁白
  1. 改写文本以适合语音播报：使用短句、易于读出的缩写、明确的停顿，以及适合生产环境的标点。
  2. 从当前文档中选择一个 Aura 语音 ID，例如 aura-2-thalia-en，并试听。
  3. 每个请求都必须低于文档规定的输入限制。对于较长的旁白，在句子／段落边界处分段，并将每段录音作为单独的产物存储。
  4. 在相应语言支持的情况下，使用发音控制处理品牌名称、医学术语或专有名词。
  5. 按要求的容器格式／采样率／编码导出。在 Deepgram 之外进行响度标准化和混音。

成本、配额和速率限制处理

Deepgram 的定价和配额变动频繁。请在执行当天核对定价页面和速率限制文档。

截至 2026-07-10，公开定价页面列出了 200 美元的免费额度，以及按用量付费的 STT 费率示例，例如 Flux English、Flux Multilingual、Nova-3 Monolingual 和 Nova-3 Multilingual，并分别列出了 Growth 费率。页面还列出了脱敏和关键术语提示等功能的附加定价。未经重新核对，请勿在客户报价中硬编码这些数值。

截至 2026-07-10，官方速率限制文档列出了因套餐、区域、产品和功能而异的并发上限。示例包括：

  • STT REST 预录音在公开表格中通常限制为约 50 个并发请求。
  • STT 流式处理限制因模型／套餐／区域而异，可能高于 REST。
  • 说话人分离和 Audio Intelligence 各自有更低的限制。
  • TTS REST 和 TTS 流式处理有各自的并发请求限制。
  • Voice Agent 的并发连接限制因套餐／区域而异。

如果一个请求组合使用多项服务，请按适用的最低限制进行规划。在生产环境中，实现排队、带退避的重试、断路器和按项目划分的用量标签。

隐私、安全、同意与权利

已记录的事实：

  • Deepgram 发布了安全与隐私资料，并表示已获得 SOC 2 Type 1 和 Type 2 认证；可通过账户渠道获取合规文档。
  • Deepgram 在速率限制文档中提供了北美、欧洲和澳大利亚等区域端点。
  • Deepgram 的 Model Improvement Partnership Program 文档介绍了数据处理方式以及选择退出和保留选项；API 参考中包含 mip_opt_out。
  • Deepgram 文档警告称，响应返回后不会存储转录文本供检索，因此你的系统必须保存所需输出。

生产规则：

  • 在录制、转录、分析或合成语音内容之前，取得适当的同意。根据司法管辖区的不同，语音可能属于生物识别数据或个人数据。
  • 除非用户的 Deepgram 合同和账户配置明确提供零数据保留，否则不要承诺零数据保留。对于严格的数据保留要求、受监管的 PHI 或隔离网络要求，应在处理前调查 Enterprise／可自托管选项并审查法律协议。
  • 对可能包含 SSN、信用卡号、电话号码、地址、健康详情或其他 PII 的转录文本进行脱敏，但仍须对脱敏结果进行质量检查；脱敏并不保证合规。
  • 避免向任何第三方发送不必要的原始音频。裁去无关片段，避免录入背景中的私人对话，并尽量减少存储的产物。
  • 生成的语音不得冒充真实人物。在需要披露的场景中标注合成语音，并保留脚本、源音频和分发内容的权利证明。

产物保管清单

对于每个生产任务，都应在最终媒体资产之外写入一份简短的运行记录：

  • 源媒体路径／URL、哈希值、时长、声道数、语言推测；
  • 同意／权利说明和保留分类；
  • Deepgram 端点、区域、模型、功能参数，以及已知的 SDK/API 版本；
  • 请求 ID、创建时间戳、警告、错误和计费标签；
  • 原始 JSON 响应；
  • 派生的转录格式：TXT、JSONL/CSV 片段、SRT/VTT、说话人映射、分析输出；
  • 质量检查记录和人工修正；
  • 最终交付路径，以及是否应删除、保留或托管源文件／原始产物。

完整示例

示例：播客单集转录文本与字幕

制作目标：为一段 48 分钟、由两位主持人主持且偶尔有嘉宾重叠发言的播客制作可编辑的转录文本、SRT 和主题摘要。

工作流和参数：

Endpoint: POST https://api.deepgram.com/v1/listen
Input: hosted WAV/MP3 URL or local audio upload
Query:
  model=nova-3
  smart_format=true
  utterances=true
  paragraphs=true
  diarize_model=latest
  summarize=v2
  topics=true
  tag=podcast-s01e04

预期结果：Deepgram 返回包含词语、时间戳、说话人标签、话语／段落结构、受支持时的摘要／主题、请求元数据，以及功能／语言组合不受支持时的警告的 JSON 转录结果。根据词语或话语的时间戳生成 SRT，然后手动修正姓名和说话人标签。

这样设计的原因：Nova-3 适合提升最终转录文本的准确性；智能格式化可提高可读性；话语／段落结构有助于编辑审核；由于混音中说话人会重叠，因此需要说话人分离；标签有助于跟踪用量。

故障模式：

  • 重叠发言时说话人标签互换；
  • 由于语言／功能支持发生变化，摘要／主题被省略或出现警告；
  • 回调载荷对于接收服务而言过大；
  • 转录文本中的词语正确，但串话部分的标点不理想。

变体：

  • 如果主持人／嘉宾音轨彼此独立，则使用 multichannel=true 代替说话人分离。
  • 为涉及敏感内容的听众来电添加脱敏。
  • 对非英语单集移除智能分析功能，并在转录后使用单独获批的模型生成摘要。
示例：实时会议字幕

生产意图：在会议直播中显示实时字幕，并归档最终转录文本。

工作流和参数：

Endpoint: wss://api.deepgram.com/v1/listen
Model: nova-3
Audio: linear16, 16000 Hz, mono, small steady chunks
Query:
  model=nova-3
  language=en-US
  encoding=linear16
  sample_rate=16000
  channels=1
  smart_format=true
  interim_results=true
  endpointing=300
  utterance_end_ms=1000
  vad_events=true

预期结果：讲话期间会更新临时识别结果；最终片段会保存到转录文本中，并以较少的变动显示。字幕 UI 会明显修订临时文本，并锁定最终文本。

这样设计的原因：实时字幕需要快速响应，但归档需要最终消息。声明原始音频格式可避免解码错误。

故障模式：

  • 采样率或编码错误会导致转录文本无法使用，或出现 WebSocket 数据错误；
  • 端点检测过于激进会过早截断句子；
  • 音乐／掌声会降低准确率；
  • 网络中断会造成内容缺失。

变体：

  • 对不应明显修订字幕的直播叠加层，关闭临时结果显示。
  • 如果预计会切换语言，请先确认当前支持的语言，再使用 language=multi&model=nova-3 或 Flux 多语言功能。
  • 如果每位嘉宾都有独立麦克风声道，请使用来源声道元数据，而不是说话人分离。
示例：客服语音 Agent 原型

生产意图：构建一个能处理打断并进行语音回复的实时客服 Agent。

工作流和参数：

Endpoint: Deepgram Voice Agent WebSocket
First message: Settings
Listen: Flux or current Deepgram conversational STT model
Think: configured LLM provider and system prompt
Speak: Deepgram Aura-2 voice, e.g. aura-2-thalia-en
Tools: order lookup, escalation, support article retrieval
Audio: telephony/browser format declared explicitly

预期结果：Agent 会输出对话文本、思考／说话状态消息、函数调用请求、警告／错误以及二进制音频。它应检测轮次结束，并根据配置允许打断。

这样设计的原因：Flux／Voice Agent 用于轮流对话，而非离线转录。优先配置设置可避免默认值不明确。

故障模式：

  • 由于端点检测／提前结束轮次设置过于激进，Agent 会抢在来电者之前说话；
  • 工具调用架构失败，导致 Agent 陷入循环；
  • 输出语音对产品名称的发音错误；
  • 对话日志存储敏感数据的时间超过允许时限。

变体：

  • 如果需要完全掌控编排，请使用 Deepgram STT + 自有 LLM + Aura TTS，而非 Voice Agent。
  • 只有在确认当前 Voice Agent 对服务商的支持情况和合同条款后，才使用托管式／自带 LLM 服务商。
示例：使用 Aura 为产品视频配音

生产意图：为一段 90 秒的产品视频生成清晰的英文旁白。

工作流和参数：

Endpoint: POST https://api.deepgram.com/v1/speak
Model: aura-2-thalia-en
Container/encoding/sample rate: choose for the editor delivery spec
Request text: one paragraph or scene beat at a time, under 2000 characters
Optional controls: speed=0.95; pronunciation overrides for product names if supported

预期结果：每个场景／段落分别生成音频文件，便于审核、替换、响度标准化，以及与音乐／音效混音。

这样设计的原因：按场景拆分的片段更易于重录和对齐。2000 字符限制可避免请求失败，而标点和基于节拍的文本有助于提升效果。

故障模式：

  • 直接复制的营销文案听起来气促或不自然；
  • 产品缩写被读成一个单词；
  • 片段边界导致语调衔接不自然；
  • 容器／采样率错误会增加编辑器导入的麻烦。

变体：

  • 将 LLM 输出实时传送给用户时，使用 WebSocket TTS。
  • 对照品牌调性试听后，选择其他 Aura 语言／语音。
  • 在 Deepgram 之外进行响度和底噪后期处理。

评论

支持 Markdown