org.deepsymmetry.beatlink.data

Class WaveformFinder

java.lang.Object

org.deepsymmetry.beatlink.LifecycleParticipant

org.deepsymmetry.beatlink.data.WaveformFinder

public class WaveformFinder
extends LifecycleParticipant

Watches for new metadata to become available for tracks loaded on players, and queries the appropriate player for track waveforms when that happens. Can be configured to load only the small waveform previews, or both those and the full scrollable waveform details.

Maintains a hot cache of waveforms 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 art is loaded in response to metadata updates.

Author:

James Elliott

Method Summary

Modifier and Type	Method and Description
void	addWaveformListener(WaveformListener listener) Adds the specified waveform listener to receive updates when the waveform information for a player changes.
WaveformDetail	getCachedWaveformDetail(ZipFile cache, DataReference dataReference) Look up waveform detail in a metadata cache.
WaveformPreview	getCachedWaveformPreview(ZipFile cache, DataReference dataReference) Look up a waveform preview in a metadata cache.
static WaveformFinder	getInstance() Get the singleton instance of this class.
WaveformDetail	getLatestDetailFor(DeviceUpdate update) Look up the waveform detail we have for a given player, identified by a status update received from that player.
WaveformDetail	getLatestDetailFor(int player) Look up the waveform detail we have for the track loaded in the main deck of a given player number.
WaveformPreview	getLatestPreviewFor(DeviceUpdate update) Look up the waveform preview we have for a given player, identified by a status update received from that player.
WaveformPreview	getLatestPreviewFor(int player) Look up the waveform preview we have for the track loaded in the main deck of a given player number.
Map<DeckReference,WaveformDetail>	getLoadedDetails() Get the waveform details available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.
Map<DeckReference,WaveformPreview>	getLoadedPreviews() Get the waveform previews available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.
Set<WaveformListener>	getWaveformListeners() Get the set of currently-registered waveform listeners.
boolean	isFindingDetails() Check whether we are retrieving the waveform details in addition to the waveform previews.
boolean	isRunning() Check whether we are currently running.
void	removeWaveformListener(WaveformListener listener) Removes the specified waveform listener so that it no longer receives updates when the waveform information for a player changes.
WaveformDetail	requestWaveformDetailFrom(DataReference dataReference) Ask the specified player for the specified waveform detail from the specified media slot, first checking if we have a cached copy.
WaveformPreview	requestWaveformPreviewFrom(DataReference dataReference) Ask the specified player for the specified waveform preview from the specified media slot, first checking if we have a cached copy.
void	setFindDetails(boolean findDetails) Set whether we should retrieve the waveform details in addition to the waveform previews.
void	start() Start finding waveforms for all active players.
void	stop() Stop finding waveforms 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

setFindDetails

public final void setFindDetails(boolean findDetails)

Set whether we should retrieve the waveform details in addition to the waveform previews.

Parameters:

findDetails - if true, both types of waveform will be retrieved, if false only previews will be retrieved

isFindingDetails

public final boolean isFindingDetails()

Check whether we are retrieving the waveform details in addition to the waveform previews.

Returns:

true if both types of waveform are being retrieved, false if only previews are being retrieved

isRunning

public boolean isRunning()

Check whether we are currently running. Unless the MetadataFinder is in passive mode, we will automatically request waveforms 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 waveforms are being kept track of for all active players

See Also:

MetadataFinder.isPassive()

getLoadedPreviews

public Map<DeckReference,WaveformPreview> getLoadedPreviews()

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

Returns:

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

Throws:

IllegalStateException - if the WaveformFinder is not running

getLoadedDetails

public Map<DeckReference,WaveformDetail> getLoadedDetails()

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

Returns:

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

Throws:

IllegalStateException - if the WaveformFinder is not running or requesting waveform details

getLatestPreviewFor

public WaveformPreview getLatestPreviewFor(int player)

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

Parameters:

player - the device number whose waveform preview for the playing track is desired

Returns:

the waveform preview for the track loaded on that player, if available

Throws:

IllegalStateException - if the WaveformFinder is not running

getLatestPreviewFor

public WaveformPreview getLatestPreviewFor(DeviceUpdate update)

Look up the waveform preview 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 waveform preview is desired

Returns:

the waveform preview for the track loaded on that player, if available

Throws:

IllegalStateException - if the WaveformFinder is not running

getLatestDetailFor

public WaveformDetail getLatestDetailFor(int player)

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

Parameters:

player - the device number whose waveform detail for the playing track is desired

Returns:

the waveform detail for the track loaded on that player, if available

Throws:

IllegalStateException - if the WaveformFinder is not running

getLatestDetailFor

public WaveformDetail getLatestDetailFor(DeviceUpdate update)

Look up the waveform detail 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 waveform detail is desired

Returns:

the waveform detail for the track loaded on that player, if available

Throws:

IllegalStateException - if the WaveformFinder is not running

requestWaveformPreviewFrom

public WaveformPreview requestWaveformPreviewFrom(DataReference dataReference)

Ask the specified player for the specified waveform preview from the specified media slot, first checking if we have a cached copy.

Parameters:

dataReference - uniquely identifies the desired waveform preview

Returns:

the preview, if it was found, or null

Throws:

IllegalStateException - if the WaveformFinder is not running

getCachedWaveformPreview

public WaveformPreview getCachedWaveformPreview(ZipFile cache,
                                                DataReference dataReference)

Look up a waveform preview in a metadata cache.

Parameters:

cache - the appropriate metadata cache file

dataReference - the unique database specification of the desired waveform preview

Returns:

the cached waveform preview (if available), or null

requestWaveformDetailFrom

public WaveformDetail requestWaveformDetailFrom(DataReference dataReference)

Ask the specified player for the specified waveform detail from the specified media slot, first checking if we have a cached copy.

Parameters:

dataReference - uniquely identifies the desired waveform detail

Returns:

the waveform detail, if it was found, or null

Throws:

IllegalStateException - if the WaveformFinder is not running

getCachedWaveformDetail

public WaveformDetail getCachedWaveformDetail(ZipFile cache,
                                              DataReference dataReference)

Look up waveform detail in a metadata cache.

Parameters:

cache - the appropriate metadata cache file

dataReference - the unique database specification of the desired waveform detail

Returns:

the cached waveform detail (if available), or null

addWaveformListener

public void addWaveformListener(WaveformListener listener)

Adds the specified waveform listener to receive updates when the waveform 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

removeWaveformListener

public void removeWaveformListener(WaveformListener listener)

Removes the specified waveform listener so that it no longer receives updates when the waveform 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

getWaveformListeners

public Set<WaveformListener> getWaveformListeners()

Get the set of currently-registered waveform listeners.

Returns:

the listeners that are currently registered for waveform updates

start

public void start()
           throws Exception

Start finding waveforms 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 waveforms.

Throws:

Exception - if there is a problem starting the required components

stop

public void stop()

Stop finding waveforms for all active players.

getInstance

public static WaveformFinder 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