DEADCA7 Open Music Database Specification

DEADCA7 Open Music Database Specification

• By Noah Zoschke • 6 min read
deadca7databasesqlitemusic-libraryspecification

AlphaTheta (Pioneer), Algoriddim, and Native Instruments lock up DJ music
libraries in proprietary formats like OneLibrary.

Open music libraries like beets and
Subsonic, and track metadata tag
formats like ID3, Vorbis, and MP4, do not natively support DJ metadata like BPM,
beat grids, cues, phrases, and waveforms.

We therefore propose a new open format and specification for managing catalogs
of DJ music.

Version

This specification is currently version 1. Catalog files record the schema
version in SQLite PRAGMA user_version.

Schema versions and evolution are part of the format from day one, so the first
version can stay small while leaving room for future analysis data, sync
metadata, and compatibility improvements.

Engine

Database files use SQLite. SQLite is broadly available,
easy to inspect, and supported by most programming languages and operating
systems.

File Extension and Layout

DEADCA7 uses .cdb catalog database files. A .cdb file can represent a full
music catalog, including tracks and playlists, and track-local metadata and
binary data associated with a single audio file.

A central catalog database can describe an entire music library. A track-local
catalog database can sit next to an audio file and describe that track’s
metadata; analysis, artwork, and waveform data; and original analysis files.

$ find ~/Music/DEADCA7
dbs/main.cdb
tracks/01.mp3
tracks/01.mp3.cdb
tracks/02.flac
tracks/02.flac.cdb

Data can flow up from device-compatible files, track-local catalogs, and source
catalogs into a central catalog during import. It can also flow back down from a
central catalog into track-local catalogs and device-compatible exports.

Schema

Tracks and Playlists

tracks

Field Description
album_id Album row for the track, when known.
artist_id Primary artist row for the track, when known.
bitrate Encoded audio bitrate reported by the source.
color Track color tag.
comment Freeform track comment tag.
composer_id Composer artist row, when known.
date_added Source date the track was added.
disc_number Disc number within a multi-disc release.
duration Track duration in seconds.
file_name Source file basename.
file_path Source file path.
file_size Source file size in bytes.
genre Track genre tag.
id Local integer track identifier.
isrc Canonical ISRC, when promoted from source metadata.
key Musical key stored as a Camelot value.
metadata_match_key Versioned cached metadata key used for duplicate detection.
mix_name Mix, subtitle, or version tag.
original_artist_id Original artist row, when known.
play_count Source play count.
rating Source rating value.
record_label Track record label tag.
release_date Release date tag.
remixer_id Remixer artist row, when known.
sample_depth Audio sample depth in bits.
sample_rate Audio sample rate in hertz.
tempo BPM multiplied by 100.
title Track title.
track_number Track number within the release.
uuid Stable canonical track identifier.
year Release year.

artists

Field Description
id Local integer artist identifier.
name Artist name.

albums

Field Description
artist_id Album artist row, when known.
id Local integer album identifier.
name Album name.

artwork_files

Field Description
data Embedded artwork bytes, when copied into the catalog.
file_index Source artwork slot or stable ordering index for the track.
kind Artwork role, such as small, large, or thumbnail.
mime Artwork MIME type.
path Source artwork file path.
provider Import provider that produced this artwork row.
sha256 SHA-256 hash of the artwork bytes, when available.
track_uuid Canonical track that owns this artwork file.

catalog_tracks

Field Description
added_at Source catalog timestamp for when the track was added.
audio_fingerprint Optional decoded-audio fingerprint captured from the source observation.
audio_sha256 Optional decoded-audio hash captured from the source observation.
catalog_uuid Catalog that observed this track.
external_id Provider-specific source track identifier.
file_sha256 Optional container file hash captured from the source observation.
file_uri Source file URI as observed in the catalog.
isrc Source-observed ISRC, when available.
metadata_match_key Versioned normalized metadata key used to compare source observations.
observed_at Timestamp for when this catalog observation was captured.
provider Import provider that produced this observation.
track_uuid Canonical track this source observation resolves to.
uuid Stable catalog-track observation identifier.

catalog_playlists

Field Description
catalog_uuid Catalog that owns this playlist node.
kind Node type, either folder or playlist.
name Playlist or folder name.
parent_uuid Parent folder in the same catalog, when nested.
position Sort position within the parent folder.
uuid Stable playlist or folder identifier.

catalog_playlist_tracks

Field Description
catalog_track_uuid Observed catalog track included in the playlist.
catalog_uuid Catalog that owns both the playlist and observed track.
playlist_uuid Playlist that contains this entry.
position Sort position inside the playlist.

All Tables

  • catalogs: Source catalogs or catalog files, such as Rekordbox.app, USB
    exports, and track-local catalogs.
  • artists: Normalized artist names referenced by canonical track metadata.
  • albums: Normalized album names and optional album artists referenced by
    canonical track metadata.
  • tracks: Canonical track metadata shared across source catalogs and duplicate
    source rows.
  • artwork_files: Track-owned artwork payloads or file references.
  • analyses: Analysis runs for canonical tracks. The selected row is preferred
    for exports.
  • analysis_files: Source or output files associated with an analysis.
  • beats: Beat grid entries for an analysis.
  • cues: Cue and loop entries for an analysis.
  • phrases: Phrase and structure segments for an analysis.
  • vbr_info: Variable bitrate metadata for an analysis.
  • waveforms: Waveform payloads for an analysis.
  • catalog_tracks: Observed source-catalog tracks or files inside a catalog,
    linked to canonical tracks.
  • catalog_playlists: Playlist and folder tree nodes for one catalog.
  • catalog_playlist_tracks: Ordered playlist entries pointing at observed
    catalog tracks.
  • activities: Planned, applied, and undone catalog workflow operations.
  • activity_changes: Row-level changes recorded for workflow audit and undo.

Relationships

flowchart TB table_catalogs["catalogs"] table_artists["artists"] table_albums["albums"] table_tracks["tracks"] table_artwork_files["artwork_files"] table_analyses["analyses"] table_analysis_files["analysis_files"] table_beats["beats"] table_cues["cues"] table_phrases["phrases"] table_vbr_info["vbr_info"] table_waveforms["waveforms"] table_catalog_tracks["catalog_tracks"] table_catalog_playlists["catalog_playlists"] table_catalog_playlist_tracks["catalog_playlist_tracks"] table_activities["activities"] table_activity_changes["activity_changes"] table_activity_changes -->|"activity_uuid"| table_activities table_albums -->|"artist_id"| table_artists table_analyses -->|"source_catalog_uuid"| table_catalogs table_analyses -->|"track_uuid"| table_tracks table_analysis_files -->|"analysis_id"| table_analyses table_artwork_files -->|"track_uuid"| table_tracks table_beats -->|"analysis_id"| table_analyses table_catalog_playlist_tracks -->|"catalog_uuid, playlist_uuid"| table_catalog_playlists table_catalog_playlist_tracks -->|"catalog_uuid, catalog_track_uuid"| table_catalog_tracks table_catalog_playlists -->|"catalog_uuid, parent_uuid"| table_catalog_playlists table_catalog_playlists -->|"catalog_uuid"| table_catalogs table_catalog_tracks -->|"catalog_uuid"| table_catalogs table_catalog_tracks -->|"track_uuid"| table_tracks table_cues -->|"analysis_id"| table_analyses table_phrases -->|"analysis_id"| table_analyses table_tracks -->|"album_id"| table_albums table_tracks -->|"artist_id; composer_id; original_artist_id; remixer_id"| table_artists table_vbr_info -->|"analysis_id"| table_analyses table_waveforms -->|"analysis_id"| table_analyses
  • activity_changes.activity_uuid -> activities.uuid
  • albums.artist_id -> artists.id
  • analyses.source_catalog_uuid -> catalogs.uuid
  • analyses.track_uuid -> tracks.uuid
  • analysis_files.analysis_id -> analyses.id
  • artwork_files.track_uuid -> tracks.uuid
  • beats.analysis_id -> analyses.id
  • catalog_playlist_tracks.catalog_uuid, catalog_track_uuid ->
    catalog_tracks.catalog_uuid, uuid
  • catalog_playlist_tracks.catalog_uuid, playlist_uuid ->
    catalog_playlists.catalog_uuid, uuid
  • catalog_playlists.catalog_uuid -> catalogs.uuid
  • catalog_playlists.catalog_uuid, parent_uuid ->
    catalog_playlists.catalog_uuid, uuid
  • catalog_tracks.catalog_uuid -> catalogs.uuid
  • catalog_tracks.track_uuid -> tracks.uuid
  • cues.analysis_id -> analyses.id
  • phrases.analysis_id -> analyses.id
  • tracks.album_id -> albums.id
  • tracks.artist_id -> artists.id
  • tracks.composer_id -> artists.id
  • tracks.original_artist_id -> artists.id
  • tracks.remixer_id -> artists.id
  • vbr_info.analysis_id -> analyses.id
  • waveforms.analysis_id -> analyses.id