save

docs/语音播报内容设计文档_V1.0.md

@@ -0,0 +1,63 @@
+# 巨子测肤 · 1'me 语音播报内容设计文档 V1.0
+
+> 用途:语音文件生成与前端播放的唯一契约。生成方按本文件的「文件名/文案/时长」产出音频;前端按「文件名/触发时机」播放。
+> 落地目录:`h5/assets/voice/<文件名>`(与代码约定一致,缺失文件前端静默跳过,不报错)。
+
+## 1. 音频格式约定(已定)
+
+| 项 | 约定 | 理由 |
+|---|---|---|
+| 容器/编码 | **MP3(MPEG-1 Layer III)** | iOS Safari / Android Chrome / 微信 webview 全量原生可解码;OGG Vorbis 在 iOS Safari 不被支持,弃用 |
+| 码率/声道/采样率 | 48 kbps CBR · 单声道 · 22050 Hz | 纯语音足够,单条约 15–25 KB |
+| 响度 | 归一化到 −16 LUFS 左右 | 各条音量一致,不与系统提示音打架 |
+| 首尾静音 | ≤150 ms | 提示要"跟手",留白会显迟钝 |
+| 音色 | 女声、普通话、语速适中偏缓、亲和 | 与品牌调性一致;三条步骤引导/姿态提示/倒计时必须同一音色 |
+
+## 2. 播报清单(14 条)
+
+### A. 步骤引导(进入每个拍照步骤时播,与屏幕步骤文案一致)
+
+| 文件名 | 文案 | 触发时机 | 时长 |
+|---|---|---|---|
+| `step1-front.mp3` | 请单人正脸出镜,面部对准取景框 | 进入拍照页 1/3 正脸步 | ≈3s |
+| `step2-rightface.mp3` | 请保持单人出镜,慢慢向左转头,露出右脸 | 进入 2/3 右脸出镜步 | ≈4s |
+| `step3-leftface.mp3` | 请慢慢向右转头,露出左脸 | 进入 3/3 左脸出镜步 | ≈3s |
+
+> 语义说明:2/3 步需要画面中看到「右脸」= 用户头向**左**转;3/3 步看到「左脸」= 头向**右**转。语音引导的是用户动作,与取景蒙版方向一致,不要改写成"露出左侧/右侧脸"这类歧义表述。
+
+### B. 姿态提示(实时检测不通过时播,同一提示 4 秒内不重复)
+
+| 文件名 | 文案 | 触发时机(与屏幕提示同文本) | 时长 |
+|---|---|---|---|
+| `hint-noface.mp3` | 未检测到人脸,请正对镜头 | 画面无人脸 | ≈3s |
+| `hint-near.mp3` | 请靠近一点 | 人脸框过高占比 <35%(太远) | ≈1.5s |
+| `hint-far.mp3` | 请远一点 | 占比 >80%(太近) | ≈1.5s |
+| `hint-front.mp3` | 请正对屏幕 | 正脸步角度不合格 | ≈1.5s |
+| `hint-turn-left.mp3` | 请向左转头 | 需要头向左转修正角度时 | ≈1.5s |
+| `hint-turn-right.mp3` | 请向右转头 | 需要头向右转修正角度时 | ≈1.5s |
+| `hint-hold.mp3` | 保持不动 | 姿态已合格、进入稳定确认 | ≈1.5s |
+
+### C. 拍摄与流程
+
+| 文件名 | 文案 | 触发时机 | 时长 |
+|---|---|---|---|
+| `countdown-321.mp3` | 三、二、一 | 自动拍摄 3s 倒计时开始(与屏幕大数字同步起播) | ≈2.5s |
+| `shot-done.mp3` | 拍摄完成 | 每张照片抓拍成功(白屏补光结束) | ≈1.5s |
+| `analyzing.mp3` | 正在生成您的肌肤报告,请稍候 | 三张拍完进入「分析中」浮层 | ≈3s |
+| `analyze-fail.mp3` | 检测失败,请调整后重新拍摄 | 检测失败回到档案页时 | ≈3s |
+
+## 3. 播放策略(前端已实现侧约定)
+
+1. **清单制**:语音文件配 `assets/voice/manifest.json`(格式 `{"files":["step1-front","hint-near",...]}`,内容为已生成的文件名去 .mp3)。前端只播清单里声明的条目;清单或条目缺失时该条静默跳过——语音文件可分批补齐,每次补齐后更新清单。
+2. **浏览器自动播放限制**:首次播放必须发生在用户手势链路里。前端在任意按钮点击时初始化并 resume WebAudio(点击「开始检测/继续/开始」即完成解锁),后续步骤提示均为程序触发。
+3. **同条去重**:同一文件名 4 秒内不重复播(姿态提示会随检测帧反复触发)。
+4. **不叠加**:新提示开播前停掉上一条未播完的(单通道),倒计时与拍摄完成音除外(允许叠在提示音上)。
+5. **不打断原则**:分析中/失败提示开播时,拍照页已离开,步骤与姿态提示不再触发。
+6. **静音开关**:V1.0 暂不提供 UI 开关,跟随系统音量与静音键;后续如加开关,在拍照页右上角放小喇叭图标,状态存 localStorage。
+
+## 4. 生成验收
+
+- 每条与第 2 节文案**逐字一致**(语气词/标点可按语感微调,但不得改变指令方向,尤其 2/3、3/3 步的转头方向)。
+- 文件名与第 2 节**完全一致**(小写、连字符、.mp3),放入 `h5/assets/voice/`。
+- **同步更新 `h5/assets/voice/manifest.json`**:`{"files":[已生成的文件名(不含 .mp3)]}`,例如只生成了 3 条就写 3 条;前端只播清单内的条目。
+- 抽验:真机微信内打开,进入拍照页能听到 `step1-front`,转头时能听到 `hint-turn-*`。