更新记录

1.0.0（2026-04-25）

初版

平台兼容性

uni-app(4.81)

rd-tts

基于阿里云百炼 CosyVoice 的语音合成(TTS)和语音识别(ASR) UTS 插件，仅支持 iOS 平台。

平台支持

前置条件

• HBuilderX >= 3.7.0
• uni-app >= 4.81
• 阿里云百炼 API Key（获取地址）
• iOS 部署目标 >= 12.0，架构 arm64

安装

将 rd-tts 目录放入项目的 uni_modules/ 下即可。

权限配置

在 manifest.json 的 iOS 权限中添加：

NSMicrophoneUsageDescription - 需要使用麦克风进行语音识别

TTS 语音合成

配置

import { setupTTS } from '@/uni_modules/rd-tts'

setupTTS({
  apikey: 'your-api-key',           // 必填：阿里云百炼 API Key
  model: 'cosyvoice-v2',            // 模型：cosyvoice-v2 / cosyvoice-v3-flash / cosyvoice-v3-plus
  voiceType: 'longxiaochun_v2',     // 发音人/音色
  format: 'mp3',                    // 音频格式：pcm / wav / mp3 / opus
  sampleRate: 24000,                // 采样率：8000/16000/22050/24000/44100/48000
  volume: 50,                       // 音量 0~100，默认 50
  speed: 1.0,                       // 语速 0.5~2.0，默认 1.0
  pitch: 1.0,                       // 音高 0.5~2.0，默认 1.0
  language: 'zh',                   // 目标语言：zh/en/ja/ko 等
  enableSsml: false,                // 是否开启 SSML
  completeWaitingMs: 10000          // stopStreamSynthesis 超时时间(ms)
})

初始化 & 销毁

import { initTTSEngine, destroyTTSEngine } from '@/uni_modules/rd-tts'

// 初始化引擎，返回空字符串表示成功
const err = initTTSEngine()
if (err) { console.error('TTS初始化失败:', err) }

// 销毁引擎
destroyTTSEngine()

一次性合成

适合短文本，支持 SSML：

import { startSynthesis, startAsyncSynthesis } from '@/uni_modules/rd-tts'

// 同步合成（阻塞等待）
const err = startSynthesis('你好，世界', null)

// 异步合成
const err = startAsyncSynthesis('你好，世界', null)

// 带缓存ID，相同 cacheId 直接播放缓存
const err = startSynthesis('你好，世界', 'greeting_001')

流式合成

适合长文本，边合成边播放：

import {
  startStreamSynthesis,
  sendStreamText,
  stopStreamSynthesis,
  asyncStopStreamSynthesis
} from '@/uni_modules/rd-tts'

// 开始流式任务
const err = startStreamSynthesis('stream_001') // 可选 cacheId

// 持续发送文本
sendStreamText('这是第一段文本')
sendStreamText('这是第二段文本')

// 同步结束（阻塞等待完成）
stopStreamSynthesis()

// 或异步结束
asyncStopStreamSynthesis()

停止合成

import { stopSynthesis } from '@/uni_modules/rd-tts'

stopSynthesis() // 取消当前合成任务

播放状态

import { isTTSPlaying } from '@/uni_modules/rd-tts'

const playing = isTTSPlaying()

静音控制

合成继续进行，但播放静音：

import { setTTSMuted } from '@/uni_modules/rd-tts'

setTTSMuted(true)  // 静音
setTTSMuted(false) // 恢复

缓存管理

import { getCurrentCacheId, clearTTSCache } from '@/uni_modules/rd-tts'

// 获取当前缓存ID
const cacheId = getCurrentCacheId()

// 清除所有缓存
clearTTSCache()

TTS 回调

import {
  onTtsSynthesisBegin,
  onTtsSynthesisEnd,
  onTtsStartPlaying,
  onTtsFinishPlaying,
  onTtsAudioData,
  onTtsPlaybackProgress,
  onTtsError
} from '@/uni_modules/rd-tts'

onTtsSynthesisBegin(() => { console.log('合成开始') })
onTtsSynthesisEnd(() => { console.log('合成完成') })
onTtsStartPlaying(() => { console.log('开始播放') })
onTtsFinishPlaying(() => { console.log('播放完成') })
onTtsAudioData((audioData: Data) => { /* 接收音频数据 */ })
onTtsPlaybackProgress((progress: Int) => { console.log('播放进度:', progress) })
onTtsError((errMsg: string) => { console.error('TTS错误:', errMsg) })

ASR 语音识别

配置

import { setupASR } from '@/uni_modules/rd-tts'

setupASR({
  apikey: 'your-api-key',                // 必填：阿里云百炼 API Key
  model: 'paraformer-realtime-v2',       // 识别模型
  sampleRate: 16000,                      // 采样率
  enableITN: true,                        // 中文数字转阿拉伯数字
  enablePunc: true,                       // 添加标点
  autoStop: true,                         // 启用语音检测(VAD)
  vadStartSilence: 10000,                 // 最大开始静音时长(ms)
  vadEndSilence: 800,                     // 最大结尾静音时长(ms)
  enableIntermediateResult: true,         // 启用中间结果
  enableVoiceDetection: true,             // 启用语音检测
  maxSentenceSilence: 800,                // 最大句间静音(ms)
  disfluency: false,                      // 过滤语气词
  serviceType: 4                          // 服务类型
})

初始化 & 销毁

import { initEngine, destroyEngine } from '@/uni_modules/rd-tts'

const success = initEngine()   // 返回 boolean
destroyEngine()

录音识别

import { startRecording, stopRecording, isRecording } from '@/uni_modules/rd-tts'

startRecording()
stopRecording(false)  // false: 正常停止; true: 强制停止
const recording = isRecording()

ASR 回调

import {
  onResult,
  onError,
  onRecordingStart,
  onRecordingStop,
  onEngineStart,
  onEngineStop,
  ,
  onAudioVolume
} from '@/uni_modules/rd-tts'

onResult((rawData: string, isFinal: boolean) => {
  console.log('识别结果:', rawData, isFinal ? '(最终)' : '(中间)')
})
onError((errMsg: string) => { console.error('ASR错误:', errMsg) })
onRecordingStart(() => { console.log('录音开始') })
onRecordingStop(() => { console.log('录音停止') })
onEngineStart(() => { console.log('引擎启动') })
onEngineStop(() => { console.log('引擎停止') })
((volume: Int) => { console.log('音量:', volume) })
onAudioVolume((volume: number) => { console.log('音频音量:', volume) })

录音文件保存

import {
  saveRecordingAsWAV,
  getRecordedDataSize,
  clearRecordedData,
  stopAndSaveRecording
} from '@/uni_modules/rd-tts'

const wavPath = saveRecordingAsWAV()    // 保存为 WAV，返回路径
const size = getRecordedDataSize()       // 获取录音数据大小
clearRecordedData()                      // 清空录音数据
const path = stopAndSaveRecording()      // 停止录音并保存

文件转写

import {
  startFileTranscription,
  queryFileTranscription,
  cancelFileTranscription,
  onFileTransResult,
  onFileTransComplete
} from '@/uni_modules/rd-tts'

const taskId = startFileTranscription('/path/to/audio.wav')
queryFileTranscription(taskId)
cancelFileTranscription(taskId)

onFileTransResult((text: string, isFinal: boolean) => {
  console.log('转写结果:', text)
})
onFileTransComplete(() => { console.log('转写完成') })

设备信息

使用 ASR/TTS 前建议初始化设备信息：

import { initDeviceInfo } from '@/uni_modules/rd-tts'

initDeviceInfo()

完整使用流程

TTS 流程

import {
  setupTTS, initTTSEngine, initDeviceInfo,
  startSynthesis, onTtsStartPlaying, onTtsFinishPlaying, onTtsError,
  destroyTTSEngine
} from '@/uni_modules/rd-tts'

// 1. 配置
setupTTS({ apikey: 'xxx', model: 'cosyvoice-v2', voiceType: 'longxiaochun_v2' })

// 2. 初始化
initDeviceInfo()
const err = initTTSEngine()

// 3. 注册回调
onTtsStartPlaying(() => console.log('开始播放'))
onTtsFinishPlaying(() => console.log('播放完成'))
onTtsError((msg) => console.error(msg))

// 4. 合成播放
startSynthesis('你好世界', null)

// 5. 销毁
destroyTTSEngine()

ASR 流程

import {
  setupASR, initEngine, initDeviceInfo,
  startRecording, stopRecording,
  onResult, onError, onRecordingStart, onRecordingStop,
  destroyEngine
} from '@/uni_modules/rd-tts'

// 1. 配置
setupASR({ apikey: 'xxx', model: 'paraformer-realtime-v2' })

// 2. 初始化
initDeviceInfo()
initEngine()

// 3. 注册回调
onResult((data, isFinal) => console.log(data, isFinal))
onError((msg) => console.error(msg))
onRecordingStart(() => console.log('录音开始'))
onRecordingStop(() => console.log('录音停止'))

// 4. 开始识别
startRecording()

// 5. 停止识别
stopRecording(false)

// 6. 销毁
destroyEngine()

TTSConfig 参数说明

ASRConfig 参数说明