Registry & Metadata (meta_registry.json)

The media registry is the single source of truth for every file in the library. Instead of re-probing audio files on every schedule, the scheduler reads the registry's cleaned, normalized metadata.

What a registry entry holds

Field	Meaning
file	Relative or absolute path under MEDIA_ROOT
artist	Cleaned artist name
title	Cleaned track title
category	Which deck the track belongs to
energy	1–5 energy rating used for sequencing
duration	Play length (seconds)
loudness	Measured integrated loudness (LUFS)
fingerprint	AcoustID/Chromaprint fingerprint (duplicate detection)
source	Origin (youtube video ID, category, etc.)
status	staged / ready / quarantined

How metadata gets cleaned

yt-dlp stores the raw YouTube video title in the ID3 TIT2 tag, which is rarely a clean Artist – Title. The pipeline (and the standalone sanitize_registry.js) re-derive clean values by stripping:

• | pipe separators — Amr Diab | Amr Diab – Ya Habibi
• / feature splits — Wegz / Marwan Pablo
• [Official ...] / [Official Music Video] / [Official Audio] brackets
• (Official ...), (Audio), (Lyrics), (...) parentheses
• known channel/label suffixes

A LABEL regex filters out content that is actually a label/marketing channel rather than a song, preventing fake "artist" entries.

Rebuilding the registry

Two tools rebuild or sanitize the registry:

scripts/sanitize_registry.js

Re-derives clean {artist, title} from the embedded TIT2 for every existing registry entry — a repair pass that fixes historical mess without re-probing files.

scripts/reprobe_registry.js

Rebuilds meta_registry.json from scratch by re-probing every file's ID3 tags with ffprobe (C:/ffmpeg/bin/ffprobe.exe) and applying the same clean logic as the content pipeline. Use this when the registry is corrupted or a schema migration is needed.

See also

• Retag tools — write cleaned metadata back into files.
• Logs & metadata — the as-run log format and analytics.