org.deepsymmetry.beatlink

Class VirtualCdj

java.lang.Object

org.deepsymmetry.beatlink.VirtualCdj

public class VirtualCdj
extends Object

Provides the ability to create a virtual CDJ device that can lurk on a DJ Link network and receive packets sent to players, monitoring the detailed state of the other devices. This detailed information is helpful for augmenting what BeatFinder reports, allowing you to keep track of which player is the tempo master, how many beats of a track have been played, how close a player is getting to its next cue point, and more.

Author:

James Elliott

Field Summary

Fields

Modifier and Type	Field and Description
static int	UPDATE_PORT The port to which other devices will send status update messages.

Method Summary

Modifier and Type	Method and Description
static void	addMasterListener(MasterListener listener) Adds the specified master listener to receive device updates when there are changes related to the tempo master.
static void	addUpdateListener(DeviceUpdateListener listener) Adds the specified device update listener to receive device updates whenever they come in.
static int	getAnnounceInterval() Get the interval, in milliseconds, at which we broadcast presence announcements on the network to pose as a virtual CDJ.
static InetAddress	getBroadcastAddress() Return the broadcast address used to reach the DJ Link network.
static String	getDeviceName() Get the name to be used in announcing our presence on the network.
static byte	getDeviceNumber() Get the device number that is used when sending presence announcements on the network to pose as a virtual CDJ.
static Set<DeviceUpdate>	getLatestStatus() Get the most recent status we have seen from all devices that are recent enough to be considered still active on the network.
static DeviceUpdate	getLatestStatusFor(DeviceAnnouncement device) Look up the most recent status we have seen for a device, given its device announcement packet as returned by DeviceFinder.currentDevices().
static DeviceUpdate	getLatestStatusFor(DeviceUpdate device) Look up the most recent status we have seen for a device, given another update from it, which might be a beat packet containing far less information.
static DeviceUpdate	getLatestStatusFor(int deviceNumber) Look up the most recent status we have seen for a device from a device identifying itself with the specified device number, if any.
static InetAddress	getLocalAddress() Return the address being used by the virtual CDJ to send its own presence announcement broadcasts, so they can be filtered out by the DeviceFinder.
static Set<MasterListener>	getMasterListeners() Get the set of master listeners that are currently registered.
static double	getMasterTempo() Get the current master tempo.
static double	getTempoEpsilon() Find out how large a tempo change is required before we consider it to be a real difference.
static DeviceUpdate	getTempoMaster() Check which device is the current tempo master, returning the DeviceUpdate packet in which it reported itself to be master.
static Set<DeviceUpdateListener>	getUpdateListeners() Get the set of device update listeners that are currently registered.
static boolean	isActive() Check whether we are presently posing as a virtual CDJ and receiving device status updates.
static void	removeMasterListener(MasterListener listener) Removes the specified master listener so that it no longer receives device updates when there are changes related to the tempo master.
static void	removeUpdateListener(DeviceUpdateListener listener) Removes the specified device update listener so it no longer receives device updates when they come in.
static void	setAnnounceInterval(int interval) Set the interval, in milliseconds, at which we broadcast presence announcements on the network to pose as a virtual CDJ.
static void	setDeviceName(String name) Set the name to be used in announcing our presence on the network.
static void	setDeviceNumber(byte number) Set the device number to be used when sending presence announcements on the network to pose as a virtual CDJ.
static void	setTempoEpsilon(double epsilon) Set how large a tempo change is required before we consider it to be a real difference.
static boolean	start() Start announcing ourselves and listening for status packets.
static void	stop() Stop announcing ourselves and listening for status updates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UPDATE_PORT

public static final int UPDATE_PORT

The port to which other devices will send status update messages.

See Also:

Constant Field Values

Method Detail

isActive

public static boolean isActive()

Check whether we are presently posing as a virtual CDJ and receiving device status updates.

Returns:

true if our socket is open, sending presence announcements, and receiving status packets

getLocalAddress

public static InetAddress getLocalAddress()

Return the address being used by the virtual CDJ to send its own presence announcement broadcasts, so they can be filtered out by the DeviceFinder.

Returns:

the local address we present to the DJ Link network

Throws:

IllegalStateException - if the VirtualCdj is not active

getBroadcastAddress

public static InetAddress getBroadcastAddress()

Return the broadcast address used to reach the DJ Link network.

Returns:

the address on which packets can be broadcast to the other DJ Link devices

Throws:

IllegalStateException - if the VirtualCdj is not active

getDeviceNumber

public static byte getDeviceNumber()

Get the device number that is used when sending presence announcements on the network to pose as a virtual CDJ.

Returns:

the virtual player number

setDeviceNumber

public static void setDeviceNumber(byte number)

Set the device number to be used when sending presence announcements on the network to pose as a virtual CDJ.

Parameters:

number - the virtual player number

getAnnounceInterval

public static int getAnnounceInterval()

Get the interval, in milliseconds, at which we broadcast presence announcements on the network to pose as a virtual CDJ.

Returns:

the announcement interval

setAnnounceInterval

public static void setAnnounceInterval(int interval)

Set the interval, in milliseconds, at which we broadcast presence announcements on the network to pose as a virtual CDJ.

Parameters:

interval - the announcement interval

Throws:

IllegalArgumentException - if interval is not between 200 and 2000

getDeviceName

public static String getDeviceName()

Get the name to be used in announcing our presence on the network.

Returns:

the device name reported in our presence announcement packets

setDeviceName

public static void setDeviceName(String name)

Set the name to be used in announcing our presence on the network. The name can be no longer than twenty bytes, and should be normal ASCII, no Unicode.

Parameters:

name - the device name to report in our presence announcement packets.

getTempoMaster

public static DeviceUpdate getTempoMaster()

Check which device is the current tempo master, returning the DeviceUpdate packet in which it reported itself to be master. If there is no current tempo master returns null.

Returns:

the most recent update from a device which reported itself as the master

Throws:

IllegalStateException - if the VirtualCdj is not active

getTempoEpsilon

public static double getTempoEpsilon()

Find out how large a tempo change is required before we consider it to be a real difference.

Returns:

the BPM fraction that will trigger a tempo change update

setTempoEpsilon

public static void setTempoEpsilon(double epsilon)

Set how large a tempo change is required before we consider it to be a real difference.

Parameters:

epsilon - the BPM fraction that will trigger a tempo change update

getMasterTempo

public static double getMasterTempo()

Get the current master tempo.

Returns:

the most recently reported master tempo

Throws:

IllegalStateException - if the VirtualCdj is not active

start

public static boolean start()
                     throws SocketException

Start announcing ourselves and listening for status packets. If already active, has no effect. Requires the DeviceFinder to be active in order to find out how to communicate with other devices, so will start that if it is not already.

Returns:

true if we found DJ Link devices and were able to create the VirtualCdj, or it was already running.

Throws:

SocketException - if the socket to listen on port 50002 cannot be created

stop

public static void stop()

Stop announcing ourselves and listening for status updates.

getLatestStatus

public static Set<DeviceUpdate> getLatestStatus()

Get the most recent status we have seen from all devices that are recent enough to be considered still active on the network.

Returns:

the most recent detailed status update received for all active devices

Throws:

IllegalStateException - if the VirtualCdj is not active

getLatestStatusFor

public static DeviceUpdate getLatestStatusFor(DeviceUpdate device)

Look up the most recent status we have seen for a device, given another update from it, which might be a beat packet containing far less information.

Parameters:

device - the update identifying the device for which current status information is desired

Returns:

the most recent detailed status update received for that device

Throws:

IllegalStateException - if the VirtualCdj is not active

getLatestStatusFor

public static DeviceUpdate getLatestStatusFor(DeviceAnnouncement device)

Look up the most recent status we have seen for a device, given its device announcement packet as returned by DeviceFinder.currentDevices().

Parameters:

device - the announcement identifying the device for which current status information is desired

Returns:

the most recent detailed status update received for that device

Throws:

IllegalStateException - if the VirtualCdj is not active

getLatestStatusFor

public static DeviceUpdate getLatestStatusFor(int deviceNumber)

Look up the most recent status we have seen for a device from a device identifying itself with the specified device number, if any.

Parameters:

deviceNumber - the device number of interest

Returns:

the matching detailed status update or null if none have been received

Throws:

IllegalStateException - if the VirtualCdj is not active

addMasterListener

public static void addMasterListener(MasterListener listener)

Adds the specified master listener to receive device updates when there are changes related to the tempo master. If listener is null or already present in the list of registered listeners, no exception is thrown and no action is performed.

To reduce latency, tempo master updates are delivered to listeners directly on the thread that is receiving them from the network, so if you want to interact with user interface objects in listener methods, you need to use javax.swing.SwingUtilities.invokeLater(Runnable) to do so on the Event Dispatch Thread. Even if you are not interacting with user interface objects, any code in the listener method must finish quickly, or it will add latency for other listeners, and master updates will back up. If you want to perform lengthy processing of any sort, do so on another thread.

Parameters:

listener - the master listener to add

removeMasterListener

public static void removeMasterListener(MasterListener listener)

Removes the specified master listener so that it no longer receives device updates when there are changes related to the tempo master. If listener is null or not present in the list of registered listeners, no exception is thrown and no action is performed.

Parameters:

listener - the master listener to remove

getMasterListeners

public static Set<MasterListener> getMasterListeners()

Get the set of master listeners that are currently registered.

Returns:

the currently registered tempo master listeners

addUpdateListener

public static void addUpdateListener(DeviceUpdateListener listener)

Adds the specified device update listener to receive device updates whenever they come in. If listener is null or already present in the list of registered listeners, no exception is thrown and no action is performed.

To reduce latency, device updates are delivered to listeners directly on the thread that is receiving them from the network, so if you want to interact with user interface objects in listener methods, you need to use javax.swing.SwingUtilities.invokeLater(Runnable) to do so on the Event Dispatch Thread. Even if you are not interacting with user interface objects, any code in the listener method must finish quickly, or it will add latency for other listeners, and device updates will back up. If you want to perform lengthy processing of any sort, do so on another thread.

Parameters:

listener - the device update listener to add

removeUpdateListener

public static void removeUpdateListener(DeviceUpdateListener listener)

Removes the specified device update listener so it no longer receives device updates when they come in. If listener is null or not present in the list of registered listeners, no exception is thrown and no action is performed.

Parameters:

listener - the device update listener to remove

getUpdateListeners

public static Set<DeviceUpdateListener> getUpdateListeners()

Get the set of device update listeners that are currently registered.

Returns:

the currently registered update listeners