Skip to content

Latest commit

 

History

History
1862 lines (1458 loc) · 81.7 KB

Application Internals.md

File metadata and controls

1862 lines (1458 loc) · 81.7 KB

Application Internals

Low-level reference for VirtualDJ's macOS application layout, user data, database files, stem sidecars, and practical open-source tooling.

Last reviewed against local files and live VirtualDJ sources on 2026-05-23 (Asia/Manila). Remote skin deployment and selector behavior updated from local testing on 2026-05-24 (Asia/Manila). External-prep cue workflow added from current official sources and local database context on 2026-05-27 (Asia/Manila).

Scope

This is an operational reference. It is meant to answer questions like:

  • Where does VirtualDJ keep preferences, databases, skins, pads, mappers, and caches?
  • What does database.xml look like?
  • What is in extra.db?
  • How are prepared stem files shaped on disk?
  • Which parts can be edited safely with command-line tools?
  • Which parts are still unknown or only locally inferred?

Source labels used below:

  • Official: current VirtualDJ manual or VDJPedia.
  • Official forum: post by VirtualDJ staff, Development Manager, CTO, or Support staff.
  • External: non-VirtualDJ technical standard or tooling reference.
  • Local observation: verified on this machine.
  • Inference: conclusion drawn from local files, official docs, or repeatable CLI inspection.
  • Unknown: documented explicitly as not yet understood.

Quick Map

macOS paths to know first:

Path Purpose Source
/Applications/VirtualDJ.app Signed application bundle. Treat as read-only. Local observation
/Applications/VirtualDJ.app/Contents/Resources Bundled default skins, pad XML pages, sample banks, icons, controller metadata, and language archives. Local observation
/Applications/VirtualDJ.app/Contents/Frameworks/ml113.dylib Bundled machine-learning runtime library. Local observation
~/Library/Application Support/VirtualDJ Active VirtualDJ home folder on this macOS install. Official forum, Local observation
~/Library/Application Support/VirtualDJ/settings.xml Preferences, audio setups, skin state, controller choices, browser settings, sampler settings, etc. Local observation
~/Library/Application Support/VirtualDJ/database.xml Main XML track database for media on the same drive as the home folder. Official forum, Local observation
~/Library/Application Support/VirtualDJ/extra.db SQLite database for related tracks, extra track identity rows, and lyrics cache. Local observation
~/Library/Application Support/VirtualDJ/Cache/cache.db SQLite waveform cache. Local observation
~/Library/Application Support/VirtualDJ/Pads User pad pages. Local observation
~/Library/Application Support/VirtualDJ/Mappers User controller and keyboard mappings. Local observation
~/Library/Application Support/VirtualDJ/Skins Installed user skins. Local observation
~/Library/Application Support/VirtualDJ/RemoteSkins Installed VirtualDJ Remote skins. Official forum, Local observation
~/Library/Application Support/VirtualDJ/VideoSkins Installed video skins. Local observation
~/Library/Application Support/VirtualDJ/Plugins64 Intel/x86_64 plugin files and settings. Local observation
~/Library/Application Support/VirtualDJ/PluginsMacArm Apple Silicon plugin files and settings. Local observation
~/Library/Application Support/VirtualDJ/MyLists VirtualDJ 2024+ XML lists. Official, Local observation
~/Library/Application Support/VirtualDJ/Folders Virtual/favorite/filter folder metadata. Local observation
~/Library/Application Support/VirtualDJ/History Daily history playlists, usually .m3u. Local observation
~/Library/Application Support/VirtualDJ/Sampler Sampler banks, bank order, and .vdjsample files. Local observation
~/Library/Application Support/VirtualDJ/ScratchBanks Scratch bank XML files. Local observation
/Volumes/<Drive>/VirtualDJ/database.xml Local database for media on a different drive from the VirtualDJ home folder. Official forum, Inference

Older answers and some Windows-centric forum posts refer to a VirtualDJ folder under Documents. On this macOS install the active folder is ~/Library/Application Support/VirtualDJ, and a 2024 CTO forum reply points macOS users there for database.xml.

Application Bundle

The app bundle is useful for inspection, but user work should live in the home folder.

Observed local app version:

defaults read /Applications/VirtualDJ.app/Contents/Info.plist CFBundleShortVersionString
defaults read /Applications/VirtualDJ.app/Contents/Info.plist CFBundleVersion

On this machine those commands returned:

8.5.8769
18.0.9295

Useful bundled resources:

find /Applications/VirtualDJ.app/Contents/Resources -maxdepth 1 -type f \
  \( -name '*.xml' -o -name '*.zip' -o -name '*.dat' \) \
  -print | sort

Typical results include:

  • skin.zip
  • pads_stems.xml
  • pads_hotcues.xml
  • pads_sampler.xml
  • controllers.dat
  • default sampler banks such as AUDIO FX.xml, FAMOUS.xml, and INSTRUMENTS.xml

Do not edit these bundled files in place. Put overrides or custom work under the VirtualDJ home folder.

The bundle is platform-neutral, and internal.data is a model archive

Cross-checked the macOS payload of bundle 18.0.9246 against the Windows installer of the same build (8.5.9246.0.exe → MSI → virtualdj.cab → virtualdj.exe, whose .rsrc section holds the same assets as RCDATA resources). Of the 34 shipped data files present on both platforms — every pads_*.xml, skin.zip, remoteskin.zip, controllers.dat, controllers2.dat, transitions.zip, videos.zip, the video skins, lite.xml, AFX_beatgrid.xml — 33 are byte-identical. The exception is languages.zip, where the container bytes differ but all 12 extracted XMLs are byte-identical, English included (811 action descriptions, no platform-only entries and no wording differences). Platform differences are confined to shader format (.cso vs .glsl/.metallib), icon naming (_dpi2x vs @2x), and helper executables.

So a Windows installer is a valid source for any bundled asset, and there is no Windows-only built-in skin, pad page, or sampler bank.

Resources/internal.data (486,064,672 bytes, undocumented and opaque on macOS) turns out to be a plain concatenation of seven Windows resources, IMG0..IMG6 in that order, verified byte-for-byte with a whole-file SHA-256 match:

Segment Offset Length Content
IMG0 0 39,290,900 plaintext float32 weights
IMG1 39290900 39,290,900 plaintext float32 weights
IMG2 78581800 39,290,900 plaintext float32 weights
IMG3 117872700 39,290,900 plaintext float32 weights
IMG4 157163600 191,508,424 encrypted, magic c9 53 4f af 06 10 df d0
IMG5 348672024 62,068,024 encrypted, same magic
IMG6 410740048 75,324,624 encrypted, same magic

These are the stem-separation / analysis models: Windows pairs them with ml125.dll and DirectML*.dll, macOS with Frameworks/ml113.dylib and the CoreML model3.mlmodelc / model4.mlmodelc trees. Nothing here is script-facing — the value is knowing that the opaque half-gigabyte in the bundle is model weights, with exact segment boundaries if it ever needs probing.

The two halves are not equally opaque:

  • IMG0..IMG3 are in the clear. Each holds exactly 9,822,725 little-endian float32 values with no header (the length divides evenly by 4). Sampled at thirteen offsets spanning each segment, 100% of values land in [-2, 2]; across 20,480 samples per segment the distribution is mean ≈ -0.002, σ ≈ 0.11, max |x| < 1.4, no exact zeros — a trained weight tensor, not a container. Four identically sized blobs suggests one model per stem. Split them with dd if=internal.data of=img$i.f32 bs=4 skip=$((i*9822725)) count=9822725. Beware alignment when sampling: seek to a multiple of 4 or the floats decode as garbage.
  • IMG4..IMG6 are encrypted. Entropy 7.997-7.998 bits/byte, an identical 8-byte header on all three followed by noise, and zero recoverable ASCII in the first megabyte. ml113.dylib is ONNX Runtime (full ONNX opset diagnostics, 9,455 onnxruntime string hits), and plaintext ONNX is protobuf that would leak node and type names immediately — so these are presumably ONNX behind a cipher whose routine lives in the binary.
  • The CoreML pair is encrypted by Apple. model3.mlmodelc / model4.mlmodelc carry the LMNE magic on metadata.json and model.mil plus a populated encryptionInfo/coremldata.bin — CoreML model encryption, with the key unwrapped by the OS at load. The on-disk files are inert without a live process.

Practical upshot for anyone tempted to reuse them: the legible weights ship without an architecture (no graph, shapes, layer names, or normalization constants — those would have to come out of the inference code), and everything that carries its own architecture is encrypted. Note also that these are Atomix's proprietary weights; local inspection is one thing, redistribution is a licensing question.

Skin Deployment

VirtualDJ interface packages are user data. Keep custom and installed skins under the VirtualDJ home folder, not inside the signed application bundle.

Observed deployment folders on this macOS install:

Package type Folder Observed package forms Notes
Desktop skin ~/Library/Application Support/VirtualDJ/Skins .zip packages and uncompressed folders Official extension installs can be done from Settings -> Extensions. Local development can use an uncompressed folder for faster edit/test cycles.
Remote skin ~/Library/Application Support/VirtualDJ/RemoteSkins .zip packages and uncompressed folders Staff forum guidance says to place the skin as a zip file inside RemoteSkins; uncompressed folders were also observed locally.
Video skin ~/Library/Application Support/VirtualDJ/VideoSkins Not mapped yet Folder observed locally; package details still need a focused pass.

The app bundle also contains default packages that are useful for inspection:

ls -1 /Applications/VirtualDJ.app/Contents/Resources/*skin*.zip

Typical bundled packages include:

  • skin.zip
  • remoteskin.zip
  • videoskinbroadcast.zip
  • videoskinkaraoke.zip
  • videoskinlive.zip

Treat those as read-only references. Copy them out before inspecting or modifying:

work="$HOME/Desktop/vdj-skin-inspect"
mkdir -p "$work"
cp /Applications/VirtualDJ.app/Contents/Resources/remoteskin.zip "$work/"
(cd "$work" && unzip remoteskin.zip -d remoteskin)

Desktop Skins

For normal desktop skins, this repo prefers a source/build split:

  • keep editable source under the repo, often split into modules
  • flatten includes at build time
  • install only the flat skin.xml plus required image/assets

Example install shape:

VDJ_HOME="$HOME/Library/Application Support/VirtualDJ"
skin_name="ModularSkeleton"

xmllint --xinclude --output build/skin.xml src/skin.xml
mkdir -p "$VDJ_HOME/Skins/$skin_name"
rsync -a --delete build/ "$VDJ_HOME/Skins/$skin_name/"

Zip-package variant:

VDJ_HOME="$HOME/Library/Application Support/VirtualDJ"
skin_name="My Skin"

(cd build && zip -r "../$skin_name.zip" .)
cp "$skin_name.zip" "$VDJ_HOME/Skins/"

After installation, select the skin from Settings -> Interface. Official add-on installs use Settings -> Extensions, then the relevant software section; for skins, that is the Interface tab.

Development tip: when a skin variable controls structural XML such as conditional layout branches, conditional <breaklines>, conditional defines, or <nbdecks> choices, pair the state change with load_skin so VirtualDJ reparses the skin. For simple live visibility="" changes, a reload is usually unnecessary.

Source: Official, Official forum, Community, Local test, Inference

Remote Skins

VirtualDJ Remote is the iOS/Android companion app. Official product text describes the Remote as skinnable and using the same skin format as VirtualDJ. Staff forum notes add the practical caveats:

Transport (Local test, 2026-07-27, live iOS Remote session observed from the desktop side): the device advertises Bonjour service type _vdjremote8._tcp (SRV record pointing at the device, port 4243 observed). VirtualDJ browses for it and connects out to the device — the desktop is the TCP client, the device is the server — over one persistent TCP connection. State updates are event-driven push, not polling: idle seconds carried 0 bytes in either direction, and a deck load pushed ~249 KiB desktop→device in one second with no inbound request (track metadata/waveform-scale payload). The Network Control HTTP channel (port 80) is not involved. The wire format (framing, handshake, message schema) is uncharacterized — see TODO task 8 for the phone-side shim plan.

  • There is no separate hidden Remote skin SDK.
  • The default Remote skin and forum examples are the main references.
  • Remote skins share the same general structure and elements as desktop skins.
  • Desktop skins usually cannot be dropped in unchanged; expect to recode the layout and device-specific behavior.
  • Remote 8 can load v7 Remote skins, but older skins may need updates for the Remote browser.
  • Older/forum examples may use action="browser" to open the Remote browser.
  • The bundled Remote 8 skins under Skins/Built-In/Remote/ mostly implement the browser as an in-skin view: toggle '$rmbrowser' switches full-screen deck/browser panels, while wide phone layouts use skin_panel 'rmbrowser' on inside a panel group.
  • Remote skins are scaled proportionally to the device screen, with side bars as needed.
  • Avoid video preview windows in Remote skins.
  • Staff guidance says to place custom Remote skins as zip files inside RemoteSkins.
  • Locally installed Remote skins are selected from Settings -> Interface -> Phone/tablet remote. Settings -> Extensions is the online add-on catalog and does not list every local Remote skin folder/zip.

Remote skin packages can contain multiple XML variants for different device classes, aspect ratios, and orientations. This is not just a third-party habit: the bundled VirtualDJ Remote skin package in /Applications/VirtualDJ.app/Contents/Resources/remoteskin.zip contains root-level files such as:

16x10T.xml
16x9P.xml
16x9T.xml
19x9P.xml
3x4T.xml
4x3T.xml
9x16P.xml
9x16T.xml
9x19P.xml

The XML roots identify the intended layout, for example:

<skin name="Remote Landscape (Phone 16:9)" version="8" width="1920" height="1080" nbdecks="2" image="tablet.png" preview="landscape.png">
<skin name="Remote Portrait (Tablet 9:16)" version="8" width="830" height="1476" nbdecks="2" image="tablet.png" preview="portrait.png">

Observed naming convention:

  • P means phone-targeted layout.
  • T means tablet-targeted layout.
  • The numeric part names the target aspect/orientation class, not necessarily a literal canvas size.
  • Older Remote 8 Default packages used names such as skinP169.xml, skinP32.xml, skinT1610.xml, and skinT43.xml.

This suggests two valid packaging styles:

  • A simple package with one skin.xml, letting Remote scale it proportionally and add black bars if needed.
  • A multi-variant package with several root-level XML layouts and shared assets, letting VirtualDJ/Remote choose or expose the better layout for the connected device class.

Some downloaded Remote add-ons also act as containers for multiple nested Remote-skin zips. In that case, extract the inner zip files into RemoteSkins before selecting them in VirtualDJ.

Bundled Remote browser/settings view patterns worth reusing:

<button action="toggle '$rmbrowser'"/>
<panel name="rmdecksview" visibility="var '$rmbrowser' 0"/>
<panel name="rmbrowserview" visibility="var '$rmbrowser' 1" breakline1="90" breakline2="1476-20"/>

<oninit action="set '$rmsettings' 0"/>
<button action="toggle '$rmsettings'"/>
<panel name="rmsettingsview" visibility="var '$rmsettings' 1"/>

For wide phone variants, the bundled files instead put browser in the same manual panel group as deck/mixer views and add pane-focus buttons:

<button action="skin_panel 'rmbrowser' on"/>
<button action="browser_window 'folders'"/>
<button action="browser_window 'songs'"/>
<panel name="rmbrowser" group="rmporpanels" visible="no"/>

Source: Built-in skin

For local development, this machine successfully used both installed forms at once: an expanded folder at RemoteSkins/<Remote Name>/ for fast inspection and a sibling RemoteSkins/<Remote Name>.zip for the staff-recommended package form. A compatibility-oriented package can include root-level files such as skin.xml/skin.png plus tablet aliases such as skinT1610.xml, 16x10T.xml, and 4x3T.xml. Some locally observed tooling also creates a wrapped top-level folder in the zip, so checking unzip -l matters before assuming one package shape.

Basic Remote skin deployment:

VDJ_HOME="$HOME/Library/Application Support/VirtualDJ"
remote_name="My Remote Skin"

xmllint --noout build/skin.xml
(cd build && zip -r "../$remote_name.zip" .)
mkdir -p "$VDJ_HOME/RemoteSkins"
cp "$remote_name.zip" "$VDJ_HOME/RemoteSkins/"
mkdir -p "$VDJ_HOME/RemoteSkins/$remote_name"
rsync -a --delete build/ "$VDJ_HOME/RemoteSkins/$remote_name/"

Connection setup is separate from skin deployment. The official manual flow is:

  1. Put the mobile device on the same Wi-Fi network as the VirtualDJ computer.
  2. Open the VirtualDJ Remote app.
  3. In VirtualDJ, open Settings -> Controllers -> Phone/Tablet.
  4. Select and connect/authorize the Remote device.

Source: Official, Official forum, Local observation, Inference

Deployment Checks

Before trying a new skin in VirtualDJ:

xmllint --noout build/skin.xml
find build -maxdepth 1 -type f -print | sort

For zip packages, verify that the XML and assets are at the package root expected by the skin:

unzip -l "My Skin.zip" | sed -n '1,80p'

Common failure points:

  • installing source modules instead of the flattened build output
  • putting a Remote skin under Skins or a desktop skin under RemoteSkins
  • looking under Settings -> Extensions instead of Settings -> Interface -> Phone/tablet remote for local Remote skins
  • missing image files referenced by the XML
  • zipping a parent folder when the skin expects files at the zip root
  • packaging only one Remote layout when the target devices need different phone/tablet, portrait/landscape, or aspect-ratio layouts
  • relying on desktop-only features such as video previews in Remote skins

Home Folder Rules

VirtualDJ has a "home" folder that contains the master database and most user configuration. Staff forum guidance describes this model:

  • Files on the same drive as the home folder use the master database in the home folder.
  • Files on other drives can use a local database in a VirtualDJ folder at that drive's root.
  • Moving the home folder changes which files land in the master database versus a local drive database.

macOS default to check:

VDJ_HOME="$HOME/Library/Application Support/VirtualDJ"
ls -la "$VDJ_HOME"

External drive database check:

find /Volumes -maxdepth 3 -path '*/VirtualDJ/database.xml' -print 2>/dev/null

Safe Editing Rules

Use these rules before touching live data:

  1. Quit VirtualDJ.
  2. Back up the file you will edit.
  3. Validate XML before and after an XML edit.
  4. For SQLite, expect write-ahead log files such as extra.db-wal and cache.db-wal.
  5. Prefer VirtualDJ's own UI for destructive operations, re-analysis, and database repair.
  6. Treat Cache/, license.dat, binary .dat, .mlmodelc, .vdjsample, and unknown binary files as read-only until their format is understood.

Quick backup and XML validation:

#!/usr/bin/env zsh
set -euo pipefail

VDJ_HOME="${VDJ_HOME:-$HOME/Library/Application Support/VirtualDJ}"
stamp="$(date +%Y%m%d-%H%M%S)"

cp -p "$VDJ_HOME/database.xml" "$VDJ_HOME/database.xml.$stamp.bak"
xmllint --noout "$VDJ_HOME/database.xml"

print "backup: $VDJ_HOME/database.xml.$stamp.bak"
print "database.xml is well-formed"

Options and the setting verb

The ~250 configuration options in the official options list are the same keys that appear in settings.xml, and the wiki's own examples address them from script with the setting verb, using the option name as the first argument:

setting "fxProcessing" "Post-fader" ? on & setting "fxProcessing" : off & setting "fxProcessing"

Named options carry their allowed values in the option's own description — globalQuantize takes 1 for beats, 4 for measures, 0.25 for quarters; pitchQuality takes 1-4 fastest to best; autoBPMMatch takes smart among others. The binary's settings-string cluster carries the same enum documentation inline, so option values can be recovered offline as well.

Official (options list appendix), Official wiki (the setting example), both fetched 2026-09-03. Not yet locally probed — the setting verb writes persistent configuration, so it sits outside the current execute-probe allowlist by design.

settings.xml

settings.xml is a single XML document rooted at <settings>.

Observed top-level sections include:

  • audioConfig
  • automation
  • controls
  • skins
  • audio
  • controllers
  • sampler
  • browser
  • options

The file stores both durable settings and UI state. Examples observed locally:

  • audio setups under <audioConfig>
  • current skin under <skins><skin>
  • skin panel and split states under <skinPanels> and <skinSplitState>
  • controller to mapper choices under <controllers><controllersCustomization> — see below
  • browser columns and shortcuts under <browser>
  • last database backup timestamp under <options><databaseBackupLast>

controllersCustomization: which mapper a controller uses

The Controllers pane's Mapping dropdown is not GUI-only state. It writes one row per device into <controllers><controllersCustomization>:

<controllersCustomization>
  <controller name="DDJGRV6" mapper="AlphaTheta DDJ-GRV6 - DeathDisco DDJ-GRV6 v1" />
  <controller name="SIMPLE_MIDI_0_0" mapper="SIMPLE_MIDI_0_0 - custom mapping" deck="left" />
</controllersCustomization>

name is the device id from the device definition, mapper is the mapper file's basename without .xml, and the optional deck / midiclockoutput attributes carry the rest of that pane's per-device settings. So a controller's mapping can be set from disk instead of through the pane — which matters because VirtualDJ's own window exposes no accessibility elements at all (System Events reports zero UI elements for it), so every GUI route degrades to blind coordinate clicking. Prefer the file.

Two cautions learned the hard way:

  • The file is rewritten on quit, so an edit made while VirtualDJ is running is discarded. Quit, edit, relaunch.
  • Entries are appended, not replaced. A device that reconnects under a new auto-created mapping accumulates duplicate <controller> rows with the same name — three for one device id here, each naming a different mapper. When duplicates exist the pane does not reliably honour a mapping chosen in the dropdown, so deduplicate to a single row rather than selecting again.

Inspect setting names without dumping personal values:

xmlstarlet sel -t -m '/settings/*' -v 'name()' -n \
  "$HOME/Library/Application Support/VirtualDJ/settings.xml"

That XPath is intentionally minimal. For a practical overview, this is usually easier:

rg -n '<[A-Za-z][A-Za-z0-9_]*' \
  "$HOME/Library/Application Support/VirtualDJ/settings.xml" |
  sed -E 's/^([0-9]+:)[[:space:]]*<([^ >]+).*/\1 \2/' |
  head -120

database.xml

database.xml is the main track metadata database. It is XML:

<?xml version="1.0" encoding="UTF-8"?>
<VirtualDJ_Database Version="8.5">
  <Song FilePath="/Music/Tracks/example.flac" FileSize="12345678" Flag="33554432">
    <Tags Author="Artist" Title="Title" Remix="Extended Mix" Stars="5" Key="Cm" Bpm="0.468750"/>
    <Infos SongLength="240.000000" FirstSeen="1767225600" PlayCount="0" Bitrate="1411.2" Cover="1"/>
    <Comment>#tag #another-tag</Comment>
    <Scan Version="801" Bpm="0.468750" Volume="1.250000" Key="Cm"/>
    <Poi Pos="0.000000" Type="beatgrid" Bpm="128.000000"/>
    <Poi Type="cue" Pos="32.000000" Name="DROP" Num="1" Color="4278255360"/>
    <Poi Type="loop" Pos="224.000000" Name="OUTRO" Num="2" Size="8" Slot="2" Color="4278190208"/>
  </Song>
</VirtualDJ_Database>

Observed structure on this machine:

VDJ_DB="$HOME/Library/Application Support/VirtualDJ/database.xml"

xmllint --xpath 'name(/*)' "$VDJ_DB"
xmllint --xpath 'string(/*/@Version)' "$VDJ_DB"
xmllint --xpath 'count(/VirtualDJ_Database/Song)' "$VDJ_DB"

rg -o '<[A-Za-z][A-Za-z0-9_:-]*' "$VDJ_DB" |
  sed 's/^<//' |
  sort |
  uniq -c |
  sort -nr

Local counts at time of review:

VirtualDJ_Database
8.5
1566 songs
17529 Poi
1566 Tags
1566 Song
1566 Scan
1566 Infos
1566 Comment
2 LockedCues

Song

<Song> identifies one database item.

Common attributes:

  • FilePath: absolute path, URL-like source path, or other VirtualDJ source path.
  • FileSize: size in bytes when known.
  • Flag: bit field. Some values are discussed in forums, but the complete current map is not maintained here yet.

Do not use FilePath alone as a stable identity. VirtualDJ also uses file size and internal identifiers elsewhere.

Tags

<Tags> contains user-facing metadata:

  • Author
  • Title
  • Genre
  • Album
  • Label
  • Remix
  • Remixer
  • TrackNumber
  • Grouping
  • Year
  • Stars
  • User1, User2, etc.
  • Key
  • Bpm
  • Flag

Key notation is not fixed. On one install (Local observation, 2026-09-26, build 18.0.9644) the home database.xml held 1,681 <Song> entries; the Key attribute was musical notation (Fm, Em, F#m, …) on all but 40, which carried Camelot codes (8A). Presumably the key-notation setting in force when each track was analysed. A reader that colours or compares keys must accept both and convert; Key is also absent on unanalysed songs.

Important BPM detail:

  • Tags/@Bpm and Scan/@Bpm are observed as beat duration in seconds.
  • Display BPM can be derived as 60 / value.
  • Poi[@Type="beatgrid"]/@Bpm is observed as display BPM.

Example:

awk 'BEGIN { stored = 0.468750; printf "%.3f BPM\n", 60 / stored }'

Infos

<Infos> stores analysis and library state:

  • SongLength: seconds.
  • FirstSeen: Unix timestamp.
  • LastModified: Unix timestamp when present.
  • PlayCount
  • LastPlay
  • Bitrate
  • UserColor: decimal color value.
  • Cover: cover-art state.

Convert a timestamp:

date -r 1767225600 '+%Y-%m-%d %H:%M:%S %Z'

Scan

<Scan> stores analysis output. A steady track, as written by build 18.0.9644 (Version="801"), observed 2026-10-14:

<Scan Version="801" Bpm="0.444444" Phase="28.444876" AltBpm="0.333333" Volume="1.718810" Key="G"
      AudioSig="iXWot7ZzqKiI867Wd_Ag0_kF" Flag="32768" />
  • Bpm is the beat period in seconds, not a BPM: 0.444444 s is 135 BPM (60 / Bpm). Tags/@Bpm repeats it. AltBpm is the alternative period (3/4 of it here).

  • Phase is the time in seconds of one beat, from which the constant grid is laid; on the tracks checked it sat on the first downbeat the analysis chose (bar 1), 28.44 s into a track that starts on a beat at 0.

  • Key is a plain note name (G, C#). AudioSig is an audio fingerprint. Flag is an unknown bit field unless a specific value has been verified.

  • A track whose tempo varies carries two more attributes: Rigid (the period a constant grid would have) and BeatGrid, a string of segments:

    BeatGrid="9482[0.061467:117,0.46878][54.9:7,0.46863][58.18:3][59.56:1][60.065:92][103.2:1,0.48963]…[139.5:7,0.46874,1/4]…[178.67:0,0.457085]"
    

    Each [start:beats,period] is a run of equal beats from start seconds; period is omitted when unchanged; an occasional third field such as 1/4 appears. The leading number and the third field are not understood. On the local database (3,341 songs, 2026-10-14) 181 of 2,180 scanned songs had one, the longest about 5 KB. In Poi, the older Type="beatgrid" form stores a BPM, not a period.

Source: Local observation (build 18.0.9644, ~/Library/Application Support/VirtualDJ/database.xml)

Comment

<Comment> contains the browser comment field. It may be empty:

<Comment/>

or contain text:

<Comment>#minimal #loud</Comment>

Poi

<Poi> stores points of interest.

Observed Type values:

rg -o 'Type="[^"]+"' "$HOME/Library/Application Support/VirtualDJ/database.xml" |
  sort |
  uniq -c |
  sort -nr

Local counts at time of review:

11253 Type="cue"
2858 Type="automix"
1721 Type="beatgrid"
1199 Type="remix"
498 Type="loop"

Common forms:

<Poi Pos="0.000000" Type="beatgrid" Bpm="128.000000"/>
<Poi Type="cue" Pos="64.000000" Name="BREAK" Num="2" Color="4293375736"/>
<Poi Type="loop" Pos="224.000000" Name="OUTRO" Num="8" Size="16" Slot="8" Color="4278190208"/>
<Poi Pos="0.050000" Type="automix" Point="realStart"/>
<Poi Name="Break 1" Pos="90.000000" Type="remix"/>

Observed interpretation:

  • Pos is seconds, and is omitted when it is 0 (a cue at the very start has no Pos).
  • cue Num is the cue number, 1-based. There is no small limit: a file whose tags carried 255 cues was imported with all 255 Poi rows (build 18.0.9644, 2026-10-14; see Serato tags in FLAC below).
  • loop Size is in beats. Loops imported from file tags are written with Seconds (length) and Slot instead, and Num="-1": <Poi Pos="28.4440" Num="-1" Type="loop" Seconds="42.6670" Slot="3" />.
  • Color is a decimal ARGB-like integer. For example, red is commonly 4294901760, which is 0xFFFF0000.

Convert decimal color to hex:

printf '0x%08X\n' 4294901760

LockedCues

<LockedCues> appears inside some <Song> entries:

<LockedCues>1</LockedCues>

Observed meaning is cue locking state, but the full set of values is not documented here yet.

External Prep And Auto-Hotcue Workflow

This section answers the practical question: "If I prepare tracks outside VirtualDJ, what can VirtualDJ pick up without hand-editing every track in the POI Editor?"

Short answer: VirtualDJ can inherit hotcue data from supported file tags or from its own database.xml cue POIs, but VirtualDJ analysis does not turn musical structure into normal Hot Cues by itself. It creates analysis POIs such as first-beat/beatgrid, automix/mix points, and remix points; user-facing Hot Cues still need to come from user action, imported cue metadata, or database preparation.

Source: Official, Local observation, Inference

What VirtualDJ Can Inherit Automatically

Input What VirtualDJ can use Practical meaning Source
File tags Stored Hotcue/cue information when getCuesFromTags is enabled. Official option text calls this "Get the cues field from the tag"; VDJPedia says VirtualDJ can read stored Hotcue information from ID3 tags, by default for files seen for the first time, or always if the option is changed. A prep tool that writes cue metadata in a format VirtualDJ recognizes can feed VirtualDJ without touching the POI Editor. This is the cleanest path for new files. Official
Existing database.xml entries <Poi Type="cue" Pos="..." Num="..." Name="..." Color="..."/> entries under a matching <Song>. If the VirtualDJ database already contains the cue POIs, the built-in Hot Cues pad page and skins can display/trigger them via hot_cue, cue_display, cue_color, cue_name, and related verbs. Official, Built-in pad page, Built-in skin, Local observation
VirtualDJ analysis Beatgrid/first-beat POIs, Automix/mix POIs, and Remix Points. These can help navigation and the Remix Points pad page, but they are not the same as normal Hot Cues 1-8/16 on controller pads. Official, Local observation
Saved loops in POIs Saved-loop POIs can appear on the HotCue pad page when saved as cue-style loop slots. Useful for prepared loop workflows, but still requires loop POIs with the right slot/size metadata rather than plain analysis markers. Official, Local observation

What Requires External Prep

If the goal is "drop new tracks into a folder and have Hot Cues appear on pads with no manual VirtualDJ work," one of these steps has to happen before performance time:

  • Write recognized cue/hotcue metadata into the media file tags before VirtualDJ first indexes the file, then leave getCuesFromTags at its default "for new files" behavior or set it to always for a tag-authoritative workflow.
  • Use a library-conversion tool, tag editor, or custom script that understands the Serato/Traktor/Rekordbox-style cue metadata you want to feed VirtualDJ. For FLAC, the Serato Vorbis comments are tested below: cues, saved loops and the key import; the beat grid and BPM do not.
  • Generate or update VirtualDJ database.xml cue POIs directly after VirtualDJ has created the <Song> rows. This is the most controllable path for custom auto-cue algorithms, but it is also the path that needs the strict backup/validation rules from this file.

Source: Official, Official forum, Local observation, Inference

Serato tags in FLAC: what VirtualDJ imports

Local test, build 18.0.9644 (macOS, VirtualDJ 2026), 2026-10-14, over the HTTP control interface. Options at the time: getCuesFromTags = always, useKeyFromTag = Yes, getTagsAuto = Yes, setTagsAuto = No. Every file was a fresh copy of one 135 BPM FLAC under a path VirtualDJ had never seen, with one Vorbis comment altered, loaded with deck 1 load "<absolute path>" and read back with get_bpm, get_firstbeat, get_key, cue_name N, cue_pos N 'absolute', loop_load N (as a query) and, after loop_load 3, get_loop. The tag layouts are Serato DJ's, as documented by the triseratops project: a base64 envelope of application/octet-stream\0\0<name>\0<data>.

Vorbis comment Content tried Deck showed Verdict
SERATO_MARKERS_V2 CUE entries 8 named, coloured cues all 8, names and positions exact imported
same 16, 64 and 255 cues (one per beat) every cue present and in place; cue_name 256 → N/A; all 255 in database.xml imported; the limit is the format's one-byte slot, not VirtualDJ
SERATO_MARKERS_V2 LOOP entries 8 named saved loops loop_load 1..8 → on, loop_load 9 → off; loop_load 3 set a 42,667 ms loop at 28.4 s, the loop's exact length; a file without the tag has no slots imported (into Poi Type="loop" with Seconds and Slot; the loop names were not seen in the UI query)
INITIALKEY=Am (track is G minor) wrong on purpose get_key → 08A imported
INITIALKEY=6A Camelot 06A imported
INITIALKEY=11M Open Key 09B, VirtualDJ's own analysis (which hears G major) not understood
SERATO_BEATGRID one marker: 133.33 BPM from 0.222 s (the track is 135 from 0.000); SERATO_AUTOGAIN tempo set to match get_bpm → 135, get_firstbeat → 28444.88, same as an untouched copy ignored
BPM=131.00 plain comment get_bpm → 135, same analysed grid did not determine deck BPM; tag-read status was not checked

For these fresh FLAC imports on build 18.0.9644, VirtualDJ took cues, saved loops and the key. The tested SERATO_BEATGRID and plain BPM comments did not override its analysed tempo or grid on the deck; this does not establish whether the BPM comment was read into Tags/@Bpm, or rule out other tag layouts or import paths. The observed analysed values live in Scan/@Bpm and Scan/@Phase. Importing a beat grid through database.xml has not been attempted (see Editing database.xml). get_firstbeat returned the Scan/@Phase value in milliseconds, not the first beat of the file.

Binary lead: Serato Markers2 reader

Binary analysis (Tier 2): the symbol-rich arm64 build 18.0.9246 names CTagEngineID3::handleSeratoMarkers2(SDBInfo*, std::string const&) at 0x1005d15d8. Its disassembly compares record prefixes CUE, COLOR and LOOP. The CUE path calls SDBInfo::addCue, stores a three-byte colour, and copies a name; COLOR writes a track colour; LOOP calls SDBInfo::getLoop or SDBInfo::addPoi with position and length. This adds a track colour candidate to the import tests. No beat-grid or tempo record branch was found in this handler. This is a finding about one historical handler, not proof that build 18.0.9644 cannot import grids by another route. Both binaries contain SERATO_MARKERS_V2; only the installed build's FLAC cue/loop behavior was tested above. A fresh-copy FLAC with a distinct Serato COLOR record, read back from the VirtualDJ database/UI, would settle that candidate.

Binary lead: separate FLAC BPM field

Binary analysis (Tier 2): build 18.0.9246 has a distinct CTagEngineFlac::handleVC reader. It compares Vorbis comments BPM=, KEY=, INITIALKEY=, COLOR=, CUEPOINT and SERATO_MARKERS_V2 (among ordinary text fields). The BPM= branch, at 0x10005c250, calls CTagEngineID3::getBPMFromTBPM, converts the result to seconds per beat, and writes the tag-BPM field of SDBInfo. The FLAC loader calls this reader for Vorbis-comment blocks. Thus the prior get_bpm result alone is insufficient to call BPM=131.00 ignored: deck BPM can differ from a parsed file-tag BPM. The installed 18.0.9644 binary still contains BPM=, but this historical code path has not been matched instruction by instruction to that build. A fresh tagged FLAC, read back through database.xml Tags/@Bpm before and after analysis, would settle current behavior. No FLAC SERATO_BEATGRID match was found in this reader; the tested tag did not affect the deck grid on build 18.0.9644. The separate ID3 (TBPM), QuickTime, Ogg/Opus, and database readers are other input paths, not evidence that they import a first beat or grid.

Binary analysis agrees (Binary analysis, reported 2026-10-14, build not stamped): the Markers2 reader in the executable branches on the entry names CUE, LOOP and COLOR only; it has no branch for a tempo or beat-grid entry, so SERATO_BEATGRID is never parsed, not merely ignored. COLOR (the Serato track colour) is therefore read, but what VirtualDJ does with it was not tested.

Realistic No-Manual-Touch Workflow On macOS

Tag-first workflow, best for external DJ-library tools:

  1. Run the outside prep tool on the audio files.
  2. Make sure it writes hotcue metadata to file tags or to an intermediate library format VirtualDJ can read.
  3. In VirtualDJ, set getCuesFromTags to for new files when tags should seed only first import, or always when the external tags should stay authoritative.
  4. Put the files in a watched folder or browse them in VirtualDJ so they are added to the database.
  5. Load a track and use the built-in Hot Cues page, or this repo's cue pad pages, to confirm the cue names, positions, and colors.

Database-first workflow, best for custom phrase/structure detection:

  1. Add or reveal the tracks to VirtualDJ once so ~/Library/Application Support/VirtualDJ/database.xml gets <Song> rows with the final file paths and sizes.
  2. Quit VirtualDJ.
  3. Back up and validate database.xml.
  4. Run the external analyzer/prep script and merge cue POIs into the matching <Song> entries:
<Poi Type="cue" Pos="64.000000" Name="DROP" Num="1" Color="4278255360"/>
<Poi Type="cue" Pos="128.000000" Name="BREAK" Num="2" Color="4293375736"/>
  1. Validate database.xml again, reopen VirtualDJ, and load the tracks.

The macOS paths for that workflow are:

Path Role Source
~/Library/Application Support/VirtualDJ/database.xml Main same-drive VirtualDJ track database and cue POI store. Official forum, Local observation
/Volumes/<Drive>/VirtualDJ/database.xml Per-drive database for media on other drives. Official forum, Inference
~/Library/Application Support/VirtualDJ/settings.xml Stores explicit overrides for options such as getCuesFromTags, getTagsAuto, watched folders, and related settings. Defaults may not appear until changed. Official, Local observation, Inference

Source: Official, Official forum, Local observation, Inference

Cautions

  • VirtualDJ does not write its cue changes back to file tags; VirtualDJ's durable cue store is its database. If another app owns the tags, decide whether tags or VirtualDJ should be authoritative before setting getCuesFromTags to always.
  • If a file already has a VirtualDJ database entry, tag changes may not be imported again unless the relevant settings and first-seen/database state allow it.
  • Direct database.xml edits should only happen while VirtualDJ is closed. Always back up, validate XML before and after, and match by exact file path plus other identity fields where possible.
  • Pos values are seconds in observed database.xml cue POIs, while cue/loop UI actions may use beats, milliseconds, or display-time formats. Convert deliberately.
  • Auto-created Remix Points can be played from the Remix Points pad page, but they are not a substitute for numbered Hot Cues when the controller workflow expects hot_cue 1 through hot_cue 8 or 16.

Source: Official, Official forum, Built-in pad page, Local observation, Inference

Querying database.xml

Install helper tools:

brew install xmlstarlet

Export a browser-like TSV:

#!/usr/bin/env zsh
set -euo pipefail

VDJ_DB="${VDJ_DB:-$HOME/Library/Application Support/VirtualDJ/database.xml}"

xmlstarlet sel -T -t \
  -m '/VirtualDJ_Database/Song' \
  -v '@FilePath' -o $'\t' \
  -v 'Tags/@Author' -o $'\t' \
  -v 'Tags/@Title' -o $'\t' \
  -v 'Tags/@Remix' -o $'\t' \
  -v 'Tags/@Key' -o $'\t' \
  -v 'format-number(60 div number(Tags/@Bpm), "0.000")' -o $'\t' \
  -v 'Infos/@PlayCount' \
  -n \
  "$VDJ_DB"

Find songs that have more than eight cue points:

xmlstarlet sel -T -t \
  -m '/VirtualDJ_Database/Song[count(Poi[@Type="cue"]) > 8]' \
  -v 'Tags/@Author' -o ' - ' -v 'Tags/@Title' -o $'\t' \
  -v 'count(Poi[@Type="cue"])' \
  -n \
  "$HOME/Library/Application Support/VirtualDJ/database.xml"

Editing database.xml

Prefer VirtualDJ's UI for normal tagging. Direct XML edits are useful for controlled bulk changes.

The script below updates Tags/@User1 for a song selected by exact file path. It:

  • requires xmlstarlet
  • requires VirtualDJ to be closed
  • backs up database.xml
  • validates XML before and after
  • handles file paths containing either single or double quotes
#!/usr/bin/env zsh
set -euo pipefail

command -v xmlstarlet >/dev/null || {
  print -u2 "missing dependency: brew install xmlstarlet"
  exit 1
}

VDJ_DB="${VDJ_DB:-$HOME/Library/Application Support/VirtualDJ/database.xml}"
filepath="${1:?usage: vdj-db-set-user1 <exact-file-path> <new-user1-value>}"
value="${2:?usage: vdj-db-set-user1 <exact-file-path> <new-user1-value>}"

xpath_literal() {
  local s="$1"

  if [[ "$s" != *"'"* ]]; then
    printf "'%s'" "$s"
    return
  fi

  if [[ "$s" != *'"'* ]]; then
    printf '"%s"' "$s"
    return
  fi

  local out="concat("
  local first=1
  local rest="$s"
  local part

  while [[ "$rest" == *"'"* ]]; do
    part="${rest%%\'*}"
    if (( ! first )); then
      out+=","
    fi
    out+="'$part',\"'\""
    rest="${rest#*\'}"
    first=0
  done

  out+=",'$rest')"
  printf "%s" "$out"
}

xmllint --noout "$VDJ_DB"

stamp="$(date +%Y%m%d-%H%M%S)"
cp -p "$VDJ_DB" "$VDJ_DB.$stamp.bak"

literal="$(xpath_literal "$filepath")"
song="/VirtualDJ_Database/Song[@FilePath=${literal}]"

matches="$(xmlstarlet sel -t -v "count($song)" "$VDJ_DB")"
if [[ "$matches" != "1" ]]; then
  print -u2 "expected exactly one matching Song, found $matches"
  exit 2
fi

has_attr="$(xmlstarlet sel -t -v "count($song/Tags/@User1)" "$VDJ_DB")"
if [[ "$has_attr" == "0" ]]; then
  xmlstarlet ed -P -L \
    -i "$song/Tags" -t attr -n User1 -v "$value" \
    "$VDJ_DB"
else
  xmlstarlet ed -P -L \
    -u "$song/Tags/@User1" -v "$value" \
    "$VDJ_DB"
fi

xmllint --noout "$VDJ_DB"
print "updated User1"
print "backup: $VDJ_DB.$stamp.bak"

extra.db

extra.db is SQLite. It can be locked while VirtualDJ is running. For read-only inspection while VirtualDJ is open, SQLite's immutable URI mode is useful:

sqlite3 "file:$HOME/Library/Application Support/VirtualDJ/extra.db?mode=ro&immutable=1" '.schema'

Observed schema:

CREATE TABLE related_tracks (id INTEGER PRIMARY KEY, sid1 INTEGER, sid2 INTEGER);
CREATE INDEX idx_sid1 ON related_tracks (sid1);
CREATE INDEX idx_sid2 ON related_tracks (sid2);

CREATE TABLE track_data (
  id INTEGER PRIMARY KEY,
  sid INTEGER,
  file TEXT,
  filesize INTEGER,
  artist TEXT,
  title TEXT,
  remix TEXT,
  UNIQUE(sid)
);
CREATE INDEX idx_sid ON track_data (sid);

CREATE TABLE lyrics (lid BLOB NOT NULL PRIMARY KEY, xml TEXT NOT NULL);

Observed local counts at time of review:

track_data: 61
related_tracks: 81
lyrics: 331

Linked Tracks

VirtualDJ's linked/remix relationships are stored in extra.db:

  • track_data.sid: signed 64-bit opaque song identifier.
  • track_data.file: path to a track.
  • track_data.filesize: file size in bytes.
  • track_data.artist, title, remix: display metadata.
  • related_tracks.sid1, related_tracks.sid2: relationship edges between track_data.sid values.

SID construction recovered

Binary analysis (Tier 2), 2026-09-13, build 18.0.9246 arm64: linked tracks use SDBInfo::getSIDCleaned(false). This makes a copy of artist, title and remix, runs CTagEngine::cleanup(copy, false), then calls SDBInfo::getSID(). The final ID is FNV-1 64-bit over concatenated, reduced metadata, with no separator between fields. Path, file size and audio bytes are not inputs to this call chain. It identifies a metadata equivalence class, not a unique physical file.

The regenerable evidence is linked-sid-9246.json: full executable SHA-256, symbol names, exact LC_FUNCTION_STARTS bounds, bounded instructions, SQL literals and vendor Unicode mapping bytes. Query the compact contract with just linked-sid --evidence. Extract again with just extract-linked-sid --app /path/to/VirtualDJ.app using the recorded unstripped build (Python with Capstone installed). Fixed literal addresses are SHA-guarded; the extractor refuses another binary rather than silently reading unrelated data.

The recovered stages are:

  1. Clean a metadata copy. getCleanedCopy copies SDBInfo offsets 0x18 (artist), 0x20 (title), and 0x50 (remix). Their meanings are independently identifiable from the field order in addTrackData's SQL bindings. Cleanup trims fields and handles bracketed remix/featuring material; it is a separate, substantial routine, not equivalent to uppercasing the database fields.

  2. Reduce each field separately. strAddReduced uppercases ASCII a–z and retains A–Z. Digits, spaces and ordinary punctuation contribute nothing. The characters (, [, /, {, and " stop processing the remainder of that field, as does lowercase www.. NUL terminates the C string. Uppercase WWW. does not trigger that particular stop rule.

  3. Apply the vendor Unicode rules. utfcanonical uses the extracted Latin, Greek, Cyrillic and Hebrew tables, retaining only table outputs a–z and uppercasing them; ß becomes SS. U+4E00–U+9FFF and U+0E00–U+0E7F retain their original UTF-8 bytes. Other unmapped Unicode contributes nothing. A generic Unicode normalization/transliteration library is not an exact substitute.

  4. Concatenate reduced artist + reduced title + reduced remix. Omit the entire remix if its pre-reduction text contains lowercase .com, .net, .org, or www. (case-sensitive searches in the inspected binary).

  5. Reject placeholder identities: empty reduced input, TRACK, UNKNOWNARTISTTRACK, and VIDEOPLAYBACK return zero. addRelated refuses zero SID endpoints.

  6. Hash the resulting UTF-8 bytes, with multiplication before XOR:

    h = 0xcbf29ce484222325
    for byte in reduced_bytes:
        h = ((h * 0x100000001b3) ^ byte) & 0xffffffffffffffff
    sid = h if h < (1 << 63) else h - (1 << 64)

    That is FNV-1, not FNV-1a. Native code carries an unsigned 64-bit value; sqlite3_bind_int64 stores the same bits as a signed SQLite INTEGER. A negative SID is normal. Do not take its absolute value or store an out-of-range unsigned decimal integer.

For an already-cleaned synthetic example:

just linked-sid --prepared --artist 'Example Artist' --title 'Example Track' --remix 'Club Mix'

The reduced input is EXAMPLEARTISTEXAMPLETRACKCLUBMIX, producing hexadecimal 57fa3f17fa7c45db / signed decimal 6339448797696640475. The calculator's --prepared flag acknowledges that it implements the post-cleanup stage, not the full CTagEngine::cleanup routine. Do not promise arbitrary raw-tag import compatibility from this helper alone.

Corroboration, not a live integration claim: the stable offline extra.db snapshot audited on 2026-09-13 matched every stored SID using the calculator against its stored artist/title/remix fields. See linked-sid-observation.json → rows, matches, mismatches, and snapshot SHA-256; row-creation builds are unknown. No private metadata or database copy is committed. Reproduce against an offline snapshot with just linked-sid --audit /path/to/extra-snapshot.db. The snapshot must include committed WAL contents; the helper refuses a nonempty companion WAL and checks for changes during its read.

Synthetic vectors also agree with the original ARM64 reducer, Unicode helper and hash-loop instructions executed in Unicorn, with narrow libc/string hooks. Regenerate with just probe-linked-sid-binary --app /path/to/VirtualDJ.app (Python with Unicorn installed); just check-linked-sid checks the calculator against these vectors. Emulation is Tier 2: it does not run VirtualDJ, execute cleanup, test SQLite writes, or prove that a currently running build accepts an externally added link.

Correction to the 2026-09-12 exclusion: the earlier unsuccessful sweep of FNV-1a/FNV-1/djb2/sdbm/MurmurHash64A/CRC64-ECMA over raw path/metadata variants ruled out only those specific input encodings. It did not rule out FNV-1 itself. It missed VirtualDJ's metadata reduction and concatenation pipeline. The hash algorithm is now recovered; complete raw-tag cleanup compatibility and a current-build external-write/readback canary remain open.

Naming endpoints the database never recorded

track_data only holds rows VirtualDJ happened to record, so most endpoints of a real related_tracks set have no metadata at all. A computable SID fixes that from the other direction — hash the library's own <Song> tags and look the endpoint up:

just list-linked-tracks --resolve-from-library

Those are raw Author/Title/Remix tags, not the post-cleanup values SDBInfo::getSID receives, so a match is evidence and a miss is not: cleanup may have altered the fields, the track may live in another volume's database, or the row may predate a retag. Default output is unchanged; the flag only adds names. One SID is a metadata equivalence class, so it can legitimately name several files — the index keeps the first.

Second install, read-only (2026-09-25, build 18.0.9644)

An independent Rust port of the calculator (the UpNext plugin, src/sid.rs, tested against linked-sid-vectors.json) re-ran the corroboration on another machine, against mode=ro&immutable=1 snapshots of extra.db and the database.xml files. Aggregates only; no metadata was recorded:

  • track_data held 68 rows and all 68 hashed back to their stored sid from their stored artist/title/remix, with no cleanup applied.
  • related_tracks held 85 edges. 37 had both endpoints in track_data, 2 only sid1, 6 only sid2, and 40 neither. So on this install the SQL join names fewer than half the relationships; the rest are only reachable through the library.
  • Of the 80 distinct endpoint SIDs with no track_data row, hashing the raw Author/Title/Remix of every <Song> in the home database.xml plus one mounted volume's database named 45 (this index treated an Original Mix remix as empty, which the correction above shows is not always right; the with-remix variant was not tried on these 35).
  • The remaining 35 matched nothing under: bracketed and feat. material stripped from artist or title; artist/title taken from the file name (Title - Artist (bpm, key)); the database.backup.xml entries; sampler names; or any file name in the cache.db waveform table (see cache.db). One such edge is (-6269945504200269713, 7020311537543996777): the second endpoint reproduces from the loaded track's current tags, the first from nothing on disk. The reading consistent with that is a link whose other file was deleted or retagged after linking; related_tracks keeps the edge and VirtualDJ itself shows such endpoints as not found. Not proven: the test is to link two tracks, delete one, and read the edge and the app's display.

What cleanup does, from one install's data (2026-09-13)

Comparing raw library tags against the stored post-cleanup metadata for the same file bounds the open cleanup question with real data rather than more reading. Correction (2026-09-25): the earlier comparison observed one raw Remix value of Original Mix paired with an empty stored remix. It did not establish that CTagEngine::cleanup always discards Original Mix, nor that cleanup is identity for other tracks. Stored metadata may differ from current tags for other reasons, including retagging.

A read-only database comparison on 2026-09-25 found a counterexample: an endpoint stores Original Mix, and hashing its stored artist/title/remix reproduces the SID of its outgoing relationship. Dropping the remix instead produces a different SID with no relationship rows. This is offline corroboration (Tier 2), not a complete cleanup specification or a live external-write test.

Reader consequence: preserve Original Mix when computing candidate SIDs. Do not implement unconditional remix stripping from the earlier observation. Compare candidates against stored identities and keep metadata-cleanup uncertainty explicit. The Python calculator and --resolve-from-library already preserve this field; consumers must not add the retracted stripping rule.

Counter-observation (Local test, build 18.0.9644, 2026-09-27): a link made in the running app via the official mark_linked_tracks verb (decks 1 and 2 loaded, sent from a plugin through SendCommand) produced one new related_tracks row and two track_data rows whose remix columns kept their raw values (Original Mix and Extended Mix), and both SIDs reproduce from the raw tags with the remix included — so on this build cleanup did not discard Original Mix. Afterwards has_linked_tracks answered yes on both decks, so a single stored row is a link in both directions as far as VirtualDJ is concerned; (sid1, sid2) order is insertion order, not a direction. Readers should hash both with and without Original Mix.

Lookup and relationship consequences

addRelated computes each cleaned SID, binds them to INSERT INTO related_tracks (sid1, sid2) VALUES (?, ?), and passes those same IDs to addTrackData. The latter uses INSERT OR IGNORE with UNIQUE(sid): it saves file, size and display metadata as a representative record for that SID. With no separators and discarded digits/punctuation, distinct inputs can intentionally collapse: prepared (artist="AB", title="C") and (artist="A", title="BC") produce the same ID. File renaming does not enter this hash, while a metadata change can change it.

Binary analysis (Tier 2): getDBIFromSID first calls CDatabaseEngine::findInfoFromSID(sid, false), whose cache-building path uses getSIDCleaned. Only on a miss does it query track_data for fallback file, size and metadata. Therefore an SQL join to track_data can miss relationships that VirtualDJ resolves through the library cache. The observation artifact's edges_missing_track_data reports missing SQL endpoints, not proven broken links. Settling that distinction requires displaying a controlled linked-track pair in the running app and independently reading the stored edge.

Observations retained from the 2026-09-12 pass, with the lookup correction:

  • sid does not appear in database.xml. <Song> keys on FilePath and FileSize, and track_data re-stores file, filesize, artist, title and remix rather than referencing the XML. Qualification from the 2026-09-13 binary trace: the runtime first resolves the computed SID through the library cache; path/size are fallback data. The previous claim that it joins only by path was too strong.
  • Edges are stored once, not mirrored. On this install no related_tracks row had a reversed twin, so a reader must match sid1 or sid2; treating the pair as directional will silently miss half the links. The read query below joins both endpoints.

List every stored relationship, retaining endpoints absent from track_data:

just list-linked-tracks
just list-linked-tracks --json
just list-linked-tracks --db /path/to/extra.db

The command is read-only and prints both tracks and their paths. Missing metadata is marked with the unresolved SID. If VirtualDJ holds an exclusive lock, it can read a stable file snapshot only when no nonempty WAL or rollback journal is present; it announces that fallback, which excludes unsaved application changes. This lists stored edges, not the application's in-memory SID-cache results.

The older SQL query below lists only relationships with both metadata rows:

#!/usr/bin/env zsh
set -euo pipefail

DB="${DB:-$HOME/Library/Application Support/VirtualDJ/extra.db}"

sqlite3 "file:$DB?mode=ro&immutable=1" <<'SQL'
.headers on
.mode tabs
select
  a.file as file1,
  b.file as file2,
  a.artist || ' - ' || a.title as track1,
  b.artist || ' - ' || b.title as track2
from related_tracks r
join track_data a on a.sid = r.sid1
join track_data b on b.sid = r.sid2
order by track1, track2;
SQL

Add a relationship only when both track_data rows already exist:

#!/usr/bin/env zsh
set -euo pipefail

DB="${DB:-$HOME/Library/Application Support/VirtualDJ/extra.db}"
left="${1:?usage: vdj-link-existing <left-file> <right-file>}"
right="${2:?usage: vdj-link-existing <left-file> <right-file>}"

sqlite_literal() {
  local s
  s="$(printf '%s' "$1" | sed "s/'/''/g")"
  printf "'%s'" "$s"
}

stamp="$(date +%Y%m%d-%H%M%S)"
cp -p "$DB" "$DB.$stamp.bak"

left_sql="$(sqlite_literal "$left")"
right_sql="$(sqlite_literal "$right")"

sqlite3 "$DB" <<SQL
insert into related_tracks (sid1, sid2)
select a.sid, b.sid
from track_data a, track_data b
where a.file = $left_sql
  and b.file = $right_sql
  and not exists (
    select 1
    from related_tracks r
    where r.sid1 = a.sid
      and r.sid2 = b.sid
  );

select changes() as inserted_rows;
SQL

print "backup: $DB.$stamp.bak"

If that script prints 0, one or both files probably do not have track_data rows yet, or the relationship already exists.

Lyrics Cache

Binary analysis (Tier 2), build 18.0.9246 arm64, extracted 2026-09-13: lyrics.lid is the track's audio signature, not the metadata-derived linked-track SID. getLyrics, saveLyrics, and deleteLyrics bind the same 18 bytes at SDBInfo + 0x130 directly as a SQLite BLOB. Their shared eligibility check reads the final little-endian word at +0x140 and requires it to exceed 1.

CREATE TABLE lyrics (lid BLOB NOT NULL PRIMARY KEY, xml TEXT NOT NULL);

There is no path, artist/title, timestamp, or expiry column in this schema. The payload is uncompressed text, despite the column being named xml. See lyrics-cache-9246.json for the executable SHA-256, symbol-addressed functions with exact LC_FUNCTION_STARTS bounds, explicitly bounded XML reader/writer excerpts, SQL and format literals, and numeric constants. just lyrics-cache --evidence is the compact entry point.

LID layout and construction

Bytes Recovered meaning
0..15 Packed four-bit occurrence ratios for each bit position in raw Chromaprint words.
16..17 Number of raw fingerprint words, unsigned little-endian. Values 0 and 1 are reserved states.

CAudioSignature::getSignature and the streaming start/process/end path use Chromaprint algorithm ID 1 with stereo audio, then feed raw 32-bit fingerprint words to the function named hash128. This is not MD5, and it is not the standard compressed Chromaprint string. Given the selected raw words w and N = len(w), its calculation is:

q = [16 * sum((word >> bit) & 1 for word in w) // (N + 1)
     for bit in range(32)]
lid = bytes((q[i] << 4) | q[i + 1] for i in range(0, 32, 2))
lid += N.to_bytes(2, "little")

Bit 0 contributes the first byte's high nibble; bit 1 contributes its low nibble, continuing through bit 31. The N + 1 denominator keeps each value within a nibble. This is a lossy summary: reordering the same fingerprint words cannot change it. It must not be described as a cryptographically unique file ID.

Audio preprocessing matters. The batch path accepts packed stereo signed 16-bit PCM frames and a sample rate. It checks duration, searches leading and trailing boundaries using a rolling channel-sum threshold, and fingerprints the selected interval. The streaming path also performs boundary handling and adjusts the returned fingerprint length using Chromaprint sample rate, delay, and item duration. The routines are captured, but the helper does not port that PCM preprocessing or promise that a default fpcalc invocation will match. Use the same raw fingerprint window as VirtualDJ when assembling a matching key.

Text representation and joining to the library

CAudioSignature::saveToString writes the signature as URL-safe Base64. An ordinary signature becomes a text AudioSig value; the XML reader explicitly loads it from Song/Scan/@AudioSig, and writes the decoded bytes into the same SDBInfo + 0x130 region used for the SQLite key.

  • Count 0 serializes to the empty string.
  • Count 1 serializes to -.
  • Other counts serialize the 18 bytes after masking the final byte with 0x1f. loadFromString accepts an ordinary decoded value only when it is exactly 18 bytes and its final byte is below 0x20.
  • The read-only helper rejects malformed text explicitly; it does not emulate every permissive edge of the native Base64 decoder.

For a valid persisted AudioSig, Base64url decoding therefore gives the BLOB needed for SELECT xml FROM lyrics WHERE lid=?. Do not bind the Base64 string, hex string, or linked-track SID where SQLite expects those raw bytes.

The inspected local database.xml snapshot contained no AudioSig attributes; see lyrics-cache-observation.json → library_comparison. Consequently this pass cannot map the cache rows back to that XML's tracks. That absence does not contradict the recovered reader/writer: the in-memory analysis state and other library snapshots are separate evidence.

Stored payload grammar and historical reader behavior

Synthetic example (not copied from a cached song):

#CUSTOM
#LANG=eng
[0.10-0.30] alpha
[0.40-0.80] beta\n

Each physical timed line has the form [start-end] text, with times in seconds. The historical reader looks for the literal ] separator. A trailing literal backslash plus n in the text becomes a newline in the displayed segment; it marks a lyric line ending without breaking the storage record into two lines. The editor writes times with two fractional digits and prefixes edited text with #CUSTOM.

Record Meaning and scope
#LANG=… Language metadata; recognized case-insensitively by setLyrics.
#CUSTOM Emitted by the lyric editor. The segment reader itself ignores this header.
#NOLYRICS Observed negative-result cache payload; it yields no segments through the reader.
A language-only payload Contains metadata without timed lyric segments; observed separately from #NOLYRICS.
[start-end] <marker> A whole text enclosed by < and > is skipped by the historical segment reader.

setLyrics is more permissive than a strict line parser: it searches for the first hyphen and then ] , with searches able to extend past the current line. It parses numbers using strToDbl, converts them to float32, clamps each accepted segment's start to the previous accepted segment's end, and changes an end that is less than its start to start + 0.01. Equal endpoints remain equal. Empty text and angle markers do not advance the previous accepted end.

Synthetic instruction-execution vectors confirm these details on the inspected build. For example, a segment at 1–1.5 after a segment ending at 3 becomes approximately 3–3.01. Also, [-1.00--1.00] pending becomes 0–1, because the first minus sign is consumed as the separator. Negative stored timestamps do occur in the inspected snapshot. The helper deliberately preserves them and reports raw storage structure; its parser is not a clone of the runtime parser or its timing repairs.

The historical has_lyrics implementation checks for a nonempty parsed segment vector, not merely a lyrics row or a song flag. get_lyrics_language returns stored language metadata when segments exist, with eng as its fallback; no segments follow a failure branch. These are binary leads, not new live-tested verb conclusions, and do not promote verb-store status.

Cache writes, flags and server path

  • saveLyrics uses REPLACE INTO lyrics (lid, xml) VALUES (?, ?) in the track's drive-selected extra.db. A matching key replaces its payload.
  • getLyrics tries the track's drive database, then the main database when different, returning the first nonempty payload. deleteLyrics attempts both locations. It passes database-kind 0 where get/save pass 1; that discrepancy is preserved in the evidence and needs a focused deletion test, not an assumption that all three route identically.
  • Saving chooses song-flag bits under mask 0x30000000: ordinary saves use 0x10000000, while the editor's custom=true call uses 0x30000000, then marks changed state dirty. These bits alone do not prove rendered lyrics exist.
  • The client contains https://live.virtualdj.com/live/lyrics.php. Its cache lookup sends lid=<Base64url AudioSig> plus version metadata and reads a JSON lyrics field. The broader worker also has streaming-ID (ns=) and upload paths. This pass made no server requests, and establishes neither server availability, permissions, retention policy nor cache-matching behavior.

Because the key is audio-derived, path or tag edits are not direct inputs. Audio edits, a different decoded fingerprint window, or preprocessing differences can change it. A migration still needs the relevant cache database; audio files do not contain the lyrics table's payload merely because they have a signature.

Read-only tools and validation

just lyrics-cache --evidence
just lyrics-cache --summary --db /path/to/offline-extra.db
just lyrics-cache --list --db /path/to/offline-extra.db
just lyrics-cache --summary --db /path/to/offline-extra.db --library /path/to/database.xml
just lyrics-cache --audiosig 'AAAAAAAAAAAAAAAAAAAAAAIA'
just lyrics-cache --fingerprint /path/to/raw-chromaprint-words.json
just lyrics-cache --payload /path/to/synthetic-lyrics.txt
just lyrics-cache --export-lid HEX_LID --db /path/to/offline-extra.db

The example AudioSig is synthetic (an all-zero histogram with count 2). --summary emits aggregates only; --list shows keys and metadata without lyric text; --export-lid prints the selected row's exact text. Use a consistent offline database snapshot with no nonempty WAL or rollback journal. No command writes the source database or contacts a server.

Regenerate structural evidence with just extract-lyrics-cache --app APP (Python with Capstone), and synthetic instruction vectors with just probe-lyrics-binary --app APP (Python with Unicorn). Both require the SHA-guarded unstripped build. just check-lyrics-cache checks key construction against those vectors, encoding limits, and storage-parser preservation.

The offline observation artifact records key-length/eligibility checks, payload categories, header and segment totals, unparsed-line totals, and source hashes. Every inspected row fit the recovered key shape and every nonempty physical line was accounted for by the storage parser. This is Tier-2 corroboration, not proof of current-build lyric rendering, audio-to-key reproduction or external cache insertion. No private lyrics, signatures, track names or database copies are committed. A disposable audio fixture, independent live readback, and a controlled lyric rendering test are the remaining integration checks.

cache.db

Cache/cache.db is SQLite and stores waveform blobs.

Observed schema:

CREATE TABLE waveforms (
  id INTEGER PRIMARY KEY,
  filepath TEXT,
  filename TEXT,
  filesize INTEGER,
  type INTEGER,
  version INTEGER,
  valuesPerSecond REAL,
  waveform BLOB
);
CREATE INDEX idx_waveform_filename ON waveforms (filename, type);

Use this for inspection only. It is a generated cache.

Read-only reinspection on 2026-09-16 found the same waveforms table and idx_waveform_filename index in the checkpointed main-file schema, with no script, action-catalog or parser table. The ordinary read-only connection was locked by the running app; mode=ro&immutable=1 inspected only the main file and excluded pending WAL changes. No private row values were read. This is a waveform-format lead, not evidence for the runtime argument grammar; it does not rule out information in other cache files or opaque blob contents.

Read-only waveform count:

sqlite3 "file:$HOME/Library/Application Support/VirtualDJ/Cache/cache.db?mode=ro&immutable=1" \
  'select count(*) from waveforms;'

Rows outlive the library (Local observation, 2026-09-26, build 18.0.9644): the table held 29,244 rows while database.xml held 1,681 songs, and a name search found three earlier file names of one current track — a rename and two retags — none of which exists in database.xml any more. So filename/filepath here are a history of every file VirtualDJ analysed, which makes the table the best local lead for putting a name to a related_tracks endpoint that no current library entry hashes to (see Linked Tracks). It is a name lead only: the row stores no tags, so it cannot reproduce a SID.

Other observed cache files:

  • Cache/cache.db-shm
  • Cache/cache.db-wal
  • Cache/cache2.db
  • Cache/cache3.db
  • Cache/cache4.db
  • Cache/fft

The non-SQLite cache files are currently Unknown.

Lists And Virtual Folders

VirtualDJ 2024+ lists are XML files under MyLists by default. VDJPedia says the only required song entry attribute is path, and size is highly recommended.

Generic list:

<?xml version="1.0" encoding="UTF-8"?>
<VirtualFolder noDuplicates="yes" ordered="yes">
  <song path="/Music/Tracks/example.flac" size="12345678" artist="Artist" title="Title" idx="0"/>
</VirtualFolder>

Observed local empty folder/list forms:

<?xml version="1.0" encoding="UTF-8"?>
<VirtualFolder />
<?xml version="1.0" encoding="UTF-8"?>
<VirtualFolder noDuplicates="no" ordered="yes" />

Sampler And Scratch Banks

Sampler bank XML lives under Sampler/.

Example shape:

<?xml version="1.0" encoding="UTF-8"?>
<samplerbank>
  <sample path="Instruments\Kick.vdjsample" group="BEATS" color="red" col="0" row="0" />
</samplerbank>

Scratch banks live under ScratchBanks/ and can embed a nested <Song> record:

<?xml version="1.0" encoding="UTF-8"?>
<scratchbank name="Bank A">
  <sample path="/Music/Samples/example.flac" filesize="108637" idx="1" color="#00FF37">
    <Song FilePath="/Music/Samples/example.flac" FileSize="108637" Flag="1">
      <Tags Flag="1" />
      <Infos SongLength="2.181812" FirstSeen="1755968487" Bitrate="398" Cover="2" />
    </Song>
  </sample>
</scratchbank>

.vdjsample is binary. Some files show a VDJ header followed by Matroska-like content, but the full format is not mapped here.

Stem Files

See VirtualDJ Stem File Format for the focused .vdjstems sidecar format reference. This section keeps the shorter application-internals view: where the files fit, how to inspect them, and how local helper scripts recreate the observed layout.

VirtualDJ's public docs describe five stem components:

  • vocal
  • instruments
  • bass
  • hihat
  • kick

The docs also say that when real-time separation is too expensive, VirtualDJ can prepare tracks in advance by saving stems in a separate file.

Observed VirtualDJ Sidecars

VirtualDJ-prepared .vdjstems files observed locally are Matroska containers with five stereo AAC streams:

0 vocal
1 hihat
2 bass
3 instruments
4 kick

Inspect one:

ffprobe -v error -select_streams a \
  -show_entries stream=index,codec_name,sample_fmt,channels:stream_tags=title \
  -of compact=p=0:nk=1 \
  "/path/to/track.flac.vdjstems"

Expected shape:

0|aac|fltp|2|vocal
1|aac|fltp|2|hihat
2|aac|fltp|2|bass
3|aac|fltp|2|instruments
4|aac|fltp|2|kick

The sidecar naming pattern is usually:

/path/to/original.ext.vdjstems

Open-Source Recreation: Five-Stream Matroska

This creates a VirtualDJ-like five-stream .vdjstems container from prepared WAV files:

#!/usr/bin/env zsh
set -euo pipefail

command -v ffmpeg >/dev/null || {
  print -u2 "missing dependency: brew install ffmpeg"
  exit 1
}

dir="${1:?usage: vdjstems-pack-matroska <stem-dir> [output.vdjstems]}"
out="${2:-$dir/$(basename "$dir").vdjstems}"

for name in vocal hihat bass instruments kick; do
  [[ -f "$dir/$name.wav" ]] || {
    print -u2 "missing $dir/$name.wav"
    exit 2
  }
done

ffmpeg -y \
  -i "$dir/vocal.wav" \
  -i "$dir/hihat.wav" \
  -i "$dir/bass.wav" \
  -i "$dir/instruments.wav" \
  -i "$dir/kick.wav" \
  -map 0:a -map 1:a -map 2:a -map 3:a -map 4:a \
  -metadata:s:a:0 title="vocal" \
  -metadata:s:a:1 title="hihat" \
  -metadata:s:a:2 title="bass" \
  -metadata:s:a:3 title="instruments" \
  -metadata:s:a:4 title="kick" \
  -c:a aac -b:a 320k \
  -f matroska \
  "$out"

ffprobe -v error -select_streams a \
  -show_entries stream=index,codec_name,channels:stream_tags=title \
  -of compact=p=0:nk=1 \
  "$out"

Open-Source Separation Pipeline

One workable pipeline is:

  1. Use Demucs or another open model to produce vocals.wav, drums.wav, bass.wav, and other.wav.
  2. Rename vocals.wav to vocal.wav.
  3. Rename other.wav to instruments.wav.
  4. Split drums.wav into kick.wav and hihat.wav with a drum separation model.
  5. If no drum-element splitter is available, use drums.wav for both kick.wav and hihat.wav as a low-quality compatibility fallback.
  6. Pack with the Matroska script above.

Minimal Demucs example:

#!/usr/bin/env zsh
set -euo pipefail

command -v demucs >/dev/null || {
  print -u2 "missing dependency: pipx install demucs"
  exit 1
}
command -v ffmpeg >/dev/null || {
  print -u2 "missing dependency: brew install ffmpeg"
  exit 1
}

input="${1:?usage: vdjstems-demucs-basic <audio-file> [out-dir]}"
outdir="${2:-stems-basic}"
work="$outdir/_work"
mkdir -p "$work"

ffmpeg -y -v error -i "$input" -ar 44100 -ac 2 -c:a pcm_s16le "$work/mix.wav"

model="${DEMUCS_MODEL:-htdemucs_ft}"
demucs -n "$model" -o "$work" "$work/mix.wav"

stemdir="$(find "$work" -type d -path "*/$model/mix" -print -quit)"
[[ -n "$stemdir" ]] || {
  print -u2 "could not find Demucs output under $work"
  exit 2
}

cp "$stemdir/vocals.wav" "$outdir/vocal.wav"
cp "$stemdir/bass.wav" "$outdir/bass.wav"
cp "$stemdir/other.wav" "$outdir/instruments.wav"

# Compatibility fallback until a real drum-element splitter is added.
cp "$stemdir/drums.wav" "$outdir/kick.wav"
cp "$stemdir/drums.wav" "$outdir/hihat.wav"

print "wrote $outdir/{vocal,hihat,bass,instruments,kick}.wav"

Six-Stream MP4/M4A Variant

Local helper scripts outside this reference have also experimented with a six-stream MP4/M4A layout:

0 mixed track
1 vocal
2 hihat
3 bass
4 instruments
5 kick

This is useful for archival or compatibility experiments, especially with ALAC:

#!/usr/bin/env zsh
set -euo pipefail

dir="${1:?usage: vdjstems-pack-mp4-6 <stem-dir> [output.mp4]}"
out="${2:-$dir/$(basename "$dir").vdjstems.mp4}"

for name in mixed vocal hihat bass instruments kick; do
  [[ -f "$dir/$name.wav" ]] || {
    print -u2 "missing $dir/$name.wav"
    exit 2
  }
done

ffmpeg -y \
  -i "$dir/mixed.wav" \
  -i "$dir/vocal.wav" \
  -i "$dir/hihat.wav" \
  -i "$dir/bass.wav" \
  -i "$dir/instruments.wav" \
  -i "$dir/kick.wav" \
  -map 0:a -map 1:a -map 2:a -map 3:a -map 4:a -map 5:a \
  -metadata:s:a:0 title="mixed track" \
  -metadata:s:a:1 title="vocal" \
  -metadata:s:a:2 title="hihat" \
  -metadata:s:a:3 title="bass" \
  -metadata:s:a:4 title="instruments" \
  -metadata:s:a:5 title="kick" \
  -c:a alac \
  -f mp4 \
  "$out"

Known unknown:

  • Current VirtualDJ recognition rules for the six-stream MP4/M4A variant need more cross-version testing.
  • Exact MP4 metadata atoms required for the broadest compatibility are not fully mapped.

File Formats We Know

File Format Notes
settings.xml XML Preferences and UI state.
database.xml XML Main track database.
*.vdjfolder XML Lists, virtual folders, sideview lists.
Mappers/*.xml XML Controller and keyboard mappings.
Pads/*.xml XML Pad pages.
Skins/*/*.xml XML Installed skin files.
RemoteSkins/*.zip ZIP Installed Remote skin packages.
RemoteSkins/*/*.xml XML Uncompressed Remote skin folders observed locally.
extra.db SQLite Related tracks, track_data, lyrics.
Cache/cache.db SQLite Waveform cache.
History/*.m3u M3U-like playlist text Daily history.
*.vdjstems Matroska in observed VirtualDJ-prepared files Five AAC streams named vocal/hihat/bass/instruments/kick.
*.vdjsample Binary Not fully mapped. Some files show a VDJ header and media payload.

Known Unknowns

  • extra.db track_data.sid: FNV-1 metadata construction recovered (see Linked Tracks); complete raw-tag cleanup compatibility and current-build external-link write/readback remain unverified.
  • extra.db lyrics.lid: packed Chromaprint statistics and count recovered (see Lyrics Cache); end-to-end audio preprocessing equivalence and current-build lyric insertion/rendering remain unverified.
  • Full Song/@Flag, Tags/@Flag, and Scan/@Flag bit maps.
  • Scan/@BeatGrid: the leading number and the occasional third segment field (1/4); whether VirtualDJ re-reads a Scan edited by hand or re-analyses (what Scan/@Flag and Infos/@LastModified trigger).
  • Cache/cache2.db, Cache/cache3.db, Cache/cache4.db, and Cache/fft.
  • Complete .vdjsample structure.
  • Whether prepared .vdjstems sidecar metadata has fields beyond stream titles that matter to every VirtualDJ version.
  • Whether every VirtualDJ 2026 build accepts custom Matroska .vdjstems generated externally.
  • Exact role and versioning of bundled Drivers/model3.mlmodelc, Drivers/model4.mlmodelc, and ml113.dylib.

Sources