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 waveforms are 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.
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	isColorPreferred() Check whether we are retrieving color versions of waveforms and previews when they are available.
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	setColorPreferred(boolean preferColor) Set whether we should obtain color versions of waveforms and previews when they are available.
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

setColorPreferred

public final void setColorPreferred(boolean preferColor)

Set whether we should obtain color versions of waveforms and previews when they are available. This will only affect waveforms loaded after the setting has been changed. If this changes the setting, and we were running, stop and restart in order to flush and reload the correct waveform versions.

Parameters:

preferColor - if true, the full-color versions of waveforms will be requested, if false only the older blue versions will be retrieved

isColorPreferred

public final boolean isColorPreferred()

Check whether we are retrieving color versions of waveforms and previews when they are available.

Returns:

true if full-color of waveform are being retrieved, false if the older blue versions 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

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

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.

Updates are delivered to listeners on the Swing Event Dispatch thread, so it is safe to interact with user interface elements within the event handler. Even so, any code in the listener method must finish quickly, or it will freeze the user interface, 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 waveform 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 update 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