Serato Integration

Serato DJ does not expose a network protocol or a simple database. Instead, it spreads library state across several files and embeds rich metadata inside the audio files themselves. Now Playing’s serato-connect package reads all of these locations to detect the current track and extract cue, beatgrid, and crate information.

What It Reads

The connector watches the _Serato_ folder in the user’s music directory (~/Music/_Serato_ on macOS, the equivalent under the user’s Music folder on Windows). Inside, it monitors:

• Session history files — one file per Serato session, updated as you play. Used to detect which track is currently playing and on which deck.
• Database V2 — the Serato library in a proprietary binary format, containing track locations and metadata.
• Crate files — .crate files defining each Serato crate, with track references.
• Embedded GEOB frames — ID3 binary payloads inside the audio files themselves, containing Serato-specific data like cue points, beatgrids, and flips.

Detecting the Current Track

Session history files are polled on an mtime-based interval. When Serato writes a new row to the session log, the file’s mtime advances and Now Playing reads the new entry. The session format includes the deck number, so multi-deck play is detected without extra work.

GEOB Frame Parsing

Serato stores non-standard data inside audio files by packing it into ID3 GEOB (General Encapsulated Object) frames. Each GEOB frame has a type identifier, and serato-connect decodes the Serato-specific types:

• Cue points and loops — with positions, colours (using Serato’s Serato32 colour encoding), and labels.
• Beatgrid — beatgrid markers including any mid-track tempo changes.
• Flips — Serato’s recorded cue-juggling sequences.
• BPM lock — whether the track’s BPM is explicitly locked.
• Overall track colour — the per-track colour assigned in the library.

For FLAC and Ogg Vorbis files, Serato stores the same data as base64-encoded Vorbis comments with linebreaks. The connector normalises both encodings transparently.

Supported Audio Formats

• MP3 (ID3v2 GEOB frames)
• AIFF (ID3v2 GEOB frames)
• FLAC (Vorbis comments with base64 payload)
• Ogg Vorbis (Vorbis comments)
• M4A / MP4 (iTunes user atoms)

What Data Is Emitted

Field	Source
Title, artist, album	Database V2 or audio file tags
BPM	Database V2 or beatgrid data
Key	Database V2
Deck number	Session history log
Cue points / loops	GEOB frames
Flip recordings	GEOB frames
Crate memberships	.crate files

What It Does Not Provide

serato-connect does not read live controller state. Serato-branded controllers report state through MIDI the same as any other controller, so fader and EQ data flow through the MIDI Bridge and feed the mix processor.