virtualdj-connect

Library to receive track metadata from VirtualDJ. Two ways to read what's playing:

• M3U history watcher — polls VirtualDJ's History/*.m3u files (title, artist, file path). Works on every VirtualDJ install with history enabled.
• Network Control client — HTTP-polls VirtualDJ's Network Control Plugin for richer per-deck data (BPM, key, genre, album, duration, audible state). Requires the plugin to be enabled in VirtualDJ.

Supports VirtualDJ 7 and 8 on macOS and Windows.

Installation

npm install virtualdj-connect

Usage — M3U history watcher

import { VirtualDjConnect } from 'virtualdj-connect';

const vdj = new VirtualDjConnect({
  pollIntervalMs: 5000,
});

vdj.on('ready', ({ basePath }) => {
  console.log(`Watching: ${basePath}`);
});

vdj.on('track', (payload) => {
  console.log(`Now playing: ${payload.artist} - ${payload.title}`);
  if (payload.filePath) console.log(`File: ${payload.filePath}`);
});

vdj.on('error', (err) => {
  console.error('Error:', err);
});

await vdj.start();

// Later...
await vdj.stop();

Usage — Network Control Plugin

Enable the Network Control plugin in VirtualDJ first (Options → Network Control). Then:

import { VirtualDjNetworkControl } from 'virtualdj-connect';

const nc = new VirtualDjNetworkControl({
  host: '127.0.0.1',
  port: 8080,
  bearer: 'your-password', // if configured
  pollIntervalMs: 1000,
});

nc.on('track', (payload) => {
  console.log(`Deck ${payload.deck}: ${payload.artist} - ${payload.title}`);
  console.log(`  ${payload.bpm} BPM, key ${payload.key}, ${payload.duration}s`);
});

await nc.start();

API

new VirtualDjConnect(options?)

Option	Type	Default	Description
basePath	string	auto-detected	Path to VirtualDJ settings folder
pollIntervalMs	number	5000	How often to poll the M3U history files
logger	Logger	noopLogger	Logger implementation

new VirtualDjNetworkControl(options?)

Option	Type	Default	Description
host	string	127.0.0.1	Host running VirtualDJ
port	number	8080	Network Control plugin port
bearer	string	—	Bearer password if configured in the plugin
decks	number[]	[1,2,3,4]	Decks to scan
pollIntervalMs	number	1000	How often to query the plugin
logger	Logger	noopLogger	Logger implementation

Events

Both classes emit:

Event	Payload	Description
ready	{ basePath } (M3U only)	Connector is ready
track	VirtualDjTrackPayload	New track detected
error	Error	An error occurred

VirtualDjTrackPayload

• title, artist, remix, album, genre, key
• bpm — original BPM (unaffected by pitch), when known
• duration — track length in seconds, when known
• deck — deck number (1-4), when known
• isOnAir — true when VirtualDJ reported the deck as audible
• filePath, fileLocation
• isBeatportStream, beatportId — set when the track is a Beatport stream

Detection utilities

• getDefaultVirtualDjPath() — Returns the default VirtualDJ settings folder for the current platform (VDJ 8 preferred, falls back to VDJ 7)
• detectVirtualDjInstallation(customPath?) — Returns { found, path, version, hasHistory, writeHistoryEnabled }
• pickOnAirDeck(snapshots) — Helper to pick the on-air deck from a set of Network Control snapshots

Low-level

• VirtualDjM3uParser — Parses VirtualDJ's M3U history files directly

License

MIT