org.deepsymmetry.beatlink.data

Class BeatGridFinder

java.lang.Object

org.deepsymmetry.beatlink.LifecycleParticipant

org.deepsymmetry.beatlink.data.BeatGridFinder

public class BeatGridFinder
extends LifecycleParticipant

Watches for new metadata to become available for tracks loaded on players, and queries the appropriate player for the track beat grid when that happens.

Maintains a hot cache of beat grids for any track currently loaded in a player, either on the main playback deck, or as a hot cue, since those tracks could start playing instantly.

Implicitly honors the active/passive setting of the MetadataFinder (see MetadataFinder.setPassive(boolean)), because beat grids are loaded in response to metadata updates.

Method Summary

Modifier and Type	Method and Description
void	addBeatGridListener(BeatGridListener listener) Adds the specified beat grid listener to receive updates when the beat grid information for a player changes.
Set<BeatGridListener>	getBeatGridListeners() Get the set of currently-registered beat grid listeners.
BeatGrid	getCachedBeatGrid(ZipFile cache, DataReference reference) Look up a beat grid in a metadata cache.
static BeatGridFinder	getInstance() Get the singleton instance of this class.
BeatGrid	getLatestBeatGridFor(DeviceUpdate update) Look up the beat grid we have for a given player, identified by a status update received from that player.
BeatGrid	getLatestBeatGridFor(int player) Look up the beat grid we have for the track loaded in the main deck of a given player number.
Map<DeckReference,BeatGrid>	getLoadedBeatGrids() Get the beat grids available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.
boolean	isRunning() Check whether we are currently running.
void	removeBeatGridListener(BeatGridListener listener) Removes the specified beat grid listener so that it no longer receives updates when the beat grid information for a player changes.
BeatGrid	requestBeatGridFrom(DataReference track) Ask the specified player for the beat grid of the track in the specified slot with the specified rekordbox ID, first checking if we have a cache we can use instead.
void	start() Start finding beat grids for all active players.
void	stop() Stop finding beat grids for all active players.
String	toString()

Methods inherited from class org.deepsymmetry.beatlink.LifecycleParticipant

addLifecycleListener, deliverLifecycleAnnouncement, ensureRunning, getLifecycleListeners, removeLifecycleListener

Methods inherited from class java.lang.Object

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

Method Detail

isRunning

public boolean isRunning()

Check whether we are currently running. Unless the MetadataFinder is in passive mode, we will automatically request beat grids from the appropriate player when a new track is loaded that is not found in the hot cache or an attached metadata cache file.

Specified by:

isRunning in class LifecycleParticipant

Returns:

true if beat grids are being kept track of for all active players

See Also:

MetadataFinder.isPassive()

getLoadedBeatGrids

public Map<DeckReference,BeatGrid> getLoadedBeatGrids()

Get the beat grids available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.

Returns:

the beat grids associated with all current players, including for any tracks loaded in their hot cue slots

Throws:

IllegalStateException - if the BeatGridFinder is not running

getLatestBeatGridFor

public BeatGrid getLatestBeatGridFor(int player)

Look up the beat grid we have for the track loaded in the main deck of a given player number.

Parameters:

player - the device number whose beat grid for the playing track is desired

Returns:

the beat grid for the track loaded on that player, if available

Throws:

IllegalStateException - if the BeatGridFinder is not running

getLatestBeatGridFor

public BeatGrid getLatestBeatGridFor(DeviceUpdate update)

Look up the beat grid we have for a given player, identified by a status update received from that player.

Parameters:

update - a status update from the player for which a beat grid is desired

Returns:

the beat grid for the track loaded on that player, if available

Throws:

IllegalStateException - if the BeatGridFinder is not running

requestBeatGridFrom

public BeatGrid requestBeatGridFrom(DataReference track)

Ask the specified player for the beat grid of the track in the specified slot with the specified rekordbox ID, first checking if we have a cache we can use instead.

Parameters:

track - uniquely identifies the track whose beat grid is desired

Returns:

the beat grid, if any

getCachedBeatGrid

public BeatGrid getCachedBeatGrid(ZipFile cache,
                                  DataReference reference)

Look up a beat grid in a metadata cache.

Parameters:

cache - the appropriate metadata cache file

reference - the track whose beat grid is desired

Returns:

the cached beat grid (if available), or null

addBeatGridListener

public void addBeatGridListener(BeatGridListener listener)

Adds the specified beat grid listener to receive updates when the beat grid information for a player changes. If listener is null or already present in the set of registered listeners, no exception is thrown and no action is performed.

To reduce latency, updates are delivered to listeners directly on the thread that is receiving packets 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 updates will back up. If you want to perform lengthy processing of any sort, do so on another thread.

Parameters:

listener - the album art update listener to add

removeBeatGridListener

public void removeBeatGridListener(BeatGridListener listener)

Removes the specified beat grid listener so that it no longer receives updates when the beat grid information for a player changes. If listener is null or not present in the set of registered listeners, no exception is thrown and no action is performed.

Parameters:

listener - the waveform listener to remove

getBeatGridListeners

public Set<BeatGridListener> getBeatGridListeners()

Get the set of currently-registered beat grid listeners.

Returns:

the listeners that are currently registered for beat grid updates

start

public void start()
           throws Exception

Start finding beat grids for all active players. Starts the MetadataFinder if it is not already running, because we need it to send us metadata updates to notice when new tracks are loaded. This in turn starts the DeviceFinder, so we can keep track of the comings and goings of players themselves. We also start the ConnectionManager in order to make queries to obtain beat grids.

Throws:

Exception - if there is a problem starting the required components

stop

public void stop()

Stop finding beat grids for all active players.

getInstance

public static BeatGridFinder getInstance()

Get the singleton instance of this class.

Returns:

the only instance of this class which exists.

toString

public String toString()

Overrides:

toString in class Object