Audio Mix Analyzer

Audio Mix Analyzer evaluates and improves audio masters. It analyzes a track's loudness, dynamics, spectral balance, clipping, and stereo image, reports detected mix issues and a quality score, and can optionally generate corrected exports.

Table of contents

• Overview
• Key features
• Repository layout
• Requirements
• Quick start (Docker)
• Local development
• Testing
• Configuration
• Contributing
• License and contact

Overview

This repository contains a two-part application:

• Backend: a FastAPI service that performs audio analysis, scoring, and optional corrective processing.
• Frontend: a Next.js application that provides the user interface for uploading audio, showing analysis results, and downloading corrected exports.

The system is designed for local development and containerized deployment using Docker Compose.

Key features

• Per-genre analysis (loudness, dynamics, spectrum, stereo, clipping)
• Issue detection and scoring (0–100)
• On-demand corrective processing (fix and export)
• Temporary storage of uploads/exports to avoid re-uploading the same file

Repository layout

Top-level layout (important folders):

• backend/ — FastAPI app, analysis engine, scoring, and fixer modules
• frontend/ — Next.js web app and UI components
• tmp_uploads/ — runtime temporary artifacts (ignored by git)

Inside backend/ you will find the analysis and fixer implementations under src/audio_analyzer/ (services, models, api routes and adapters).

Requirements

• Docker and Docker Compose (recommended for an identical environment)
• Python 3.10+ for local backend development
• Node 18+ and npm for local frontend development

Quick start (Docker Compose)

1. Copy and adapt environment templates as needed (example in the repo):

   • Copy .env.example to backend/.env and fill secrets used by the backend.

2. Build and start services:

docker compose up --build

3. After the services start:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000

Notes:

• For production builds of the frontend, ensure NEXT_PUBLIC_API_URL is set to the deployed API host before building the frontend image.

Local development

Backend (development):

1. Create and activate a Python virtual environment.
2. Install dependencies from backend/requirements.txt.
3. Run the FastAPI server from the backend/ folder:

python -m uvicorn main:app --reload

Frontend (development):

1. Change to the frontend/ folder.
2. Install dependencies and start the dev server:

npm install
npm run dev

3. Optionally set the API base URL for local development:

setx NEXT_PUBLIC_API_URL "http://127.0.0.1:8000"

Testing

Backend tests are located under backend/src/audio_analyzer/tests.

Run tests from the backend/ folder using pytest:

python -m pytest src\\audio_analyzer\\tests

Frontend quality checks:

cd frontend
npm run lint
npm run build

Configuration and environment

• backend/.env: backend-specific secrets and runtime configuration. Do not commit secrets to version control.
• NEXT_PUBLIC_API_URL: frontend environment variable that points the browser to the backend API host.

Runtime temporary files are written to backend/tmp_uploads/ (local runs) or tmp_uploads/ when using Docker Compose. These directories are intended for transient files and are excluded from source control.

Contributing

Contributions are welcome. For code changes:

1. Open an issue describing the change or bug.
2. Create a feature branch and submit a pull request with tests and concise description.

Coding standards and guidelines:

• Keep functions and modules small and focused.
• Add or update tests for new behavior or bug fixes.
• Run the backend test suite and frontend linters before opening a PR.

Contact

For questions or to report issues, open an issue on the repository.

---

If you want, I can also:

• run the backend tests and fix any simple issues found
• add a minimal CONTRIBUTING.md and LICENSE
• adapt the README to include API route documentation examples

Tell me which follow-up you prefer.