Enhanced RVC Training System with full TypeScript stack, 20 optimizers, Python FastAPI backend, WebSocket real-time monitoring, and Google Colab support.
📚 Documentation · ⚡ Quick Start · ☁️ Colab · 💻 Install · 🎨 WebUI · 🎯 Optimizers · 🔄 Workflow
Built on PolTrain · Full Documentation →
🎉 VCTrain is now fully TypeScript with optimized Colab support!
- ✅ Frontend: Next.js 16 + TypeScript (all components, API client, WebSocket hook)
- ✅ Bridge: TypeScript WebSocket bridge running on Bun
- ✅ Backend: FastAPI + Pydantic type definitions
- ✅ Colab: Node.js 20 LTS auto-install, fixed frontend startup
- ✅ Type Safety: End-to-end type validation prevents runtime errors
- ✅ Better Organization: Clean folder structure with
ts/directory
📚 New here? Check our Documentation for step-by-step tutorials!
Complete documentation is in the docs/ folder:
| Resource | Description | Link |
|---|---|---|
| 📖 Documentation Index | All docs organized in docs/ folder |
Browse |
| 🏠 Home | Main documentation hub | docs/wiki/Home.md |
| 📦 Installation | Complete setup guide | docs/wiki/Installation-Guide.md |
| 🎓 First Training | Step-by-step tutorial | docs/wiki/First-Training.md |
| ☁️ Colab Guide | Free GPU setup | docs/wiki/Colab-Setup.md |
| 🏗️ Architecture | Technical deep dive | docs/wiki/Architecture.md |
| ⚡ Quick Reference | Commands & tips | docs/guides/Quickstart.md |
3 Steps to Training:
- Click "Open in Colab" button above
- Run all cells sequentially (takes ~5 minutes)
- Open ngrok URL → Start training in WebUI
What you need:
- Google account
- Free ngrok token from https://dashboard.ngrok.com/auth (for public access)
- Audio dataset (10+ minutes of clean speech)
See Colab Setup Guide for detailed instructions.
# 1. Clone & Install
git clone https://github.com/BF667-IDLE/VCTrain.git
cd VCTrain
# Install Python deps
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
pip install fastapi uvicorn[standard] websockets
# Install frontend deps
curl -fsSL https://bun.sh/install | bash
bun install
# Download models
python download_files.py
# 2. Start everything
bun run dev:full
# 3. Open browser
# http://localhost:3000Requirements:
- Python 3.8+
- Node.js 20.x LTS (18.18.0+ minimum)
- PyTorch 2.0+ with CUDA
- 8GB+ RAM (16GB+ recommended)
See Installation Guide for complete instructions.
- ✅ Free T4 GPU with 16GB VRAM
- ✅ Zero setup - everything automated
- ✅ Public access via ngrok tunnels
- ✅ Persistent storage with Google Drive
- ✅ Keep-alive prevents disconnection
| Cell | Purpose | Time |
|---|---|---|
| 1 | GPU Check | ~10s |
| 2 | Install Dependencies (Python only) | ~3-5 min |
| 3 | Download Pre-trained Models | ~1-2 min |
| 4 | Setup Advanced Client Files | ~5s |
| 5 | Upload Dataset (Optional) | ~1 min |
| 6 | Start Server + ngrok | ~30s |
| 7 | Keep Alive + Monitoring | Runs forever |
- ✅ Use T4 GPU: Runtime → Change runtime type → T4 GPU
- ✅ Run cells in order: Don't skip cells
- ✅ Don't stop Cell 7: Prevents disconnection
- ✅ Use Ranger optimizer: Best for T4 GPU
- ✅ Batch size 4-8: Don't exceed T4's 16GB VRAM
- ✅ Save to Drive: Persist models across sessions
📚 Full guide: Colab-Setup
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.8+ | 3.10+ recommended |
| Node.js | 18.18.0+ | 20.x LTS recommended |
| PyTorch | 2.0+ | With CUDA for GPU |
| GPU | Optional | NVIDIA with CUDA 11.7+ |
| RAM | 8GB+ | 16GB+ recommended |
Detailed guide: Installation-Guide
Quick version:
# 1. Clone repo
git clone https://github.com/BF667-IDLE/VCTrain.git && cd VCTrain
# 2. Install Python deps
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
pip install fastapi uvicorn[standard] websockets
# 3. Install frontend
bun install
# 4. Download models
python download_files.py
# 5. Start
bun run dev:fullSimple method (recommended):
python main.py
# Open: http://localhost:7860/client/Or for development (3 services):
# Terminal 1 - Backend (FastAPI)
python main.py
# Terminal 2 - WebSocket Bridge (optional)
cd mini-services/ws-bridge && bun run index.ts
# Terminal 3 - Frontend (Next.js dev mode)
bun run devOpen http://localhost:7860/client/ for advanced client or http://localhost:3000 for full WebUI
- 📊 Experiment list from filesystem
- 🚀 Active training jobs with live status
- 🎮 GPU monitoring (name, memory, CUDA version)
- 🔌 Connection indicator (backend online/offline)
- ⚡ Quick actions (New Training, Compare Models)
- 📝 Complete form matching all
train.pyCLI arguments - 🎯 20 optimizers with live info panel
- 💻 Live CLI command preview with copy button
- 🚀 Starts real training via FastAPI backend
- 🆔 Shows job ID on success
- 📈 Real-time WebSocket metrics
- 📊 4 interactive Recharts:
- Loss Curves (discriminator, generator, mel, KL)
- Mel Similarity (%) over epochs
- Gradient Norms (G vs D)
- Learning Rate Schedule
- 📜 Scrollable log viewer - raw training output
- 🎭 Demo mode with mock data when offline
- 🏆 6 recommendation cards: Best Overall, Fastest, Memory Efficient, etc.
- 📋 All 20 optimizers organized by category
- ⭐ Star ratings: Speed, Quality, Memory, Stability
- 🔍 Click for details: Description, LR range, key features
📚 Full WebUI guide: WebUI-Dashboard
VCTrain supports 20 different optimizers for RVC training:
| Goal | Optimizer | Batch Size | Notes |
|---|---|---|---|
| Best Overall | Ranger | 8 | RAdam + Lookahead, very stable |
| Best Quality | Sophia | 8 | Curvature-aware, fast convergence |
| No LR Tuning | Prodigy | 8 | Auto-adjusts LR, set lr=1.0 |
| Memory Saver | Adafactor | 12 | Lowest VRAM usage |
| Fastest | SignSGD | 16 | Minimal memory per step |
| Category | Optimizers | Best For |
|---|---|---|
| Adaptive | AdamW, Adam, AdaBelief, AdaBeliefV2, Adafactor, AMSGrad, RAdam, AdamP, Apollo, NovoGrad, LAMB | Most use cases |
| Sign-Based | Lion, SignSGD | Memory efficiency |
| Second-Order | Sophia, CAME | Fast convergence |
| Hybrid | Ranger, Lookahead | Stability + quality |
| Auto-LR | DAdaptAdam, Prodigy | Zero tuning needed |
📚 Full guide: Optimizer-Guide
- Collect 10-60 minutes of clean speech
- Save as WAV (recommended), FLAC, or MP3
- Place in
experiments/my_voice/raw/
# Or use WebUI form
python rvc/train/train.py \
--experiment_dir "experiments" \
--model_name "my_voice" \
--total_epoch 300 \
--batch_size 8 \
--optimizer "AdamW"- Open http://localhost:7860/client/ for advanced client
- Or http://localhost:7860/ for full WebUI
- Watch metrics in real-time:
- Loss should decrease ✅
- Mel similarity should increase (target: 80%+) ✅
- Gradient norms should be stable ✅
- Training finishes automatically
- Checkpoint saved to
experiments/my_voice/ - Use with RVC for voice conversion
📚 Full guide: Training-Workflow
VCTrain/
├── client/ # Advanced Client System
│ ├── html/ # Pure HTML client
│ ├── css/ # CSS styles
│ ├── js/ # JavaScript
│ ├── python/ # Python launchers
│ └── ts/ # TypeScript/Next.js source
│
├── main.py # FastAPI server (serves client + API)
├── colab_simple_client.ipynb # Simple Colab notebook (recommended)
├── colab_advanced_client.ipynb # Full-featured Colab notebook
├── universal_client.py # Universal launcher
├── deploy_colab.sh # Colab deployment script
│
├── rvc/ # Core training code (Python)
│ ├── train/ # Training script + 20 optimizers
│ └── lib/ # Algorithm implementations
│
├── src/ # Next.js Frontend (TypeScript)
│ ├── app/ # Next.js pages
│ ├── components/ # React components
│ └── lib/ # API client, store, utils
│
├── web/ # Built static frontend
│ ├── index.html # Next.js export
│ └── client/ # Advanced client (copy)
│
└── docs/ # Documentation
├── wiki/ # Wiki pages
└── guides/ # Quick guides
📚 Architecture details: Architecture
python main.py # Start server (recommended)
python universal_client.py # Universal launcher
python colab_simple_client.ipynb # Colab notebookbun run dev # Frontend only (Next.js dev mode)
bun run build # Build frontend for production
npm start # Start backend onlypython download_files.py # Download pre-trained models
bash deploy_colab.sh # Deploy to Colab| Problem | Solution |
|---|---|
| Frontend won't start | Install Node.js 20.x LTS |
| CUDA out of memory | Lower batch size or use Adafactor |
| Loss is NaN | Lower learning rate or try Prodigy |
| Colab disconnects | Don't stop keep-alive cell |
| Port already in use | Kill process: lsof -ti:3000 | xargs kill |
📚 Full troubleshooting: Troubleshooting
- 📖 Wiki: https://github.com/BF667-IDLE/VCTrain/wiki
- 🐛 Issues: https://github.com/BF667-IDLE/VCTrain/issues
- 💬 Discussions: https://github.com/BF667-IDLE/VCTrain/discussions
- Installation-Guide - Get everything setup
- First-Training - Train your first model
- Colab-Setup - Use free GPU
- Optimizer-Guide - Learn about all 20 optimizers
- Dataset-Preparation - Prepare better datasets
- GPU-Configuration - Optimize for your hardware
- Architecture - Understand the stack
- TypeScript-Stack - Type safety details
- API-Reference - Backend API documentation
We welcome contributions! Here's how:
git clone https://github.com/BF667-IDLE/VCTrain.git
cd VCTrain
bun install
bun run dev:full- ✅ Follow TypeScript best practices
- ✅ Write tests for new features
- ✅ Update documentation
- ✅ Use conventional commits
- Improve WebUI UX
- Add dataset validation
- Write integration tests
- Translate documentation
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16, React 19, TypeScript 5 | WebUI |
| Styling | Tailwind CSS 4, shadcn/ui | Components |
| State | Zustand, React Query | Data management |
| Charts | Recharts | Real-time metrics |
| Bridge | Bun, WebSocket | REST proxy + WS relay |
| Backend | FastAPI, Uvicorn, Pydantic | API server |
| ML | PyTorch 2.0+, CUDA | Training pipeline |
| Audio | librosa, pydub, ffmpeg | Audio processing |
This project is built on top of PolTrain and follows the same license.
- PolTrain - Base RVC implementation
- RVC Project - Original voice conversion system
- ContentVec - Feature embedder
- RMVPE - Pitch detector
Happy Training! 🎤✨
Made with ❤️ by the VCTrain Team