# 巨子测肤 · 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 |

> 语义说明:拍摄顺序对齐 Figma,为正脸 → 右脸 → 左脸。左右一律以**用户本人**的左右为准:2/3「右脸」= 用户头向自己的**左**侧转;3/3「左脸」= 头向自己的**右**侧转。前置预览为镜像(照镜子),与取景蒙版方向一致。不要改写成"露出左侧/右侧脸"这类歧义表述。

### B. 姿态提示(实时检测不通过时播,同一提示 4 秒内不重复)

| 文件名 | 文案 | 触发时机(与屏幕提示同文本) | 时长 |
|---|---|---|---|
| `hint-noface.mp3` | 未检测到人脸,请正对镜头 | 画面无人脸 | ≈3s |
| `hint-near.mp3` | 请靠近一点 | 人脸框高占画面高 <26%(太远) | ≈1.5s |
| `hint-far.mp3` | 请远一点 | 占比 >58%(太近) | ≈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. **不叠加、不截断**:单通道,两类播报分开处理——
   - **流程音**(A 类步骤引导 + C 类倒计时/拍摄完成/分析中):排队顺序播,不互相截断(如「拍摄完成」播完再播下一步引导)。例外:`analyze-fail` 直接打断「分析中」。
   - **姿态提示**(B 类):提示之间可互相打断;流程音播放期间到来的提示不截断流程音,只挂起最新一条,流程音收尾后补播;换步或提示清空时挂起作废。
   - 倒计时「三、二、一」等全部在播/排队/挂起的播报自然收尾后,与画面数字同步起播(`voice.afterCurrent` 接续,期间姿态被破坏则取消倒计时)。
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-*`。