# 语音合成功能集成文档

## 概述

在 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. **状态管理**：精确的状态控制，避免不必要的重渲染

## 扩展功能

- 支持自定义缓存策略
- 支持批量预生成常用语音
- 支持语音质量选择
- 支持播放进度控制