Backend portfolio project

Mastering reference analysis for a single track.

Upload an audio file and the API hands it to a worker for loudness, true-peak and frequency-band analysis. The browser submits the file, gets a private token, and streams the report back over a WebSocket.

Loudness path — K-weighting and gated integrated LUFS measurement.

True peak — oversampled dBTP check against a common delivery ceiling.

Reference spectrum — six-band tonal balance compared with a typical genre range.

FastAPI Celery Redis MongoDB C++ DSP

Analyze a track Most audio formats · max 100 MB

↑

Drop an audio file here, or browse

Most audio formats · stereo · max 100 MB

Stereo audio only. Mono and multichannel support is coming later.

Max length ~6 min, max size 100 MB. Files normalize to 48 kHz/24-bit/stereo, so decoded size stays bounded.

Choose genre reference

Report preview

A small, data-first result page.

Band energy, typical range, LUFS, dBTP and a rule-based verdict summary from the stored result.

Preview track Pop reference

hover a band to inspect

Loudness

—

LUFS integrated

—

dBTP true peak

−14 LUFS target your track

Measure 1 · Delivery

Loudness and peak check

Integrated loudness and true peak are shown against common delivery references, without pretending to master the track automatically.

Measure 2 · Balance

Reference-band comparison

Six broad spectrum bands are compared with a typical genre range so low-end, midrange or air-band outliers are easy to spot.

Preview data. Baselines are orientation profiles, not mastering advice.

Pipeline

An async pipeline that deduplicates repeated uploads.

The browser uploads a file and gets a token back. FastAPI hashes the bytes, opens a report for that request, and pushes the work to a Celery worker. While the analysis is in flight or cached, repeated uploads share the same measurements, copied into each report.

Loudness uses the BS.1770 / EBU R128 model in a small C++ core; the band spectrum and true peak run in NumPy/SciPy. Redis is both the broker and the live-status bus, MongoDB holds two short-lived collections, and Docker Compose wires it up locally.

BrowserCLIENT

Uploads the file and genre, gets back a private token, and opens a WebSocket for live status. If the socket drops it falls back to HTTP polling.

POST /analyze · audio + genre

FastAPIAPI GATEWAY

Runs the guard chain, hashes the file, stores the bytes and creates a report row for this request. The token comes back before analysis runs, so the request never blocks.

API keyrate limitsizebacklog

One analysis per content hash. A duplicate upload attaches to the in-flight or cached analysis instead of recomputing.

enqueue analysis · fencing attempt

RedisBROKER · LIMITS · PUB/SUB

The same Redis is used three ways: as Celery's broker, as the sliding-window rate-limit counter, and as a pub/sub channel per token that the WebSocket reads from.

job brokerrate-limit storestatus pub/sub

deliver task

Celery workerSTATELESS WORKER

Checks the attempt token so stale tasks are dropped, converts the audio to 48 kHz / 24-bit stereo, runs the DSP, and writes the result into every report waiting on that file. It keeps no state, so throughput scales with the worker count.

└

DSP coreNATIVE + NUMERIC

C++ (via pybind11) does the K-weighting filters and gated integrated LUFS. The six-band spectrum and 4× oversampled true peak run in NumPy / SciPy.

write measurements · fan-out to every reportsource audio deleted here

MongoDBTWO COLLECTIONS

The per-file analysis is kept separate from the per-request result, so one analysis can back many uploads. Both expire on a TTL index.

analyses · per file

Claim lock and measurements, keyed by the content hash.

results · per request

One row per upload: token, genre and verdict. Expires after 15 min.

live push over WebSocket · GET /result/{token} fallback

Report pageDELIVERY

When the worker finishes, the done event comes back over the WebSocket and the browser draws the band chart, loudness meter and verdict. The link expires by itself.

The stack

API & web

FastAPIUvicornPydantic v2WebSocket

Async pipeline

CeleryRedis brokerRedis pub/subfencing tokens

DSP core

C++ / pybind11NumPySciPyffmpegsoundfile

Data

MongoDB · 2 collectionsTTL indexesobject store · local/S3boto3

Guards

API key authRate limitingBacklog capsUpload + audio bounds

Quality & infra

pytestfakeredishttpxstructlogDocker ComposeGitHub Actions

Edge & deploy

nginx reverse proxyTLS · Let's Encryptedge rate limitingAWS EC2 · S3CI/CD · OIDC + SSM

Code paths worth checking

APIEndpoints, token flow and the live WebSocket WorkerDSP path, fan-out and file cleanup Dedup storeTwo-collection split, claim and fencing DSP coreK-weighting and integrated LUFS in C++