CopilotKit 语音演示音频样本准备指南为 /demos/voice 生成 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本指南围绕 CopilotKit 的 Claude SDK TypeScript 集成示例中语音演示所需的本地音频样本sample.wav展开说明其作用、格式要求、生成方法以及它如何在无麦克风权限的情况下驱动完整的语音转写链路。读完本文你将能独立为/demos/voice准备一份合规的 WAV 音频并理解它在前端获取、/transcribe转写与 E2E 断言中的具体角色。一、sample.wav 在语音演示中的角色在 claude-sdk-typescript 集成示例 中语音演示页面位于/demos/voice。为了让用户以及自动化测试在没有麦克风权限的环境下也能完整体验语音 → 转写 → 对话的流程该演示引入了一份预置音频样本。按照 demo-audio 目录说明你需要在showcase/integrations/claude-sdk-typescript/public/demo-audio/目录下放置一个小于 100KB、名为sample.wav的 WAV 文件。演示页面会在客户端获取这份文件并将音频内容 POST 到转写端点/transcribe从而实现无需麦克风授权即可验证转写链路的效果。目前仓库中已存在一份 sample.wav但任何需要重建、替换或在不同语言环境下重新生成该文件的开发者都应按本文规范产出合规样本。期望的音频内容文档明确要求音频内容为一句特定的话What is the weather in Tokyo?选择这句话并非随意演示页面的文案会向用户宣传这句短语同时配套的 QA 清单与 E2E 测试会断言转写结果中包含weather和/或Tokyo关键字。这意味着音频内容与测试断言强耦合生成样本时不能随意更换句子否则转写结果将无法通过既有断言。二、音频格式硬性要求原文档给出了三项目标规格这些规格与下游转写服务的输入约束直接相关指标要求说明文件格式WAV.wav兼容各平台 TTS 输出与浏览器端获取解析采样率16kHzmono 单声道对齐语音转写服务如 Whisper的标准输入采样率时长35 秒保证内容完整且文件体积可控文件大小 100KB前端客户端获取、上传转写的硬性上限在低于 100KB 的体积约束下16kHz 单声道是保证短句清晰 文件小巧的关键组合。若使用 44.1kHz 立体声同等时长的 WAV 体积会膨胀数倍很容易突破 100KB 上限。三、三种平台的本地生成方法原文档提供了 macOS、Linux、Windows 三套命令行/脚本方案下面逐一展开说明含必要的参数解释。macOSsayffmpeg组合macOS 自带文本转语音工具say但它默认输出 AIFF 格式因此需要用ffmpeg转码为 16kHz 单声道 WAVsay -o sample.aiff What is the weather in Tokyo? \ ffmpeg -i sample.aiff -ar 16000 -ac 1 sample.wav参数含义-ar 16000将采样率重采样为 16kHz-ac 1转换为单声道mono。转码完成后删除中间产物sample.aiff并确认sample.wav小于 100KB。Linuxespeak-ngLinux 下可使用espeak-ng直接输出 WAVespeak-ng -w sample.wav What is the weather in Tokyo?-w指定输出 WAV 文件。注意espeak-ng默认输出可能不是 16kHz建议生成后用ffprobeffmpeg 套件验证采样率必要时追加-s 16000指定采样率参数不同发行版参数略有差异。WindowsPowerShell System.SpeechWindows 环境下可使用 .NET 内置的语音合成 API通过 PowerShell 生成 WAV$speech New-Object System.Speech.Synthesis.SpeechSynthesizer $speech.SetOutputToWaveFile(sample.wav) $speech.Speak(What is the weather in Tokyo?) $speech.Dispose()其中SetOutputToWaveFile用于设置 WAV 输出路径Speak完成一次同步合成。生成后同样需检查采样率与文件体积若超出 100KB可用 ffmpeg 降采样或缩短停顿。生成后的统一校验清单无论使用哪种平台建议按以下步骤验收播放确认内容为 What is the weather in Tokyo?用ffprobe确认格式ffprobe -show_streams sample.wav核对采样率 16kHz、单声道确认时长在 35 秒之间确认ls -l sample.wav显示文件小于 100KB。四、源码佐证sample.wav 与转写链路的关系1. 前端页面的双入口设计语音演示页面 page.tsx 使用CopilotKitruntimeUrl/api/copilotkit-voice、agentvoice-demo包裹 voice-chat.tsx麦克风入口当运行时在/info中声明audioFileTranscriptionEnabled: true时CopilotChat /会渲染麦克风按钮点击后录音并走真实的/transcribe转写样本音频入口页面下方的SampleAudioButton /见 sample-audio-button.tsx点击后同步把预设文案What is the weather in Tokyo?注入聊天输入框不经过/transcribe往返。源码注释明确指出样本按钮是确定性的测试/演示设施deterministic test/demo affordance让 Playwright 与截图流程不依赖转写端点健康状态。这也解释了为什么sample.wav的内容必须与页面宣传短语一致——它是这个确定性链路的语义锚点。2. 转写端点的实现GuardedOpenAITranscriptionService语音专用运行时位于 route.ts其职责包括在/info上声明audioFileTranscriptionEnabled: true让聊天输入框渲染麦克风按钮处理POST /transcribe调用来自copilotkit/voice的TranscriptionServiceOpenAIOpenAI Whisper 转写当OPENAI_API_KEY未配置时返回确定性的 4xx 错误而非 5xx。关键实现是GuardedOpenAITranscriptionService构造函数读取process.env.OPENAI_API_KEY有密钥则创建委托对象否则置空transcribeFile()在无密钥时抛出带明确提示的错误信息。也就是说sample.wav最终被送入的转写服务就是 OpenAI Whisper——这也是格式要求16kHz mono与转写服务的输入偏好一致的底层原因。3. E2E 测试如何断言 sample.wav 的内容voice.spec.ts 是验证该链路的 Playwright 套件三个用例层层递进页面加载断言验证 Voice input 标题、Try a sample audio 按钮、data-testidcopilot-chat-input以及麦克风按钮data-testidcopilot-start-transcribe-button可见样本按钮注入断言点击后文本域data-testidcopilot-chat-textarea在 1 秒内出现匹配/weather|tokyo/i的内容端到端发送断言点击发送后等待出现天气卡片weather-card、工具渲染卡片custom-catchall-card且data-tool-nameget_weather或助手消息copilot-assistant-message任一结果超时放宽至 45 秒。其中第二个用例直接以正则/weather|tokyo/i断言转写/注入文本——这正是原文档要求音频内容必须为 What is the weather in Tokyo? 的原因测试断言与音频内容强耦合更换句子会导致断言失败。4. QA 清单的补充视角配套的 qa/voice.md 提供了人工验证视角关键预期包括聊天页面 3 秒内加载完成样本音频转写在 8 秒内完成缺少OPENAI_API_KEY时返回 HTTP 401 及可读错误信息而非 500/503。其中点击 Play sample 后状态从 Transcribing… 回到空闲这一步骤对应麦克风路径的真实转写过程而样本按钮路径是同步注入无中间态。两条路径共同覆盖了sample.wav驱动的演示体验。五、常见问题与注意事项音频内容不能随意更换转写断言依赖 weather 与 Tokyo 关键字替换成其他句子将导致 E2E 失败文件体积务必小于 100KB过大的 WAV 在客户端获取与上传阶段都会失败优先保证 16kHz 单声道平台差异espeak-ng的默认采样率可能不是 16kHz生成后务必用ffprobe校验必要时重采样转写依赖环境变量真实转写麦克风路径要求部署环境配置OPENAI_API_KEY未配置时系统返回确定性的 4xx 错误这是设计行为而非故障演示的两种入口定位不同麦克风入口是唯一走真实转写链路的路径样本按钮则服务于无麦克风的演示与自动化测试——理解这一点有助于排查点击样本按钮没有走转写的疑惑。六、小结一份合规的sample.wav是/demos/voice语音演示能够无麦克风即可运行的关键物料。它同时服务于三个目标为用户提供无需授权即可体验的语音转写路径、为 Playwright E2E 提供确定性的断言基础、为手动 QA 提供可复现的转写样本。遵循 16kHz 单声道、35 秒、小于 100KB、内容为 What is the weather in Tokyo? 四项要求配合各平台生成命令即可随时在本地重建该资源并保持整条语音链路可用。【免费下载链接】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 语音演示音频样本准备指南：为 /demos/voice 生成 sample.wav
CopilotKit 语音演示音频样本准备指南为 /demos/voice 生成 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本指南围绕 CopilotKit 的 Claude SDK TypeScript 集成示例中语音演示所需的本地音频样本sample.wav展开说明其作用、格式要求、生成方法以及它如何在无麦克风权限的情况下驱动完整的语音转写链路。读完本文你将能独立为/demos/voice准备一份合规的 WAV 音频并理解它在前端获取、/transcribe转写与 E2E 断言中的具体角色。一、sample.wav 在语音演示中的角色在 claude-sdk-typescript 集成示例 中语音演示页面位于/demos/voice。为了让用户以及自动化测试在没有麦克风权限的环境下也能完整体验语音 → 转写 → 对话的流程该演示引入了一份预置音频样本。按照 demo-audio 目录说明你需要在showcase/integrations/claude-sdk-typescript/public/demo-audio/目录下放置一个小于 100KB、名为sample.wav的 WAV 文件。演示页面会在客户端获取这份文件并将音频内容 POST 到转写端点/transcribe从而实现无需麦克风授权即可验证转写链路的效果。目前仓库中已存在一份 sample.wav但任何需要重建、替换或在不同语言环境下重新生成该文件的开发者都应按本文规范产出合规样本。期望的音频内容文档明确要求音频内容为一句特定的话What is the weather in Tokyo?选择这句话并非随意演示页面的文案会向用户宣传这句短语同时配套的 QA 清单与 E2E 测试会断言转写结果中包含weather和/或Tokyo关键字。这意味着音频内容与测试断言强耦合生成样本时不能随意更换句子否则转写结果将无法通过既有断言。二、音频格式硬性要求原文档给出了三项目标规格这些规格与下游转写服务的输入约束直接相关指标要求说明文件格式WAV.wav兼容各平台 TTS 输出与浏览器端获取解析采样率16kHzmono 单声道对齐语音转写服务如 Whisper的标准输入采样率时长35 秒保证内容完整且文件体积可控文件大小 100KB前端客户端获取、上传转写的硬性上限在低于 100KB 的体积约束下16kHz 单声道是保证短句清晰 文件小巧的关键组合。若使用 44.1kHz 立体声同等时长的 WAV 体积会膨胀数倍很容易突破 100KB 上限。三、三种平台的本地生成方法原文档提供了 macOS、Linux、Windows 三套命令行/脚本方案下面逐一展开说明含必要的参数解释。macOSsayffmpeg组合macOS 自带文本转语音工具say但它默认输出 AIFF 格式因此需要用ffmpeg转码为 16kHz 单声道 WAVsay -o sample.aiff What is the weather in Tokyo? \ ffmpeg -i sample.aiff -ar 16000 -ac 1 sample.wav参数含义-ar 16000将采样率重采样为 16kHz-ac 1转换为单声道mono。转码完成后删除中间产物sample.aiff并确认sample.wav小于 100KB。Linuxespeak-ngLinux 下可使用espeak-ng直接输出 WAVespeak-ng -w sample.wav What is the weather in Tokyo?-w指定输出 WAV 文件。注意espeak-ng默认输出可能不是 16kHz建议生成后用ffprobeffmpeg 套件验证采样率必要时追加-s 16000指定采样率参数不同发行版参数略有差异。WindowsPowerShell System.SpeechWindows 环境下可使用 .NET 内置的语音合成 API通过 PowerShell 生成 WAV$speech New-Object System.Speech.Synthesis.SpeechSynthesizer $speech.SetOutputToWaveFile(sample.wav) $speech.Speak(What is the weather in Tokyo?) $speech.Dispose()其中SetOutputToWaveFile用于设置 WAV 输出路径Speak完成一次同步合成。生成后同样需检查采样率与文件体积若超出 100KB可用 ffmpeg 降采样或缩短停顿。生成后的统一校验清单无论使用哪种平台建议按以下步骤验收播放确认内容为 What is the weather in Tokyo?用ffprobe确认格式ffprobe -show_streams sample.wav核对采样率 16kHz、单声道确认时长在 35 秒之间确认ls -l sample.wav显示文件小于 100KB。四、源码佐证sample.wav 与转写链路的关系1. 前端页面的双入口设计语音演示页面 page.tsx 使用CopilotKitruntimeUrl/api/copilotkit-voice、agentvoice-demo包裹 voice-chat.tsx麦克风入口当运行时在/info中声明audioFileTranscriptionEnabled: true时CopilotChat /会渲染麦克风按钮点击后录音并走真实的/transcribe转写样本音频入口页面下方的SampleAudioButton /见 sample-audio-button.tsx点击后同步把预设文案What is the weather in Tokyo?注入聊天输入框不经过/transcribe往返。源码注释明确指出样本按钮是确定性的测试/演示设施deterministic test/demo affordance让 Playwright 与截图流程不依赖转写端点健康状态。这也解释了为什么sample.wav的内容必须与页面宣传短语一致——它是这个确定性链路的语义锚点。2. 转写端点的实现GuardedOpenAITranscriptionService语音专用运行时位于 route.ts其职责包括在/info上声明audioFileTranscriptionEnabled: true让聊天输入框渲染麦克风按钮处理POST /transcribe调用来自copilotkit/voice的TranscriptionServiceOpenAIOpenAI Whisper 转写当OPENAI_API_KEY未配置时返回确定性的 4xx 错误而非 5xx。关键实现是GuardedOpenAITranscriptionService构造函数读取process.env.OPENAI_API_KEY有密钥则创建委托对象否则置空transcribeFile()在无密钥时抛出带明确提示的错误信息。也就是说sample.wav最终被送入的转写服务就是 OpenAI Whisper——这也是格式要求16kHz mono与转写服务的输入偏好一致的底层原因。3. E2E 测试如何断言 sample.wav 的内容voice.spec.ts 是验证该链路的 Playwright 套件三个用例层层递进页面加载断言验证 Voice input 标题、Try a sample audio 按钮、data-testidcopilot-chat-input以及麦克风按钮data-testidcopilot-start-transcribe-button可见样本按钮注入断言点击后文本域data-testidcopilot-chat-textarea在 1 秒内出现匹配/weather|tokyo/i的内容端到端发送断言点击发送后等待出现天气卡片weather-card、工具渲染卡片custom-catchall-card且data-tool-nameget_weather或助手消息copilot-assistant-message任一结果超时放宽至 45 秒。其中第二个用例直接以正则/weather|tokyo/i断言转写/注入文本——这正是原文档要求音频内容必须为 What is the weather in Tokyo? 的原因测试断言与音频内容强耦合更换句子会导致断言失败。4. QA 清单的补充视角配套的 qa/voice.md 提供了人工验证视角关键预期包括聊天页面 3 秒内加载完成样本音频转写在 8 秒内完成缺少OPENAI_API_KEY时返回 HTTP 401 及可读错误信息而非 500/503。其中点击 Play sample 后状态从 Transcribing… 回到空闲这一步骤对应麦克风路径的真实转写过程而样本按钮路径是同步注入无中间态。两条路径共同覆盖了sample.wav驱动的演示体验。五、常见问题与注意事项音频内容不能随意更换转写断言依赖 weather 与 Tokyo 关键字替换成其他句子将导致 E2E 失败文件体积务必小于 100KB过大的 WAV 在客户端获取与上传阶段都会失败优先保证 16kHz 单声道平台差异espeak-ng的默认采样率可能不是 16kHz生成后务必用ffprobe校验必要时重采样转写依赖环境变量真实转写麦克风路径要求部署环境配置OPENAI_API_KEY未配置时系统返回确定性的 4xx 错误这是设计行为而非故障演示的两种入口定位不同麦克风入口是唯一走真实转写链路的路径样本按钮则服务于无麦克风的演示与自动化测试——理解这一点有助于排查点击样本按钮没有走转写的疑惑。六、小结一份合规的sample.wav是/demos/voice语音演示能够无麦克风即可运行的关键物料。它同时服务于三个目标为用户提供无需授权即可体验的语音转写路径、为 Playwright E2E 提供确定性的断言基础、为手动 QA 提供可复现的转写样本。遵循 16kHz 单声道、35 秒、小于 100KB、内容为 What is the weather in Tokyo? 四项要求配合各平台生成命令即可随时在本地重建该资源并保持整条语音链路可用。【免费下载链接】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），仅供参考