crush-level-web/docs/VoiceTTSIntegration.md

语音合成功能集成文档

概述

在 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  # 本文档

使用方法

基础用法

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 集成

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 参数

interface FetchVoiceTtsV2Request {
  text?: string // 文本内容
  voiceType?: string // 语音类型 (以 S_ 开头)
  speechRate?: number // 语速 [-50, 100]
  loudnessRate?: number // 音量 [-50, 100]
}

useVoiceTTS 选项

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

扩展功能

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