ACE-Step LoRA Trainer

A streamlined web application for training custom LoRA models with ACE-Step Music Generation

Train custom music generation models with minimal effort. Upload audio files, let the system handle metadata extraction and file organization, extract lyrics automatically, and build training datasets—all through an intuitive web interface.

✨ Features

• 🎵 Smart Audio Processing - Automatic file renaming, metadata extraction, and tag generation
• 📝 Auto Lyrics Extraction - Whisper integration for automatic lyric transcription (CPU or GPU)
• 🏷️ Tag Management - Edit and organize tags with an intuitive chip-based interface
• 📦 Dataset Builder - Select tracks and build training datasets with one click
• ⚙️ LoRA Configuration - Easy parameter tuning with VRAM optimization tips
• 🚀 Training Management - Start, monitor, and manage training sessions with real-time progress

🎯 What It Does

ACE-Step LoRA Trainer simplifies the entire workflow of training custom music generation models:

1. Upload audio files → automatically renamed and tagged
2. Edit metadata, tags, and lyrics in a clean UI
3. Extract lyrics using Whisper (optional, one-click)
4. Build training datasets by selecting tracks
5. Train your custom LoRA model

No manual file renaming, no complex command-line tools, no scattered scripts—everything is automated and organized.

🚀 Quick Start

Prerequisites

• Python 3.8+ and Node.js 18+
• ACE-Step git submodule initialized (REQUIRED - see setup below)
• FFmpeg installed (for audio processing)

Installation

# Clone the repository
git clone https://github.com/audiohacking/ace-step-lora-app.git
cd ace-step-lora-app

# Install Python dependencies (includes all ACE-Step dependencies)
pip install -r requirements.txt

# Install Node.js dependencies
npm install

# Set up ACE-Step submodule (REQUIRED for training)
# Option 1: Use the setup script (recommended)
./setup_ace_step.sh  # macOS/Linux
# OR
setup_ace_step.bat   # Windows

# Option 2: Manual setup
# Initialize the git submodule:
git submodule update --init --recursive

# Optional: Create symlinks for convenience
ln -s ace-step/convert2hf_dataset.py .
ln -s ace-step/trainer.py .

Running

# Start backend (terminal 1)
python backend/app.py

# Start frontend (terminal 2)
npm run dev

# Open http://localhost:3000

Or use the startup scripts:

• macOS/Linux: ./start.sh
• Windows: start.bat

📖 Documentation

• USAGE.md - Comprehensive usage guide and detailed instructions
• API Reference - Complete API documentation
• Troubleshooting - Common issues and solutions

🏗️ Architecture

Frontend (React + TypeScript)
    ↓
Backend API (Flask)
    ↓
Services:
  • Audio Processor (metadata extraction)
  • Track Manager (metadata storage)
  • Whisper Service (lyric transcription)
  • Dataset Builder (training dataset assembly)
    ↓
ACE-Step Training Pipeline

🧪 Testing

# Run all tests
pytest tests/              # Backend tests
npm test                   # Frontend tests
./run_tests.sh            # All tests (macOS/Linux)

# With coverage
pytest tests/ --cov=backend --cov-report=html
npm run test:coverage

See Testing for more details.

🛠️ Development

# Install development dependencies
pip install -r requirements.txt
npm install

# Run in development mode
python backend/app.py    # Backend with hot-reload
npm run dev              # Frontend with hot-reload

# Build for production
npm run build

📦 Project Structure

ace-step-lora-app/
├── ace-step/            # ACE-Step git submodule (training scripts)
│   ├── trainer.py       # Training script
│   └── convert2hf_dataset.py  # Dataset conversion script
├── backend/              # Flask API server
│   ├── app.py           # Main API endpoints
│   ├── audio_processor.py
│   ├── track_manager.py
│   ├── whisper_service.py
│   └── dataset_builder.py
├── src/                  # React frontend
│   ├── components/      # UI components
│   └── App.tsx
├── tests/               # Test suite
├── data/                # Uploaded tracks (auto-created)
├── datasets/            # Built datasets (auto-created)
└── weights/             # Training outputs (auto-created)

🔧 Configuration

Environment Variables

• USE_GPU_WHISPER=true - Enable GPU acceleration for Whisper
• WHISPER_MODEL=base - Whisper model size (tiny/base/small/medium/large)
• FLASK_ENV=production - Production mode

Whisper Setup

The app supports two Whisper implementations:

1. whisper-cpp (recommended) - Faster, lower memory

   • Install: git clone https://github.com/ggerganov/whisper.cpp.git
   • Place in project root or set path in code

2. openai-whisper (fallback) - Python library

   • Automatically installed via requirements.txt

🤝 Contributing

Contributions welcome! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the AGPLv3 License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for use with ACE-Step - a music generation model framework
• Whisper transcription powered by OpenAI Whisper and whisper.cpp

🐛 Troubleshooting

Python lzma Module Error

If you see ModuleNotFoundError: No module named '_lzma':

macOS (with pyenv):

# Install xz library
brew install xz

# Rebuild Python with lzma support
export LDFLAGS="-L$(brew --prefix xz)/lib"
export CPPFLAGS="-I$(brew --prefix xz)/include"
export PKG_CONFIG_PATH="$(brew --prefix xz)/lib/pkgconfig:$PKG_CONFIG_PATH"
pyenv install --force 3.11.6

# Verify
python3 -c "import lzma; print('✅ lzma works!')"

Check your environment:

python3 check_python.py

For more troubleshooting, see USAGE.md.

📞 Support

• Issues: GitHub Issues
• Documentation: See USAGE.md for detailed guides
• ACE-Step Docs: ACE-Step Repository

---

Made with ❤️ for the music generation community