Appearance
VoiceToonBot SDK（卡通形象） 快捷使用说明
SDK 资源
https://robot.chaoxing.com/sdk/VoiceToonBot.js — 正式环境 SDK 文件
https://robot1.chaoxing.com/sdk/VoiceToonBot.js — 测试环境 SDK 文件
https://robot-dev.chaoxing.com/sdk/VoiceToonBot.js — 开发环境 SDK 文件
初始化属性
请保证 origin 与 SDK js 资源引用地址始终一致
| 属性名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| appId | string | ✅ | 智能体开放平台应用 ID 鉴权说明 | |
| appAuthToken | string | ✅ | SDK 接入 token 鉴权说明 | |
| origin | string | ✅ | - | 服务地址 查看选项 |
| element | string/HTMLElement | ✅ | - | 容器元素，可以是选择器或元素对象 |
| preset | string | ✅ | - | 形象预置名称 |
| animationType | string | json | 动画数据类型 可选值 | |
| tone | string | xiaoyan | 语音音色可选值 | |
| asr | number | 0 | 是否启用 ASR 语音识别 可选值 | |
| speak | number | 0 | 是否启用语音合成 可选值 | |
| talkRules | object | - | 朗读读音纠错规则 查看详情 | |
| listenWeakup | number | 1 | 唤醒监听开关，为0时允许用户手动启动，为1时自动启动 可选值 | |
| wakeword | number | - | 唤醒词，仅支持中文 （启动 ASR 后生效） | |
| wakewordAuxs | number | - | 辅助唤醒词，仅支持中文，多个用逗号分隔 （启动 ASR 后生效） | |
| locale | string | zh-CN | 多语言设置可选值 | |
| renderer | string | svg | 指定渲染器可选值 | |
| rendererSettings | object | - | 渲染设置 |
属性值说明
origin
服务提供地址，请根据不同的环境选择不同的地址。
开发环境：
https://robot-dev.chaoxing.com测试环境：
https://robot1.chaoxing.com生产环境：
https://robot.chaoxing.com
animationType
| 动画类型 | 说明 |
|---|---|
| json | JSON 动画 |
| apng | apng 动画 |
| image | image 动画 |
locale
| 语言值 | 说明 |
|---|---|
| zh-CN | 中文 |
| en-US | 英文 |
tone
| 音色值 | 说明 |
|---|---|
| x4_guange | 男声 |
| x4_lingxiaoyao_em | 女声 |
| x4_ningning | 男童 |
| tencent:601012 | 女童 |
asr
| 值 | 说明 |
|---|---|
| 0 | 关闭 |
| 1 | 开启 |
speak
| 值 | 说明 |
|---|---|
| 0 | 关闭 |
| 1 | 开启 |
talkRules
提示
若您需要使用智能体页面的读音规则请对接 获取机器人文字发音配置接口
| 属性名 | 类型 | 是否必填 | 示例格式 | 说明 |
|---|---|---|---|---|
| phoneticRules | Array | 否 | [{ "scene": "丽水市", "pronunciation": "li2 shui3 shi4" }] | 拼音标注规则 |
| regexRules | Array | 否 | [{"scene": "文档编码:(\d+)\/ks", flag:"g", "pronunciation": "$1-ks"}] | 正则替换规则 |
| textRules | Array | 否 | [{ "scene": "丽水市", "pronunciation": "丽水", flag: "g" }] | 文本替换规则 |
listenWeakup
提示
- 为
0时允许用户手动启动，为1时自动启动 - 启用 ASR 后生效
- 推荐为
0，用户手动启动更符合使用习惯
| 值 | 说明 |
|---|---|
| 0 | 关闭（手动开启） |
| 1 | 开启（自动开启） |
renderer
提示
默认svg渲染器存在问题时可切换canvas渲染器尝试修复
| 渲染器 | 说明 |
|---|---|
| svg | SVG 渲染器 |
| canvas | Canvas 渲染器 |
rendererSettings 配置
| 属性名 | 类型 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|---|
| preserveAspectRatio | string | 否 | xMinYMin slice | 缩放控制，可选值 |
静态方法
| 方法签名 | 说明 |
|---|---|
init(options: Object) => Promise<VoiceToonBotInstance> | 初始化形象 |
getClass(animationType: string) => VoiceToonBotClass | （🚀 高级用法）获取指定动画数据类型的专用初始化类 |
实例方法
| 方法签名 | 说明 |
|---|---|
talk(text:string, options?:{ intercept?:boolean = true }) => void | 触发语音朗读, intercept = false 时允许连续多次调用而不打断前序朗读 |
on(event: string, callback: function) => void | 监听事件 |
once(event: string, callback: function) => void | 监听事件（仅监听一次，触发后自动取消监听） |
off(event: string, callback?: function) => void | 关闭事件监听 |
setLocale(locale:string) => void | 切换多语言设置 |
setVolume(volume:number, duration?:number) => void | 设置音量，第一个参数为音量（0-1），第二个参数为淡入淡出过渡时间（ms） |
setSpeed(volume:number) => void | 设置语音倍速，值为 0.5-2.5，设置后下次调用 talk 生效 |
playThinkingAnimation() => void | 随机播放一个思考动画（需要动画拥有thinkFrames） |
stopAnimation() => void | 停止动画播放 |
playAnimationBySegment(animation: String | Array, options: { loop?: boolean }) => void | 播放指定动画 |
pause() => void | 暂停语音 |
resume() => void | 恢复语音（不能恢复被 intercept中断的语音） |
intercept() => void | 中断语音 |
destroy() => void | 销毁形象 |
事件
| 事件名称 | 回调签名 | 说明 |
|---|---|---|
| analysis | (isMute: boolean, data: Float32Array[]) => void | 音频时点分析事件，第一个参数为当前是否静音，第二个参数为的音频数据采样 |
| speakControl | (status: boolean) => void | 语音控制开关状态变更 |
| talkStart | (e: Event) => void | 语音播放时触发 |
| talkEnd | (e: Event) => void | 语音播放结束时触发 |
| loadProgress | (percent: number) => void | 形象加载进度变化 |
| loadComplete | (percent: number) => void | 形象加载完成 |
| wakeup | () => void | 语音唤醒成功 |
| asrStart | (status: boolean) => void | 语音识别开启 |
| asrStop | (status: boolean) => void | 语音识别关闭 |
| animationStart | (animationName: String | Array) => void | 开始播放动画 |
| animationEnd | (animationName: String | Array) => void | 停止播放动画（被打断的动画不会触发该事件） |
| asrControl | (status: boolean) => void | 点击形象上的 ASR 控制开关时返回 ASR 启用状态 |
| asrResult | (text: string) => void | ASR 语音识别成功 |
| asrError | (error: Error) => void | ASR 语音识别触发异常 |
| localeChange | (locale: string) => void | 多语言切换时触发，提供当前使用的新语言 |
| error | (error: string) => void | 运行时异常捕获 |
代码示例
javascript
// ESM 模式引入 SDK；浏览器可直接使用 script 标签引入 IIFE 格式的 SDK
import VoiceToonBot from "path-to-sdk";
const options = {
appId: "your_app_id",
appAuthToken: "your_app_auth_token",
origin: "", // TTS服务认证源
preset: "", // 预置配置名称，仅用于预置建议模式
element: "#botContainer", // 容器元素，可以是选择器或元素对象
};
const bot = await VoiceToonBot.init(options).catch((error) => {
// 初始化异常捕获
});
if (!bot) return;
bot.on("error", (error) => {
// 运行时异常捕获
});
bot.on("loadProgress", (percent) => {
// 加载进度
});
bot.on("loadComplete", () => {
// 加载成功做点什么
});
bot.on("talkStart", () => {
// 讲话开始做点什么
});
bot.on("talkEnd", () => {
// 讲话结束做点什么
});
// 触发语音
bot.talk("你好，让我说点什么吧");
// 中断语音
bot.intercept();
// 销毁实例，释放资源
bot.destroy();