更新记录

1.0.0（2026-09-07）

• 首次发布
• 支持离线语音合成（内置度小宇/度小美/度逍遥/度丫丫 4 个发音人模型）
• 支持在线语音合成（永久 iamKey 鉴权）
• 支持 speak/synthesize/pause/resume/stop/release 完整控制接口
• 支持合成事件回调：开始/进度/音频数据/完成/错误
• 支持引擎与模型信息查询（getTTSInfo）

平台兼容性

uni-app(4.27)

uni-app x(3.8.5)

zy-baidutts 百度离线语音合成

基于百度语音合成 Android SDK 6.4.0（tts_1.0.3-9c93a23）封装的 UTS 插件（原生混编实现），支持纯离线语音合成与在线语音合成，内置 4 个离线发音人模型，无需联网即可完成语音播报。

功能特性

• 离线合成：插件内置 4 个发音人声学模型 + 中文文本模型，首次启动自动复制到应用私有目录，断网可用
• 在线合成：支持永久 iamKey 鉴权，一次配置长期使用
• 混合模式（mix）：离线引擎与在线引擎同时加载，单次合成可指定模式
• 完整控制：speak（合成并播放）、synthesize（仅合成不播放）、pause（暂停）、resume（继续）、stop（停止）、release（释放资源）
• 按次切换发音人：单次合成可临时指定发音人，无需重新初始化
• 单次合成参数：语速/音量/音调可按次覆盖
• 音频数据回调：可获取合成音频（16K 16bits 单声道 PCM 的 Base64），用于保存文件或自定义播放
• 事件回调：合成开始、合成数据、播放进度、播放完成、错误等全流程事件

平台支持

环境要求

• HBuilderX 4.27 及以上版本（回调 keepAlive 特性依赖 4.27+）
• uni-app 项目（vue2 / vue3 均可）
• 必须打云端自定义基座：插件包含三方原生 SDK（AAR 约 10MB）与离线模型（约 55MB），标准基座不包含，本地标准基座运行无法生效

集成方式

1. 将插件放入项目 uni_modules 目录（或通过插件市场导入）
2. 在 HBuilderX 中选择「运行 → 运行到手机或模拟器 → 制作自定义调试基座」或「发行 → 原生 App-云打包」，勾选自定义基座
3. 代码中导入使用：

import { initTTS, speak, synthesize, pauseTTS, resumeTTS, stopTTS, releaseTTS, getTTSInfo } from "@/uni_modules/zy-baidutts";

快速上手

import { initTTS, speak } from "@/uni_modules/zy-baidutts";

// 1. 初始化引擎（离线模式需要 appId + 序列号 SN）
initTTS({
  mode: "offline",
  appId: "您的AppId",
  authSn: "您的序列号SN",
  speaker: "duxiaomei",
  speed: "5",
  enableLog: false,
  success: (res) => {
    console.log("初始化成功，引擎版本=" + res.engineVersion);
    console.log("文本模型：" + res.textModelPath);
    console.log("声学模型：" + res.speechModelPath);
  },
  fail: (err) => {
    console.log("初始化失败：" + err.errMsg + " (errCode=" + err.errCode + ")");
  }
});

// 2. 合成并播放
speak({
  text: "你好，世界",
  onStart: (res) => {
    console.log("合成开始，utteranceId=" + res.utteranceId);
  },
  : (res) => {
    console.log("播放进度：" + res.progress + "%");
  },
  onFinish: (res) => {
    console.log("播放完成，engineType=" + (res.engineType === 0 ? "在线" : "离线"));
  },
  onError: (res) => {
    console.log("合成出错：" + res.errorMessage);
  }
});

鉴权说明

内置离线模型

插件 utssdk/app-android/assets/ 目录内置以下模型（共约 55MB），首次初始化自动复制到应用私有目录 filesDir/tts_models/（只复制一次，之后直接使用）：

中文文本模型（所有发音人共用）：bd_etts_common_text_txt_all_mand_eng_middle_big_v6.0.0_20240731.dat（15.5MB）

如需替换为其他百度模型，将模型文件放入插件 assets 目录，并通过 initTTS 的 textModelPath / speechModelPath 指定文件绝对路径即可。

API 详细说明

initTTS(options) 初始化语音合成引擎

初始化流程：创建合成器实例 → 复制离线模型（异步）→ 设置鉴权与参数 → 加载引擎。重复调用会先释放旧实例再重新初始化。

参数 TTSInitOptions：

TTSInitResult：

speak(options) 合成并播放

将文本加入合成队列，合成完成后自动播放。支持多次调用，SDK 内部按顺序排队播放。

参数 TTSSpeakOptions：

TTSSpeakResult：

注意：success 仅表示任务入队成功，合成与播放结果请通过 onStart / onProgress / onFinish / onError 事件回调获取。

synthesize(options) 仅合成不播放

参数与 speak 完全一致，区别是不自动播放，仅完成合成（音频数据可通过 onAudioData 获取，采样率等信息在 onFinish 的 sampleRate 字段）。

pauseTTS / resumeTTS / stopTTS / releaseTTS 播放控制

// 暂停播放（之后可通过 resumeTTS 恢复）
pauseTTS({ success: (res) => console.log(res.code) });

// 继续播放（只能恢复被"暂停"的任务）
resumeTTS();

// 停止合成并停止播放（彻底终止，不可恢复！）
stopTTS();

// 释放引擎资源（彻底销毁实例，需重新 initTTS 才能继续使用）
releaseTTS();

控制接口参数均为可选 TTSControlOptions：

三个接口的语义区别（重要）：

getTTSInfo(options) 查询引擎/模型信息

参数 TTSInfoOptions：

TTSInfoResult：

事件类型（TTSEvent）

所有事件回调的参数均为 TTSEvent 对象：

type 取值：

保存音频文件示例：将 audioData Base64 解码后按顺序写入同一文件，即可得到完整 PCM；文件扩展名建议 .pcm，16K 采样率 16bit 单声道。

插件错误码

插件自身错误码（errCode），错误对象为 TTSFail（含 errSubject="zy-baidutts"、errCode、errMsg）：

合成/播放过程中的引擎级错误（如授权失败 -102/-109 等）通过 onError 事件的 errorCode / errorMessage 返回，详见百度官方文档《语音合成 Android SDK》错误码章节。

示例代码

<template>
    <view class="page">
        <view class="header">
            <text class="app-title">百度离线语音合成</text>
            <text class="app-subtitle">支持离线合成（内置4发音人）与在线合成</text>
        </view>

        <view class="section">
            <view class="section-title">鉴权配置</view>
            <input class="input" v-model="appId" placeholder="AppId（离线合成必填）" placeholder-class="ph" />
            <input class="input" v-model="authSn" placeholder="序列号 SN（离线合成必填）" placeholder-class="ph" />
            <input class="input" v-model="iamKey" placeholder="永久 iamKey（在线合成必填）" placeholder-class="ph" />
            <view class="mode-row">
                <view class="mode-item" :class="{ active: mode === 'offline' }" @click="mode = 'offline'">离线</view>
                <view class="mode-item" :class="{ active: mode === 'online' }" @click="mode = 'online'">在线</view>
                <view class="mode-item" :class="{ active: mode === 'mix' }" @click="mode = 'mix'">混合</view>
            </view>
        </view>

        <view class="section">
            <view class="section-title">发音人与语速</view>
            <view class="mode-row">
                <view class="mode-item" :class="{ active: speaker === 'duxiaomei' }" @click="speaker = 'duxiaomei'">度小美</view>
                <view class="mode-item" :class="{ active: speaker === 'duxiaoyu' }" @click="speaker = 'duxiaoyu'">度小宇</view>
                <view class="mode-item" :class="{ active: speaker === 'duxiaoyao' }" @click="speaker = 'duxiaoyao'">度逍遥</view>
                <view class="mode-item" :class="{ active: speaker === 'duyaya' }" @click="speaker = 'duyaya'">度丫丫</view>
            </view>
            <view class="slider-row">
                <text class="slider-label">语速 {{ speed }}</text>
                <slider class="slider" :min="0" :max="15" :step="1" :value="speed" activeColor="#4f6ef7" @change="onSpeedChange" />
            </view>
        </view>

        <view class="section">
            <view class="section-title">合成文本</view>
            <textarea class="textarea" v-model="text" placeholder="请输入待合成文本（不超过60个汉字）" placeholder-class="ph"></textarea>
            <view class="progress-row" v-if="playing">
                <text class="progress-label">播放进度：{{ progress }}%</text>
            </view>
        </view>

        <view class="btn-grid">
            <button class="btn primary" @click="handleInit">初始化</button>
            <button class="btn success" @click="handleSpeak">合成播放</button>
            <button class="btn info" @click="handleSynthesize">仅合成</button>
            <button class="btn warn" @click="handlePause">暂停</button>
            <button class="btn warn" @click="handleResume">继续</button>
            <button class="btn warn" @click="handleStop">停止</button>
            <button class="btn danger" @click="handleRelease">释放</button>
            <button class="btn info" @click="handleInfo">引擎信息</button>
        </view>

        <view class="section">
            <view class="section-title">日志</view>
            <scroll-view class="log-area" scroll-y>
                <text class="log-text">{{ logs }}</text>
            </scroll-view>
        </view>
    </view>
</template>

<script>
    import { initTTS, speak, synthesize, pauseTTS, resumeTTS, stopTTS, releaseTTS, getTTSInfo } from "@/uni_modules/zy-baidutts";

    export default {
        data() {
            return {
                appId: '',
                authSn: '',
                iamKey: '',
                mode: 'offline',
                speaker: 'duxiaomei',
                speed: 5,
                text: '百度语音合成，让应用开口说话。',
                logs: '',
                playing: false,
                progress: 0
            }
        },
        methods: {
            log(msg) {
                const now = new Date();
                const time = now.getHours() + ':' + now.getMinutes() + ':' + now.getSeconds();
                this.logs = '[' + time + '] ' + msg + '\n' + this.logs;
            },
            onSpeedChange(e) {
                this.speed = e.detail.value;
            },
            handleInit() {
                if (this.mode === 'offline' && (!this.appId || !this.authSn)) {
                    this.log('离线合成需要填写 AppId 和序列号 SN');
                    return;
                }
                if (this.mode === 'online' && !this.iamKey) {
                    this.log('在线合成需要填写永久 iamKey');
                    return;
                }
                this.log('开始初始化（首次启动需复制模型文件，请耐心等待）...');
                initTTS({
                    mode: this.mode,
                    appId: this.appId,
                    authSn: this.authSn,
                    iamKey: this.iamKey,
                    speaker: this.speaker,
                    speed: String(this.speed),
                    enableLog: true,
                    success: (res) => {
                        this.log('初始化成功 mode=' + res.mode + ' engineVersion=' + res.engineVersion);
                        this.log('文本模型: ' + res.textModelPath);
                        this.log('声学模型: ' + res.speechModelPath);
                    },
                    fail: (err) => {
                        this.log('初始化失败: ' + err.errMsg + ' (errCode=' + err.errCode + ')');
                    }
                });
            },
            handleSpeak() {
                this.playing = true;
                this.progress = 0;
                speak({
                    text: this.text,
                    onStart: (res) => {
                        this.log('合成开始 utteranceId=' + res.utteranceId);
                    },
                    : (res) => {
                        this.progress = res.progress;
                    },
                    onFinish: (res) => {
                        this.playing = false;
                        this.log('播放完成 engineType=' + (res.engineType === 0 ? '在线' : '离线'));
                    },
                    onError: (res) => {
                        this.playing = false;
                        this.log('合成出错: ' + res.errorMessage + ' (code=' + res.errorCode + ')');
                    },
                    fail: (err) => {
                        this.playing = false;
                        this.log('调用失败: ' + err.errMsg + ' (errCode=' + err.errCode + ')');
                    }
                });
            },
            handleSynthesize() {
                synthesize({
                    text: this.text,
                    onFinish: (res) => {
                        this.log('合成完成（未播放），采样率=' + res.sampleRate);
                    },
                    onError: (res) => {
                        this.log('合成出错: ' + res.errorMessage + ' (code=' + res.errorCode + ')');
                    },
                    fail: (err) => {
                        this.log('调用失败: ' + err.errMsg);
                    }
                });
            },
            handlePause() {
                pauseTTS({
                    success: (res) => this.log('已暂停'),
                    fail: (err) => this.log('暂停失败: ' + err.errMsg)
                });
            },
            handleResume() {
                resumeTTS({
                    success: (res) => this.log('已继续'),
                    fail: (err) => this.log('继续失败: ' + err.errMsg)
                });
            },
            handleStop() {
                stopTTS({
                    success: (res) => {
                        this.playing = false;
                        this.log('已停止');
                    },
                    fail: (err) => this.log('停止失败: ' + err.errMsg)
                });
            },
            handleRelease() {
                releaseTTS({
                    success: (res) => this.log('资源已释放 code=' + res.code),
                    fail: (err) => this.log('释放失败: ' + err.errMsg)
                });
            },
            handleInfo() {
                getTTSInfo({
                    success: (res) => {
                        this.log('引擎版本=' + res.engineVersion);
                        this.log('引擎信息=' + res.engineInfo);
                        this.log('设备 cuid=' + res.cuid);
                    },
                    fail: (err) => this.log('查询失败: ' + err.errMsg)
                });
            }
        }
    }
</script>

<style>
.page { min-height: 100vh; background: #f0f2f5; padding-bottom: 40rpx; }
.header { padding: 60rpx 40rpx 40rpx; background: linear-gradient(135deg, #4f6ef7 0%, #6c5ce7 100%); }
.app-title { display: block; color: #ffffff; font-size: 40rpx; font-weight: bold; }
.app-subtitle { display: block; color: rgba(255,255,255,0.85); font-size: 24rpx; margin-top: 10rpx; }
.section { background: #ffffff; border-radius: 16rpx; margin: 24rpx; padding: 24rpx; }
.section-title { font-size: 30rpx; font-weight: bold; color: #333333; margin-bottom: 20rpx; }
.input { border: 1px solid #e0e0e0; border-radius: 8rpx; padding: 16rpx 20rpx; font-size: 28rpx; margin-bottom: 16rpx; }
.ph { color: #bbbbbb; }
.mode-row { display: flex; flex-direction: row; flex-wrap: wrap; }
.mode-item { padding: 12rpx 30rpx; border-radius: 32rpx; background: #f0f2f5; color: #666666; font-size: 26rpx; margin: 0 16rpx 16rpx 0; }
.mode-item.active { background: #4f6ef7; color: #ffffff; }
.slider-row { display: flex; flex-direction: row; align-items: center; }
.slider-label { width: 160rpx; font-size: 26rpx; color: #666666; }
.slider { flex: 1; }
.textarea { width: 100%; height: 160rpx; border: 1px solid #e0e0e0; border-radius: 8rpx; padding: 16rpx 20rpx; font-size: 28rpx; box-sizing: border-box; }
.progress-row { margin-top: 16rpx; }
.progress-label { font-size: 26rpx; color: #4f6ef7; }
.btn-grid { display: flex; flex-direction: row; flex-wrap: wrap; justify-content: space-between; margin: 24rpx; }
.btn { width: 23%; margin-bottom: 16rpx; font-size: 26rpx; line-height: 2.4; }
.btn.primary { background: #4f6ef7; color: #ffffff; }
.btn.success { background: #11998e; color: #ffffff; }
.btn.info { background: #6c5ce7; color: #ffffff; }
.btn.warn { background: #f39c12; color: #ffffff; }
.btn.danger { background: #e74c3c; color: #ffffff; }
.log-area { height: 300rpx; background: #1e1e28; border-radius: 12rpx; padding: 16rpx; }
.log-text { color: #9ae6b4; font-size: 22rpx; font-family: monospace; white-space: pre-wrap; }
</style>

注意事项

1. 自定义基座：插件依赖原生 SDK（AAR）与 55MB 模型资源，必须云端打包自定义基座后运行，标准基座无效。
2. 首次初始化耗时：首次启动需复制约 55MB 模型文件到私有目录，耗时数秒（异步执行，不阻塞 UI），仅执行一次。
3. 文本长度限制：单次合成文本不超过 120 GBK 字节（约 60 个汉字）。长文本请分句后多次调用 speak，SDK 内部会排队依次播放。
4. stop 与 pause 的区别：stopTTS 会彻底终止任务，之后调用 resumeTTS 无效；需要"暂停后继续"请使用 pauseTTS。
5. 回调生命周期（keepAlive）：speak / synthesize 的事件回调（/onAudioData 等）需持续触发，插件已启用 @UTSJS.keepAlive，回调对象常驻内存。请避免高频循环调用 speak（如 for 循环中短间隔调用），正常业务频率无影响。
6. 发音人切换：speak 时传入非默认 speaker，插件会自动将对应声学模型复制到私有目录（首次约需 1 秒）后再入队合成。
7. 鉴权一致性：离线授权校验 appId、应用包名、SN 三者匹配，打包时请确认云打包使用的 Android 包名与百度控制台登记一致。
8. 在线模式数据安全：在线/混合模式下，待合成文本会发送至百度语音服务器；纯离线模式文本仅本地处理。

常见问题（FAQ）

Q1：初始化报 -102 / -109 授权错误？ A：检查 appId、SN 与百度控制台登记信息是否一致；确认云打包的 Android 包名与控制台登记包名完全一致；设备首次使用需联网激活一次授权。

Q2：初始化报 9060008 模型复制失败？ A：确认插件 utssdk/app-android/assets/ 目录下 5 个 .dat 模型文件完整（文本模型 1 个 + 声学模型 4 个），重新打包基座后重试。

Q3：调用 resumeTTS 显示成功但没有继续播放？ A：resumeTTS 只能恢复被 pauseTTS 暂停的任务。若之前调用的是 stopTTS（彻底终止），resume 无法恢复，请重新调用 speak。

Q4： 只触发一次或报"回调函数已释放"？ A：HBuilderX 4.25+ 回调默认单次触发后回收。本插件 speak/synthesize 已配置 @UTSJS.keepAlive 支持持续回调，请确认 HBuilderX 版本 ≥ 4.27。

Q5：支持后台播放吗？ A：合成与播放基于 SDK 内部线程，App 切后台通常可继续播放，但系统回收进程后无法保证；如需长时后台播报，请配合前台服务使用。

Q6：如何获取合成音频保存为文件？ A：speak/synthesize 时设置 needAudioData: true，在 onAudioData 回调中收集 audioData（Base64），全部到齐后（SYNTHESIZE_FINISH）Base64 解码写入文件，即为 16K 16bits 单声道 PCM 数据。

更新日志

见 changelog.md