# AutoRemaster - Audio Mastering Tool

An audio mastering GUI application designed to automatically fix common artifacts in AI-generated EDM music and apply genre-specific mastering chains.

## Features

- **Waveform Visualization**: Real-time before/after waveform and spectrogram display
- **Stem Separation**: Uses Demucs (Meta Research) for isolating drums, bass, vocals, and other stems
- **Auto-Sidechain**: Automatic sidechain compression triggered by detected kick drums
- **Mono Bass Correction**: M/S processing to collapse low frequencies to mono
- **Transient Shaping**: Enhance drum punch and tighten tails
- **Spectral Exciter**: Add high-frequency harmonics (fixes AI "16kHz hard cut")
- **Loudness Normalization**: Target LUFS with limiting
- **Genre Presets**: Pre-configured settings for Techno, Trance, Psytrance, Deep House, and more

## Project Structure

```
AutoRemaster/
├── src/
│   ├── main.py              # Entry point - launches the application
│   ├── utils.py             # Utility helper functions
│   ├── ui/
│   │   ├── __init__.py
│   │   ├── app.py           # AutoRemasterApp - main GUI window
│   │   ├── header_frame.py  # Zone A - File input controls
│   │   ├── controls_frame.py # Zone B - Genre & processing options
│   │   ├── waveform_frame.py # Zone D - Waveform visualization
│   │   └── status_frame.py  # Zone C - Progress & execution
│   └── engine/
│       ├── __init__.py
│       ├── processor.py     # AudioEngine - core audio processing
│       ├── presets.py       # GENRE_PRESETS - mastering presets
│       └── worker.py        # ProcessingThread - background worker
├── tests/
│   ├── test_dsp_numpy.py    # Unit tests for DSP functions
│   └── test_waveform_display.py # Tests for waveform visualization
├── assets/                   # Images, icons, resources
├── temp/                     # Temporary file processing
├── venv310/                  # Python 3.10 virtual environment
├── requirements.txt          # Python dependencies
├── start.sh                  # Easy launch script (recommended)
├── check_env.sh              # Environment diagnostic tool
├── run.sh                    # Simple launch script
├── QUICK_START.md            # Quick start guide
├── WAVEFORM_FEATURE.md       # Waveform visualization documentation
└── README.md                 # This file
```

## Requirements

- Python 3.10 (required for Demucs/NumPy compatibility)
- NVIDIA GPU (optional, for faster stem separation)

## Setup

1. Install dependencies (requires Python 3.10):
   ```bash
   cd /home/user/Projects/AutoRemaster
   ./venv310/bin/pip install -r requirements.txt
   ```

2. For GPU acceleration (optional):
   - Ensure CUDA drivers are installed
   - PyTorch with CUDA is included in requirements

## Running the Application

### Quick Start (Recommended)

```bash
./start.sh
```

The `start.sh` script will:
- Verify your Python environment
- Check and install missing dependencies
- Configure proper environment variables
- Launch the application

### Check Your Environment

Before running, verify everything is set up correctly:

```bash
./check_env.sh
```

### Alternative Launch Methods

**Option 1: Simple launch script**
```bash
./run.sh
```

**Option 2: Direct Python execution**
```bash
./venv310/bin/python src/main.py
```

For detailed launch instructions, see [QUICK_START.md](QUICK_START.md)

## Usage

1. **Load Audio**: Click "Load WAV File" to select an audio file
   - Waveform and spectrogram display automatically in "BEFORE" panel
2. **Select Genre**: Choose a genre preset from the dropdown
3. **Configure Processing**: Enable/disable processing modules:
   - Stem Separation (required for Sidechain and Transient Shaper)
   - AI De-Haze / Exciter
   - Mono Bass Correction
   - Auto-Sidechain
   - Transient Shaper
   - Final Limiting & Loudness
4. **Process**: Click "PROCESS" to start mastering
5. **Compare**: View before/after waveforms and spectrograms side-by-side
6. **Preview**: Use "Play Result" to audition the mastered audio
7. **Save**: Click "SAVE MASTER" to export the final WAV file

For detailed visualization features, see [WAVEFORM_FEATURE.md](WAVEFORM_FEATURE.md)

## Genre Presets

| Genre | Target LUFS | Mono Cutoff | Sidechain | Transient | Exciter |
|-------|-------------|-------------|-----------|-----------|---------|
| Techno | -7.0 | 150 Hz | Heavy (80%) | +4dB | Low |
| Trance | -7.5 | 130 Hz | Med (60%) | +2dB | High |
| Psytrance | -6.5 | 100 Hz | Tight (90%) | +5dB | Med |
| Deep House | -10.0 | 120 Hz | Gentle (40%) | Low | Low |
| Dubstep | -6.0 | 80 Hz | None | Extreme | High |
| Organic House | -11.0 | 100 Hz | Gentle | Low | None |

## Development

### Running Tests
```bash
./venv310/bin/python tests/test_dsp_numpy.py
```

### Development Status

- [x] Project structure and scaffolding
- [x] Python 3.10 environment setup
- [x] Genre presets configuration
- [x] AudioEngine with DSP methods
- [x] Stem separation wrapper (Demucs)
- [x] Sidechain compression
- [x] Mono bass correction (M/S processing)
- [x] Transient shaping
- [x] Spectral exciter
- [x] Loudness normalization
- [x] GUI Zone A (Header & Input)
- [x] GUI Zone B (Controls & Presets)
- [x] GUI Zone C (Status & Execution)
- [x] Background processing thread
- [x] File save functionality
- [x] Audio playback preview
- [x] Unit tests for DSP functions

## Dependencies

- customtkinter >= 5.0.0 - Modern GUI framework
- pedalboard >= 0.9.0 - Audio effects processing
- demucs >= 4.0.0 - Source separation
- numpy >= 1.24.0, < 2.0.0 - Numerical operations
- scipy >= 1.11.0 - Signal processing
- pyloudnorm >= 0.1.0 - Loudness normalization
- soundfile >= 0.12.0 - Audio I/O
- pygame >= 2.5.0 - Audio playback
- torch >= 2.0.0 - Deep learning backend
- torchaudio >= 2.0.0 - Audio ML utilities

## License

TBD