Vision-Agents Fish Audio 插件实战高保真语音合成TTS与多语言语音识别STT接入指南【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents本文是 Vision-AgentsOpen Vision Agents中 Fish Audio 插件的完整使用指南围绕仓库内 plugins/fish/README.md 展开讲解如何用 Fish Audio API 为语音/视觉 Agent 接入高质量的文本转语音TTS与语音转文本STT能力并支持多语言识别与参考音频克隆音色。读完本文你将掌握该插件的安装、双引擎 API 调用、参数配置、源码级工作机理以及如何在完整 Agent 中组合 Fish Audio 与 GetStream 边缘网络、智能打断检测等能力。插件定位与整体架构Fish Audio 插件是 Vision-Agents 官方插件生态plugins/目录的一员为 Agent 提供两大语音能力TTSText-to-Speech将 Agent 的回复文本合成为自然、多语言的语音默认使用 Fish Audio 的s2-pro模型支持细粒度韵律控制如[laugh]、[whisper]内联标签与参考音频音色克隆。STTSpeech-to-Text将用户/参与者的语音实时转写为文本支持多语言与自动语言检测供下游 LLM 理解用户意图。从源码结构看插件实现非常轻量——核心只有两个文件plugins/fish/vision_agents/plugins/fish/tts.pyTTS类继承核心基类vision_agents.core.tts.TTSagents-core/vision_agents/core/tts/tts.py通过fish_audio_sdk.Session与 Fish Audio 服务端通信plugins/fish/vision_agents/plugins/fish/stt.pySTT类继承核心基类vision_agents.core.stt.STTagents-core/vision_agents/core/stt/stt.py内置按参与者participant分流的音频缓冲与同步 ASR 逻辑。这种继承核心基类 适配特定供应商 SDK的模式与仓库内其他插件Cartesia、Deepgram、ElevenLabs 等一致意味着 Fish Audio 可以无缝替换任意语音通道无需改动 Agent 其他组件。安装插件以独立分发包发布可通过uv两种方式安装# 方式一通过主包 extras 安装 uv add vision-agents[fish] # 方式二直接安装插件包 uv add vision-agents-plugins-fish从 plugins/fish/pyproject.toml 可以看到插件包名与依赖声明包名vision-agents-plugins-fish依赖vision-agents工作区主包Python 要求3.10依赖fish-audio-sdk1.3.0,2README 则建议至少使用fish-audio-sdk2025.4.2以获得完整功能。TTS文本转语音快速上手from vision_agents.plugins.fish import TTS from getstream.video.rtc.audio_track import AudioStreamTrack # 从环境变量读取 API key 初始化 tts TTS() # 或直接指定 API key tts TTS(api_keyyour_fish_audio_api_key) # 创建用于输出语音的音频轨 track AudioStreamTrack(framerate16000) tts.set_output_track(track) # 注册事件处理器接收音频分片 tts.events.subscribe async def on_audio(event): print(fReceived audio chunk: {len(event.audio_data)} bytes) # 发送文本转换为语音 async for chunk in tts.send_iter(Hello, this is a test of the Fish Audio text-to-speech plugin.): pass关键点tts.send_iter(text)是核心基类提供的异步生成器见 agents-core/vision_agents/core/tts/tts.py内部会先发出TTSSynthesisStartEvent随后逐个产出TTSOutputChunk携带PcmData、final标记、synthesis_id等并支持中断interrupt()递增 epoch丢弃过期分片以实现抢话打断场景。tts.events是基类统一管理的EventManageraudio事件回调中event.audio_data即为音频字节流。TTS 配置参数参数说明默认值api_keyFish Audio API key读取FISH_API_KEY环境变量源码同时兼容FISH_AUDIO_API_KEY见 tts.pyreference_id参考音色 ID用于音色克隆/固定音色合成源码中有一个内置默认参考音色 ID见 tts.pybase_url自定义 API 端点Fish Audio 官方默认端点client自行传入的fish_audio_sdk.Session实例内部自动创建model后端合成模型s2-pro注意当传入base_url时源码要求必须同时提供api_key否则抛出ValueErrorclient一旦传入则直接复用忽略base_url/api_key。支持的模型与韵律控制TTS.__init__的 docstring 与示例代码明确列出了可用模型tts.pys2-pro默认最新 S2 模型支持细粒度韵律控制与自然语言标签如[laugh]笑、[whisper]耳语、[super happy]超开心speech-1.5旧版模型speech-1.6改进版旧模型s1快速模型s1-mini轻量快速模型。默认模型即带韵律控制可直接在文本中内联标签# 指定 legacy 模型 tts TTS(modelspeech-1.5) # s2-pro 韵律控制示例 text [whisper] This is a secret. [super happy] But this is great news!集成测试 plugins/fish/tests/test_tts.py 正是以这两种形态验证的一条测试直接用含[laugh]的文本走默认s2-pro另一条专门验证[whisper]/[super happy]韵律标签还有一条验证speech-1.5legacy 模型可正常出音。源码级行为输出格式stream_audiotts.py的底层实现要点构造TTSRequest(formatpcm, sample_rate16000, normalizeTrue)并通过self.client.tts.awaitable(tts_request, backendself.model)流式拉取 PCM 音频返回值经PcmData.from_response(stream, sample_rate16000, channels1, formatAudioFormat.S16)包装成16kHz 采样率、单声道、16-bit PCM的标准PcmData与基类send_iter期望的返回类型完全对齐reference_id会被自动写入请求其余**kwargs会透传给TTSRequest从而支持在调用时动态传入参考音频等高级参数。STT语音转文本快速上手from vision_agents.plugins.fish import STT from getstream.video.rtc.track_util import PcmData # 从环境变量读取 API key 初始化 stt STT() # 或直接指定 API key 和语言 stt STT(api_keyyour_fish_audio_api_key, languageen) # 注册事件处理器接收转写结果 stt.events.subscribe async def on_transcript(event): print(fTranscript: {event.text}) # 处理音频数据 pcm_data PcmData(samplesaudio_samples, sample_rate16000) await stt.process_audio(pcm_data)STT 配置参数README 文档化的参数如下参数说明默认值api_keyFish Audio API key读取FISH_API_KEY环境变量language转写语言代码如en、zhNone时自动语言检测Noneignore_timestamps跳过时间戳处理以加速返回Falsesample_rate音频采样率Hz16000base_url自定义 API 端点Fish Audio 默认端点client自行传入的fish_audio_sdk.Session实例内部自动创建源码补充当前版本 stt.py 中STT.__init__实际接受api_key、language、client三个参数ignore_timestampsTrue在构造ASRRequest时被硬编码开启stt.py采样率则直接从传入的PcmData推导无需单独配置。若你传入自定义client同样会直接复用而不走api_key分支。核心机制最小时长缓冲Fish Audio 的 ASR 接口要求每次请求至少 1 秒音频。为此STT 实现内置了一套按参与者participant维度的缓冲队列常量MIN_DURATION_MS 1000.0见 stt.pyprocess_audio(pcm_data, participant)被调用后音频先以participant.user_id为 key 追加到对应缓冲当缓冲时长仍不足 1000ms 时直接返回None不发起请求达到阈值后调用_send_buffer把缓冲转成 WAV 字节pcm_to_send.to_wav_bytes()通过asyncio.to_thread(self.client.asr, asr_request)在独立线程中同步调用 Fish Audio ASR避免阻塞事件循环转写文本非空时构造TranscriptResponse携带audio_duration_ms、language、model_namefish-audio-asr、processing_time_ms等元数据并通过基类_emit_transcript_event(..., modefinal)推入output流——Fish Audio 只产出最终结果final transcript无中间临时结果clear()会冲刷剩余缓冲满 1 秒的发送不足的直接丢弃stt.py。基类 agents-core/vision_agents/core/stt/stt.py 会把每条 final 转写同时写入stt.outputStream[Transcript | TurnEnded | TurnStarted]并记录 STT 指标供下游 Agent 消费与观测。参考音频与音色克隆Fish Audio 支持用参考音频实现音色克隆插件提供两种使用方式from vision_agents.plugins.fish import TTS # 方式一初始化时指定参考音色 ID tts TTS(reference_idyour_reference_voice_id) # 方式二发送文本时动态传入参考音频等高级参数 # 通过 **kwargs 透传至 TTSRequest详见 Fish Audio SDK 文档 async for chunk in tts.send_iter(Hello!, references[...]): pass如 TTS 配置参数 所述reference_id在源码中有默认内置值当你希望为 Agent 固定一套品牌音色时显式指定自己的reference_id即可。动态传入的**kwargs会通过tts_request_kwargs.update(kwargs)覆盖默认请求字段tts.py因此高级用法如按句切换参考音频无需改动插件源码。STT 支持的语言与音频格式支持的语言Fish Audio STT 支持多语言与自动检测常见语言代码包括en- 英语zh- 中文es- 西班牙语fr- 法语de- 德语ja- 日语ko- 韩语pt- 葡萄牙语需要自动语言检测时保持languageNone默认值即可。支持的音频格式STT 实现接受 PCM 音频数据并在内部转换为 WAV 后发送。建议配置最大音频大小100MB最大时长60 分钟采样率推荐 16kHz 或更高插件内部按 16kHz 单声道 16-bit PCM 的PcmData处理测试中 48kHz 输入同样可用见 plugins/fish/tests/test_stt.py格式单声道Mono、16-bit PCM组合到完整 Agent官方示例除了插件级 API仓库还提供了完整 Agent 示例 plugins/fish/example/fish_example.py演示 Fish Audio TTS STT、GetStream 边缘实时通信、Gemini LLM 与 Smart Turn 打断检测的组合agent Agent( edgegetstream.Edge(), agent_userUser(nameFriendly AI, idagent), instructionsYoure a friendly voice AI assistant. Keep your responses short and conversational., # Fish Audio S2 模型默认支持韵律控制 # 可选模型s2-pro默认、speech-1.5、speech-1.6、s1、s1-mini ttsfish.TTS(), sttfish.STT(), # Fish Audio 语音识别 llmgemini.LLM(), turn_detectionsmart_turn.TurnDetection( silence_duration_ms2000, speech_probability_threshold0.5, ), )运行前需准备环境变量FISH_API_KEY以及完整示例所需的STREAM_API_KEY、STREAM_API_SECRET。示例还附带elon.md模拟 Elon Musk 人设的指令文件plugins/fish/example/elon.md可直接用于打造特定风格的声音 Agent。获取 API Key 与运行前提注册 Fish Audio 账号https://fish.audio在控制台的 API Keys 页面创建新的 API key将 key 写入环境变量FISH_API_KEYTTS 亦兼容FISH_AUDIO_API_KEY或在代码中直接传给插件构造器。运行要求Python 3.10fish-audio-sdk见 plugins/fish/pyproject.toml 依赖声明集成测试pytest.mark.integration见 plugins/fish/tests/test_tts.py 与 plugins/fish/tests/test_stt.py需要真实 API key 与网络环境离线状态下不会自动执行。注意事项环境变量差异TTS 兼容FISH_API_KEY与FISH_AUDIO_API_KEY两个变量名STT 仅读取FISH_API_KEY配置时建议统一使用前者。STT 只出 final 结果Fish Audio 采用同步请求模式无流式中间转写适合对延迟不敏感或需要完整句子的场景追求逐词流式体验可评估仓库内其他 STT 插件如 Deepgram。1 秒缓冲约束单次 ASR 请求至少需要 1 秒音频插件已按参与者自动缓冲无需调用方处理但每条音频流过短合计不足 1 秒时不会产生转写。文档与实现的细微出入README 中列出的ignore_timestamps、sample_rate、base_url等 STT 参数属于文档化能力当前源码版本的部分选项如ignore_timestamps为固定开启实际以 stt.py 实现为准。综合来看Fish Audio 插件在 Vision-Agents 中承担了语音出入口的关键角色TTS 侧以s2-pro模型提供带韵律控制、支持音色克隆的高质量合成STT 侧以同步 ASR 加按参与者缓冲的方式提供多语言转写。二者都严格遵循核心基类契约接入成本低、替换成本也低是快速构建可对话语音/视觉 Agent 的可靠选择。【免费下载链接】Vision-AgentsOpen Vision Agents by Stream. Build voice and vision agents quickly with any model or video provider. Uses Streams edge network for ultra-low latency.项目地址: https://gitcode.com/GitHub_Trending/vi/Vision-Agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
