元视界 AI 妙妙屋—魔法语音

基于千问 3 TTS 的音色创造和音色克隆 Web 应用

项目简介

元视界 AI 妙妙屋—魔法语音是一个功能强大的语音合成应用，让你轻松创造和克隆个性化音色。通过简单的文字描述或录音，你就能生成独特的语音风格，并实时预览和使用这些音色进行文本转语音。

核心亮点

• 智能音色创造：通过自然语言描述生成个性化音色
• 高质量音色克隆：录制 10 秒语音即可克隆专属音色
• 多引擎支持：支持 阿里云 DashScope API 与 本地 Qwen3-TTS 模型 双引擎切换
• 双模式运行：
  • 云端模式：低资源占用，快速部署，需网络连接。
  • 本地模式：隐私安全，无网络依赖，性能更强（推荐使用 GPU）。
• 实时音频预览：立即试听生成的音色效果
• 流式语音合成：通过 WebSocket 实现极低延迟的语音合成
• 现代化响应式界面：美观、易用的 Web 后台管理系统

运行模式

项目支持两种运行模式，通过环境变量 QWEN3_TTS_ENV 进行切换：

1. aliyun (默认)：使用阿里云 DashScope 服务。需要配置 DASHSCOPE_API_KEY。适用于大多数用户，无需昂贵的 GPU 资源。
2. local：在本地运行 Qwen3-TTS 模型。需要 NVIDIA GPU（建议 RTX 30 系列及以上）和 CUDA 环境。适用于追求极致响应速度和隐私的用户。

快速开始

1. 环境准备

• 如果是本地模式：需要安装 NVIDIA Driver, CUDA 12.1+, 和 NVIDIA Container Toolkit (用于 Docker)。
• 如果是云端模式：只需基础 Docker 环境或 Python 环境。
• 通用：获取 阿里云 API Key（仅云端模式需要）。

2. Docker 部署 (推荐)

这是最简单的运行方式，所有依赖已打包。

2.1 云端模式 (Aliyun API)

# 1. 复制 .env.example 并更名为 .env，填入 API Key
cp .env.example .env

# 2. 启动容器
docker compose up -d

注意：默认镜像标签为 aliyun。如果需要手动指定，修改 docker-compose.yml 中的 image。

2.2 本地模式 (GPU 加速)

# 1. 修改 .env 配置文件
# QWEN3_TTS_ENV=local

# 2. 修改 docker-compose.yml 使用 local 镜像标签
# image: yuzhiheng/voice-magic:local

# 3. 启动并开启 GPU 支持
docker compose up -d

3. 本地开发模式

如果您想在本地直接运行源码：

3.1 后端设置

# 进入后端目录
cd backend

# 安装依赖
pip install -r requirements.txt

# 如果使用本地模型，还需安装 torch 和 qwen-tts
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# pip install qwen-tts

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置 QWEN3_TTS_ENV 和 DASHSCOPE_API_KEY

环境变量说明：

# 运行环境: aliyun 或 local
QWEN3_TTS_ENV=aliyun

# 阿里云 API Key（aliyun 模式下必填）
DASHSCOPE_API_KEY=your_api_key_here

# 启动后端服务
python main.py

3.2 前端设置

# 进入前端目录
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

4. Docker 镜像构建

如果您希望从源码自行构建镜像，可以使用以下命令：

4.1 构建云端版 (aliyun)

docker build -t voice-magic:aliyun -f Dockerfile.aliyun .

4.2 构建本地版 (local)

docker build -t voice-magic:local -f Dockerfile.local .

技术栈

后端

• FastAPI / Uvicorn - Web 框架与服务器
• Qwen3-TTS - 千问语音模型核心
• DashScope SDK - 阿里云模型服务接入
• WebSocket - 实现流式音频传输

前端

• Vue 3 / Vite - 现代前端框架与构建工具
• Element Plus - UI 组件库
• Pinia - 状态管理

项目结构

Voice_Magic/
├── backend/            # Python 后端代码
│   ├── api/            # 接口定义 (TTS, 克隆, 创作)
│   ├── services/       # 业务逻辑 (阿里云/本地双引擎实现)
│   └── main.py         # 启动入口
├── frontend/           # Vue 前端代码
├── Dockerfile.aliyun   # 云端模式 Docker 配置文件
├── Dockerfile.local    # 本地模式 Docker 配置文件
└── docker-compose.yml  # Docker 编排配置

功能说明

1. 音色创造模式

步骤：

1. 在"音色创造"页面输入详细的音色描述（例如："温柔的女声，音色甜美，语速适中，带有轻微的江南口音"）
2. 输入预览文本（可选，用于生成音色预览）
3. 点击"创建音色"按钮
4. 等待系统生成音色（通常需要 10-30 秒）
5. 生成完成后，在音色列表中会显示新创建的音色
6. 点击音色卡片上的"播放"按钮预览音色效果
7. 选择音色，输入要转换的文字，点击"生成语音"按钮进行流式合成

提示：

• 描述越详细，生成的音色越符合预期
• 可以尝试不同的形容词组合，如"低沉"、"活泼"、"优雅"等

2. 音色克隆模式

步骤：

1. 在"音色克隆"页面设置录音时长（建议 10 秒以上）
2. 点击"开始录音"按钮，对着麦克风说话
3. 点击"停止录音"按钮结束录音
4. 预览录音内容，确保声音清晰
5. 点击"克隆声音"按钮开始克隆（通常需要 1-2 分钟）
6. 克隆完成后，在音色列表中会显示新克隆的音色
7. 选择音色，输入文字进行语音合成

重要注意事项：

• 录音时长限制：阿里云 API 要求音频的有效时长（去除静音后）必须大于 5 秒。如果录音中包含大量静音或噪音被过滤，可能导致克隆失败。建议录制 10 秒以上 且保持连续说话。
• 浏览器安全限制：由于浏览器安全策略，录音功能必须在 localhost 或 HTTPS 环境下使用。如果使用 HTTP + IP 地址访问，录音功能将被浏览器禁用。
• 环境要求：录音环境应保持安静，避免背景噪音。
• 设备建议：建议使用高质量麦克风录制以获得最佳效果。

3. 音频预览功能

• 每个音色卡片都有一个"播放"按钮，点击即可预览音色
• 预览音频文件存储在后端的 previews/ 目录
• 前端通过静态文件服务访问音频文件：http://localhost:8000/previews/文件名.wav
• 自动增益：系统会自动对生成的预览音频进行增益处理（放大音量），确保试听效果清晰。

API Key 获取

1. 访问阿里云官网：https://help.aliyun.com/zh/model-studio/get-api-key
2. 登录或注册阿里云账号
3. 进入模型服务平台控制台
4. 创建并获取 API Key
5. 注意选择正确的地域（北京或新加坡）

重要提示：

• 不同地域的 API Key 不通用
• 确保 API Key 安全，不要泄露给他人
• 如果 API Key 失效，请生成新的并重新配置

常见问题

Q: 为什么创建音色失败？

A: 请检查：

1. API Key 是否正确配置
2. 网络连接是否正常
3. 描述是否符合要求（建议 10-50 个字符）

Q: 为什么克隆时提示“音频有效时长不足”或报错 500？

A: 阿里云 API 会对上传的音频进行 VAD（语音活动检测），自动切除静音和噪音。

1. 原因：你的录音虽然总时长够长，但去除静音后的有效人声不足 5 秒。
2. 解决：请尝试录制更长的音频（建议 10-20 秒），并保持连续说话，减少停顿。

Q: 为什么生成的音量太小？

A: 原始生成的音频音量可能较低。本项目已内置了自动增益控制（AGC）：

1. 前端合成：实时语音合成时，前端会自动放大音量（Gain=10.0）。
2. 后端预览：新创建音色的预览文件，后端会自动放大音量（Gain=5.0）。
3. 自定义：如需调整，可修改 frontend/src/views/VoiceClone.vue 或 backend/services/voice_design_service.py 中的 gain 参数。

Q: 为什么录音功能无法使用？

A: 请检查：

1. 浏览器是否支持 MediaRecorder API
2. 是否已授予麦克风权限
3. 是否在安全上下文中使用：必须使用 localhost 或 HTTPS 访问，HTTP + IP 地址无法使用录音功能。

Q: 克隆动物声音失败怎么办？

A: 虽然模型支持跨物种克隆，但 VAD 算法主要针对人声优化，纯动物叫声容易被当成噪音过滤导致“时长不足”错误。 建议：在录音开头加一两句人声引导（如“这是一只小狗的声音”），然后再录制动物叫声，有助于通过检测。

许可证

MIT License

更新日志

v1.2.0 (2026-01-31)

• 新增功能：
  • 新增“官方音色”模块，预置多种高质量官方音色。
  • 支持本地模型运行，可在无网络环境下使用基础音色功能。
• 架构优化：
  • 重构后端服务，支持阿里云 API 与本地模型双引擎切换。
  • 优化项目版本管理，同步版本号至 v1.2.0。

v1.1.0 (2025-12-28)

• 功能优化：
  • 增加音量自动增益控制，解决生成音量过小问题
  • 优化错误提示，明确“有效时长不足”的具体原因
  • 增加浏览器安全上下文检测，提示录音功能限制
• 文档更新：完善 README，补充音量控制、克隆限制等说明

v1.0.0 (2025-12-26)

• 初始版本发布
• 实现音色创造和克隆功能
• 支持实时音频预览
• 实现流式语音合成
• 响应式界面设计

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请通过以下方式联系：

• 作者：元视界_O 凌枫 o
• 项目地址：https://github.com/lfenghx/Voice_Magic
• 邮箱：550916599@qq.com