[ { "path": ".dockerignore", "content": "# This .dockerignore is mostly irrelevant since we don't COPY from local context\n# The Dockerfile clones everything from GitHub\n# However, we keep this to prevent accidentally copying if someone modifies the Dockerfile\n\n# Everything - we clone from GitHub instead\n*\n\n# Exception: Allow Dockerfile itself for reference (not actually copied in our Dockerfile)\n!Dockerfile\n" }, { "path": ".gitignore", "content": ".claude\nCLAUDE.md\n.vscode/\nuv.lock\nmedia/\n\n\ndemo/example/\n\n# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[codz]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py.cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n# For a library or package, you might want to ignore these files since the code is\n# intended to run in multiple environments; otherwise, check them in:\n# .python-version\n\n# pipenv\n# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.\n# However, in case of collaboration, if having platform-specific dependencies or dependencies\n# having no cross-platform support, pipenv may install dependencies that don't work, or not\n# install all needed dependencies.\n#Pipfile.lock\n\n# UV\n# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n#uv.lock\n\n# poetry\n# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.\n# This is especially recommended for binary packages to ensure reproducibility, and is more\n# commonly ignored for libraries.\n# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control\n#poetry.lock\n#poetry.toml\n\n# pdm\n# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.\n# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.\n# https://pdm-project.org/en/latest/usage/project/#working-with-version-control\n#pdm.lock\n#pdm.toml\n.pdm-python\n.pdm-build/\n\n# pixi\n# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.\n#pixi.lock\n# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one\n# in the .venv directory. It is recommended not to include this directory in version control.\n.pixi\n\n# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.envrc\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n# JetBrains specific template is maintained in a separate JetBrains.gitignore that can\n# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore\n# and can be added to the global gitignore or merged into this file. For a more nuclear\n# option (not recommended) you can uncomment the following to ignore the entire idea folder.\n#.idea/\n\n# Abstra\n# Abstra is an AI-powered process automation framework.\n# Ignore directories containing user credentials, local state, and settings.\n# Learn more at https://abstra.io/docs\n.abstra/\n\n# Visual Studio Code\n# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore \n# that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore\n# and can be added to the global gitignore or merged into this file. However, if you prefer, \n# you could uncomment the following to ignore the entire vscode folder\n# .vscode/\n\n# Ruff stuff:\n.ruff_cache/\n\n# PyPI configuration file\n.pypirc\n\n# Cursor\n# Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to\n# exclude from AI features like autocomplete and code analysis. Recommended for sensitive data\n# refer to https://docs.cursor.com/context/ignore-files\n.cursorignore\n.cursorindexingignore\n\n# Marimo\nmarimo/_static/\nmarimo/_lsp/\n__marimo__/\nmodels\n*.txt\n*.pt\n*.swp\n*.safetensors\noutputs/\n\n# Backend\nbackend/.env\nbackend/uploads/\nbackend/__pycache__/\nbackend/**/__pycache__/\n!backend/models/\n\n!frontend/lib/\n\n# Workspace\nworkspace/\noutputs_offloading/\ndemo/datasets/\ntensorboard_logs/\nnohup.out\n\ndocs/images/vibevoice_architecture_1.svg\n" }, { "path": "CHANGELOG.md", "content": "# Changelog\n\nAll notable changes to VibeVoice will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n## [v2.2.0] - 2026-01-09\n\n### Added\n\n- **Quick Generation**: Simplified voice generation workflow without project context\n - One-click generation with preset voice selection\n - Support for multiple voice prompt files\n - Multiple prompt voices displayed in generation history detail view\n - Task indicator for quick generation status\n - Per-item progress tracking for each generating voice\n\n- **Navigation Enhancement**: Click logo to return to home page\n\n### Fixed\n\n- Task indicator display bugs in quick generation\n- Card status not updating in time\n- Styling consistency for deleting generation history\n\n---\n\n## [v2.1.0] - 2025-12-28\n\n### Added\n\n- **Narration Mode Editor**: New editing mode for single-speaker narration content\n - Support for changing narrator\n - Plain text editing without speaker prefixes\n\n- **Preset Voices Management**: Manage preset voice samples for quick speaker creation\n\n- **Auto Version Generation**: Frontend version automatically generated from git\n\n### Fixed\n\n- Offloading config save issue during inference\n- Offloading config error\n- Duplicated speaker ID issue\n- Missing tags in Docker repository\n- Dockerfile dependency errors\n\n---\n\n## [v2.0.0] - 2025-12-19\n\n### Added\n\n- **Fine-Tuning Support**: Full LoRA training workflow with real-time metrics\n - Training page with live progress bars and configuration options\n - Training metrics charts (Loss/LR/Timing) with 5-second auto-refresh\n - Support for layer offloading presets (Balanced/Aggressive/Extreme)\n - Gradient accumulation steps and checkpoint saving per epoch\n - TensorBoard metrics reader for training visualization\n\n- **Dataset Management**: Complete dataset CRUD operations\n - Dataset list and detail pages with pagination\n - Import/Export functionality for datasets\n - JSONL format for efficient line-by-line operations\n - Scripts for generating datasets from Mozilla Common Voice and KeSpeech\n\n- **Multi-Generation**: Batch generation with different random seeds\n - Generate 2-20 audio variations in a single request\n - Per-item progress tracking with individual audio players\n - Expandable history view with aggregate statistics\n\n- **LoRA Inference**: Apply trained LoRA models during voice generation\n - Select LoRA model from training output directory\n - Configurable LoRA weight (0-1]\n\n- **Unified Task API**: Single endpoint for checking any running task (inference or training)\n\n- **Preset Voice Feature**: Quick speaker creation from preset voice samples\n\n- **Audio Denoising**: Scripts for audio denoising with DeepFilter\n\n- **Dataset Processing Scripts**:\n - Script for ASR-SCCantDuSC (Scripted Chinese Cantonese Daily-use Speech Corpus)\n - Script for Mozilla Common Voice datasets\n\n### Changed\n\n- Improved training completion UI with better status display\n- Enhanced training history list to display all information regardless of success/failure\n- Better estimated training time calculation\n- Increased file upload limits (500MB configurable)\n- Project-scoped current generation and training API endpoints\n\n### Fixed\n\n- Training metadata update error\n- Generated voices having same name in batch generation\n- Seeds reset issue with multi-generation\n- CUDA resource cleanup when training finishes or fails\n- Invalid audio and voice_prompts field values in datasets.jsonl\n- Delete training history validation\n- OOM error handling with specific error messages\n- Various npm build errors and UI style issues\n\n## [v1.0.0] - 2025-11-14\n\n### Added\n\n- **Core TTS Model**: AR + diffusion architecture for multi-speaker text-to-speech synthesis\n - Float8 inference support for optimized performance\n - Mono model file inference support\n\n- **Full-Stack Web Application**:\n - Next.js frontend with responsive UI\n - Flask backend with RESTful API\n - Static export for production deployment\n\n- **Project Management**: Create and manage multiple voice projects\n\n- **Speaker Voice Management**:\n - Upload and manage speaker voices\n - Voice recording directly in browser\n - Auto-assigned speaker names (\"Speaker 1\", etc.)\n\n- **Dialog Editor**: 4-panel layout for creating and editing dialog sessions\n - Clickable session names in generation history\n - Session navigation to voice editor\n\n- **Voice Generation**:\n - Live progress monitoring\n - Generation history with pagination\n - Audio playback and download\n - Task icon notification in navigation\n\n- **Layer Offloading**: VRAM optimization for GPU memory constraints\n - Configurable number of layers for GPU/CPU\n - Async transfers with ThreadPoolExecutor\n - Smart cache clearing for performance\n\n- **Internationalization (i18n)**: Full bilingual support\n - English and Chinese languages\n - Auto-detection via browser settings\n - Persistence in localStorage\n\n- **Docker Support**:\n - Dockerfile for containerized deployment\n - GPU support with nvidia-docker\n\n- **Documentation**:\n - Comprehensive API documentation\n - Architecture diagrams with Mermaid\n - Offloading configuration guide\n\n### Fixed\n\n- Invisible text color in browser dark theme\n- Frontend project selection issues\n- Refresh page navigation bugs\n- Layout issues in various components\n- Scripts not starting with ID 1\n- Various typos and documentation errors\n\n[v2.2.0]: https://github.com/zhao-kun/vibevoice/compare/v2.1.0...v2.2.0\n[v2.1.0]: https://github.com/zhao-kun/vibevoice/compare/v2.0.0...v2.1.0\n[v2.0.0]: https://github.com/zhao-kun/vibevoice/compare/v1.0.0...v2.0.0\n[v1.0.0]: https://github.com/zhao-kun/vibevoice/releases/tag/v1.0.0\n" }, { "path": "CHANGELOG_zh.md", "content": "# 更新日志\n\nVibeVoice 的所有重要更改都将记录在此文件中。\n\n本文档格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，\n并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。\n\n## [v2.2.0] - 2026-01-09\n\n### 新增\n\n- **快速生成**: 无需项目上下文的简化语音生成流程\n - 一键生成，支持预设音色选择\n - 支持多个音色提示文件\n - 生成历史详情中显示多个提示音色\n - 快速生成任务状态指示器\n - 每个生成语音的独立进度跟踪\n\n- **导航增强**: 点击 Logo 返回首页\n\n### 修复\n\n- 快速生成中的任务指示器显示问题\n- 卡片状态未及时更新\n- 删除生成历史的样式一致性问题\n\n---\n\n## [v2.1.0] - 2025-12-28\n\n### 新增\n\n- **旁白模式编辑器**: 单人朗读内容的新编辑模式\n - 支持切换朗读者\n - 无需说话人前缀的纯文本编辑\n\n- **预设音色管理**: 管理预设音色样本，快速创建说话人\n\n- **自动版本生成**: 前端版本号自动从 git 生成\n\n### 修复\n\n- 推理过程中的 Offloading 配置保存问题\n- Offloading 配置错误\n- 说话人 ID 重复问题\n- Docker 仓库缺少标签\n- Dockerfile 依赖错误\n\n---\n\n## [v2.0.0] - 2025-12-19\n\n### 新增\n\n- **微调支持**: 完整的 LoRA 训练工作流，支持实时指标监控\n - 训练页面，带有实时进度条和配置选项\n - 训练指标图表（Loss/LR/Timing），5 秒自动刷新\n - 支持层卸载预设（均衡/激进/极限）\n - 梯度累积步数和每轮检查点保存\n - TensorBoard 指标读取器用于训练可视化\n\n- **数据集管理**: 完整的数据集 CRUD 操作\n - 数据集列表和详情页面，支持分页\n - 数据集导入/导出功能\n - JSONL 格式，高效逐行操作\n - 从 Mozilla Common Voice 和 KeSpeech 生成数据集的脚本\n\n- **批量生成**: 使用不同随机种子批量生成\n - 单次请求生成 2-20 个音频变体\n - 每个项目的进度跟踪和独立音频播放器\n - 可展开的历史视图，显示汇总统计\n\n- **LoRA 推理**: 在语音生成时应用训练好的 LoRA 模型\n - 从训练输出目录选择 LoRA 模型\n - 可配置的 LoRA 权重 (0-1]\n\n- **统一任务 API**: 单一接口检查任何运行中的任务（推理或训练）\n\n- **预设音色功能**: 从预设音色样本快速创建说话人\n\n- **音频降噪**: 使用 DeepFilter 的音频降噪脚本\n\n- **数据集处理脚本**:\n - ASR-SCCantDuSC（粤语日常用语语音语料库）处理脚本\n - Mozilla Common Voice 数据集处理脚本\n\n### 变更\n\n- 改进训练完成 UI，更好的状态显示\n- 增强训练历史列表，无论成功或失败都显示所有信息\n- 更准确的预估训练时间计算\n- 增加文件上传限制（500MB，可配置）\n- 项目范围的当前生成和训练 API 端点\n\n### 修复\n\n- 训练元数据更新错误\n- 批量生成中生成的语音名称相同\n- 批量生成时种子重置问题\n- 训练完成或失败时的 CUDA 资源清理\n- datasets.jsonl 中无效的音频和 voice_prompts 字段值\n- 删除训练历史的验证问题\n- OOM 错误处理，提供具体错误信息\n- 各种 npm 构建错误和 UI 样式问题\n\n## [v1.0.0] - 2025-11-14\n\n### 新增\n\n- **核心 TTS 模型**: AR + 扩散架构的多说话人文本转语音合成\n - Float8 推理支持，优化性能\n - 单体模型文件推理支持\n\n- **全栈 Web 应用**:\n - Next.js 前端，响应式 UI\n - Flask 后端，RESTful API\n - 静态导出用于生产部署\n\n- **项目管理**: 创建和管理多个语音项目\n\n- **说话人音色管理**:\n - 上传和管理说话人音色\n - 浏览器内直接录音\n - 自动分配说话人名称（\"说话人 1\" 等）\n\n- **对话编辑器**: 四面板布局，创建和编辑对话会话\n - 生成历史中可点击的会话名称\n - 会话导航到语音编辑器\n\n- **语音生成**:\n - 实时进度监控\n - 生成历史，支持分页\n - 音频播放和下载\n - 导航栏任务图标通知\n\n- **层卸载**: GPU 显存优化\n - 可配置的 GPU/CPU 层数\n - ThreadPoolExecutor 异步传输\n - 智能缓存清理以提升性能\n\n- **国际化 (i18n)**: 完整的双语支持\n - 英语和中文\n - 通过浏览器设置自动检测\n - localStorage 持久化\n\n- **Docker 支持**:\n - Dockerfile 容器化部署\n - nvidia-docker GPU 支持\n\n- **文档**:\n - 完整的 API 文档\n - Mermaid 架构图\n - 层卸载配置指南\n\n### 修复\n\n- 浏览器深色主题中不可见的文字颜色\n- 前端项目选择问题\n- 页面刷新导航问题\n- 各组件布局问题\n- 脚本未从 ID 1 开始\n- 各种拼写错误和文档错误\n\n[v2.2.0]: https://github.com/zhao-kun/vibevoice/compare/v2.1.0...v2.2.0\n[v2.1.0]: https://github.com/zhao-kun/vibevoice/compare/v2.0.0...v2.1.0\n[v2.0.0]: https://github.com/zhao-kun/vibevoice/compare/v1.0.0...v2.0.0\n[v1.0.0]: https://github.com/zhao-kun/vibevoice/releases/tag/v1.0.0\n" }, { "path": "Dockerfile", "content": "# Multi-stage Dockerfile for VibeVoice\n# This Dockerfile is completely self-contained and requires no local source code\n# All source code is cloned from GitHub during build\n\nARG BASE_IMAGE=nvidia/cuda:12.1.1-cudnn8-devel-ubuntu22.04\nARG WORKDIR=/workspace/zhao-kun/vibevoice\nARG GITHUB_REPO=https://github.com/zhao-kun/vibevoice.git\nARG GITHUB_BRANCH=main\n\n#############################################\n# Stage 1: Download model from HuggingFace\n#############################################\nFROM python:3.10-slim AS model-downloader\n\n# Install huggingface-cli\nRUN pip install --no-cache-dir huggingface-hub[cli]\n\n# Set working directory\nWORKDIR /tmp/models\n\n# Download model (float8_e4m3fn only) using huggingface-cli\nRUN hf download zhaokun/vibevoice-large \\\n vibevoice7b_float8_e4m3fn.safetensors \\\n --local-dir /tmp/models/VibeVoice-large\n\nRUN hf download zhaokun/vibevoice-large \\\n vibevoice7b_bf16.safetensors \\\n --local-dir /tmp/models/VibeVoice-large\n\n#############################################\n# Stage 2: Clone Repository and Build Frontend\n#############################################\nFROM node:20-alpine AS source-and-frontend\n\nARG GITHUB_REPO\nARG GITHUB_BRANCH\nARG CACHE_BUST=unknown\n\n# Install git\nRUN apk add --no-cache git\n\n# Cache bust: Force rebuild from here when CACHE_BUST changes\nRUN echo \"Cache bust: ${CACHE_BUST}\"\n\n# Clone repository (shallow clone, then unshallow to get full history for git describe)\nWORKDIR /build\nRUN git clone --depth 1 --branch ${GITHUB_BRANCH} ${GITHUB_REPO} vibevoice && \\\n cd /build/vibevoice && \\\n git fetch --unshallow origin && \\\n git fetch --tags origin && \\\n git checkout main && \\\n git rev-parse HEAD > backend/version.txt\n\n# Build frontend\nWORKDIR /build/vibevoice/frontend\n\n# Install dependencies\nRUN npm ci\n\n# Build frontend\nRUN npm run build\n\n# Verify build output\nRUN ls -la out/\n\n#############################################\n# Stage 3: Create Python Virtual Environment\n#############################################\nFROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 AS python-builder\n\nARG WORKDIR=/workspace/zhao-kun/vibevoice\nENV DEBIAN_FRONTEND=noninteractive\n\nRUN apt-get update --allow-releaseinfo-change --yes && \\\n apt-get upgrade --yes && \\\n apt install --yes --no-install-recommends \\\n bash \\\n libgl1 \\\n software-properties-common \\\n ffmpeg \\\n zip \\\n unzip \\\n iputils-ping \\\n libtcmalloc-minimal4 \\\n net-tools \\\n vim \\\n p7zip-full && \\\n rm -rf /var/lib/apt/lists/*\n\nRUN add-apt-repository ppa:deadsnakes/ppa\n\nRUN apt-get update --allow-releaseinfo-change --yes && \\\n apt install python3.10-dev python3.10-venv python3-pip \\\n build-essential git curl -y --no-install-recommends && \\\n ln -s /usr/bin/python3.10 /usr/bin/python && \\\n rm /usr/bin/python3 && \\\n ln -s /usr/bin/python3.10 /usr/bin/python3 && \\\n apt-get clean && rm -rf /var/lib/apt/lists/* && \\\n echo \"en_US.UTF-8 UTF-8\" > /etc/locale.gen\n\n# Create working directory at EXACT runtime path\nRUN mkdir -p ${WORKDIR}\nWORKDIR ${WORKDIR}\n\n# Copy source code from frontend stage\nCOPY --from=source-and-frontend /build/vibevoice .\n\n# Create virtual environment at runtime path (critical for absolute paths in venv)\nRUN python3.10 -m venv ${WORKDIR}/venv\n\n# Upgrade pip and install dependencies\nRUN ${WORKDIR}/venv/bin/pip install --no-cache-dir --upgrade pip setuptools wheel && \\\n ${WORKDIR}/venv/bin/pip install --no-cache-dir .\n\nRUN rm -rf ${WORKDIR}/frontend\n\n#############################################\n# Stage 4: Final Image\n#############################################\nFROM nvidia/cuda:12.4.1-cudnn-devel-ubuntu22.04 AS builder\n\nARG WORKDIR=/workspace/zhao-kun/vibevoice\nENV DEBIAN_FRONTEND=noninteractive\nENV PYTHONUNBUFFERED=1\n\nRUN apt-get update --allow-releaseinfo-change --yes && \\\n apt-get upgrade --yes && \\\n apt install --yes --no-install-recommends \\\n bash \\\n libgl1 \\\n software-properties-common \\\n ffmpeg \\\n zip \\\n unzip \\\n iputils-ping \\\n libtcmalloc-minimal4 \\\n net-tools \\\n vim \\\n p7zip-full && \\\n rm -rf /var/lib/apt/lists/*\n\nRUN add-apt-repository ppa:deadsnakes/ppa\n\nRUN apt-get update --allow-releaseinfo-change --yes && \\\n apt install python3.10-dev python3.10-venv python3-pip \\\n build-essential git curl -y --no-install-recommends && \\\n ln -s /usr/bin/python3.10 /usr/bin/python && \\\n rm /usr/bin/python3 && \\\n ln -s /usr/bin/python3.10 /usr/bin/python3 && \\\n apt-get clean && rm -rf /var/lib/apt/lists/* && \\\n echo \"en_US.UTF-8 UTF-8\" > /etc/locale.gen\n\n\n# Copy downloaded model from model-downloader stage\nRUN mkdir -p /tmp/models/\nCOPY --from=model-downloader /tmp/models/VibeVoice-large /tmp/models\n\n# Create working directory at EXACT same path as build stage\nRUN mkdir -p ${WORKDIR}\nWORKDIR ${WORKDIR}\n# Copy virtual environment from python-builder stage (with preserved absolute paths)\nCOPY --from=python-builder ${WORKDIR} .\n\nRUN mkdir -p ${WORKDIR}/models/vibevoice/ && ln -s /tmp/models/vibevoice7b_float8_e4m3fn.safetensors ${WORKDIR}/models/vibevoice/\nRUN mkdir -p ${WORKDIR}/models/vibevoice/ && ln -s /tmp/models/vibevoice7b_bf16.safetensors ${WORKDIR}/models/vibevoice/\n\n# Copy frontend build from source-and-frontend stage\nRUN mkdir -p ${WORKDIR}/backend/dist\nCOPY --from=source-and-frontend /build/vibevoice/frontend/out ${WORKDIR}/backend/dist\n\n# Create workspace directory for runtime data\nRUN mkdir -p ${WORKDIR}/workspace\n\n# Expose port\nEXPOSE 9527\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\n CMD curl -f http://localhost:9527/health || exit 1\n\n# Use venv python explicitly (critical - do not rely on PATH)\nCMD [\"/workspace/zhao-kun/vibevoice/venv/bin/python\", \"backend/run.py\"]\n\n" }, { "path": "README.md", "content": "# VibeVoiceFusion\n\n
\n\n\"VibeVoiceFusion\n\n**A Complete Web Application for Multi-Speaker Voice Generation**\n\n*Built on Microsoft's VibeVoice Model*\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9+-blue.svg?logo=python)](https://www.python.org/)\n[![TypeScript](https://img.shields.io/badge/typescript-5.0+-blue.svg?logo=typescript)](https://www.typescriptlang.org/)\n[![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](Dockerfile)\n[![Docker Hub](https://img.shields.io/badge/Docker%20Hub-vibevoicefusion-blue?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n[![Docker Pulls](https://img.shields.io/docker/pulls/zhaokundev/vibevoicefusion?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n[![Image Size](https://img.shields.io/docker/image-size/zhaokundev/vibevoicefusion/latest?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n\n[English](README.md) | [简体中文](README_zh.md)\n\n[Features](#features) • [Demo Samples](#demo-samples) • [Get Started](#get-started) • [Documentation](#documentation) • [Community](#community) • [Contributing](#contributing)\n\n
\n\n---\n\n## Overview\n\n### Purpose\n\nVibeVoiceFusion is a **web application** for generating high-quality, multi-speaker synthetic speech with voice cloning capabilities. Built on Microsoft's VibeVoice model (AR + diffusion architecture), this project provides a complete full-stack solution with voice generation, LoRA fine-tuning, dataset management, batch generation, and advanced VRAM optimization features.\n\n**Key Goals:**\n- Provide a user-friendly interface for voice generation without requiring coding knowledge\n- Enable efficient multi-speaker dialog synthesis with distinct voice characteristics\n- Support LoRA fine-tuning for custom voice adaptation and style transfer\n- Generate multiple audio variations in batch with different random seeds\n- Optimize memory usage for consumer-grade GPUs (10GB+ VRAM)\n- Support bilingual workflows (English/Chinese)\n- Offer both web UI and CLI interfaces for different use cases\n\n
\n \n \"Video\n \n
\n\n### Principle\n\nVibeVoice combines **autoregressive (AR)** and **diffusion** techniques for text-to-speech synthesis:\n\n1. **Text Processing**: Input text is tokenized and processed through a Qwen-based language model backbone\n2. **Voice Encoding**: Reference voice samples are encoded into acoustic and semantic embeddings\n3. **AR Generation**: The model autoregressively generates speech tokens conditioned on text and voice embeddings\n4. **Diffusion Refinement**: A DPM-Solver-based diffusion head converts tokens to high-quality audio waveforms\n5. **Voice Cloning**: The unified processor preserves speaker characteristics from reference audio samples\n\n**Technical Highlights:**\n- **Model Architecture**: Qwen backbone + VAE acoustic tokenizer + semantic encoder + diffusion head\n- **Quantization**: Float8 (FP8 E4M3FN) support for ~50% VRAM reduction with minimal quality loss\n- **Layer Offloading**: Dynamic CPU/GPU memory management for running on limited VRAM\n- **Attention Mechanism**: PyTorch native SDPA for maximum compatibility\n\n### Features\n\n#### Quick Generation\n\n- **One-Click Generation**: Generate voice without creating projects, speakers, or sessions\n- **Voice Source Options**:\n - Upload custom audio files (WAV, MP3, M4A, FLAC, WebM) - up to 4 files\n - Select from preset voice samples with language/gender filters\n- **Auto Mode Detection**: Automatically detects dialogue vs narration format\n- **Multi-Voice Support**: Use up to 4 voice prompts for generation\n- **Generation History**: Persistent history with expandable details, bulk delete\n- **Per-Item Progress**: Real-time progress tracking for each generating voice\n\n#### Complete Web Application\n\n- **Project Management**: Organize voice generation projects with metadata and descriptions\n- **Speaker/Voice Management**:\n - Upload and manage reference voice samples (WAV, MP3, M4A, FLAC, WebM)\n - Audio preview with playback controls\n - Voice file replacement with automatic cache-busting\n - Audio trimming functionality\n- **Dialog Editor**:\n - Visual editor with drag-and-drop line reordering\n - Text editor mode for bulk editing\n - Support for multi-speaker dialogs (up to 4+ speakers)\n - **Narration mode** for single-speaker content (audiobooks, articles, podcasts)\n - Real-time preview and validation\n- **Generation System**:\n - Queue-based task management (prevents GPU conflicts)\n - Real-time progress monitoring with live updates\n - Configurable parameters (CFG scale, random seed, model precision)\n - **Multi-Generation**: Generate 2-20 audio variations in a single batch with different seeds\n - LoRA model support with configurable weight (0-1]\n - Generation history with filtering, sorting, and pagination\n - Audio playback and download for completed generations\n\n#### LoRA Fine-Tuning\n\n- **Dataset Management**:\n - Create and manage training datasets with audio/text pairs\n - Import datasets from ZIP archives or local folders\n - JSONL format for efficient data handling\n - Pagination and search for large datasets\n - Export datasets for backup or sharing\n\n- **Training System**:\n - LoRA (Low-Rank Adaptation) fine-tuning for voice customization\n - Configurable training parameters (epochs, learning rate, LoRA rank, batch size)\n - Layer offloading support for training on consumer GPUs\n - Real-time training progress with tqdm-style progress bar\n - Live training metrics charts (Loss, Learning Rate, Timing)\n - TensorBoard integration for detailed metrics\n - Training history with status tracking (Prepare, Training, Completed, Failed)\n - OOM detection with helpful suggestions for recovery\n\n- **LoRA Model Usage**:\n - Select trained LoRA models during voice generation\n - Configurable LoRA weight for blending with base model\n - Multiple LoRA files per training job (epoch checkpoints + final)\n\n#### VRAM Optimization\n\n- **Layer Offloading**: Move transformer layers between CPU/GPU to reduce VRAM requirements\n - **Balanced** (12 GPU / 16 CPU layers): ~5GB VRAM savings, ~2.0x slower - RTX 3060 16GB, 4070\n - **Aggressive** (8 GPU / 20 CPU layers): ~6GB VRAM savings, ~2.5x slower - RTX 3060 12GB, 4060\n - **Extreme** (4 GPU / 24 CPU layers): ~7GB VRAM savings, ~3.5x slower - RTX 3060 10GB (minimum)\n- **Float8 Quantization**: Reduce model size from ~14GB to ~7GB with comparable quality. (Supported by RTX 40 series and above graphics cards.)\n- **Adaptive Configuration**: Automatic VRAM estimation and optimal layer distribution\n\n**VRAM Requirements:**\n\n| Configuration | GPU Layers | VRAM Usage | Speed | Target Hardware |\n|--------------|-----------|------------|-------|-----------------|\n| No offloading | 28 | 11-14GB | 1.0x | RTX 4090, A100, 3090 |\n| Balanced | 12 | 6-8GB | 0.70x | RTX 4070, 3080 16GB |\n| Aggressive | 8 | 5-7GB | 0.55x | RTX 3060 12GB |\n| Extreme | 4 | 4-5GB | 0.40x | RTX 3080 10GB |\n\n> Float8 Quantization only supports by RTX 40XX or 50XX serial nvidia card.\n\n#### Internationalization\n\n- **Full Bilingual Support**: Complete English/Chinese UI with 360+ translation keys\n- **Auto-Detection**: Automatically detects browser language on first visit\n- **Persistent Preference**: Language selection saved in localStorage\n- **Backend i18n**: API error messages and responses translated to user's language\n\n#### Docker Deployment\n\n- **Multi-Stage Build**: Optimized Dockerfile with frontend build, Python venv, and model download\n- **Self-Contained**: Clones from GitHub and builds entirely from source\n- **HuggingFace Integration**: Automatically downloads model file (~3-4GB) during build\n\n#### Additional Features\n\n- **Responsive Design**: Mobile-friendly interface with Tailwind CSS\n- **Real-Time Updates**: WebSocket-free polling with smart update intervals (2s active, 60s background)\n- **Audio Cache-Busting**: Ensures audio updates are immediately reflected\n- **Toast Notifications**: User-friendly feedback for all operations\n- **Dark Mode Ready**: Modern UI with consistent styling\n- **Accessibility**: Keyboard navigation and ARIA labels\n\n---\n\n## Demo Samples\n\nListen to voice generation samples created with VibeVoiceFusion. Click the links below to download and play:\n\n### Single Speaker\n\n**🎧 [Pandora's Box Story (BFloat16 Model)](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/1p_pandora_box_bf16.wav)**\n\n*Generated with bfloat16 precision model - Full quality, 14GB VRAM*\n\n**🎧 [Pandora's Box Story (Float8 Model)](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/1p_pandora_box_float8_e4m3fn.wav)**\n\n*Generated with float8 quantization - Optimized for 7GB VRAM with comparable quality*\n\n### Multi-Speaker (3 Speakers)\n\n**🎭 [东邪西毒 - 西游版 (Journey to the West Version)](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/东邪西毒-西游版.wav)**\n\n*Multi-speaker dialog with distinct voice characteristics for each character*\n\n---\n\n## Get Started\n\n### Prerequisites\n\n- **Python**: 3.9 or higher\n- **Node.js**: 16.x or higher (for frontend development)\n- **CUDA**: Compatible GPU with CUDA support (recommended)\n- **VRAM**: Minimum 6GB for extreme offloading, 14GB recommended for best performance\n- **Docker**: Optional, for containerized deployment\n\n### Installation\n\n#### Option 1: Docker (Recommended for Production)\n\nBuild docker image \n```bash\n# Clone the repository\ngit clone https://github.com/zhao-kun/vibevoicefusion.git\ncd vibevoicefusion\n# Build and the docker image\ndocker compose build vibevoice\n```\n\nAfter build successfully, run command:\n\n```bash\ndocker run -d \\\n --name vibevoicefusion \\\n --gpus all \\\n -p 9527:9527 \\\n -v $(pwd)/workspace:/workspace/zhao-kun/vibevoice/workspace \\\n zhaokundev/vibevoicefusion:latest\n```\n\nAccess the application at `http://localhost:9527`\n\n**The Docker image is available on Docker Hub, and you can launch VibeVoiceFusion using the following command.**\n\n```bash\ndocker pull zhaokundev/vibevoicefusion\ndocker run -d \\\n --name vibevoicefusion \\\n --gpus all \\\n -p 9527:9527 \\\n -v $(pwd)/workspace:/workspace/zhao-kun/vibevoice/workspace \\\n zhaokundev/vibevoicefusion:latest\n```\n\n**Build Time**: 18-28 minutes | **Image Size**: ~12-15GB\n\n#### Option 2: Manual Installation\n\n**1. Install Backend Dependencies**\n\n```bash\n# Clone the repository\ngit clone https://github.com/zhao-kun/vibevoice.git\ncd vibevoice\n\n# Install Python package\npip install -e .\n```\n\n**2. Download Pre-trained Model**\n\nDownload from HuggingFace (choose one):\n- **Float8 (Recommended)**: [vibevoice7b_float8_e4m3fn.safetensors](https://huggingface.co/zhaokun/vibevoice-large/blob/main/vibevoice7b_float8_e4m3fn.safetensors) (~7GB) (Supported by RTX 40 series and above graphics cards.)\n- **BFloat16 (Full Precision)**: [vibevoice7b_bf16.safetensors](https://huggingface.co/zhaokun/vibevoice-large/blob/main/vibevoice7b_bf16.safetensors) (~14GB)\n- **Config**: [config.json](https://huggingface.co/zhaokun/vibevoice-large/blob/main/config.json)\n\nPlace files in `./models/vibevoice/`\n\n**3. Install Frontend Dependencies** (for development)\n\n```bash\ncd frontend\nnpm install\n```\n\n**4. Build Frontend** (for production)\n\n```bash\ncd frontend\nnpm run build\ncp -r out/* ../backend/dist/\n```\n\n### Usage\n\n#### Web Application (Recommended)\n\n**Production Mode** (single server):\n```bash\n# Start backend server (serves both API and frontend)\npython backend/run.py\n\n# Access at http://localhost:9527\n```\n\n**Development Mode** (separate servers):\n```bash\n# Terminal 1: Start backend API\npython backend/run.py # http://localhost:9527\n\n# Terminal 2: Start frontend dev server\ncd frontend\nnpm run dev # http://localhost:3000\n```\n\n### Quick Generation (No Project Required)\n\nFor quick testing without setting up projects:\n\n1. Click **\"Quick Generate\"** from the home page\n2. **Select Voice Source**:\n - **Upload**: Drag & drop your audio file (supports up to 4 files)\n - **Preset**: Choose from preset voices with language/gender filters\n3. **Enter Text**: Type dialogue (`Speaker 1: Hello`) or narration (plain text)\n4. **Configure**: Set seed, batch size (2-20), and offloading options\n5. **Generate**: Click generate and monitor per-item progress\n6. **Download**: Play or download generated audio\n\n**Key Points:**\n- Auto-detects dialogue vs narration mode\n- All speakers use the same voice in dialogue mode\n- No LoRA support (base model only)\n- History persists across sessions\n\n---\n\n### Complete Workflow Guide\n\nThis guide walks you through the complete process of creating multi-speaker voice generation from start to finish.\n\n#### Step 1: Create a Project\n\nStart by creating a new project or selecting an existing one. Projects help organize your voice generation work with metadata and descriptions.\n\n
\n\"Project\n

Create and manage projects from the home page

\n
\n\n**Actions:**\n- Click \"Create New Project\" card\n- Enter a project name (e.g., \"Podcast Episode 1\")\n- Optionally add a description\n- Click \"Create Project\"\n\nThe project will be automatically selected and you'll be navigated to the Speaker Role page.\n\n#### Step 2: Add Speakers and Upload Voice Samples\n\nUpload reference voice samples for each speaker. The system supports various audio formats (WAV, MP3, M4A, FLAC, WebM).\n\n
\n\"Speaker\n

Upload and manage voice samples for each speaker

\n
\n\n**Actions:**\n- Click \"Add New Speaker\" button\n- The speaker will be automatically named (e.g., \"Speaker 1\", \"Speaker 2\")\n- Click \"Upload Voice\" to select a reference audio file (3-30 seconds recommended)\n- Preview the uploaded voice using the audio player\n- Repeat for additional speakers (supports 2-4+ speakers)\n\n**Tips:**\n- Use clean audio with minimal background noise\n- 5-15 seconds of speech is ideal for voice cloning\n- Each speaker needs a unique voice sample\n- You can replace voice files later by clicking \"Change Voice\"\n\n#### Step 3: Create and Edit Dialog\n\nCreate a dialog session and write the multi-speaker conversation. The dialog editor supports drag-and-drop reordering and real-time preview.\n\n
\n\"Dialog\n

Multi-speaker dialog editor with visual and text modes

\n
\n\n**Actions:**\n- Click \"Create New Session\" in the session list\n- Enter a session name (e.g., \"Chapter 1\")\n- In the dialog editor, add lines for each speaker:\n - Select a speaker from the dropdown\n - Enter the dialog text\n - Click \"Add Line\" or press Enter\n- Reorder lines by dragging the handle icons\n- Use \"Text Editor\" mode for bulk editing\n- Click \"Save\" to persist your changes\n\n**Dialog Format (Text Mode):**\n```\nSpeaker 1: Welcome to our podcast!\n\nSpeaker 2: Thanks for having me. It's great to be here.\n\nSpeaker 1: Let's dive into today's topic.\n```\n\n**Narration Mode:**\n\nFor single-speaker content like audiobooks, articles, or podcasts, use **Narration Mode**:\n\n1. When creating a new session, toggle to \"Narration\" mode\n2. Select a narrator voice from your uploaded speakers\n3. Enter plain text without `Speaker N:` prefixes\n4. Each paragraph will be spoken by the selected narrator\n\n```\nThis is the first paragraph of your narration.\n\nThis is the second paragraph. No speaker formatting needed.\n\nThe narrator voice you selected will read all the text.\n```\n\n**Features:**\n- Visual editor with drag-and-drop\n- Text editor for bulk editing\n- Real-time preview\n- Copy and download functionality\n- Format validation\n- **Narration mode** for single-speaker content\n\n#### Step 4: Generate Voice\n\nConfigure generation parameters and start the voice synthesis process. Monitor real-time progress and manage generation history.\n\n
\n\"Voice\n

Generation interface with parameters, live progress, and history

\n
\n\n**Actions:**\n- Navigate to \"Generate Voice\" page\n- Select a dialog session from the dropdown\n- Configure parameters:\n - **Model Type**:\n - `float8_e4m3fn` (recommended): 7GB VRAM, faster loading\n - `bfloat16`: 14GB VRAM, full precision\n - **CFG Scale** (1.0-2.0): Controls generation adherence to text\n - Lower (1.0-1.3): More natural, varied\n - Higher (1.5-2.0): More controlled, may sound robotic\n - Default: 1.3\n - **Random Seed**: Any positive integer for reproducibility\n - **Offloading** (optional): Enable if VRAM < 14GB\n - **Balanced**: 12 GPU layers, ~5GB savings, 2.0x slower (RTX 3070 12GB, 4070)\n - **Aggressive**: 8 GPU layers, ~6GB savings, 2.5x slower (RTX 3080 12GB)\n - **Extreme**: 4 GPU layers, ~7GB savings, 3.5x slower (minimum 10GB VRAM)\n- Click \"Start Generation\"\n\n**Real-Time Monitoring:**\n- Progress bar shows completion percentage\n- Phase indicators: Preprocessing → Inferencing → Saving\n- Live token generation count\n- Estimated time remaining\n\n
\n\"Voice\n

Generation interface with parameters, live progress, and history

\n
\n\n**Generation History:**\n- View all past generations with status (completed, failed, running)\n- Filter and sort by date, status, or session\n- Play generated audio inline\n- Download WAV files\n- Delete unwanted generations\n- View detailed metrics (tokens, duration, RTF, VRAM usage)\n\n#### Command-Line Interface\n\nFor CLI-based generation without the web UI:\n\n```bash\npython demo/local_file_inference.py \\\n --model_file ./models/vibevoice/vibevoice7b_float8_e4m3fn.safetensors \\\n --txt_path demo/text_examples/1p_pandora_box.txt \\\n --speaker_names zh-007 \\\n --output_dir ./outputs \\\n --dtype float8_e4m3fn \\\n --cfg_scale 1.3 \\\n --seed 42\n```\n\n**CLI Arguments:**\n- `--model_file`: Path to model `.safetensors` file\n- `--config`: Path to `config.json` (optional)\n- `--txt_path`: Input text file with speaker-labeled dialog\n- `--speaker_names`: Speaker name(s) for voice file mapping\n- `--output_dir`: Output directory for generated audio\n- `--device`: `cuda`, `mps`, or `cpu` (auto-detected)\n- `--dtype`: `float8_e4m3fn` or `bfloat16`\n- `--cfg_scale`: Classifier-Free Guidance scale (default: 1.3)\n- `--seed`: Random seed for reproducibility\n\n### Configuration\n\n#### Backend Configuration\n\nEnvironment variables (optional):\n```bash\nexport WORKSPACE_DIR=/path/to/workspace # Default: ./workspace\nexport FLASK_DEBUG=False # Production mode\n```\n\n#### Frontend Configuration\n\nDevelopment API URL (`frontend/.env.local`):\n```bash\nNEXT_PUBLIC_API_URL=http://localhost:9527/api/v1\n```\n\n---\n\n## Documentation\n\n### Architecture Overview\n\n```\nvibevoice/\n├── backend/ # Flask API server\n│ ├── api/ # REST API endpoints\n│ │ ├── projects.py # Project CRUD\n│ │ ├── speakers.py # Speaker management\n│ │ ├── dialog_sessions.py # Dialog CRUD\n│ │ ├── generation.py # Voice generation\n│ │ ├── dataset.py # Dataset management\n│ │ └── training.py # LoRA training\n│ ├── services/ # Business logic layer\n│ ├── models/ # Data models\n│ ├── task_manager/ # Background task queue\n│ ├── inference/ # Inference engine\n│ ├── training/ # Training engine & state management\n│ ├── i18n/ # Backend translations\n│ └── dist/ # Frontend static files (production)\n├── frontend/ # Next.js web application\n│ ├── app/ # Next.js pages\n│ │ ├── page.tsx # Home/Project selector\n│ │ ├── quick-generate/ # Quick generation (no project)\n│ │ ├── speaker-role/ # Speaker management\n│ │ ├── voice-editor/ # Dialog editor\n│ │ ├── generate-voice/ # Generation page\n│ │ ├── dataset/ # Dataset management\n│ │ └── fine-tuning/ # LoRA training page\n│ ├── components/ # React components\n│ ├── lib/ # Context providers & utilities\n│ │ ├── ProjectContext.tsx\n│ │ ├── SessionContext.tsx\n│ │ ├── SpeakerRoleContext.tsx\n│ │ ├── GenerationContext.tsx\n│ │ ├── TrainingContext.tsx\n│ │ ├── GlobalTaskContext.tsx\n│ │ ├── i18n/ # Frontend translations\n│ │ └── api.ts # API client\n│ └── types/ # TypeScript type definitions\n└── vibevoice/ # Core inference library\n ├── modular/ # Model implementations\n │ ├── custom_offloading_utils.py # Layer offloading\n │ └── adaptive_offload.py # Auto VRAM config\n ├── processor/ # Input processing\n └── schedule/ # Diffusion scheduling\n```\n\n### API Reference\n\nFor complete API documentation including request/response examples, see [docs/APIs.md](docs/APIs.md).\n\n### Workspace Structure\n\n```\nworkspace/\n├── projects.json # All projects metadata\n├── _quick-generate/ # Quick generation storage\n│ ├── voices/ # Uploaded voice samples\n│ ├── outputs/ # Generated audio files\n│ └── history.json # Generation history\n└── {project-id}/\n ├── voices/\n │ ├── speakers.json # Speaker metadata\n │ └── {uuid}.wav # Voice files\n ├── scripts/\n │ ├── sessions.json # Session metadata\n │ └── {uuid}.txt # Dialog text files\n ├── output/\n │ ├── generation.json # Generation metadata\n │ └── {request_id}.wav # Generated audio files\n ├── datasets/\n │ ├── datasets.json # Dataset metadata\n │ └── {dataset-id}/\n │ ├── datasets.jsonl # Dataset items (one JSON per line)\n │ ├── audio/ # Audio files\n │ └── voice_prompts/ # Voice prompt files\n └── training/\n ├── training_history.json # Training job metadata\n └── lora_output/\n └── {lora-name}/\n ├── model_epoch_*.safetensors # Checkpoint files\n └── model_final.safetensors # Final model\n```\n\n### Performance Benchmarks\n\n**RTX 4090 (24GB VRAM):**\n| Configuration | VRAM | Generation Time | RTF | Quality |\n|--------------|------|-----------------|-----|---------|\n| BFloat16, No offload | 14GB | 15s (50s audio) | 0.30x | Excellent |\n| Float8, No offload | 7GB | 16s (50s audio) | 0.32x | Excellent |\n\n**RTX 3060 12GB:**\n| Configuration | VRAM | Generation Time | RTF | Quality |\n|--------------|------|-----------------|-----|---------|\n| Float8, Balanced | 7GB | 30s (50s audio) | 0.60x | Excellent |\n| Float8, Aggressive | 6GB | 40s (50s audio) | 0.80x | Good |\n\n*RTF (Real-Time Factor) < 1.0 means faster than real-time*\n\n---\n\n## Community\n\n### Getting Help\n\n- **Issues**: [GitHub Issues](https://github.com/zhao-kun/vibevoice/issues) - Bug reports and feature requests\n- **Discussions**: [GitHub Discussions](https://github.com/zhao-kun/vibevoice/discussions) - Questions and community support\n\n### Showcase\n\nShare your projects and experiences:\n- **Demo Audio**: Submit your generated samples to the showcase\n- **Use Cases**: Share how you're using VibeVoice\n- **Improvements**: Contribute optimizations and enhancements\n\n### Responsible AI\n\n**Important**: This project is for **research and development** purposes only.\n\n#### Risks\n- **Deepfakes & Impersonation**: Synthetic speech can be misused for fraud or disinformation\n- **Voice Cloning Ethics**: Always obtain explicit consent before cloning voices\n- **Biases**: Model may inherit biases from training data\n- **Unexpected Outputs**: Generated audio may contain artifacts or inaccuracies\n\n#### Guidelines\n\n**DO:**\n\n- Clearly disclose when audio is AI-generated\n- Obtain explicit consent for voice cloning\n- Use responsibly for legitimate purposes\n- Respect privacy and intellectual property\n- Follow all applicable laws and regulations\n\n**DO NOT:**\n\n- Create deepfakes or impersonation without consent\n- Spread disinformation or misleading content\n- Use for fraud, scams, or malicious purposes\n- Violate laws or ethical guidelines\n\n**By using this software, you agree to use it ethically and responsibly.**\n\n---\n\n## Contributing\n\nWe welcome contributions from the community! Here's how you can help:\n\n### Ways to Contribute\n\n1. **Report Bugs**: Open an issue with detailed reproduction steps\n2. **Suggest Features**: Propose new features via GitHub issues\n3. **Submit Pull Requests**:\n - Fix bugs\n - Add features\n - Improve documentation\n - Add translations\n4. **Improve Documentation**: Help make the project more accessible\n5. **Share Use Cases**: Show how you're using VibeVoice\n\n### Testing\n\n```bash\n# Backend tests (when available)\npytest tests/\n\n# Frontend tests (when available)\ncd frontend\nnpm test\n\n# Manual testing\n# 1. Create project\n# 2. Add speakers\n# 3. Create dialog\n# 4. Generate voice\n# 5. Verify output quality\n```\n\n---\n\n## License\n\nThis project follows the same license terms as the original Microsoft VibeVoice repository. Please refer to the [LICENSE](LICENSE) file for details.\n\n### Third-Party Licenses\n\n- **Frontend**: React, Next.js, Tailwind CSS (MIT License)\n- **Backend**: Flask, PyTorch (Various open-source licenses)\n- **Model Weights**: Microsoft VibeVoice (subject to Microsoft's terms)\n\n---\n\n## Acknowledgments\n\n- **Microsoft Research**: Original VibeVoice model and architecture\n- **ComfyUI**: Float8 casting techniques inspiration\n- **kohya-ss/musubi-tuner**: Offloading implementation and LoRA network reference\n- **[voicepowered-ai/VibeVoice-finetuning](https://github.com/voicepowered-ai/VibeVoice-finetuning)**: Training dataloader implementation\n- **HuggingFace**: Model hosting and distribution\n- **Open Source Community**: Libraries and frameworks that made this possible\n\n---\n\n## Citation\n\nIf you use this implementation in your research, please cite both this project and the original VibeVoice paper:\n\n```bibtex\n@software{vibevoice_webapp_2024,\n title={VibeVoice: Complete Web Application for Multi-Speaker Voice Generation},\n author={Zhao, Kun},\n year={2024},\n url={https://github.com/zhao-kun/vibevoice}\n}\n\n@article{vibevoice2024,\n title={VibeVoice: Unified Autoregressive and Diffusion for Speech Generation},\n author={Microsoft Research},\n year={2024}\n}\n```\n\n---\n\n## Troubleshooting\n\n### CUDA Out of Memory\n```bash\n# Try Float8 model\n--dtype float8_e4m3fn\n\n# Enable layer offloading in web UI\n# Or use CLI with manual configuration\n```\n\n### Audio Quality Issues\n```bash\n# Adjust CFG scale (try 1.0 - 2.0)\n--cfg_scale 1.5\n\n# Use higher precision model\n--dtype bfloat16\n```\n\n### Port Already in Use\n```bash\n# Change port in backend/run.py\napp.run(host='0.0.0.0', port=9528)\n```\n\n### Frontend Build Errors\n```bash\ncd frontend\nrm -rf node_modules .next\nnpm install\nnpm run build\n```\n\n---\n\n
\n\n**Made by the VibeVoice Community**\n\n[Back to Top](#vibevoice)\n\n
\n" }, { "path": "README_zh.md", "content": "# VibeVoiceFusion\n\n
\n\n\"VibeVoiceFusion\n\n**完整的多说话人语音生成 Web 应用**\n\n*基于 Microsoft VibeVoice 模型构建*\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.9+-blue.svg?logo=python)](https://www.python.org/)\n[![TypeScript](https://img.shields.io/badge/typescript-5.0+-blue.svg?logo=typescript)](https://www.typescriptlang.org/)\n[![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](Dockerfile)\n[![Docker Hub](https://img.shields.io/badge/Docker%20Hub-vibevoicefusion-blue?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n[![Docker Pulls](https://img.shields.io/docker/pulls/zhaokundev/vibevoicefusion?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n[![Image Size](https://img.shields.io/docker/image-size/zhaokundev/vibevoicefusion/latest?logo=docker)](https://hub.docker.com/r/zhaokundev/vibevoicefusion)\n\n[English](README.md) | [简体中文](README_zh.md)\n\n[功能特性](#功能特性) • [演示样本](#演示样本) • [快速开始](#快速开始) • [文档](#文档) • [社区](#社区) • [贡献](#贡献)\n\n
\n\n---\n\n## 概述\n\n### 项目目的\n\nVibeVoiceFusion 是一个**Web 应用**，用于生成高质量、多说话人的合成语音，具备声音克隆功能。基于微软的 VibeVoice 模型（AR + 扩散架构），本项目提供完整的全栈解决方案，包含语音生成、LoRA 微调、数据集管理、批量生成和先进的显存优化功能。\n\n**核心目标：**\n\n- 提供无需编程知识的友好界面进行语音生成\n- 支持高效的多说话人对话合成，保持不同说话人的独特声音特征\n- 支持 LoRA 微调，实现自定义声音适配和风格迁移\n- 批量生成多个音频变体，使用不同的随机种子\n- 优化显存使用，支持消费级 GPU（10GB+ 显存）\n- 支持双语工作流（英语/中文）\n- 提供 Web 界面和命令行界面以适应不同使用场景\n\n
\n \n \"Video\n \n
\n\n### 技术原理\n\nVibeVoice 结合**自回归（AR）**和**扩散**技术进行文本转语音合成：\n\n1. **文本处理**：输入文本经过分词并通过基于 Qwen 的语言模型主干网络处理\n2. **声音编码**：参考语音样本被编码为声学和语义嵌入\n3. **AR 生成**：模型基于文本和声音嵌入自回归生成语音 token\n4. **扩散细化**：基于 DPM-Solver 的扩散头将 token 转换为高质量音频波形\n5. **声音克隆**：统一处理器从参考音频样本中保留说话人特征\n\n**技术亮点：**\n\n- **模型架构**：Qwen 主干网络 + VAE 声学分词器 + 语义编码器 + 扩散头\n- **量化技术**：Float8 (FP8 E4M3FN) 支持，显存减少约 50%，质量损失极小\n- **层卸载**：动态 CPU/GPU 内存管理，可在有限显存上运行\n- **注意力机制**：PyTorch 原生 SDPA，最大化兼容性\n\n### 功能特性\n\n#### 快速生成\n\n- **一键生成**：无需创建项目、说话人或会话即可生成语音\n- **音源选项**：\n - 上传自定义音频文件（WAV、MP3、M4A、FLAC、WebM）- 最多 4 个文件\n - 从预设音色样本中选择，支持语言/性别筛选\n- **自动模式检测**：自动识别对话格式与旁白格式\n- **多音色支持**：支持使用最多 4 个音色提示进行生成\n- **生成历史**：持久化历史记录，支持展开详情和批量删除\n- **逐项进度**：实时跟踪每个生成语音的进度\n\n#### 完整的 Web 应用\n\n- **项目管理**：使用元数据和描述组织语音生成项目\n- **说话人/声音管理**：\n - 上传和管理参考语音样本（WAV、MP3、M4A、FLAC、WebM）\n - 音频预览与播放控制\n - 声音文件替换，自动缓存清除\n - 音频裁剪功能\n- **对话编辑器**：\n - 可视化编辑器，支持拖拽重排对话行\n - 文本编辑模式用于批量编辑\n - 支持多说话人对话（最多 4+ 个说话人）\n - **旁白模式**支持单说话人内容（有声书、文章、播客）\n - 实时预览和验证\n- **生成系统**：\n - 基于队列的任务管理（防止 GPU 冲突）\n - 实时进度监控与动态更新\n - 可配置参数（CFG scale、随机种子、模型精度）\n - **批量生成**：单次生成 2-20 个音频变体，使用不同随机种子\n - LoRA 模型支持，可配置权重 (0-1]\n - 生成历史记录，支持过滤、排序和分页\n - 完成的生成可播放和下载\n\n#### LoRA 微调\n\n- **数据集管理**：\n - 创建和管理包含音频/文本对的训练数据集\n - 支持从 ZIP 压缩包或本地文件夹导入数据集\n - JSONL 格式高效处理数据\n - 大型数据集支持分页和搜索\n - 导出数据集用于备份或分享\n\n- **训练系统**：\n - LoRA（低秩适应）微调，实现声音定制\n - 可配置训练参数（训练轮数、学习率、LoRA 秩、批量大小）\n - 支持层卸载，可在消费级 GPU 上训练\n - 实时训练进度，带 tqdm 风格进度条\n - 实时训练指标图表（损失、学习率、时间）\n - TensorBoard 集成，查看详细指标\n - 训练历史记录，状态跟踪（准备中、训练中、已完成、失败）\n - OOM 检测，提供恢复建议\n\n- **LoRA 模型使用**：\n - 在语音生成时选择已训练的 LoRA 模型\n - 可配置 LoRA 权重，与基础模型混合\n - 每个训练任务支持多个 LoRA 文件（epoch 检查点 + 最终模型）\n\n#### 显存优化\n\n- **层卸载**：在 CPU/GPU 之间移动 Transformer 层以减少显存需求\n - **平衡模式** (12 GPU / 16 CPU 层)：约 5GB 显存节省，约 2.0 倍慢 - RTX 3060 16GB、4070\n - **激进模式** (8 GPU / 20 CPU 层)：约 6GB 显存节省，约 2.5 倍慢 - RTX 3080 12GB、4060\n - **极限模式** (4 GPU / 24 CPU 层)：约 7GB 显存节省，约 3.5 倍慢 - RTX 3080 10GB（最低配置）\n- **Float8 量化**：将模型大小从约 14GB 减少到约 7GB，质量相当 (RTX 40系及以上显卡支持)\n- **自适应配置**：自动显存估算和最优层分配\n\n**显存需求：**\n\n| 配置 | GPU 层数 | 显存占用 | 速度 | 目标硬件 |\n|------|---------|---------|------|---------|\n| 无卸载 | 28 | 11-14GB | 1.0x | RTX 4090、A100、3090 |\n| 平衡 | 12 | 6-8GB | 0.70x | RTX 4070、3080 12GB |\n| 激进 | 8 | 5-7GB | 0.55x | RTX 3060 12GB |\n| 极限 | 4 | 4-5GB | 0.40x | RTX 3080 10GB |\n\n> Float8 量化，只有RTX 40系及以上显卡支持。\n\n#### 国际化\n\n- **完整双语支持**：完整的英文/中文界面，360+ 翻译键\n- **自动检测**：首次访问自动检测浏览器语言\n- **持久化偏好**：语言选择保存在 localStorage\n- **后端国际化**：API 错误消息和响应翻译为用户语言\n\n#### Docker 部署\n\n- **多阶段构建**：优化的 Dockerfile，包含前端构建、Python venv 和模型下载\n- **自包含**：从 GitHub 克隆并完全从源代码构建\n- **HuggingFace 集成**：构建过程中自动下载模型文件（约 3-4GB）\n\n#### 其他功能\n\n- **响应式设计**：使用 Tailwind CSS 的移动友好界面\n- **实时更新**：无需 WebSocket 的智能轮询更新间隔（活动时 2 秒，后台 60 秒）\n- **音频缓存清除**：确保音频更新立即反映\n- **Toast 通知**：所有操作的用户友好反馈\n- **深色模式就绪**：现代化一致的样式\n- **可访问性**：键盘导航和 ARIA 标签\n\n---\n\n## 演示样本\n\n试听使用 VibeVoiceFusion 生成的语音样本。点击下方链接下载并播放：\n\n### 单说话人\n\n**🎧 [大话西游（BFloat16 模型）](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/1p_pandora_box_bf16.wav)**\n\n*使用 bfloat16 精度模型生成 - 完整质量，需要 14GB 显存*\n\n**🎧 [大话西游（Float8 模型）](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/1p_pandora_box_float8_e4m3fn.wav)**\n\n*使用 float8 量化生成 - 优化至 7lGB 显存，质量相当, RTX 40系及以上显卡支持*\n\n### 多说话人（3 个说话人）\n\n**🎭 [东邪西毒 - 西游版](https://raw.githubusercontent.com/zhao-kun/VibeVoiceFusion/main/demo/outputs/东邪西毒-西游版.wav)**\n\n*多说话人对话，每个角色具有独特的声音特征*\n\n---\n\n## 快速开始\n\n### 前置要求\n\n- **Python**：3.9 或更高版本\n- **Node.js**：16.x 或更高版本（用于前端开发）\n- **CUDA**：支持 CUDA 的 GPU（推荐）\n- **显存**：极限卸载最少 6GB，推荐 14GB 以获得最佳性能\n- **Docker**：可选，用于容器化部署\n\n### 安装\n\n#### 方式 1：Docker（生产环境推荐）\n\n构建Docker镜像\n```bash\n# 克隆仓库\ngit clone https://github.com/zhao-kun/vibevoicefusion.git\ncd vibevoicefusion\n\n# 使用 Docker Compose 构建和运行\ndocker compose build vibevoice\n```\n\n运行Docker 容器\n\n```bash\ndocker run -d \\\n --name vibevoice \\\n --gpus all \\\n -p 9527:9527 \\\n -v $(pwd)/workspace:/workspace/zhao-kun/vibevoice/workspace \\\n zhaokundev/vibevoicefusion:latest\n```\n\n在 `http://localhost:9527` 访问应用\n\n**Docker 镜像已经上传至Docker Hub， 你可以通过如下的命令直接启动vibevoicefusion 服务。**\n\n```bash\ndocker pull zhaokundev/vibevoicefusion\ndocker run -d \\\n --name vibevoicefusion \\\n --gpus all \\\n -p 9527:9527 \\\n -v $(pwd)/workspace:/workspace/zhao-kun/vibevoice/workspace \\\n zhaokundev/vibevoicefusion:latest\n```\n\n**构建时间**：18-28 分钟 | **镜像大小**：约 12-15GB\n\n#### 方式 2：手动安装\n\n**1. 安装后端依赖**\n\n```bash\n# 克隆仓库\ngit clone https://github.com/zhao-kun/vibevoice.git\ncd vibevoice\n\n# 安装 Python 包\npip install -e .\n```\n\n**2. 下载预训练模型**\n\n从 HuggingFace 下载（选择其一）：\n\n- **Float8（推荐）**：[vibevoice7b_float8_e4m3fn.safetensors](https://huggingface.co/zhaokun/vibevoice-large/blob/main/vibevoice7b_float8_e4m3fn.safetensors)（约 7GB）\n- **BFloat16（全精度）**：[vibevoice7b_bf16.safetensors](https://huggingface.co/zhaokun/vibevoice-large/blob/main/vibevoice7b_bf16.safetensors)（约 14GB）\n- **配置文件**：[config.json](https://huggingface.co/zhaokun/vibevoice-large/blob/main/config.json)\n\n将文件放置在 `./models/vibevoice/` 目录\n\n**3. 安装前端依赖**（用于开发）\n\n```bash\ncd frontend\nnpm install\n```\n\n**4. 构建前端**（用于生产）\n\n```bash\ncd frontend\nnpm run build\ncp -r out/* ../backend/dist/\n```\n\n### 使用方法\n\n#### Web 应用（推荐）\n\n**生产模式**（单服务器）：\n\n```bash\n# 启动后端服务器（同时提供 API 和前端）\npython backend/run.py\n\n# 在 http://localhost:9527 访问\n```\n\n**开发模式**（分离服务器）：\n\n```bash\n# 终端 1：启动后端 API\npython backend/run.py # http://localhost:9527\n\n# 终端 2：启动前端开发服务器\ncd frontend\nnpm run dev # http://localhost:3000\n```\n\n### 快速生成（无需项目）\n\n快速测试，无需设置项目：\n\n1. 从主页点击 **\"快速生成\"**\n2. **选择音源**：\n - **上传**：拖放音频文件（最多支持 4 个文件）\n - **预设**：从预设音色中选择，支持语言/性别筛选\n3. **输入文本**：输入对话格式（`Speaker 1: 你好`）或旁白格式（纯文本）\n4. **配置参数**：设置种子、批量大小（2-20）和卸载选项\n5. **生成**：点击生成并监控每项进度\n6. **下载**：播放或下载生成的音频\n\n**要点：**\n- 自动检测对话模式与旁白模式\n- 对话模式下所有说话人使用相同音色\n- 不支持 LoRA（仅基础模型）\n- 历史记录跨会话持久保存\n\n---\n\n### 完整工作流程指南\n\n本指南将带您完成从头到尾创建多说话人语音生成的完整过程。\n\n#### 步骤 1：创建项目\n\n首先创建一个新项目或选择现有项目。项目帮助您使用元数据和描述组织语音生成工作。\n\n
\n\"项目管理\"\n

从主页创建和管理项目

\n
\n\n**操作步骤：**\n- 点击\"创建新项目\"卡片\n- 输入项目名称（例如：\"播客第 1 集\"）\n- 可选择添加描述\n- 点击\"创建项目\"\n\n项目将自动被选中，并导航到说话人角色页面。\n\n#### 步骤 2：添加说话人并上传音色样本\n\n为每个说话人上传参考音频样本。系统支持多种音频格式（WAV、MP3、M4A、FLAC、WebM）。\n\n
\n\"说话人管理\"\n

为每个说话人上传和管理音色样本

\n
\n\n**操作步骤：**\n- 点击\"添加新说话人\"按钮\n- 说话人将被自动命名（例如：\"Speaker 1\"、\"Speaker 2\"）\n- 点击\"上传音色\"选择参考音频文件（建议 3-30 秒）\n- 使用音频播放器预览已上传的音色\n- 重复以上步骤添加更多说话人（支持 2-4+ 个说话人）\n\n**提示：**\n- 使用背景噪音最小的清晰音频\n- 5-15 秒的语音最适合音色克隆\n- 每个说话人需要独特的音色样本\n- 稍后可以通过点击\"更改音色\"替换音频文件\n\n#### 步骤 3：创建和编辑对话\n\n创建对话会话并撰写多说话人对话。对话编辑器支持拖放重排和实时预览。\n\n
\n\"对话编辑器\"\n

支持可视化和文本模式的多说话人对话编辑器

\n
\n\n**操作步骤：**\n- 在会话列表中点击\"创建新会话\"\n- 输入会话名称（例如：\"第 1 章\"）\n- 在对话编辑器中为每个说话人添加对话行：\n - 从下拉菜单中选择说话人\n - 输入对话文本\n - 点击\"添加行\"或按回车键\n- 通过拖动句柄图标重新排序对话行\n- 使用\"文本编辑器\"模式进行批量编辑\n- 点击\"保存\"保存更改\n\n**对话格式（文本模式）：**\n```\nSpeaker 1: 欢迎来到我们的播客！\n\nSpeaker 2: 谢谢邀请。很高兴来到这里。\n\nSpeaker 1: 让我们深入探讨今天的话题。\n```\n\n**旁白模式：**\n\n对于有声书、文章、播客等单说话人内容，可使用**旁白模式**：\n\n1. 创建新会话时，切换到\"旁白\"模式\n2. 从已上传的说话人中选择旁白音色\n3. 输入纯文本，无需 `Speaker N:` 前缀\n4. 选定的旁白音色将朗读所有文本\n\n```\n这是旁白的第一段内容。\n\n这是第二段。无需说话人格式。\n\n您选择的旁白音色将朗读所有文本。\n```\n\n**功能特性：**\n- 支持拖放的可视化编辑器\n- 批量编辑的文本编辑器\n- 实时预览\n- 复制和下载功能\n- 格式验证\n- **旁白模式**支持单说话人内容\n\n#### 步骤 4：生成语音\n\n配置生成参数并启动语音合成过程。监控实时进度并管理生成历史。\n\n
\n\"语音生成\"\n

带有参数配置、实时进度和历史记录的生成界面

\n
\n\n**操作步骤：**\n- 导航到\"生成语音\"页面\n- 从下拉菜单中选择对话会话\n- 配置参数：\n - **模型类型**：\n - `float8_e4m3fn`（推荐）：7GB 显存，加载更快\n - `bfloat16`：14GB 显存，完整精度\n - **CFG Scale**（1.0-2.0）：控制生成对文本的遵循程度\n - 较低（1.0-1.3）：更自然、多变\n - 较高（1.5-2.0）：更可控，可能听起来机械\n - 默认值：1.3\n - **随机种子**：任意正整数，用于可重现性\n - **卸载**（可选）：如果显存 < 14GB 则启用\n - **平衡**：12 GPU 层，节省约 5GB，慢 2.0 倍（RTX 3060 16GB、4070）\n - **激进**：8 GPU 层，节省约 6GB，慢 2.5 倍（RTX 3060 12GB）\n - **极端**：4 GPU 层，节省约 7GB，慢 3.5 倍（最低 10GB 显存）\n- 点击\"开始生成\"\n\n**实时监控：**\n- 进度条显示完成百分比\n- 阶段指示器：预处理 → 推理 → 保存\n- 实时 token 生成计数\n- 估计剩余时间\n\n
\n\"语音生成中\"\n

带有参数配置、实时进度和历史记录的生成界面

\n
\n\n**生成历史：**\n- 查看所有过往生成及其状态（已完成、失败、运行中）\n- 按日期、状态或会话筛选和排序\n- 在线播放生成的音频\n- 下载 WAV 文件\n- 删除不需要的生成\n- 查看详细指标（token、时长、RTF、显存使用）\n\n#### 命令行界面\n\n不使用 Web UI 的命令行生成：\n\n```bash\npython demo/local_file_inference.py \\\n --model_file ./models/vibevoice/vibevoice7b_float8_e4m3fn.safetensors \\\n --txt_path demo/text_examples/1p_pandora_box.txt \\\n --speaker_names zh-007 \\\n --output_dir ./outputs \\\n --dtype float8_e4m3fn \\\n --cfg_scale 1.3 \\\n --seed 42\n```\n\n**CLI 参数：**\n\n- `--model_file`：模型 `.safetensors` 文件路径\n- `--config`：`config.json` 路径（可选）\n- `--txt_path`：带说话人标签的对话文本文件\n- `--speaker_names`：语音文件映射的说话人名称\n- `--output_dir`：生成音频的输出目录\n- `--device`：`cuda`、`mps` 或 `cpu`（自动检测）\n- `--dtype`：`float8_e4m3fn` 或 `bfloat16`\n- `--cfg_scale`：分类器自由引导比例（默认：1.3）\n- `--seed`：可重现性的随机种子\n\n### 配置\n\n#### 后端配置\n\n环境变量（可选）：\n\n```bash\nexport WORKSPACE_DIR=/path/to/workspace # 默认：./workspace\nexport FLASK_DEBUG=False # 生产模式\n```\n\n#### 前端配置\n\n开发 API URL（`frontend/.env.local`）：\n\n```bash\nNEXT_PUBLIC_API_URL=http://localhost:9527/api/v1\n```\n\n---\n\n## 文档\n\n### 架构概览\n\n```\nvibevoice/\n├── backend/ # Flask API 服务器\n│ ├── api/ # REST API 端点\n│ │ ├── projects.py # 项目 CRUD\n│ │ ├── speakers.py # 说话人管理\n│ │ ├── dialog_sessions.py # 对话 CRUD\n│ │ ├── generation.py # 语音生成\n│ │ ├── dataset.py # 数据集管理\n│ │ └── training.py # LoRA 训练\n│ ├── services/ # 业务逻辑层\n│ ├── models/ # 数据模型\n│ ├── task_manager/ # 后台任务队列\n│ ├── inference/ # 推理引擎\n│ ├── training/ # 训练引擎和状态管理\n│ ├── i18n/ # 后端翻译\n│ └── dist/ # 前端静态文件（生产）\n├── frontend/ # Next.js Web 应用\n│ ├── app/ # Next.js 页面\n│ │ ├── page.tsx # 主页/项目选择器\n│ │ ├── quick-generate/ # 快速生成（无需项目）\n│ │ ├── speaker-role/ # 说话人管理\n│ │ ├── voice-editor/ # 对话编辑器\n│ │ ├── generate-voice/ # 生成页面\n│ │ ├── dataset/ # 数据集管理\n│ │ └── fine-tuning/ # LoRA 训练页面\n│ ├── components/ # React 组件\n│ ├── lib/ # Context providers 和工具\n│ │ ├── ProjectContext.tsx\n│ │ ├── SessionContext.tsx\n│ │ ├── SpeakerRoleContext.tsx\n│ │ ├── GenerationContext.tsx\n│ │ ├── TrainingContext.tsx\n│ │ ├── GlobalTaskContext.tsx\n│ │ ├── i18n/ # 前端翻译\n│ │ └── api.ts # API 客户端\n│ └── types/ # TypeScript 类型定义\n└── vibevoice/ # 核心推理库\n ├── modular/ # 模型实现\n │ ├── custom_offloading_utils.py # 层卸载\n │ └── adaptive_offload.py # 自动显存配置\n ├── processor/ # 输入处理\n └── schedule/ # 扩散调度\n```\n\n### API 参考\n\n完整的 API 文档（包含请求/响应示例），请参阅 [docs/APIs.md](docs/APIs.md)。\n\n### 工作空间结构\n\n```\nworkspace/\n├── projects.json # 所有项目元数据\n├── _quick-generate/ # 快速生成存储\n│ ├── voices/ # 上传的音色样本\n│ ├── outputs/ # 生成的音频文件\n│ └── history.json # 生成历史\n└── {project-id}/\n ├── voices/\n │ ├── speakers.json # 说话人元数据\n │ └── {uuid}.wav # 语音文件\n ├── scripts/\n │ ├── sessions.json # 会话元数据\n │ └── {uuid}.txt # 对话文本文件\n ├── output/\n │ ├── generation.json # 生成元数据\n │ └── {request_id}.wav # 生成的音频文件\n ├── datasets/\n │ ├── datasets.json # 数据集元数据\n │ └── {dataset-id}/\n │ ├── datasets.jsonl # 数据集条目（每行一个 JSON）\n │ ├── audio/ # 音频文件\n │ └── voice_prompts/ # 语音提示文件\n └── training/\n ├── training_history.json # 训练任务元数据\n └── lora_output/\n └── {lora-name}/\n ├── model_epoch_*.safetensors # 检查点文件\n └── model_final.safetensors # 最终模型\n```\n\n### 性能基准\n\n**RTX 4090 (24GB 显存)：**\n\n| 配置 | 显存 | 生成时间 | RTF | 质量 |\n|------|------|---------|-----|------|\n| BFloat16，无卸载 | 14GB | 15秒（50秒音频）| 0.30x | 优秀 |\n| Float8，无卸载 | 7GB | 16秒（50秒音频）| 0.32x | 优秀 |\n\n**RTX 3060 12GB：**\n\n| 配置 | 显存 | 生成时间 | RTF | 质量 |\n|------|------|---------|-----|------|\n| Float8，平衡 | 7GB | 30秒（50秒音频）| 0.60x | 优秀 |\n| Float8，激进 | 6GB | 40秒（50秒音频）| 0.80x | 良好 |\n\n*RTF（实时因子）< 1.0 表示快于实时生成*\n\n---\n\n## 社区\n\n### 获取帮助\n\n- **Issues**：[GitHub Issues](https://github.com/zhao-kun/vibevoice/issues) - 错误报告和功能请求\n- **Discussions**：[GitHub Discussions](https://github.com/zhao-kun/vibevoice/discussions) - 问题和社区支持\n\n### 展示\n\n分享您的项目和经验：\n\n- **演示音频**：提交您的生成样本到展示区\n- **使用案例**：分享您如何使用 VibeVoice\n- **改进建议**：贡献优化和增强功能\n\n### 负责任的 AI\n\n**重要**：本项目仅用于**研究和开发**目的。\n\n#### 风险\n\n- **深度伪造与冒充**：合成语音可能被滥用于欺诈或虚假信息\n- **声音克隆伦理**：克隆声音前务必获得明确同意\n- **偏见**：模型可能继承训练数据中的偏见\n- **意外输出**：生成的音频可能包含瑕疵或不准确之处\n\n#### 指南\n\n**应该做：**\n\n- 明确披露音频是 AI 生成的\n- 获得声音克隆的明确同意\n- 负责任地用于合法目的\n- 尊重隐私和知识产权\n- 遵守所有适用的法律法规\n\n**不应该做：**\n\n- 未经同意创建深度伪造或冒充\n- 传播虚假信息或误导性内容\n- 用于欺诈、诈骗或恶意目的\n- 违反法律或道德准则\n\n**使用本软件即表示您同意以道德和负责任的方式使用它。**\n\n---\n\n## 贡献\n\n我们欢迎社区贡献！以下是您可以帮助的方式：\n\n### 贡献方式\n\n1. **报告错误**：使用详细的重现步骤开启 issue\n2. **建议功能**：通过 GitHub issues 提出新功能\n3. **提交 Pull Request**：\n - 修复错误\n - 添加功能\n - 改进文档\n - 添加翻译\n4. **改进文档**：帮助使项目更易访问\n5. **分享用例**：展示您如何使用 VibeVoice\n\n### 测试\n\n```bash\n# 后端测试（可用时）\npytest tests/\n\n# 前端测试（可用时）\ncd frontend\nnpm test\n\n# 手动测试\n# 1. 创建项目\n# 2. 添加说话人\n# 3. 创建对话\n# 4. 生成语音\n# 5. 验证输出质量\n```\n\n---\n\n## 许可证\n\n本项目遵循与原始 Microsoft VibeVoice 仓库相同的许可条款。详情请参阅 [LICENSE](LICENSE) 文件。\n\n### 第三方许可证\n\n- **前端**：React、Next.js、Tailwind CSS（MIT 许可证）\n- **后端**：Flask、PyTorch（各种开源许可证）\n- **模型权重**：Microsoft VibeVoice（受 Microsoft 条款约束）\n\n---\n\n## 致谢\n\n- **Microsoft Research**：原始 VibeVoice 模型和架构\n- **ComfyUI**：Float8 转换技术灵感\n- **kohya-ss/musubi-tuner**: Offloading 和 LoRA 网络实现参考\n- **[voicepowered-ai/VibeVoice-finetuning](https://github.com/voicepowered-ai/VibeVoice-finetuning)**：训练数据加载器实现\n- **HuggingFace**：模型托管和分发\n- **开源社区**：使本项目成为可能的各种库和框架\n\n---\n\n## 引用\n\n如果您在研究中使用本实现，请同时引用本项目和原始 VibeVoice 论文：\n\n```bibtex\n@software{vibevoice_webapp_2024,\n title={VibeVoice: Complete Web Application for Multi-Speaker Voice Generation},\n author={Zhao, Kun},\n year={2024},\n url={https://github.com/zhao-kun/vibevoice}\n}\n\n@article{vibevoice2024,\n title={VibeVoice: Unified Autoregressive and Diffusion for Speech Generation},\n author={Microsoft Research},\n year={2024}\n}\n```\n\n---\n\n## 故障排除\n\n### CUDA 内存不足\n\n```bash\n# 尝试 Float8 模型\n--dtype float8_e4m3fn\n\n# 在 Web UI 中启用层卸载\n# 或在 CLI 中使用手动配置\n```\n\n### 音频质量问题\n\n```bash\n# 调整 CFG scale（尝试 1.0 - 2.0）\n--cfg_scale 1.5\n\n# 使用更高精度模型\n--dtype bfloat16\n```\n\n### 端口已被占用\n\n```bash\n# 在 backend/run.py 中更改端口\napp.run(host='0.0.0.0', port=9528)\n```\n\n### 前端构建错误\n\n```bash\ncd frontend\nrm -rf node_modules .next\nnpm install\nnpm run build\n```\n\n---\n\n
\n\n**VibeVoice 社区制作**\n\n[返回顶部](#vibevoice)\n\n
\n" }, { "path": "backend/.gitignore", "content": ".env\n" }, { "path": "backend/README.md", "content": "# VibeVoice Backend\n\nFlask-based REST API backend for VibeVoice speech generation system.\n\n## Architecture\n\n```\nbackend/\n├── api/ # API endpoints (blueprints)\n│ ├── __init__.py # Main API blueprint\n│ ├── projects.py # Project management endpoints\n│ ├── speakers.py # Speaker role endpoints\n│ ├── dialog_sessions.py # Dialog session endpoints\n│ └── generation.py # Voice generation endpoints (TBD)\n├── models/ # Data models\n│ ├── project.py # Project dataclass\n│ ├── speaker.py # SpeakerRole dataclass\n│ └── dialog_session.py # DialogSession dataclass\n├── services/ # Business logic services\n│ ├── project_service.py\n│ ├── speaker_service.py\n│ └── dialog_session_service.py\n├── utils/ # Utility functions\n│ ├── file_handler.py\n│ └── dialog_validator.py\n├── app.py # Flask application factory\n├── config.py # Configuration management\n├── run.py # Development server\n└── .env.example # Environment variables template\n```\n\n## Setup\n\n### Install Dependencies\n\nThe backend shares dependencies with the main VibeVoice project. Install from the project root:\n\n```bash\npip install -e .\n```\n\n### Configuration\n\n1. Copy the example environment file:\n```bash\ncp backend/.env.example backend/.env\n```\n\n2. Edit `backend/.env` with your configuration\n\n### Running the Development Server\n\nFrom the project root:\n\n```bash\npython backend/run.py\n```\n\nOr using the module:\n\n```bash\npython -m backend.run\n```\n\nThe server will start at `http://localhost:9527` by default.\n\n## API Endpoints\n\n### Health Check\n\n```\nGET /health\n```\n\nReturns server health status.\n\n### API Base\n\n```\nGET /\n```\n\nReturns API information.\n\n### Test Endpoint\n\n```\nGET /api/v1/ping\n```\n\nSimple ping endpoint for testing.\n\n### Projects API\n\n#### List Projects\n```\nGET /api/v1/projects\n```\n\nReturns all projects with metadata.\n\n**Response:**\n```json\n{\n \"projects\": [\n {\n \"id\": \"my-project\",\n \"name\": \"My Project\",\n \"description\": \"Project description\",\n \"created_at\": \"2025-10-22T03:18:58.969507\",\n \"updated_at\": \"2025-10-22T03:18:58.969507\"\n }\n ],\n \"count\": 1\n}\n```\n\n#### Get Project\n```\nGET /api/v1/projects/\n```\n\nGet specific project by ID.\n\n#### Create Project\n```\nPOST /api/v1/projects\nContent-Type: application/json\n\n{\n \"name\": \"Project Name\",\n \"description\": \"Optional description\"\n}\n```\n\nCreates a new project directory with subdirectories (`voices/`, `scripts/`, `outputs/`) and adds metadata entry.\n\n**Response:** HTTP 201 with project data\n\n#### Update Project\n```\nPUT /api/v1/projects/\nContent-Type: application/json\n\n{\n \"name\": \"Updated Name\",\n \"description\": \"Updated description\"\n}\n```\n\nUpdates project metadata (name and/or description).\n\n#### Delete Project\n```\nDELETE /api/v1/projects/\n```\n\nDeletes project directory and removes from metadata.\n\n**Response:**\n```json\n{\n \"message\": \"Project deleted successfully\",\n \"project_id\": \"my-project\"\n}\n```\n\n## Configuration\n\nEnvironment variables (see `.env.example`):\n\n- `FLASK_ENV`: Environment (development/production/testing)\n- `FLASK_HOST`: Server host (default: 0.0.0.0)\n- `FLASK_PORT`: Server port (default: 9527)\n- `FLASK_DEBUG`: Enable debug mode (default: true)\n- `SECRET_KEY`: Flask secret key\n- `CORS_ORIGINS`: Allowed CORS origins (comma-separated)\n- `WORKSPACE_DIR`: Root directory for all projects (default: ./workspace)\n- `MODEL_PATH`: Path to VibeVoice model\n- `MODEL_DEVICE`: Device for model inference (cuda/cpu)\n- `UPLOAD_FOLDER`: Directory for uploaded files\n- `MAX_CONTENT_LENGTH`: Maximum file upload size\n\n## Development\n\n### Project Structure\n\n- **api/**: REST API endpoints organized by resource\n- **models/**: Data models and schemas\n- **services/**: Business logic and model integration\n- **utils/**: Helper functions and utilities\n\n### Adding New Endpoints\n\n1. Create a new file in `api/` (e.g., `api/myresource.py`)\n2. Define routes using Flask blueprints\n3. Import and register the blueprint in `api/__init__.py`\n\n## Project Directory Structure\n\nEach project is stored as a directory under `WORKSPACE_DIR`:\n\n```\nworkspace/\n├── projects.json # Metadata for all projects\n└── my-project/ # Project directory (named by project ID)\n ├── voices/ # Speaker voice samples\n │ ├── speakers.json # Speaker metadata\n │ └── *.wav # Voice sample files\n ├── scripts/ # Dialog scripts\n │ ├── sessions.json # Dialog session metadata\n │ └── *.txt # Dialog text files\n └── outputs/ # Generated audio files (TBD)\n```\n\n### Speakers API\n\n#### List Speakers\n```\nGET /api/v1/projects//speakers\n```\n\nReturns all speaker roles for a project.\n\n**Response:**\n```json\n{\n \"speakers\": [\n {\n \"speaker_id\": \"Speaker 1\",\n \"name\": \"Alice\",\n \"description\": \"Main host\",\n \"voice_filename\": \"abc123.wav\",\n \"created_at\": \"2025-10-22T...\",\n \"updated_at\": \"2025-10-22T...\"\n }\n ],\n \"count\": 1\n}\n```\n\n#### Get Speaker\n```\nGET /api/v1/projects//speakers/\n```\n\nGet specific speaker by ID (e.g., \"Speaker 1\").\n\n#### Add Speaker\n```\nPOST /api/v1/projects//speakers\nContent-Type: multipart/form-data\n\nname: Speaker Name\ndescription: Speaker description (optional)\nvoice_file: