README.md

---
title: EraEcho
emoji: 🎧
colorFrom: purple
colorTo: blue
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
---

# EraEcho

EraEcho is a Hugging Face Space that transposes uploaded music into the style of a selected historical decade, from the 1920s through the 2020s.

The app uses:

- **Gradio** for the Hugging Face Space UI.
- **Modal.com** for remote GPU-accelerated audio processing.
- **Qwen/Qwen3-14B** for era-aware transformation notes and historical fidelity reporting.
- DSP filters (running on Modal) for decade-specific audio transformation.

All planned model choices stay at **32B parameters or under**.

## Features

- Upload a music file.
- Select a target decade from the 1920s to the 2020s.
- Generate an era-simulated audio file.
- Receive a historical fidelity report explaining instruments, production norms, and audio imperfections.

## Local Space development

```bash
pip install -r requirements.txt
python app.py
```

Requires a deployed Modal backend. See Modal setup below.

## Modal setup

1. Install and authenticate Modal:

   ```bash
   pip install modal
   modal setup
   ```

2. Deploy the Modal service:

   ```bash
   modal deploy modal_app.py
   ```

3. In Hugging Face Spaces, add any required Modal credentials/secrets according to Modal's client setup.

## Architecture

- `app.py` — Gradio frontend, calls Modal for all processing.
- `modal_app.py` — Modal backend with A10G GPU, runs Qwen3-14B + DSP pipeline.
- `eraecho_core.py` — Audio DSP engine and era profiles, runs inside the Modal container.