170 lines
4.6 KiB
Markdown
170 lines
4.6 KiB
Markdown
# 语音合成功能集成文档
|
||
|
||
## 概述
|
||
|
||
在 VoiceSelector 组件中集成了基于 `useFetchVoiceTtsV2` 接口的语音合成功能，实现了智能缓存、自动播放和错误回退机制。
|
||
|
||
## 核心功能
|
||
|
||
### 1. 智能缓存
|
||
- 基于配置参数生成唯一哈希值作为缓存键
|
||
- 相同配置的语音只生成一次，存储在内存中
|
||
- 支持手动清除缓存
|
||
|
||
### 2. 参数映射
|
||
- `tone` (音调) → `loudnessRate` (音量)
|
||
- `speed` (语速) → `speechRate` (语速)
|
||
- 参数范围：[-50, 100]
|
||
|
||
### 3. 播放逻辑
|
||
1. **优先级**：TTS 生成的语音 > 预设语音文件
|
||
2. **错误回退**：TTS 失败时自动使用预设语音
|
||
3. **状态管理**：生成中、播放中、已缓存等状态
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
src/
|
||
├── hooks/
|
||
│ ├── useVoiceTTS.ts # 语音合成核心 Hook
|
||
│ └── useCommon.ts # TTS 接口 Hook
|
||
├── components/
|
||
│ └── features/
|
||
│ └── VoiceTTSPlayer.tsx # 独立的语音播放器组件
|
||
├── app/
|
||
│ ├── (main)/create/components/Voice/
|
||
│ │ └── VoiceSelector.tsx # 集成了 TTS 的语音选择器
|
||
│ ├── test-voice-tts/
|
||
│ │ └── page.tsx # TTS 功能测试页面
|
||
│ └── test-voice-selector/
|
||
│ └── page.tsx # VoiceSelector 测试页面
|
||
└── docs/
|
||
└── VoiceTTSIntegration.md # 本文档
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基础用法
|
||
|
||
```tsx
|
||
import { useVoiceTTS } from '@/hooks/useVoiceTTS'
|
||
|
||
function MyComponent() {
|
||
const { generateAndPlay, isPlaying, isGenerating } = useVoiceTTS()
|
||
|
||
const config = {
|
||
text: '你好，这是测试语音',
|
||
voiceType: 'S_zh_xiaoxiao_emotion',
|
||
speechRate: 0,
|
||
loudnessRate: 0
|
||
}
|
||
|
||
return (
|
||
<button
|
||
onClick={() => generateAndPlay(config)}
|
||
disabled={isGenerating}
|
||
>
|
||
{isGenerating ? '生成中...' : isPlaying(config) ? '播放中' : '播放'}
|
||
</button>
|
||
)
|
||
}
|
||
```
|
||
|
||
### VoiceSelector 集成
|
||
|
||
```tsx
|
||
import VoiceSelector from '@/app/(main)/create/components/Voice/VoiceSelector'
|
||
|
||
function CreateForm() {
|
||
const [voiceConfig, setVoiceConfig] = useState({
|
||
tone: 0, // 音调 [-50, 100]
|
||
speed: 0, // 语速 [-50, 100]
|
||
content: 'voice_id' // 语音类型ID
|
||
})
|
||
|
||
return (
|
||
<VoiceSelector
|
||
value={voiceConfig}
|
||
onChange={setVoiceConfig}
|
||
onPlay={handlePlayVoice} // 预设语音播放回调
|
||
playing={isPlayingPreset} // 预设语音播放状态
|
||
/>
|
||
)
|
||
}
|
||
```
|
||
|
||
## 接口说明
|
||
|
||
### useFetchVoiceTtsV2 参数
|
||
|
||
```typescript
|
||
interface FetchVoiceTtsV2Request {
|
||
text?: string // 文本内容
|
||
voiceType?: string // 语音类型 (以 S_ 开头)
|
||
speechRate?: number // 语速 [-50, 100]
|
||
loudnessRate?: number // 音量 [-50, 100]
|
||
}
|
||
```
|
||
|
||
### useVoiceTTS 选项
|
||
|
||
```typescript
|
||
interface UseVoiceTTSOptions {
|
||
autoPlay?: boolean // 生成完成后自动播放，默认 true
|
||
cacheEnabled?: boolean // 启用缓存，默认 true
|
||
onPlayStart?: (configHash: string) => void
|
||
onPlayEnd?: (configHash: string) => void
|
||
onGenerateStart?: (config: FetchVoiceTtsV2Request) => void
|
||
onGenerateEnd?: (config: FetchVoiceTtsV2Request, url: string) => void
|
||
onError?: (error: string) => void
|
||
}
|
||
```
|
||
|
||
## 状态说明
|
||
|
||
### VoiceSelector 状态
|
||
|
||
- **未选择**：显示提示选择语音
|
||
- **已选择 + 未生成**：显示播放按钮
|
||
- **生成中**：显示动画和 "Generating..."
|
||
- **播放中**：显示播放动画
|
||
- **已缓存**：显示 "Cached" 标识
|
||
- **错误**：显示错误信息
|
||
|
||
### 播放优先级
|
||
|
||
1. TTS 生成的语音（如果有有效的 voiceType 和 voiceText）
|
||
2. 预设语音文件（回退机制）
|
||
3. 错误处理和用户提示
|
||
|
||
## 缓存机制
|
||
|
||
- **缓存键**：基于 `text + voiceType + speechRate + loudnessRate` 生成哈希
|
||
- **存储方式**：内存中存储（页面刷新后清除）
|
||
- **清除策略**：手动清除或组件卸载时清除
|
||
|
||
## 错误处理
|
||
|
||
1. **TTS 接口错误**：自动回退到预设语音
|
||
2. **播放错误**：显示错误信息给用户
|
||
3. **网络错误**：重试机制（在 useVoiceTTS 中实现）
|
||
|
||
## 测试页面
|
||
|
||
- `/test-voice-tts` - 独立的 TTS 功能测试
|
||
- `/test-voice-selector` - VoiceSelector 组件测试
|
||
|
||
## 性能优化
|
||
|
||
1. **缓存机制**：避免重复生成相同配置的语音
|
||
2. **懒加载**：只在用户点击播放时才生成语音
|
||
3. **错误回退**：TTS 失败时使用预设语音，不影响用户体验
|
||
4. **状态管理**：精确的状态控制，避免不必要的重渲染
|
||
|
||
## 扩展功能
|
||
|
||
- 支持自定义缓存策略
|
||
- 支持批量预生成常用语音
|
||
- 支持语音质量选择
|
||
- 支持播放进度控制
|