CopilotKit LangGraph 语音演示 sample.wav 样本音频生成指南免麦克风跑通语音转录流程【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit导读/demos/voice是 CopilotKit 仓库中 langgraph-fastapi 集成示例showcase/integrations/langgraph-fastapi内置的语音输入演示页。为了让这一演示在无人声录制、无麦克风权限的环境下依然可以完整验证语音 → 转录 → 对话的端到端流程仓库要求在 public/demo-audio/ 目录下放置一个特定规格的 WAV 音频文件sample.wav。读完本文你将掌握该样本音频的规格要求、三大主流平台macOS / Linux / Windows的本地生成命令、内容约束背后的 QA 与 E2E 断言逻辑以及它在前端渲染层与运行时转录服务中的实际调用位置。一、样本音频在语音演示中的定位语音演示页/demos/voice的核心思路是在不申请麦克风权限的前提下让整条音频 → 转录文本 → 发送给 Agent的链路可复现。sample.wav正是这条链路的确定性输入。按照该目录下 README.md 的说明该文件被命名为sample.wav体积要求小于 100KB演示页会在客户端获取这段音频并将其 POST 到转录端点transcription endpoint从而避免依赖麦克风权限即可触发转录流程。需要说明的是从当前源码看演示页的用户交互已经演进为双通道设计默认由CopilotChat /渲染的麦克风按钮走真实的MediaRecorder录音 /transcribe转录路径而页面底部的 Try a sample audio 按钮则是一个确定性的测试/演示辅助控件点击后同步注入固定文案到输入框不经过音频抓取与/transcribe往返详见下文第四节。因此sample.wav在当前实现中主要承担规范样本音频的角色——它定义了演示对外承诺的音频内容与格式基线并为需要真实转录的路径麦克风、手动 QA 清单 qa/voice.md 中提及的qa/voice.md提供标准素材。二、样本音频的硬性规格16kHz 单声道、3–5 秒、100KB原文档对sample.wav的规格要求非常明确这也是生成时必须满足的验收标准规格项要求值说明采样率16kHz16000 Hz与常见 ASR 引擎如 Whisper的输入采样率对齐过低会损失语音特征过高则徒增体积声道单声道mono转录场景通常只需单声道双声道会成倍增大文件体积时长3–5 秒覆盖完整一句话的发音又不至于让文件超限体积 100KB客户端抓取与上传的硬性上限文件格式WAV未压缩 PCM WAV 为佳兼容性最广体积约束是相互关联的16kHz 单声道 PCM 编码下每秒数据量约为 32000 字节16000 样本/秒 × 16bit/样本 ≈ 31.25KB/s3–5 秒的录音换算后恰好在 100KB 量级附近这正是规格设计自洽之处。三、三大平台生成命令可直接复制运行原文档提供了 macOS、Linux、Windows 三条生成路径均为系统自带或常见工具无需额外安装重型依赖macOSsay -o sample.aiff What is the weather in Tokyo? ffmpeg -i sample.aiff -ar 16000 -ac 1 sample.wav先用系统内置的say语音合成器生成 AIFF再通过ffmpeg转码为 16kHz-ar 16000、单声道-ac 1的 WAV。若未安装ffmpeg可先brew install ffmpeg。Linuxespeak-ng -w sample.wav What is the weather in Tokyo?espeak-ng直接输出 WAV 文件默认即单声道如需显式指定采样率可追加-s语速与-a振幅参数微调。Debian/Ubuntu 系可用sudo apt install espeak-ng安装。Windows使用 PowerShell 调用 .NET 内置的System.Speech.Synthesis.SpeechSynthesizer通过SetOutputToWaveFile输出 WAV$synth New-Object System.Speech.Synthesis.SpeechSynthesizer $synth.SetOutputToWaveFile(sample.wav) $synth.Speak(What is the weather in Tokyo?) $synth.Dispose()生成后将文件命名为sample.wav放入 public/demo-audio/ 目录即可。可先ls -la确认体积 100KB若超出可适当缩短语音、降低振幅或压缩为更低位深。四、内容约束为何必须是 What is the weather in Tokyo?样本音频的文案被硬性固定为What is the weather in Tokyo?这不是随意选择而是由两处测试基建共同锁定的演示文案承诺演示页顶部展示给用户的标语就是这句话用户点击播放/试听时听到的音频必须与界面承诺一致否则体验会前后矛盾。QA 清单与 E2E 断言仓库内置的 Playwright 端到端测试 tests/e2e/voice.spec.ts 与打包的 QA 检查清单均会断言转录文本包含 weather 和/或 Tokyo。例如该测试中的断言await expect(textarea).toHaveValue(/weather|tokyo/i, { timeout: 1000 });这意味着如果开发者用其他文案生成样本音频即便转录链路完全正常也可能因为关键词不匹配而导致 E2E 或 QA 检查失败。因此生成时请严格使用原句不要自行替换句子内容。从源码结构看这条短语在前端被定义为常量SAMPLE_TEXT What is the weather in Tokyo?见 voice-chat.tsx由 sample-audio-button.tsx 注入输入框与音频内容形成了所见即所听、所听即所测的闭环。五、源码级佐证语音运行时与转录服务的真实调用链要理解sample.wav最终流向哪里需要看清语音演示专用的运行时入口 src/app/api/copilotkit-voice/[[...slug]]/route.ts。该文件是/demos/voice专属的 V2 运行时承担三个职责在/info上对外宣告audioFileTranscriptionEnabled: true让聊天组件渲染出麦克风按钮通过POST /transcribe调用 OpenAI 支撑的TranscriptionServiceOpenAI来自copilotkit/voice把录音转成文本并自动发送在未配置OPENAI_API_KEY时返回确定性的 4xx 错误而非晦涩的 5xx。其中转录服务的接入点与sample.wav直接相关——客户端把音频文件交给/transcribe由GuardedOpenAITranscriptionService包装的transcribeFile(options: TranscribeFileOptions)完成转写。该守卫类会在缺少OPENAI_API_KEY时抛出包含 api key missing 的错误信息利用 V2 运行时handleTranscribe对 api key/unauthorized 字样的映射将缺失密钥的情况收敛到AUTH_FAILED → HTTP 401路径。这也解释了原文档通过样本音频让流程在没有麦克风权限时也能工作的设计意图它把不确定性最高的麦克风录音环节替换成了确定性的文件转录。此外manifest.yaml 中对该 demo 的描述为 Speech-to-text via copilotkit/voice with a bundled sample audio button路由为/demos/voice涉及 page.tsx 与 sample-audio-button.tsx 两个前端文件可视为该功能的目录索引。六、端到端验证E2E 如何消费这段样本音频tests/e2e/voice.spec.ts 完整覆盖了样本音频相关的三条链路可作为放置sample.wav后验收的参考页面装配断言页面标题 Voice input、voice-sample-audio-button与copilot-chat-input均可见并等待copilot-start-transcribe-button麦克风按钮在/info往返完成后出现——该按钮是运行时正确宣告audioFileTranscriptionEnabled: true的权威信号样本注入点击 sample 按钮后输入框在 1 秒内被填充匹配/weather|tokyo/i的文案且无瞬态 Transcribing… 状态、无/transcribe往返——这正是当前实现与播放 WAV 再转录路径的差异点保证测试在 Whisper 或 aimock 不可用的环境依然稳定完整对话发送转录文本后断言weather-card、custom-catchall-card[data-tool-nameget_weather]或copilot-assistant-message任一 Agent 输出出现验证转录文本 → Agent 响应闭环并为冷启动预留了 90 秒超时。对需要验证真实转录的场合麦克风路径MediaRecorder/transcribe与手动 QA 清单是唯一真正经过转录服务的那条路——这也是sample.wav规格存在的根本意义为这类需要真实音频的场景提供一个与测试断言完全对齐的标准样本。七、快速核对清单完成生成后建议按以下顺序做最终确认文件名必须是sample.wav位于 public/demo-audio/ 下用file sample.wav确认编码为 16kHz 单声道 WAV时长 3–5 秒用ls -la确认体积 100KB16kHz 单声道 PCM 3–5 秒约 94–156KB超限时优先缩短时长试听确认内容为 What is the weather in Tokyo?且发音可被 ASR 清晰识别启动演示后访问/demos/voice确认页面文案、样本按钮、麦克风按钮均正常渲染E2E 三组用例页面装配 / 样本注入 / 完整对话全部通过。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CopilotKit LangGraph 语音演示 sample.wav 样本音频生成指南免麦克风跑通语音转录流程【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit导读/demos/voice是 CopilotKit 仓库中 langgraph-fastapi 集成示例showcase/integrations/langgraph-fastapi内置的语音输入演示页。为了让这一演示在无人声录制、无麦克风权限的环境下依然可以完整验证语音 → 转录 → 对话的端到端流程仓库要求在 public/demo-audio/ 目录下放置一个特定规格的 WAV 音频文件sample.wav。读完本文你将掌握该样本音频的规格要求、三大主流平台macOS / Linux / Windows的本地生成命令、内容约束背后的 QA 与 E2E 断言逻辑以及它在前端渲染层与运行时转录服务中的实际调用位置。一、样本音频在语音演示中的定位语音演示页/demos/voice的核心思路是在不申请麦克风权限的前提下让整条音频 → 转录文本 → 发送给 Agent的链路可复现。sample.wav正是这条链路的确定性输入。按照该目录下 README.md 的说明该文件被命名为sample.wav体积要求小于 100KB演示页会在客户端获取这段音频并将其 POST 到转录端点transcription endpoint从而避免依赖麦克风权限即可触发转录流程。需要说明的是从当前源码看演示页的用户交互已经演进为双通道设计默认由CopilotChat /渲染的麦克风按钮走真实的MediaRecorder录音 /transcribe转录路径而页面底部的 Try a sample audio 按钮则是一个确定性的测试/演示辅助控件点击后同步注入固定文案到输入框不经过音频抓取与/transcribe往返详见下文第四节。因此sample.wav在当前实现中主要承担规范样本音频的角色——它定义了演示对外承诺的音频内容与格式基线并为需要真实转录的路径麦克风、手动 QA 清单 qa/voice.md 中提及的qa/voice.md提供标准素材。二、样本音频的硬性规格16kHz 单声道、3–5 秒、100KB原文档对sample.wav的规格要求非常明确这也是生成时必须满足的验收标准规格项要求值说明采样率16kHz16000 Hz与常见 ASR 引擎如 Whisper的输入采样率对齐过低会损失语音特征过高则徒增体积声道单声道mono转录场景通常只需单声道双声道会成倍增大文件体积时长3–5 秒覆盖完整一句话的发音又不至于让文件超限体积 100KB客户端抓取与上传的硬性上限文件格式WAV未压缩 PCM WAV 为佳兼容性最广体积约束是相互关联的16kHz 单声道 PCM 编码下每秒数据量约为 32000 字节16000 样本/秒 × 16bit/样本 ≈ 31.25KB/s3–5 秒的录音换算后恰好在 100KB 量级附近这正是规格设计自洽之处。三、三大平台生成命令可直接复制运行原文档提供了 macOS、Linux、Windows 三条生成路径均为系统自带或常见工具无需额外安装重型依赖macOSsay -o sample.aiff What is the weather in Tokyo? ffmpeg -i sample.aiff -ar 16000 -ac 1 sample.wav先用系统内置的say语音合成器生成 AIFF再通过ffmpeg转码为 16kHz-ar 16000、单声道-ac 1的 WAV。若未安装ffmpeg可先brew install ffmpeg。Linuxespeak-ng -w sample.wav What is the weather in Tokyo?espeak-ng直接输出 WAV 文件默认即单声道如需显式指定采样率可追加-s语速与-a振幅参数微调。Debian/Ubuntu 系可用sudo apt install espeak-ng安装。Windows使用 PowerShell 调用 .NET 内置的System.Speech.Synthesis.SpeechSynthesizer通过SetOutputToWaveFile输出 WAV$synth New-Object System.Speech.Synthesis.SpeechSynthesizer $synth.SetOutputToWaveFile(sample.wav) $synth.Speak(What is the weather in Tokyo?) $synth.Dispose()生成后将文件命名为sample.wav放入 public/demo-audio/ 目录即可。可先ls -la确认体积 100KB若超出可适当缩短语音、降低振幅或压缩为更低位深。四、内容约束为何必须是 What is the weather in Tokyo?样本音频的文案被硬性固定为What is the weather in Tokyo?这不是随意选择而是由两处测试基建共同锁定的演示文案承诺演示页顶部展示给用户的标语就是这句话用户点击播放/试听时听到的音频必须与界面承诺一致否则体验会前后矛盾。QA 清单与 E2E 断言仓库内置的 Playwright 端到端测试 tests/e2e/voice.spec.ts 与打包的 QA 检查清单均会断言转录文本包含 weather 和/或 Tokyo。例如该测试中的断言await expect(textarea).toHaveValue(/weather|tokyo/i, { timeout: 1000 });这意味着如果开发者用其他文案生成样本音频即便转录链路完全正常也可能因为关键词不匹配而导致 E2E 或 QA 检查失败。因此生成时请严格使用原句不要自行替换句子内容。从源码结构看这条短语在前端被定义为常量SAMPLE_TEXT What is the weather in Tokyo?见 voice-chat.tsx由 sample-audio-button.tsx 注入输入框与音频内容形成了所见即所听、所听即所测的闭环。五、源码级佐证语音运行时与转录服务的真实调用链要理解sample.wav最终流向哪里需要看清语音演示专用的运行时入口 src/app/api/copilotkit-voice/[[...slug]]/route.ts。该文件是/demos/voice专属的 V2 运行时承担三个职责在/info上对外宣告audioFileTranscriptionEnabled: true让聊天组件渲染出麦克风按钮通过POST /transcribe调用 OpenAI 支撑的TranscriptionServiceOpenAI来自copilotkit/voice把录音转成文本并自动发送在未配置OPENAI_API_KEY时返回确定性的 4xx 错误而非晦涩的 5xx。其中转录服务的接入点与sample.wav直接相关——客户端把音频文件交给/transcribe由GuardedOpenAITranscriptionService包装的transcribeFile(options: TranscribeFileOptions)完成转写。该守卫类会在缺少OPENAI_API_KEY时抛出包含 api key missing 的错误信息利用 V2 运行时handleTranscribe对 api key/unauthorized 字样的映射将缺失密钥的情况收敛到AUTH_FAILED → HTTP 401路径。这也解释了原文档通过样本音频让流程在没有麦克风权限时也能工作的设计意图它把不确定性最高的麦克风录音环节替换成了确定性的文件转录。此外manifest.yaml 中对该 demo 的描述为 Speech-to-text via copilotkit/voice with a bundled sample audio button路由为/demos/voice涉及 page.tsx 与 sample-audio-button.tsx 两个前端文件可视为该功能的目录索引。六、端到端验证E2E 如何消费这段样本音频tests/e2e/voice.spec.ts 完整覆盖了样本音频相关的三条链路可作为放置sample.wav后验收的参考页面装配断言页面标题 Voice input、voice-sample-audio-button与copilot-chat-input均可见并等待copilot-start-transcribe-button麦克风按钮在/info往返完成后出现——该按钮是运行时正确宣告audioFileTranscriptionEnabled: true的权威信号样本注入点击 sample 按钮后输入框在 1 秒内被填充匹配/weather|tokyo/i的文案且无瞬态 Transcribing… 状态、无/transcribe往返——这正是当前实现与播放 WAV 再转录路径的差异点保证测试在 Whisper 或 aimock 不可用的环境依然稳定完整对话发送转录文本后断言weather-card、custom-catchall-card[data-tool-nameget_weather]或copilot-assistant-message任一 Agent 输出出现验证转录文本 → Agent 响应闭环并为冷启动预留了 90 秒超时。对需要验证真实转录的场合麦克风路径MediaRecorder/transcribe与手动 QA 清单是唯一真正经过转录服务的那条路——这也是sample.wav规格存在的根本意义为这类需要真实音频的场景提供一个与测试断言完全对齐的标准样本。七、快速核对清单完成生成后建议按以下顺序做最终确认文件名必须是sample.wav位于 public/demo-audio/ 下用file sample.wav确认编码为 16kHz 单声道 WAV时长 3–5 秒用ls -la确认体积 100KB16kHz 单声道 PCM 3–5 秒约 94–156KB超限时优先缩短时长试听确认内容为 What is the weather in Tokyo?且发音可被 ASR 清晰识别启动演示后访问/demos/voice确认页面文案、样本按钮、麦克风按钮均正常渲染E2E 三组用例页面装配 / 样本注入 / 完整对话全部通过。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
