Beatix System Documentation

Technical reference for the Beatix catalog domain — the Album, Artist and Track entities, their audio analysis data, and every piece of metadata that describes the music: genres, moods, labels, contributor credits, geography and images.

3
Core Entities
14
Persisted Models
22
Enumerations
1280d
pgvector Embedding

1 Start here

This documentation covers the music catalog of Beatix end to end. The catalog is built around three core entities, each with its own satellite models. Use the cards below (or the sidebar) to jump in.

A

Album

The release container: type, dates, copyright, AI disclosure, label, cover artwork and contributor credits.

R

Artist

People, groups and AI projects: identity, origin, lifespan, verification, aliases, memberships and social links.

T

Track

The publishable recording: editorial metadata, commercial identifiers, DMCA fields and the processing state machine.

F

TrackAudioFeatures

Per-field reference for every acoustic and ML feature extracted from the audio — origin, unit, algorithm and usage.

M

Catalog Metadata

Genres, moods, labels, contributor roles, image variants and the GeoNames-backed places dataset.

∞

Relationships

The full entity-relationship model: cardinality, foreign keys and cascade rules across the whole catalog.

2 The domain at a glance

Every recording in Beatix is a Track. Every Track belongs to exactly one Album (a single is just an album with one track). Both Albums and Tracks credit one or more Artists. Everything else — genres, moods, labels, contributor credits, images, audio features — hangs off these three.

Entity Owns References
Album Tracks, AlbumImages, AlbumContributors Artists (N:N), Moods (N:N), Label, cover image
Artist ArtistAliases, ArtistImages, ArtistSocialLinks, ArtistMemberships Genres (N:N), origin city/state, owner user
Track TrackAudioFeatures, TrackSegments, TrackJobs, TrackContributors Album, Artists (N:N), Genres (N:N), Moods (N:N)

3 Two-phase audio analysis

After a track is uploaded, the audio is analysed in two asynchronous phases, each handled by a separate worker consumer listening to its own RabbitMQ queue.

1

Phase 1 — Acoustic

audio-analyzer · Python · librosa

BPM, key, mode, loudness (LUFS), peaks, Chromaprint fingerprint and a speech/music profile. Runs alongside HLS encoding inside ProcessTrackConsumer.

2

Phase 2 — Enrichment

audio-enricher · Python · Essentia + TensorFlow

Danceability, energy, mood scores, valence/arousal, MTG-Jamendo tags, energy bands and a 1280-d similarity embedding. Runs in EnrichTrackAudioConsumer.

See the Analysis Pipeline page for the full sequence, queues, retries and fail-open strategy.

4 Stack & layout

Component Technology Path
API (entities + endpoints) ASP.NET Core 10 · FastEndpoints · EF Core · PostgreSQL + pgvector apps/api
Worker (RabbitMQ consumers) .NET · MassTransit apps/worker
Acoustic analysis (Phase 1) Python · librosa · pyloudnorm · Chromaprint apps/audio-analyzer
ML enrichment (Phase 2) Python · Essentia · TensorFlow (discogs-effnet) apps/audio-enricher
Listener app Next.js 16 · React 19 apps/web
Creator / management app Next.js · React · packages/ui apps/studio
Desktop app Tauri 2 · React apps/desktop

Domain models live under apps/api/src/Features/<Feature>/Models, their enumerations under .../Enums, and their EF Core mappings under .../Persistence. All entities inherit Id, CreatedAtUtc and UpdatedAtUtc from BaseModel unless noted.

5 Conventions used in these docs

Tags

Fields and values are annotated with coloured tags: phase 1 phase 2 derived heuristic jsonb pgvector

Current status

Some reserved fields are not populated yet (e.g. Track.AcoustIdMatch awaits the AcoustID integration). Such fields are marked pending integration wherever they appear.