# web.edgeTextToSpeech 库模块帮助文档 [流式语音与可替换接口](https://www.aardio.com/zh-cn/docs/library/web/edgeTextToSpeech/) ## web 成员列表 # ### web.edgeTextToSpeech # Edge 流式文本转语音。使用 web.socket.client + dotNet.sslTunnel.client，不依赖 SocketSharp 或播放器。一次提交完整文本，按序交付 MP3 字节块；不是向同一合成任务持续追加文本的双向流。单次转义后 UTF-8 文本上限 4096 字节，是本适配器的保守策略。按需在调用层使用 string.sentences。 [使用指南](https://www.aardio.com/zh-cn/docs/library/web/edgeTextToSpeech/) ### web.edgeTextToSpeech() # [返回对象:edgeTtsEngineObject](#edgeTtsEngineObject) ### web.edgeTextToSpeech(config) # 创建引擎，构造时不联网。config 可省略，设置请求默认值。 voice: 默认 zh-CN-XiaoxiaoNeural；rate: 默认 1；volume: 默认 1；format: mp3。 boundary: sentence(默认)、word、none。 connectTimeoutMs=10000,receiveTimeoutMs=30000,timeoutMs=120000。 providerOptions={pitch="+0Hz";language="en-US"}。没有 proxy、voiceOptions、ConnectAsync、pushText/popSpeech 等旧接口。 ## edgeTtsEngineObject 成员列表 # ### edgeTtsEngineObject.capabilities # 能力表：audioStreaming=true,textStreaming=false,formats=["mp3"],boundaries=["sentence","word"],maxTextBytes=4096。 ### edgeTtsEngineObject.synthesize() # [返回对象:edgeTtsTaskObject](#edgeTtsTaskObject) ### edgeTtsEngineObject.synthesize(request,output) # 创建并启动异步合成任务；request 是包含 text 及可选请求默认值覆盖项的表。 output 为有 write/finish 方法的输出对象（播放器、httpStreamMp3 等）时：音频交给 output.write，成功调用 output.finish()，失败调用 output.finish(错误信息)；取消时不调用 output，由调用者 close。write 失败会终止合成。 output 也可以是回调表：onAudio(data,format)、onBoundary(info)、onFinish(result,err)。成功返回 task；参数错误返回 null,err，不触发回调，也不调用 output。回调在当前消息循环线程中执行，且始终在 synthesize 返回后开始。 ### edgeTtsEngineObject.voices(locale) # 联网获取可用音色（进程内缓存，第二次不联网）；locale 可选，按地区前缀筛选（忽略大小写），如 "zh"（含 zh-HK、zh-TW、zh-CN-shaanxi 等）、"zh-HK"、"en-US"。返回数组，每项 {id;locale;localeName;gender;name;categories;personalities}， id 即 synthesize 的 voice，gender 为小写 "female"/"male"。失败返回 null,err。请求在工作线程执行，GUI 线程调用不会卡住界面。 ## edgeTtsTaskObject 成员列表 # ### edgeTtsTaskObject.audioBytes # 已交付的编码字节数。 ### edgeTtsTaskObject.audioChunks # 已交付的音频块数。 ### edgeTtsTaskObject.callbackError # onFinish 回调自身抛出的错误（如有）；不会重复触发结束回调。 ### edgeTtsTaskObject.cancel() # 幂等取消当前合成。首次取消返回 true，已结束返回 false。使用输出对象时：不调用 output 的任何方法；停止声音请另行调用 output.close()。使用回调表时：在 cancel 内同步触发一次 onFinish(null,err)，err.code 为 cancelled。之后不再有任何回调。 ### edgeTtsTaskObject.done # 合成是否已终结。 ### edgeTtsTaskObject.elapsedMs # 任务终结时的总耗时。 ### edgeTtsTaskObject.error # 错误表：code,message,stage,partial,retryable，以及可选 httpStatus。 partial 表示已交付过音频。不自动重试，避免重复朗读。 ### edgeTtsTaskObject.firstAudioMs # 自任务创建到首音频块的毫秒数；尚无音频则为 null。 ### edgeTtsTaskObject.format # 音频描述：codec,mimeType,sampleRate,channels,bitrate。描述编码流，不是 PCM。 ### edgeTtsTaskObject.id # 本次请求唯一 ID。 ### edgeTtsTaskObject.result # 成功结果：id,format,audioBytes,audioChunks,firstAudioMs,elapsedMs。不包含完整音频，完整音频由调用者按需收集。 ### edgeTtsTaskObject.state # connecting,synthesizing,streaming,completed,failed,cancelled。 ### edgeTtsTaskObject.wait(timeoutMs) # 消息泵等待合成结束，返回 result,err。可选等待超时不取消任务，错误码为 wait_timeout。不要在该任务的回调内调用 wait。