ruiyun-human 1.0.19 → 1.0.21

package/README.md

@@ -1,7 +1,296 @@
 # shuzirenzujian
 
-数字人前端自助机组件
-npm 发包
+数字人前端自助机组件（Vue 3）
+
+---
+
+## 发布 / 安装
+
+```bash
+# 发包（npm 所有人：睿政云-陆洋）
 npm publish
 
-npm所有人 睿政云-陆洋
+# 使用方安装
+npm install ruiyun-human
+```
+
+---
+
+## 功能一览
+
+| 能力 | 说明 |
+|---|---|
+| 说话同步 | `playTTS(text)` 调京东 TTS → 播放音频 → `onplaying` 驱动说话动画，`onended` 自动回待机 |
+| 音色切换 | 每个 `humanId` 预置 `timbre`，父组件可覆写 |
+| 静音控制 | 父组件改 `human.isMuted` **实时生效**，播放中静音会立即停声并回待机 |
+| 录音转写 | `startRecord()` / `stopRecord()` 录 16kHz / 16bit / 单声道 WAV → ASR → emit `audio-ready` |
+| 形象内置 | 组件内置 5 套预设形象，父组件只需传 `{ humanId }` |
+| PC / 移动端 | 同一 `humanId` 配 `folder`(PC) 与 `folder_mobile`(移动端)，由 `humanType` 选择 |
+
+---
+
+## 快速上手
+
+```vue
+<template>
+  <DigitalHuman
+    ref="humanRef"
+    :human="human"
+    :szraddress="'https://116.198.239.205:8443/'"
+    style="width:500px;height:500px"
+    @loaded="onLoaded"
+    @frames-loaded="onFramesLoaded"
+    @load-error="onLoadError"
+    @changed="onChanged"
+    @audio-ready="onAudioText"
+  />
+</template>
+
+<script setup>
+import { ref, nextTick } from 'vue'
+import DigitalHuman from '@/components/DigitalHuman'
+
+const humanRef = ref(null)
+
+// 最小配置：只传 humanId，其余字段取预设默认值
+const human = ref({ humanId: 5 })
+
+// 画面就绪：待机帧已加载并完成首次绘制
+const onLoaded = (h, info) => console.log('画面已就绪:', h.title, info.total, '张待机帧')
+// 全部帧（待机 + 说话）加载完成
+const onFramesLoaded = (info) => console.log('全部帧加载完成:', info.allReady, `${info.broken}/${info.total} 损坏`)
+// 待机帧一张都没出来
+const onLoadError = (info) => console.error('图片加载失败:', info.folder)
+const onChanged = (h) => console.log('已切换:', h.title)
+const onAudioText = (res) => console.log('转写结果:', res.text)
+
+// 播报（自动驱动说话动画）
+const speak = () => {
+  humanRef.value.playTTS('您好，我是政务服务中心 AI 数字人')
+}
+
+// 切音色 → 必须 await nextTick() 再播，否则用的是上一次的音色
+const setTimbreAndPlay = async (timbre, text) => {
+  human.value = { ...human.value, timbre }
+  await nextTick()
+  humanRef.value.playTTS(text)
+}
+
+// 静音开关：改 human 即可，子组件 watch 立即生效
+const toggleMuted = async () => {
+  human.value = { ...human.value, isMuted: !human.value.isMuted }
+  await nextTick()
+}
+</script>
+```
+
+> 组件根元素是 `width:100%;height:100%`，**父容器必须给出明确宽高**，否则画面会按 300×300 兜底并在控制台告警。
+
+---
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+|---|---|---|---|---|
+| `human` | `Object \| null` | `null` | ✅ | 数字人描述对象，最小只需 `{ humanId }`，其余字段覆盖预设默认值 |
+| `szraddress` | `String` | `https://sqsyky.xzspj.suqian.gov.cn:8443` | ❌ | 服务根地址，同时用于 TTS / ASR / 图片资源 |
+
+### `human` 对象字段
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `humanId` | `number` | ✅ | — | 形象编号 **1~5**，见下方预设表 |
+| `humanType` | `number` | ❌ | 按 UA 自动判断 | `1` PC 端资源；`2` 移动端资源（头部特写） |
+| `isMuted` | `boolean` | ❌ | `false` | **`true` = 静音（不发声）；`false` = 正常播放**。实时生效，播放中改也会立刻停声 |
+| `timbre` | `number` | ❌ | 预设值 | 京东 TTS 音色编号，常用：男 `1`/`35`/`47`，女 `0`/`3`/`34`/`45`/`51`/`52` |
+| `title` | `string` | ❌ | 预设值 | 形象名称，用于 `loaded` / `changed` 事件与日志 |
+
+---
+
+## Emits
+
+| 事件名 | 负载 | 触发时机 |
+|---|---|---|
+| `loaded` | `(human, info)` | **画面就绪**：待机帧加载完并完成首次绘制（首帧不可用则不触发，改发 `load-error`） |
+| `frames-loaded` | `(info)` | **全部帧**（待机 + 说话）加载完成或超时；说话帧可达上百张，通常晚于 `loaded` |
+| `load-error` | `(info)` | 待机帧一张都没加载出来（地址错误 / 跨域 / 超时），画面出不来 |
+| `changed` | `(human, info)` | 调用 `switchHuman()` 切换形象并加载完成后 |
+| `paused` | — | 调用 `pause()` 后 |
+| `resumed` | — | 调用 `resume()` 后 |
+| `audio-ready` | `({ status, text })` | `stopRecord()` 转写完成后；录音过短（<1KB）或转写失败**不 emit** |
+
+`info` 字段：`{ humanId, title, folder, total, broken, timedOut }`，`frames-loaded` 额外带 `allReady`。
+
+---
+
+## defineExpose 方法
+
+父组件通过 `ref.value.xxx()` 调用。
+
+| 方法 | 参数 | 说明 |
+|---|---|---|
+| `playTTS(text)` | `text: string` | 合成并播报：中止上一次 TTS → 请求音频 → 播放并驱动说话动画 → 播完回待机。**静音时直接跳过，不发起请求** |
+| `standby()` | — | 立即切回待机动画，不发声 |
+| `speak()` | — | 立即播放说话动画，不发声 |
+| `stopSpeaking()` | — | 中止未完成 TTS → 停当前音频 → 跑说话结束动画 → 自动回待机 |
+| `pause()` | — | 停声 + 冻结画面，emit `paused` |
+| `resume()` | — | 从冻结帧继续播放，emit `resumed`（**不会续播被停掉的音频**，需重新 `playTTS`） |
+| `switchHuman(humanId)` | `humanId: number` | 直接切形象（不经过父组件 `human`），emit `changed` |
+| `startRecord()` | — | 开始录音（需麦克风授权），16kHz / 16bit / 单声道 |
+| `stopRecord()` | — | 停止录音 → 过短丢弃 → ASR 转写 → emit `audio-ready` |
+| `isReady()` | — | 返回 `boolean`：画面是否已就绪（待机帧已加载并完成首次绘制） |
+| `isFullyLoaded()` | — | 返回 `boolean`：全部帧（待机 + 说话）是否已加载完成 |
+| `whenReady(timeout)` | `timeout? = 15000` | 返回 `Promise<boolean>`，等画面就绪；超时 resolve `false` |
+| `whenFullyLoaded(timeout)` | `timeout? = 30000` | 返回 `Promise<boolean>`，等全部帧加载完成；超时或存在损坏帧 resolve `false` |
+
+---
+
+## 判断图片是否加载完成
+
+组件提供「事件回调」和「主动查询」两种方式，按场景选一种即可。
+
+### 方式一：事件回调（推荐）
+
+```vue
+<DigitalHuman
+  ref="humanRef"
+  :human="human"
+  @loaded="onLoaded"               <!-- 画面就绪：可以开始交互 / 播报 -->
+  @frames-loaded="onFramesLoaded"  <!-- 全部帧就绪：口型动画完整 -->
+  @load-error="onLoadError"        <!-- 加载失败：地址错误 / 跨域 / 超时 -->
+/>
+```
+
+| 阶段 | 事件 | 含义 |
+|---|---|---|
+| 1 | `loaded` | 待机帧加载完并画出第一帧，**画面已可见**，此时调用 `playTTS` 是安全的 |
+| 2 | `frames-loaded` | 待机 + 说话帧全部处理完（或 30s 超时），`info.allReady === true` 表示零损坏 |
+| — | `load-error` | 待机帧一张都没出来，画面空白；与 `loaded` **互斥**，不会同时触发 |
+
+`loaded` / `changed` 第一个参数仍是 human 对象（兼容旧写法），第二个参数是 `info`：
+`{ humanId, title, folder, total, broken, timedOut }`。
+
+### 方式二：主动查询（ref 方法）
+
+```js
+humanRef.value.isReady()        // boolean：画面是否已就绪
+humanRef.value.isFullyLoaded()  // boolean：全部帧（待机+说话）是否加载完
+
+await humanRef.value.whenReady(10000)        // Promise<boolean>，等画面出来
+await humanRef.value.whenFullyLoaded(30000)  // Promise<boolean>，等全部帧
+```
+
+典型用法：切换形象后等画面出来再播报
+
+```js
+const switchAndSpeak = async (humanId, text) => {
+  human.value = { ...human.value, humanId }   // 触发重新加载
+  const ok = await humanRef.value.whenReady(10000)
+  if (!ok) {
+    console.warn('数字人加载超时')
+    return
+  }
+  humanRef.value.playTTS(text)
+}
+```
+
+> 说话帧可达上百张，`isReady()` 通常几百毫秒内为 true，`isFullyLoaded()` 要等全部下载完。
+> **播报不依赖 `isFullyLoaded()`**——说话帧没下完时动画会自动回退待机帧，不会白屏。
+
+---
+
+## 预设形象表
+
+| humanId | title | folder (PC) | folder_mobile (移动端) | timbre |
+|---|---|---|---|---|
+| 1 | 西装动漫男 | `xiangyu-green-suit` | `xiangyu-green-suit-header` | 47 |
+| 2 | 西装动漫女 | `anime-woman` | `anime-woman-header` | 45 |
+| 3 | 真人形象男 | `real-man` | `real-man-header` | 47 |
+| 4 | 真人形象女 | `real-woman` | `real-woman-header` | 34 |
+| 5 | Q 版形象 | `xiangyu-q` | `xiangyu-q-header` | 47 |
+
+图片实际路径：`{szraddress}/szrimage/{folder}/standby|speak/...`
+
+### humanType 资源选择规则
+
+```
+1. humanType = 2 且 folder_mobile 存在 → 用 folder_mobile
+2. humanType = 1                      → 用 folder
+3. humanType 未传 → 按 UA 自动判断（Android / iPhone / iPad / HarmonyOS → 移动端）
+```
+
+> `folder_mobile` 未配置时永远回退到 `folder`，不会 404。
+> `humanId` 或 `humanType` 变化才会重新加载帧；只改 `isMuted` / `timbre` 不会重载，画面无闪烁。
+
+---
+
+## 依赖
+
+| 包 | 版本 | 用途 |
+|---|---|---|
+| `vue` | `^3.4` | Composition API |
+| `js-audio-recorder` | `^1.0.7` | 浏览器录音，固定 16kHz / 16bit / 单声道（与京东 ASR 匹配） |
+
+---
+
+## 接口对照
+
+| 服务 | 方法 | URL | 请求体 | 返回 |
+|---|---|---|---|---|
+| 京东 TTS | POST | `{szraddress}/web/voice/jd/text-to-speech` | `{ text, user, timbre }` + `clientid` / `tenant-id` 头 | 音频二进制（裸 PCM 自动补 WAV 头）或 JSON（兼容 `data.url` / `data.audio` / `data.base64`） |
+| 京东 ASR | POST | `{szraddress}/web/voice/jd/speech-to-text?domain=general&sampleRate=16000` | `multipart/form-data: file=<wav>` + 同上头 | JSON，兼容 `text` / `data.text` / `result` |
+
+---
+
+## ⚠️ 注意事项
+
+### 1. `isMuted` 语义：**true = 静音**
+
+早期版本语义是反的（`true` 反而出声），现已修正为符合直觉的语义。升级后原来写 `isMuted: true` 表示"开启声音"的调用方需要改成 `false`。
+
+不传该字段时默认 `false`（正常播放）。
+
+静音是**实时**的：
+
+- 播放前静音 → `playTTS` 直接跳过，不发起合成请求
+- 合成中静音 → 音频合成回来后被丢弃，不播放
+- 播放中静音 → 立即中止 TTS、停掉声音并切回待机动画
+
+### 2. 切音色 / 切形象后必须 `await nextTick()`
+
+Vue 响应式更新是**微任务**。父组件改完 `human` 同步立刻调 `playTTS()`，子组件 `props.human` 还是旧值，会用上一次的 `timbre` / `isMuted`。
+
+```js
+// ❌ 会用旧的 timbre
+human.value = { ...human.value, timbre: 47 }
+humanRef.value.playTTS(text)
+
+// ✅
+human.value = { ...human.value, timbre: 47 }
+await nextTick()
+humanRef.value.playTTS(text)
+```
+
+`playTTS` 内部也会再读一次 `props.human` 兜底，但建议父组件自己养成 `await nextTick()` 的习惯。
+
+### 3. 切换形象 / 再次 playTTS 会中止上一次 TTS
+
+组件内部有完整取消链：`playTTS` 开头、`switchHuman` / `init` 重载帧前、`onUnmounted` 都会 `abortTTS()`，不会出现多个 TTS 叠加。`pause()` 同样会停掉正在播的声音。
+
+### 4. 录音过短会被静默丢弃
+
+`stopRecord()` 内 `blob.size < 1000` 直接 return，既不请求 ASR 也不 emit `audio-ready`（1KB ≈ 0.5 秒语音，用于过滤误触）。
+
+### 5. 帧图加载失败有明确事件，不再只是白屏
+
+- **单张**帧图失败：不抛错，绘制时自动跳过该帧（`pickDrawable` 找邻近可用帧），动画不中断。
+- **待机帧全部**失败：emit `load-error`（不发 `loaded`），父组件可据此显示错误态；控制台也会打印 `[DigitalHuman] ❌ 帧加载失败` 与 folder 地址。
+- 全部帧处理完后 emit `frames-loaded`，用 `info.broken` 可知道损坏了几张。
+
+若整体白屏，先确认父容器宽高非 0，再看控制台日志与 `load-error` 是否触发。
+
+---
+
+## npm publish
+
+睿政云-陆洋