# Functional Design Specification: SunoRemaster

**Version:** 1.0  
**Date:** December 20, 2025  
**Author:** [Your Name]  
**Status:** Draft  

---

## 1. Executive Summary
**SunoRemaster** is a local, Python-based desktop application designed to automate the post-production process of AI-generated Electronic Dance Music (EDM). It targets specific artifacts common in current generative audio models (muddy low-end, lack of transients, poor stereo imaging) and applies genre-specific mixing and mastering chains to produce "club-ready" WAV files.

### 1.1 Objectives
* **Fix AI Artifacts:** Automatically repair frequency masking and poor transient response.
* **Genre-Specific Mastering:** Apply different DSP logic based on the sub-genre (e.g., Trance vs. Organic House).
* **Privacy First:** All processing is done locally (offline) using Python libraries.
* **User Control:** Allow users to toggle specific processing modules via a GUI.

---

## 2. User Interface (UI) Specification

The application will use `customtkinter` for a modern, dark-mode interface.

### 2.1 Main Window Layout
The window resolution is fixed at **800x600**.

#### Zone A: Header & Input
* **Title Label:** "SunoRemaster Tool v1.0"
* **File Input:**
    * [Button] `Load WAV File` (Opens OS file picker).
    * [Label] Displays selected file path (e.g., `.../my_track.wav`).
    * [Button] `Play Original` (Preview using `pygame` or `sounddevice`).

#### Zone B: Configuration (The Control Center)
* **Genre Selector (Dropdown Menu):**
    * *Options:* Techno, Trance, Psytrance, Organic House, Progressive House, Complextro, Dubstep, EDM (Mainstage), Deep House, Tech House, Custom.
    * *Behavior:* Selecting an option updates the hidden DSP parameters (Target LUFS, Sidechain Strength, etc.).
    
* **Processing Modules (Checkboxes):**
    * `[x]` **1. Stem Separation (Demucs)** *(Required for Advanced Mixing)*
    * `[ ]` **2. AI De-Haze / Exciter** *(Fixes muffled high-end)*
    * `[ ]` **3. Mono Bass Correction** *(Collapses sub-bass to mono)*
    * `[ ]` **4. Auto-Sidechain** *(Ducks bass/synths based on Kick)*
    * `[ ]` **5. Transient Shaper** *(Boosts drum punch)*
    * `[ ]` **6. Final Limiting & Loudness** *(Target LUFS)*

#### Zone C: Execution & Feedback
* **Progress Bar:** 0% to 100% (Green accent color).
* **Status Log (Scrollable Text Box):**
    * Displays real-time steps: *"Separating Stems... (This may take 45s)"*, *"Applying Compressor..."*.
* **Action Buttons:**
    * [Button] `PROCESS` (Triggers the worker thread).
    * [Button] `SAVE MASTER` (Enabled only after processing is complete).
    * [Button] `Play Result` (A/B testing).

---

## 3. Technical Architecture

### 3.1 Technology Stack
* **GUI:** `customtkinter` (Python)
* **Audio DSP:** `pedalboard` (Spotify), `scipy.signal`
* **Stem Separation:** `demucs` (Meta Research) - *Must run in a separate thread.*
* **Matrix Math:** `numpy` (for manual sidechaining/mixing)
* **Loudness:** `pyloudnorm` (ITU-R BS.1770-4 standard)

### 3.2 Threading Model
To prevent GUI freezing during heavy rendering:
1.  **Main Thread:** UI Event Loop.
2.  **Worker Thread (`QThread` or `threading.Thread`):**
    * Receives `input_path` and `config_dict`.
    * Runs the audio pipeline.
    * Emits signals: `progress_percent(int)` and `log_message(str)`.

---

## 4. Functional Requirements (The Pipeline)

### 4.1 Step 1: Ingest & Analysis
* **Input:** Load WAV/MP3. Convert to 32-bit Float `numpy` array.
* **Validation:** Check if Sample Rate is 44.1kHz or 48kHz. If 48kHz, resample or warn user.

### 4.2 Step 2: Stem Separation (Conditional)
* **Condition:** If `Stem Separation` OR `Auto-Sidechain` OR `Transient Shaper` is checked.
* **Action:** Execute `demucs.separate()`.
* **Output:** 4 temporary arrays: `drums`, `bass`, `other`, `vocals`.

### 4.3 Step 3: Genre-Based Logic (The "Brain")
The application pulls parameters from a `PRESETS` dictionary based on the user's dropdown selection.

**Preset Data Structure Table:**

| Genre | Target LUFS | Mono Cutoff | Sidechain | Transient Boost | Exciter Amt |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Techno** | -7.0 | 150 Hz | Heavy (80%) | High (+4db) | Low |
| **Trance** | -7.5 | 130 Hz | Med (60%) | Med (+2db) | High |
| **Psytrance** | -6.5 | 100 Hz | Tight (90%) | High (+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 |
| **Complextro** | -6.5 | 120 Hz | Med | High | High |

*\*Note: Dubstep usually relies on arrangement for sidechain, but can optionally use Multiband.*

### 4.4 Step 4: DSP Processing Chain

#### A. Bass Correction
* **Logic:** Apply High-Pass Filter to the *Side Channel* (M/S Processing) of the `Bass` stem (or full mix if no stems).
* **Default:** Cut sides below `Mono Cutoff` Hz.

#### B. Transient Shaping (Drums Stem Only)
* **Logic:** If `demucs` was used, isolate `drums`.
* **Effect:** Load `TransientShaper` logic (or VST). Increase Attack by `Transient Boost` value. Decrease Sustain by 10% to tighten tails.

#### C. Auto-Sidechaining
* **Logic:**
    1.  Calculate RMS Envelope of `drums`.
    2.  Invert Envelope.
    3.  Multiply `bass` and `other` arrays by the Inverted Envelope.
    4.  Apply `Sidechain` strength factor (Mix Dry/Wet).

#### D. Spectral Exciter (Master Bus)
* **Logic:** High-pass copy of signal at 5kHz -> Distort -> Blend back at -20dB.
* **Purpose:** Fixes the "16kHz Hard Cut" often seen in Suno generations.

#### E. Final Limiting
* **Logic:**
    1.  Measure current Integrated LUFS.
    2.  Calculate Gain needed to hit `Target LUFS`.
    3.  Apply `Limiter` (Ceiling -0.3 dB, Release 100ms).

---

## 5. File Management & Output

### 5.1 Temporary Files
* The tool creates a `_temp` folder for Demucs stems.
* **Cleanup:** The folder is cleared automatically when the application closes or when a new file is loaded.

### 5.2 Export
* **Format:** WAV (16-bit or 24-bit PCM).
* **Naming Convention:** `{OriginalName}_{Genre}_Mastered.wav`

---

## 6. Future Expansion (Roadmap)
* **VST3 Loader Tab:** Allow users to point to their own `.vst3` files (e.g., FabFilter) to replace the internal `pedalboard` effects.
* **Batch Processing:** "Select Folder" to master 10 tracks in a queue.
* **Reference Match:** Load a "Reference Track" and auto-adjust EQ to match it.

---

## 7. Delivery Deliverables
1.  `main.py` (Entry point).
2.  `gui.py` (Layout and widgets).
3.  `audio_engine.py` (The DSP logic class).
4.  `presets.py` (The dictionary of genre settings).
5.  `requirements.txt`.