DEADCA7 Open Music Database Specification

DEADCA7 Open Music Database Specification

• By Noah Zoschke • 10 min read
deadca7databasesqlitemusic-libraryspecification

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

Audio tags can hold metadata such as title, artist, and BPM. A DJ library also
needs structured beat grids, cues, phrases, waveforms, playlists, and records
of where each track came from. DEADCA7 brings those relationships together in
one inspectable database format.

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

Version

The current schema version is 1, recorded in SQLite PRAGMA user_version. Future
stable changes will use forward migrations.

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.

For example, under the default ~/Music/DEADCA7 application home:

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.
Audio bytes stay in separate files. A standalone track sidecar carries that
track’s metadata, complete analysis history, and artwork; it does not carry
the whole library’s playlists or archived source databases. Device exports
are projections and cannot preserve every provider-specific field.

Schema

Catalogs, Tracks, and Playlists

catalogs

Field Description
created_at Catalog creation timestamp.
id Local integer identifier; 0 is reserved for the main row.
kind Catalog kind, such as main, collection, or sidecar.
name Catalog name.
revision Database mutation token, populated only on the main row.
source_audio_path Audio path for a track-local source, when applicable.
source_audio_sha256 Source audio digest, when available.
source_uri Durable source identity used for resync, when applicable.
updated_at Catalog update timestamp.
uuid Unique catalog identifier.

catalog_files

Field Description
catalog_uuid Catalog that owns this source database snapshot.
data Archived source file bytes.
id Local integer file identifier.
imported_at Import timestamp.
kind Source file kind.
path Source file path.
sha256 SHA-256 of the archived bytes.
size_bytes Source file size in bytes.

These rows preserve source databases such as export.pdb, exportExt.pdb,
and exportLibrary.db. A catalog can retain multiple versions of a file;
catalog_uuid, kind, path, and sha256 identify a unique version.

tracks

Field Description
album_id Album row for the track, when known.
artist_id Primary artist row for the track, when known.
artwork_revision Mutation token for accepted artwork changes.
audio_revision Mutation token for accepted audio changes.
bitrate Encoded audio bitrate reported by the source.
color Track color tag.
comment Freeform track comment tag.
composer_id Composer artist row, when known.
content_revision Mutation token for track metadata and dependent content.
date_added Source date the track was added.
disc_number Disc number within a multi-disc release.
duration Track duration in seconds.
file_name Canonical audio file basename.
file_path Canonical audio path, referencing original or managed audio.
file_size Audio file size in bytes.
genre Track genre tag.
isrc Canonical ISRC, when promoted from source metadata.
key Musical key stored as a Camelot value.
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 Canonical track identifier and primary key.
year Release year.

The revision fields are local mutation tokens, not content hashes. Portable
sidecars clear them so a receiving catalog can establish its own revisions.

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.
album Source album name.
album_artist Source album artist name.
artist Source primary artist name.
audio_fingerprint Optional decoded-audio fingerprint captured from the source observation.
audio_sha256 Optional decoded-audio hash captured from the source observation.
bitrate Source audio bitrate.
catalog_uuid Catalog that observed this track.
color Source color tag.
comment Source comment tag.
composer Source composer name.
disc_number Source disc number.
duration Source duration in seconds.
external_ids JSON object of provider identifiers, such as content_id and master_content_id.
file_match_key Five-element JSON array used for file matching, or NULL for incomplete observations.
file_name Source file basename.
file_path Source file path.
file_sha256 Optional container file hash captured from the source observation.
file_size Source file size in bytes.
file_uri Source file URI as observed in the catalog.
genre Source genre tag.
isrc Source-observed ISRC, when available.
key Source musical key normalized to Camelot notation.
mix_name Source mix or version tag.
observed_at Timestamp for when this catalog observation was captured.
original_artist Source original artist name.
play_count Source play count.
provider Import provider that produced this observation.
rating Source rating.
record_label Source record label.
release_date Source release date.
remixer Source remixer name.
sample_depth Source sample depth in bits.
sample_rate Source sample rate in hertz.
tempo Source BPM multiplied by 100.
title Source track title.
track_number Source track number.
track_uuid Canonical track this source observation resolves to.
uuid Stable catalog-track observation identifier.
year Source release year.

Several source observations can point to the same canonical track. Their
original tags, file facts, and provider identifiers remain on catalog_tracks.

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.

Analysis

analyses

Field Description
audio_path Audio path associated with the analysis.
date Analysis timestamp.
id Local integer analysis identifier and primary key.
provider Analysis provider, such as deadca7.
selected 0 or 1; at most one analysis per track can be selected.
track_uuid Canonical track that owns this analysis.
uuid Unique analysis identifier.
version Provider’s analysis version, independent of the database schema version.

Exports prefer the selected analysis, falling back to the latest matching
analysis when none is selected. Original analysis files and generated artifacts
belong in analysis_files; parsed cues, phrases, and waveforms use their own
tables.

beats

Field Description
analysis_id Analysis identifier and primary key: one beat-grid row per analysis.
beats_json JSON array containing the analysis’s beat tuples.

Catalog Tables

  • catalogs: The reserved main row, named collections, and sources such as
    Rekordbox.app, USB exports, and track-local catalogs.
  • catalog_files: Archived source database bytes and file versions.
  • 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: One JSON beat grid per 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.

Goose also maintains goose_db_version. Managed destinations can add
dc_store, dc_files, and dc_pending for file ownership and recovery.
Those operational tables have their own format contract; see the
filesystem specification.

Relationships

flowchart TB table_catalogs["catalogs"] table_catalog_files["catalog_files"] 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 -->|"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_files -->|"catalog_uuid"| table_catalogs 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.track_uuid -> tracks.uuid
  • analysis_files.analysis_id -> analyses.id
  • artwork_files.track_uuid -> tracks.uuid
  • beats.analysis_id -> analyses.id
  • catalog_files.catalog_uuid -> catalogs.uuid
  • 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