stagelinq 1.0.0

package/LogEmitter/index.ts

@@ -0,0 +1,51 @@
+import { EventEmitter } from 'stream';
+
+export declare interface Logger {
+  on(event: 'log', listener: (...args: any) => void): this;
+  on(event: 'error', listener: (...args: any) => void): this;
+  on(event: 'warn', listener: (...args: any) => void): this;
+  on(event: 'info', listener: (...args: any) => void): this;
+  on(event: 'debug', listener: (...args: any) => void): this;
+  on(event: 'silly', listener: (...args: any) => void): this;
+  on(event: 'any', listener: (...args: any) => void): this;
+}
+
+export class Logger extends EventEmitter {
+
+  private static _instance: Logger;
+
+  static get instance() {
+    return this._instance || (this._instance = new this());
+  }
+
+  static log(...args: any) {
+    Logger.instance.emit('log', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+  static error(...args: any) {
+    Logger.instance.emit('error', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+  static warn(...args: any) {
+    Logger.instance.emit('warn', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+  static info(...args: any) {
+    Logger.instance.emit('info', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+  static debug(...args: any) {
+    Logger.instance.emit('debug', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+  static silly(...args: any) {
+    Logger.instance.emit('silly', ...args);
+    Logger.instance.emit('any', ...args);
+  }
+
+}

package/README.md

@@ -0,0 +1,83 @@
+# StageLinq
+
+NodeJS library implementation to access information through the Denon StageLinq protocol.
+
+# Features
+
+* Tested with Denon two SC6000s, X1850, Prime 4, Prime 2, and Prime Go.
+* Event emitters for state changes, tracks getting loaded, and current playing track.
+* Event emitter for debug logging.
+* Downloads source databases for you.
+* You can implement handling the database yourself or use this library's BetterSqlite3 dependency.
+
+---
+
+## Usage
+
+```ts
+import { StageLinq } from '../StageLinq';
+
+const options = { downloadDbSources: true };
+const stageLinq = new StageLinq(options);
+
+stageLinq.devices.on('ready', (connectionInfo) => {
+  console.log(`Device ${connectionInfo.software.name} on ` +
+    `${connectionInfo.address}:${connectionInfo.port} is ready.`);
+});
+
+stageLinq.devices.on('trackLoaded', (status) => {
+  console.log(`"${status.title}" - ${status.artist} loaded on player ` +
+    `${status.deck})`);
+});
+
+stageLinq.devices.on('nowPlaying', (status) => {
+  console.log(`Now Playing: "${status.title}" - ${status.artist})`);
+});
+```
+
+A [complete example](https://github.com/chrisle/StageLinq/blob/main/cli/index.ts) with all events and options can be found in the CLI.
+
+---
+
+## Overview
+
+The idea behind this library is to have a structure something like this:
+
+**StageLinq > Devices > Player > Deck**
+
+A StageLinq sets up a device listener and a class that handles all the
+devices (`StageLinqDevices`).
+
+`StageLinqDevices` figures out if it wants to connect or not and handles
+connections. There may be one or more device on the network. For each device it
+will try to connect to it and subscribe to it's `StateMap`.
+
+Currently there is only one type of device: `Player`. A `Player` may have up to
+4 decks A, B, C, D (aka "layers"). The `Player` handles incoming messages,
+parses them, groups them, and emits events. These events bubble up to the
+`Device`.
+
+## Database
+
+You can use BetterSqlite3 bundled into this library or let this library
+download the files for you, then choose your own Sqlite library to
+query the database. See CLI example.
+
+## Logging
+
+I needed the logging to be used outside of the library so I made them events
+that you can listen to.
+
+* `error`: When something bad happens.
+* `warn`: When something happens but doesn't affect anything.
+* `info`/`log`: When we have something to say
+* `debug`: Spits out the parsed version of the packets.
+* `silly`: Dumps all kinds of internal stuff
+
+## About
+
+Forked from @MarByteBeep's code.
+
+Additional reverse engineering work: https://github.com/chrisle/stagelinq-pcap
+
+Used in my app Now Playing https://www.nowplaying2.com

package/StageLinq/index.ts

@@ -0,0 +1,58 @@
+import { announce, createDiscoveryMessage, StageLinqListener, unannounce } from '../network';
+import { EventEmitter } from 'events';
+import { StageLinqDevices } from '../network/StageLinqDevices';
+import { Logger } from '../LogEmitter';
+import { Action, ActingAsDevice, StageLinqOptions } from '../types';
+
+const DEFAULT_OPTIONS: StageLinqOptions = {
+  maxRetries: 3,
+  actingAs: ActingAsDevice.NowPlaying,
+  downloadDbSources: true
+};
+
+/**
+ * Main StageLinq class.
+ */
+export class StageLinq extends EventEmitter {
+
+  devices: StageLinqDevices;
+  logger: Logger = Logger.instance;
+  options: StageLinqOptions;
+
+  private listener: StageLinqListener = new StageLinqListener();
+
+  constructor(options?: StageLinqOptions) {
+    super();
+    this.options = { ...DEFAULT_OPTIONS, ...options };
+    this.devices = new StageLinqDevices(this.options);
+  }
+
+  /**
+   * Connect to the StageLinq network.
+   */
+  async connect() {
+    const msg = createDiscoveryMessage(Action.Login, this.options.actingAs);
+    await announce(msg);
+    this.listener.listenForDevices(async (connectionInfo) => {
+      await this.devices.handleDevice(connectionInfo);
+    });
+  }
+
+  /**
+   * Disconnect from the StageLinq network.
+   */
+  async disconnect() {
+    try {
+      this.devices.disconnectAll();
+      const msg = createDiscoveryMessage(Action.Logout, this.options.actingAs)
+      await unannounce(msg);
+    } catch(e) {
+      throw new Error(e);
+    }
+  }
+
+  get databases() {
+    return this.devices.databases;
+  }
+
+}

package/TODO.md

@@ -0,0 +1,5 @@
+# TODO
+
+- [ ] Figure out how fader start works.
+- [ ] Refactor MarByteBeep's album art code.
+- [ ] Get track metadata from DB.

package/albumArt/index.ts

@@ -0,0 +1,2 @@
+export * from '../utils/getTempFilePath';
+export * from './maybeDownloadFiles';

package/albumArt/maybeDownloadFiles.ts

@@ -0,0 +1,34 @@
+import { NetworkDevice } from '../network';
+import { FileTransfer } from '../services';
+import { getTempFilePath } from "../utils/getTempFilePath";
+import { strict as assert } from 'assert';
+import * as fs from 'fs';
+import minimist = require('minimist');
+import { Logger } from '../LogEmitter';
+
+export async function maybeDownloadFiles(controller: NetworkDevice) {
+	const args = minimist(process.argv.slice(2));
+	if (!args.disableFileTransfer) {
+		const ftx = await controller.connectToService(FileTransfer);
+		assert(ftx);
+		const sources = await ftx.getSources();
+		{
+			const sync = !args.skipsync;
+			for (const source of sources) {
+				const dbPath = getTempFilePath(source.database.location);
+				// FIXME: Move all this away from main
+				if (sync) {
+					const file = await ftx.getFile(source.database.location);
+					fs.writeFileSync(dbPath, file);
+					Logger.info(`downloaded: '${source.database.location}' and stored in '${dbPath}'`);
+				}
+				await controller.addSource(source.name, dbPath, getTempFilePath(`${source.name}/Album Art/`));
+
+				if (sync) {
+					await controller.dumpAlbumArt(source.name);
+				}
+			}
+			ftx.disconnect();
+		}
+	}
+}

package/cli/index.ts

@@ -0,0 +1,142 @@
+import { ActingAsDevice } from '../types';
+import { DbConnection } from "../Databases";
+import { sleep } from '../utils/sleep';
+import { StageLinq } from '../StageLinq';
+require('console-stamp')(console, {
+  format: ':date(HH:MM:ss) :label',
+});
+
+
+(async () => {
+
+  console.log('Starting CLI');
+
+  const stageLinqOptions = {
+
+    // If set to true, download the source DBs in a temporary location.
+    // (default: true)
+    downloadDbSources: true,
+
+    // Max number of attempts to connect to a StageLinq device.
+    // (default: 3)
+    maxRetries: 3,
+
+    // What device to emulate on the network.
+    // (default: Now Playing)
+    actingAs: ActingAsDevice.NowPlaying
+  }
+
+  const stageLinq = new StageLinq(stageLinqOptions);
+
+  // Setup how you want to handle logs coming from StageLinq
+  stageLinq.logger.on('error', (...args: any) => {
+    console.error(...args);
+  });
+  stageLinq.logger.on('warn', (...args: any) => {
+    console.warn(...args);
+  });
+  stageLinq.logger.on('info', (...args: any) => {
+    console.info(...args);
+  });
+  stageLinq.logger.on('log', (...args: any) => {
+    console.log(...args);
+  });
+  stageLinq.logger.on('debug', (...args: any) => {
+    console.debug(...args);
+  });
+  // Note: Silly is very verbose!
+  // stageLinq.logger.on('silly', (...args: any) => {
+  //   console.debug(...args);
+  // });
+
+  // Fires when we connect to any device
+  stageLinq.devices.on('connected', async (connectionInfo) => {
+    console.log(`Successfully connected to ${connectionInfo.software.name}`);
+
+    // Fires when the database source starts downloading.
+    stageLinq.databases.on('dbDownloading', (sourceName, dbPath) => {
+      console.log(`Downloading ${sourceName} to ${dbPath}`);
+    });
+
+    // Fires while the database source is being read
+    stageLinq.databases.on('dbProgress', (sourceName, total, bytes, percent) => {
+      console.debug(`Reading ${sourceName}: ${bytes}/${total} (${Math.ceil(percent)}%)`);
+    });
+
+    // Fires when the database source has been read and saved to a temporary path.
+    stageLinq.databases.on('dbDownloaded', (sourceName, dbPath) => {
+      console.log(`Database (${sourceName}) has been downloaded to ${dbPath}`);
+    });
+  });
+
+  // Fires when StageLinq has successfully connect to at least one device and is ready to use.
+  stageLinq.devices.on('ready', (connectionInfo) => {
+    console.log(`Device ${connectionInfo.software.name} is ready!`);
+  });
+
+  // Fires when a new track is loaded on to a player.
+  stageLinq.devices.on('trackLoaded', async (status) => {
+
+    // Example of how to connect to the database using this library's
+    // implementation of BetterSqlite3 to get additional information.
+    if (stageLinq.options.downloadDbSources && status.dbSourceName) {
+      try {
+        const connection = new DbConnection(stageLinq.databases.getDbPath(status.dbSourceName));
+        const result = connection.getTrackInfo(status.trackPath);
+        connection.close();
+        console.log('Database entry:', result);
+      } catch(e) {
+        console.error(e);
+      }
+    }
+    console.log('New track loaded:', status);
+  });
+
+  // Fires when a track has started playing.
+  stageLinq.devices.on('nowPlaying', (status) => {
+    console.log(`Now Playing on [${status.deck}]: ${status.title} - ${status.artist}`)
+  });
+
+  // Fires when StageLinq receives messages from a device.
+  stageLinq.devices.on('message', (connectionInfo, data) => {
+    const msg = data.message.json
+      ? JSON.stringify(data.message.json)
+      : data.message.interval;
+    console.debug(`${connectionInfo.address}:${connectionInfo.port} ` +
+      `${data.message.name} => ${msg}`);
+  });
+
+  // Fires when the state of a device has changed.
+  stageLinq.devices.on('stateChanged', (status) => {
+    console.log(`State changed on [${status.deck}]`, status)
+  });
+
+  let returnCode = 0;
+  try {
+    process.on('SIGINT', async function () {
+      console.info('... exiting');
+      // Ensure SIGINT won't be impeded by some error
+      try {
+        await stageLinq.disconnect();
+      } catch (err: any) {
+        const message = err.stack.toString();
+        console.error(message);
+      }
+      process.exit(returnCode);
+    });
+
+    await stageLinq.connect();
+
+    while (true) {
+      await sleep(250);
+    }
+
+  } catch (err: any) {
+    const message = err.stack.toString();
+    console.error(message);
+    returnCode = 1;
+  }
+
+  await stageLinq.disconnect();
+  process.exit(returnCode);
+})();

package/devices/Player.ts

@@ -0,0 +1,182 @@
+import { EventEmitter } from 'events';
+import { PlayerLayerState, PlayerStatus, ServiceMessage } from '../types';
+import { PlayerMessageQueue } from './PlayerMessageQueue';
+import { StateData, StateMap } from '../services';
+
+export declare interface Player {
+  on(event: 'trackLoaded', listener: (status: PlayerStatus) => void): this;
+  on(event: 'stateChanged', listener: (status: PlayerStatus) => void): this;
+  on(event: 'nowPlaying', listener: (status: PlayerStatus) => void): this;
+}
+
+//////////////////////////////////////////////////////////////////////////////
+
+interface PlayerOptions {
+  stateMap: StateMap;
+  address: string,
+  port: number;
+}
+
+interface SourceAndTrackPath {
+  source: string;
+  trackPath: string;
+}
+
+/**
+ * A player represents a device on the StageLinq network.
+ *
+ * A player on the network may have up to 4 decks (or "layers" as they're
+ * called on the harware). A player may also be given a player number.
+ *
+ * If you're using a Denon Prime Go/2/4 then you should only get one number.
+ * If you're using a Denon SC5000/SC6000 then you assign the numbers in the
+ * Denon's settings screen.
+ *
+ * Master tempo and master status only apply if you are using SC5000/SC6000
+ * and if they're both on the network.
+ *
+ * A queue is used to group all the incoming messages from StageLinq to give us
+ * a single updated PlayerStatus object.
+ */
+export class Player extends EventEmitter {
+
+  private player: number;           // Player number as reported by the device.
+  private address: string;          // IP address
+  private port: number;             // Port
+  private masterTempo: number;      // Current master tempo BPM
+  private masterStatus: boolean;    // If this device has the matser tempo
+  private decks: Map<string, PlayerLayerState> = new Map();
+  private queue: {[layer: string]: PlayerMessageQueue} = {};
+
+  /**
+   * Initialize a player device.
+   *
+   * @param networkDevice Network device
+   * @param stateMap Statemap service
+   */
+  constructor(options: PlayerOptions) {
+    super();
+    options.stateMap.on('message', this.messageHandler.bind(this));
+    this.address = options.address;
+    this.port = options.port;
+    this.queue = {
+      A: new PlayerMessageQueue('A').onDataReady(this.handleUpdate.bind(this)),
+      B: new PlayerMessageQueue('B').onDataReady(this.handleUpdate.bind(this)),
+      C: new PlayerMessageQueue('C').onDataReady(this.handleUpdate.bind(this)),
+      D: new PlayerMessageQueue('D').onDataReady(this.handleUpdate.bind(this)),
+    };
+  }
+
+  /**
+   * Parse the state data and push it into the update queue.
+   *
+   * @param data State data from Denon.
+   * @returns
+   */
+  private messageHandler(data: ServiceMessage<StateData>) {
+    const message = data.message
+    if (!message.json) return;
+    const name = message.name;
+    const json = message.json as any;
+
+    if (/Client\/Preferences\/Player$/.test(name)) {
+      this.player = parseInt(json.string);
+      return;
+    }
+    if (/Engine\/Master\/MasterTempo/.test(name)) {
+      this.masterTempo = json.value;
+      return;
+    }
+    if (/Engine\/Sync\/Network\/MasterStatus/.test(name)) {
+      this.masterStatus = json.state;
+      return;
+    }
+
+    const split = message.name.split('/');
+
+    const deck =
+      (/PlayerJogColor[A-D]$/.test(name)) ? split[3].replace('PlayerJogColor', '')
+      : (/Engine\/Deck\d\//.test(name)) ? this.deckNumberToLayer(split[2])
+      : null;
+
+    const cueData =
+        (/PlayState$/.test(name)) ? { playState: json.state }
+      : (/Track\/TrackNetworkPath$/.test(name)) ? {
+          trackNetworkPath: json.string,
+          source: this.getSourceAndTrackPath(json.string).source,
+          trackPath: this.getSourceAndTrackPath(json.string).trackPath
+        }
+      : (/Track\/SongLoaded$/.test(name)) ? { songLoaded: json.state }
+      : (/Track\/SongName$/.test(name)) ? { title: json.string }
+      : (/Track\/ArtistName$/.test(name)) ? { artist: json.string }
+      : (/Track\/TrackData$/.test(name)) ? { hasTrackData: json.state }
+      : (/Track\/TrackName$/.test(name)) ? { fileLocation: json.string }
+      : (/CurrentBPM$/.test(name)) ? { currentBpm: json.value }
+      : (/ExternalMixerVolume$/.test(name)) ? { externalMixerVolume: json.value }
+      : (/Play$/.test(name)) ? { play: json.state }
+      : (/PlayerJogColor[A-D]$/.test(name)) ? { jogColor: json.color }
+      : null;
+
+    if (cueData) {
+      this.queue[deck].push({ layer: deck, ...cueData });
+    }
+  }
+
+  /**
+   * Update current state and emit.
+   * @param data
+   */
+  private handleUpdate(data: PlayerLayerState) {
+    const layer = data.layer;
+    const songLoadedSignalPresent = data.hasOwnProperty('songLoaded');
+
+    // If a new song is loaded drop all the previous track data.
+    if (songLoadedSignalPresent) {
+      this.decks.set(layer, data);
+    } else {
+      this.decks.set(layer, { ...this.decks.get(layer), ...data });
+    }
+
+    const result = this.decks.get(layer);
+    const deck = `${this.player}${result.layer}`;
+
+    const output = {
+      deck: deck,
+      player: this.player,
+      layer: layer,
+      address: this.address,
+      port: this.port,
+      masterTempo: this.masterTempo,
+      masterStatus: this.masterStatus,
+      ...result
+    };
+
+    // We're casting it because we originally built it up piecemeal.
+    const currentState = output as PlayerStatus;
+    currentState.dbSourceName = currentState.source ? `${this.address}_${this.port}_${currentState.source}` : '';
+    if (songLoadedSignalPresent && currentState.trackNetworkPath) this.emit('trackLoaded', currentState);
+    if (result.playState) this.emit('nowPlaying', currentState);
+    this.emit('stateChanged', currentState);
+  }
+
+  private deckNumberToLayer(deck: string) {
+    const index = parseInt(deck.replace('Deck', '')) - 1;
+    return 'ABCD'[index];
+  }
+
+  private getSourceAndTrackPath(p_path: string): SourceAndTrackPath {
+    if (!p_path || p_path.length === 0) return { source: '', trackPath: '' };
+    const parts = p_path.split('/');
+    const source = parts[3];
+    let trackPath = parts.slice(5).join('/');
+    if (parts[4] !== 'Engine Library') {
+      // This probably occurs with RekordBox conversions; tracks are outside Engine Library folder
+      trackPath = `../${parts[4]}/${trackPath}`;
+    }
+    return {
+      source: source,
+      trackPath: trackPath,
+    };
+  }
+
+}

package/devices/PlayerMessageQueue.ts

@@ -0,0 +1,62 @@
+import { PlayerLayerState } from '../types';
+
+// How long to wait for all the messages to come in before firing the callback.
+export const UPDATE_RATE_MS = 500;
+
+export type DataQueueCallback = (data: PlayerLayerState) => void;
+
+/**
+ * Collect all the messages from a player together and return it as one object.
+ *
+ * The Denon hardware will fire several messages in quick succession. This will
+ * take them all in, then after UPDATE_RATE_MS will merge all the data
+ * as a single update to the `onDataReady` callback.
+ *
+ * For example, when you move the fader up you get several ExternalMixerVolume
+ * messages where the value goes up from 0 to 1. Instead firing off loads
+ * of updates we're only interested in the last one.
+ */
+export class PlayerMessageQueue {
+
+  private callback: DataQueueCallback;
+  private data: PlayerLayerState[] = [];
+  private timeout: NodeJS.Timer | null = null;
+  private layer: string;
+
+  constructor(layer: string) {
+    this.layer = layer;
+  }
+
+  /**
+   * Push data into the queue.
+   * @param data Parsed data from a player.
+   */
+  push(data: PlayerLayerState) {
+    this.data.push(data);
+    if (!this.timeout) {
+      this.timeout = setTimeout(this.emptyCue.bind(this), UPDATE_RATE_MS);
+    }
+  }
+
+  /**
+   * Merge data, empty the queue, clear the timeout, and fire the callback.
+   */
+  emptyCue() {
+    let output: any = { layer: this.layer };
+    this.data.map(d => { output = { ...output, ...d }; });
+    this.data = [];
+    clearTimeout(this.timeout);
+    this.timeout = null;
+    this.callback(output as PlayerLayerState);
+  }
+
+  /**
+   * Execute this callback when there is new data from the Denon hardware.
+   * @param callback User callback when we have an update.
+   * @returns
+   */
+  onDataReady(callback: DataQueueCallback) {
+    this.callback = callback;
+    return this;
+  }
+}

package/index.ts

@@ -0,0 +1,5 @@
+export * from './network';
+export * from './services';
+export * from './StageLinq';
+export * from './types';
+export * from './utils';