# 何时使用

- 录音过程中展示**音波条**或**光圈**反馈
- 播放或分析已有 `Blob` / `File` 音频时做简单可视化
- 主包从 `./SoundWave` 具名导出 **`Wave`**、**`Halo`**；二者可单独使用。源码中的组合组件默认导出未随 `export *` 进入主入口时，请直接用 `Wave` / `Halo` 或参考 `Input` 内置录音 UI

---

# API

## 组合形态 SoundWaveProps（概念说明，对应源码中组合组件）

| 属性      | 类型                                                         | 默认值   | 说明 |
| --------- | ------------------------------------------------------------ | -------- | ---- |
| source    | `MediaStream` \| `Blob` \| `File` \| `null`                  | -        | 音频源 |
| mode      | `'wave' \| 'halo' \| 'wave-halo'`                            | `'wave'` | 音波 / 光圈 / 同时 |
| wave      | `WaveConfig`                                                 | -        | 音波条配置（见下） |
| halo      | `HaloConfig`                                                 | -        | 光圈配置（见下） |
| className | `string`                                                     | -        | |

`WaveConfig` 为 `WaveProps` 去掉 `source`、`className`；`HaloConfig` 为 `HaloProps` 去掉 `source`、`className`。

## Wave（音波条 WaveProps）

| 属性             | 类型 | 默认值 | 说明 |
| ---------------- | ---- | ------ | ---- |
| source           | `MediaStream` \| `Blob` \| `File` \| `null` | - | 无源时可为装饰动画（视 waveMode） |
| color            | `string` | `#606e85` | |
| count            | `number` | `60` / 实现内可能不同 | 条数 |
| waveMode         | `'volume' \| 'random' \| 'wave'` | `'volume'` | |
| minHeight        | `number` | `6` | px |
| maxHeight        | `number` | `40` | px |
| updateInterval   | `number` | `100` | ms |
| className        | `string` | - | |
| willCancel       | `boolean` | `false` | 取消态样式 |
| willSpeechToText | `boolean` | `false` | 转文字态样式 |

## Halo（光圈 HaloProps）

| 属性      | 类型 | 默认值 | 说明 |
| --------- | ---- | ------ | ---- |
| source    | `MediaStream` \| `Blob` \| `File` \| `null` | - | |
| color     | `'blue' \| 'pink'` | `'blue'` | |
| radius    | `number` | - | px |
| gradient  | `Array<{ stop: number; color: string }>` | - | |
| className | `string` | - | |

---

# FAQ

- 与 `Input` / `TextArea` 联动时，常用 `allowAudio.onStreamChange` 得到 `MediaStream` 再交给 `Halo`/`Wave` 做叠层展示。