Audio Metadata Extraction

Now Playing’s metadata-connect package reads the metadata embedded inside audio files. It is a shared library used by every local-file DJ integration (Rekordbox, Serato, djay, VirtualDJ) and by the PRO DJ LINK artwork extractor. Its design lets Now Playing pull title, artist, and artwork from an audio file without downloading the full file — important when the file lives on a CDJ’s USB drive reached over NFS.

What It Reads

Metadata is stored differently in each audio format:

Format	Container	Metadata Encoding
MP3	—	ID3v2.2, v2.3, v2.4 frames
M4A / MP4 / AAC	ISO BMFF (mp4)	iTunes atoms
FLAC	Flac native	Vorbis comments
AIFF	AIFF chunks	ID3v2 chunks
Ogg Vorbis	OGG	Vorbis comments

The package understands all of these and returns a normalised result regardless of the underlying encoding.

What Fields Are Extracted

Field	Notes
Title	String
Artist	String
Album	String
Genre	String
Year	Number or ISO date
BPM	Number
Musical key	String (where tagged)
Artwork	Image bytes (JPEG, PNG, or GIF) with MIME type

Partial Reads via a Pluggable Reader

The package is built around a FileReader abstraction. A reader is a small object that knows how to fetch a byte range from somewhere. Several reader implementations exist:

• Local file reader — fs.read with an offset and length.
• HTTP range reader — ranged GET requests with Range: bytes=….
• NFS partial reader — read a byte range from a remote NFS export, used by the PRO DJ LINK artwork path for CDJs.
• Custom readers — any caller can supply a reader for unusual sources.

By requesting only the first few kilobytes of an audio file, the metadata extractor can obtain title, artist, and even artwork without transferring the entire track. For a full CDJ USB library, this turns a 10 MB per-track fetch into a 100 KB one.

Why Pure TypeScript

The package has zero runtime dependencies and is implemented entirely in TypeScript. That choice matters for two reasons:

• Works in Electron’s renderer and main processes — no native modules means no platform-specific rebuild headaches.
• Works in the cloud services — the server-side enrichment path uses the same library for files delivered over the file-upload endpoint.

Relationship to Other Integrations

metadata-connect is used under other integrations, not alongside them:

• rekordbox-connect uses it to read embedded artwork from tracks found in the Rekordbox database.
• serato-connect uses it to parse ID3 tags in tracks, then layers GEOB frame decoding on top.
• djay-connect uses it to read artwork referenced by djay’s MediaLibrary.db.
• alphatheta-connect uses it (with an NFS reader) to read artwork from CDJ USB drives without downloading the whole track.

The result is that artwork extraction is consistent and deduplicated across every source.