本文系统记录 Timeline Studio 在浏览器端实现多语言声音克隆、语音音色迁移与本地推理的工程方案，主要涉及：
项目仓库：
https://github.com/MartinDelophy/ai-video-editor
在线体验：
https://video-editor.ai-creator.top
一、功能工作流
Timeline Studio 将声音克隆流程拆分为两个相互独立的阶段：
阶段一：生成目标语言语音文本 → 基础 TTS → 中文、英文或其他语言音频阶段二：迁移目标音色源音频 → OpenVoice V2 → 克隆音色结果完整的浏览器端工作流如下：
录制或上传参考声音↓统一解码并重采样↓提取 256 维音色 Embedding↓生成所选语言的基础语音↓提取源音频音色↓执行 OpenVoice V2 音色迁移↓清理尾部填充与低幅噪声↓应用输出增益和软限幅↓试听并保存到 IndexedDB↓用于配音生成或时间线音频片段语言由基础 TTS 决定，而 OpenVoice V2 负责完成音色迁移与声音克隆。
这意味着同一个声音档案可以复用于多种语言场景，无需在音色档案中绑定某一种固定语言。
二、模型文件
浏览器版本当前使用两个 FP16 ONNX 模型文件：
| 文件 | 大小 | 用途 |
|---|---|---|
reference-encoder.onnx | 1,637,269 Bytes | 提取参考声音音色 |
converter.onnx | 64,314,222 Bytes | 执行音色迁移 |
| 合计 | 65,951,491 Bytes | 完整浏览器运行模型 |
模型目录：
openvoice-v2-converter-fp16/├── LICENSE├── README.md├── config.json├── reference-encoder.onnx└── converter.onnxModelScope 固定版本：
https://www.modelscope.cn/models/martindelophy/timeline-studio-voice-models/files?version=226b24270b69b38781a35566c7d442061f9e3b81&subpath=openvoice-v2-converter-fp16
Hugging Face 固定版本：
生产环境代码不会从 main 分支动态拉取模型，而是固定到不可变的 revision。
这样可以确保：
模型文件不会被远端更新静默替换 浏览器缓存身份保持稳定 两个模型平台可以对应到同一运行版本 出现问题时能够定位到具体模型快照三、浏览器音频预处理
用户上传的参考音频可能来自不同设备、不同编码格式和不同采样率。
浏览器会首先通过：
AudioContext.decodeAudioData()完成音频解码，再使用：
OfflineAudioContext进行统一重采样处理。
内部音频格式固定为：
| 参数 | 数值 |
|---|---|
| 采样率 | 22,050 Hz |
| 声道 | 单声道 |
| 内部数据 | Float32 PCM |
| 输出格式 | 16-bit PCM WA V |
数据流如下：
WA V / MP3 / M4A / WebM↓AudioContext 解码↓OfflineAudioContext 重采样↓22.05 kHz Mono Float32Array参考声音、基础 TTS 音频以及音色迁移输出，全部使用统一的内部采样率，以保证后续推理流程一致。
四、STFT 与频谱输入
OpenVoice Converter 需要接收频谱特征作为输入。
浏览器 Worker 中实现了 Hann Window、FFT 与 STFT 计算。
参数为：
| 参数 | 数值 |
|---|---|
| FFT Size | 1024 |
| Hop Size | 256 |
| Frequency Bins | 513 |
Reference Encoder 的输入形状：
[1, FrameCount, 513]Converter 的频谱输入形状：
[1, 513, FrameCount]音频时长会直接决定 FrameCount，因此 ONNX Session 需要支持动态时间维度。
频谱计算、转置以及张量构造均在 Worker 中完成，不会占用 React 主线程资源。
五、音色 Embedding
参考音频经过 Reference Encoder 后会生成：
speaker_embedding: [1, 256, 1]保存声音时，系统会保存：
{ id,name,sourceKind,referenceBlob,testBlob,embedding,fa vorite,authorized,createdAt,updatedAt}其中：
referenceBlob：原始参考声音 testBlob：克隆测试结果 embedding：256 维音色特征 sourceKind：录制或上传 authorized：授权确认状态 当再次使用该声音档案时，可以直接读取 Embedding，无需重复运行 Reference Encoder，从而提升浏览器端声音克隆效率。
六、Converter 输入
Converter 使用以下张量：
spectrogram: [1, 513, T]frame_mask:[1, 1, T]source_embedding:[1, 256, 1]target_embedding:[1, 256, 1]noise: [1, 192, T]其中：
source_embedding 来自需要转换的源音频 target_embedding 来自用户保存的参考声音 frame_mask 标记有效频谱区域 noise 使用固定种子生成 固定种子可以保证相同输入具备更好的可复现性，便于浏览器调试、结果比对与质量验证。
七、Web Worker 运行时
OpenVoice Runtime 运行在独立 Worker 中：
Main Thread ├── React 界面 ├── AudioContext 解码 ├── IndexedDB └── Timeline State↓ postMessage↓OpenVoice Worker ├── 模型下载 ├── ONNX Session ├── FFT / STFT ├── Embedding ├── Converter └── 尾部处理PCM 数据通过 Transferable ArrayBuffer 进行传输：
worker.postMessage(payload, [samples.buffer]);这样可以避免浏览器在线程之间复制完整音频数组，减少额外开销。
取消任务时会直接终止 Worker：
worker.terminate();同时拒绝所有尚未完成的请求，防止旧任务继续回写界面状态。
八、ONNX Runtime Web
浏览器端使用：
import * as ort from "onnxruntime-web/webgpu";WASM 配置：
ort.env.wasm.simd = true;ort.env.wasm.numThreads = crossOriginIsolated? Math.max(1,Math.min(4, na vigator.hardwareConcurrency || 1)): 1;WebGPU 配置：
ort.env.webgpu.powerPreference = "high-performance";Session 策略：
Reference Encoder└── WASMConverter├── WebGPU└── WASM FallbackConverter 会优先尝试：
ort.InferenceSession.create(modelBytes, { executionProviders: ["webgpu", "wasm"],graphOptimizationLevel: "all",});如果初始化失败，则会重新创建 WASM Session 作为回退方案。
模型文件采用并行下载策略：
Promise.all([loadReferenceEncoder(),loadConverter(),]);Session 按顺序初始化，避免两个 ONNX 图同时编译时带来瞬时内存峰值。
九、ModelScope 与 Hugging Face 双源分发
模型分发并不是简单准备两个下载 URL。
系统为两个平台定义了统一的模型身份：
RepositoryRevisionRelative PathCache Identity路由逻辑为：
中文界面或国内网络环境↓ModelScope 优先↓失败后切换 Hugging Face其他语言环境↓Hugging Face 优先↓失败后切换 ModelScope第一次成功的模型来源会成为当前会话中的优先线路。
如果网络环境发生变化，或当前线路请求失败，运行时会清除会话线路记录，并自动尝试另一个来源。
两个平台使用相同缓存身份，因此不会出现：
ModelScope 缓存一份 Hugging Face 再缓存一份十、Cache Storage
模型加载前会向浏览器请求持久化存储能力：
na vigator.storage.persist()但浏览器可能拒绝该请求，因此缓存不能作为浏览器推理的前置条件。
实际策略为：
检查统一缓存↓命中：加载本地模型↓未命中：访问模型镜像↓下载成功：尝试写入缓存↓缓存写入失败：继续以内存运行发生 QuotaExceededError 时：
预发布阶段遗留的重复缓存会在新 Worker 初始化时删除，避免多个缓存版本竞争浏览器存储空间。
十一、FP16 部署记录
当前发布模型固定使用 FP16。
FP16 在当前工程中的价值包括：
降低模型下载大小 降低权重在 GPU Buffer 中的占用 保留 WebGPU 浮点执行路径 允许浏览器使用 WASM 回退 避免额外的反量化节点FP8 暂未进入当前生产链路。
虽然 ONNX 文件格式可以表达 Float8 类型，但浏览器 WebGPU 目前仍缺少稳定、通用的 FP8 原生计算路径。
FP8 权重进入浏览器后，可能需要：
FP8 ↓Cast / Dequantize ↓FP16 或 FP32 ↓WebGPU Kernel这会增加：
类型转换节点 图切分概率 WASM 回退概率 CPU/GPU 数据交换 浏览器兼容验证范围 音频质量验证成本因此，当前版本仅保留已经完成验证的 FP16 模型。
FP8 作为后续独立实验，不进入当前生产模型目录与缓存身份体系。
十二、尾部低幅噪声处理
音色迁移结果的尾部可能包含模型填充区域。
随机噪声输入可能使这些区域产生轻微呼吸声或低幅底噪。
我们根据源音频 RMS 来判断真实结束位置。
参数如下：
| 参数 | 数值 |
|---|---|
| RMS Window | 20 ms |
| RMS Hop | 10 ms |
| 最低有效峰值 | 0.0025 |
| 活动阈值 | max(0.0015, peakRms × 0.035) |
| 尾部保留 | 160 ms |
| 淡出 | 40 ms |
流程：
计算源音频分段 RMS↓找到最后一个活动窗口↓保留 160 ms 自然尾部↓裁掉后续模型填充↓应用 40 ms 余弦淡出对于非常安静的输入，如果峰值不足以可靠判断活动边界，则保留原始长度，不主动执行裁剪。
十三、输出增益
音色迁移结果支持 0% 到 400% 的输出增益。
在高增益情况下使用 tanh 软限幅：
const amplified = sample * gain;const output =Math.tanh(amplified * 1.35) /Math.tanh(1.35);处理后的音频会重新编码为：
RIFF WA VPCMMono22,050 Hz16-bit十四、IndexedDB 声音档案
声音档案保存在 IndexedDB 中。
IndexedDB 可以保存：
Blob Float32Array 字符串和时间戳 收藏状态 授权状态保存成功后，克隆声音会出现在：
声音克隆 语音合成声音列表 收藏声音 音频片段音色属性用户可以取消收藏，也可以彻底删除对应档案。
十五、时间线集成
选中音频片段后，属性面板中包含独立的“音色”页面。
操作链路：
选择音频片段↓打开音色属性↓选择已保存声音或上传/录制临时声音↓转换当前片段↓试听转换结果↓保存到 My assets↓替换当前片段替换前会保留原始音频地址和元数据。
因此可以执行：
替换为克隆音色↓继续编辑↓恢复原始声音生成结果不会自动插入时间线，必须由用户手动确认后才会应用。
十六、多语言界面
声音克隆工作流目前已经覆盖：
中文 English 日本語 한국어 Español Français Deutsch Português ไทย Tiếng Việt Русский本地化内容包括：
录制与上传 音色提取 模型准备 克隆试听 保存声音 收藏与删除 转换失败 本地处理说明 授权确认 片段替换与恢复不同语言会根据实际文本长度调整 Tab 与卡片排版，避免直接翻译后出现内容溢出。
十七、工程文件
核心运行文件：
src/lib/openVoiceRuntime.jssrc/workers/openvoice.worker.jssrc/lib/baseVoiceSynthesis.jssrc/lib/voiceProfileStorage.jssrc/hooks/useVoiceProfiles.jssrc/hooks/useVoiceGeneration.jssrc/components/VoicePanel.jsxsrc/components/panels.jsxsrc/config/voiceModels.jspublic/model-cache-sw.js本文用于归档 Timeline Studio 浏览器本地多语言音色迁移、声音克隆与 ONNX/WebGPU 推理的当前生产实现。后续如果模型版本、ONNX Runtime Web、WebGPU 后端或缓存策略发生变化，将继续按照固定 revision 与 Git 提交记录进行更新。
