Audio Reconstruction

July 14, 2026 · View on GitHub

Reconstruct high-fidelity audio from compressed MP3 sources using adversarial neural networks. The model restores lost high-frequency harmonics, spectral detail, and natural timbre — producing near-lossless FLAC output from lossy input.

Input: MP3 (128 / 256 / 320 kbps) | Output: FLAC (~800+ kbps effective bitrate)

Quick Start (CLI)

The fastest way to reconstruct audio — no training, no GPU, no repo clone. The audioreconstructor package ships an ONNX build of the trained model that runs on CPU:

pip install audioreconstructor
audioreconstructor setup                                       # downloads + verifies model
audioreconstructor enhance --input song.mp3 --output song.flac # single file
audioreconstructor enhance --folder ./songs                    # whole folder

Supports 64-bit Linux and Windows. See onnx/cli/README.md for doctor, execution providers, and cache locations.

How It Works

A GAN (Generative Adversarial Network) learns to reverse compression artifacts:

Generator — a 1D U-Net (~28M params) that predicts high-resolution spectral content from the compressed waveform via a residual connection (learns the difference, not the full signal)
Discriminator — a multi-scale network (~25M params) that enforces perceptual realism by distinguishing real from reconstructed audio
Training objective — combines LSGAN adversarial loss, multi-scale spectral loss (STFT at 512/1024/2048), and feature matching loss

Use Cases

Music remastering from low-bitrate sources
Streaming audio quality enhancement
Archival recovery of degraded recordings

Architecture

audioreconstruction/
├── backend/           # Local FastAPI inference server
├── server/            # Production server (Modal.com GPU deployment)
├── frontend/          # React 19 + Vite 8 + Tailwind CSS 4 UI
├── model/             # PyTorch model definition, training, and evaluation
├── onnx/cli/          # audioreconstructor — pip-installable ONNX CLI (PyPI)
├── test/              # Audio similarity evaluation scripts
├── design/            # UI design briefs and mockups
├── docs/              # Contributing, security, code of conduct
└── pyproject.toml     # Python project config (uv)

Tech Stack

Layer	Technology
Model	PyTorch, torchaudio, safetensors
Backend	FastAPI, uvicorn, SlowAPI
Deployment	Modal.com (GPU serverless — T4)
Frontend	React 19, Vite 8, Tailwind CSS 4
Metrics	PESQ, SNR (perceptual evaluation)
Tooling	uv (Python), Bun (JS), Ruff (lint)

Getting Started

Prerequisites

Python >= 3.10
Node.js >= 20
uv (Python package manager)
Bun (JS package manager, optional — npm works too)
FFmpeg (for data preparation)

Setup

git clone git@github.com:rohan-prasen/audioreconstruction.git
cd audioreconstruction

# Python dependencies
uv sync

# Frontend dependencies
cd frontend && bun install

Model weights are hosted on HuggingFace — download here. Place generator.safetensors under ./model/checkpoints/best/.

Run Locally

# Start the local backend
uv run uvicorn backend.main:app --reload

# Start the frontend (in a separate terminal)
cd frontend && bun dev

# Deploy the production server to Modal.com (requires `modal` CLI auth)
cd server && modal deploy modal_app.py

Development

# Lint Python
uv run ruff check .

# Lint frontend
cd frontend && bun lint

# Run tests
uv run pytest

# Prepare training data (requires FFmpeg)
uv run python -m model.prepare_data

# Train the model
uv run python -m model.train

# Evaluate / infer
uv run python -m model.evaluate --checkpoint model/checkpoints/best --input song.mp3 --output output/