org.deepsymmetry.beatlink.data

Class SignatureFinder

java.lang.Object

org.deepsymmetry.beatlink.LifecycleParticipant

org.deepsymmetry.beatlink.data.SignatureFinder

public class SignatureFinder
extends LifecycleParticipant

Watches for new metadata to become available for tracks loaded on players, and when enough elements have been loaded, calculates a signature string that uniquely identifies the track, based on its title, artist, duration, waveform, and beat grid. Reports the signatures to any registered listeners once they have been identified. This supports the efficient triggering of cues based on the recognition of specific tracks, regardless of the media from which they have been loaded.

Author:

James Elliott

Method Summary

Modifier and Type	Method and Description
void	addSignatureListener(SignatureListener listener) Adds the specified signature listener to receive updates when the track signature for a player changes.
String	computeTrackSignature(String title, String artist, int duration, WaveformDetail waveformDetail, BeatGrid beatGrid) Calculate the signature by which we can reliably recognize a loaded track.
static SignatureFinder	getInstance() Get the singleton instance of this class.
String	getLatestSignatureFor(DeviceUpdate update) Look up the signature we have calculated for the track loaded in a player, identified by a status update received from that player.
String	getLatestSignatureFor(int player) Look up the signature we have calculated for the track loaded in the specified player.
Set<SignatureListener>	getSignatureListeners() Get the set of currently-registered signature listeners.
Map<Integer,String>	getSignatures() Get the signatures that have been computed for all tracks currently loaded in any player for which we have been able to obtain all necessary metadata.
boolean	isRunning() Check whether we are currently running.
void	removeSignatureListener(SignatureListener listener) Removes the specified signature listener so that it no longer receives updates when the track signature for a player changes.
void	start() Start finding waveforms for all active players.
void	stop() Stop finding signatures 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.

Specified by:

isRunning in class LifecycleParticipant

Returns:

true if track signatures are being computed for all active players

See Also:

MetadataFinder.isPassive()

getSignatures

public Map<Integer,String> getSignatures()

Get the signatures that have been computed for all tracks currently loaded in any player for which we have been able to obtain all necessary metadata.

Returns:

the signatures that uniquely identify the tracks loaded in each player

Throws:

IllegalStateException - if the SignatureFinder is not running

getLatestSignatureFor

public String getLatestSignatureFor(int player)

Look up the signature we have calculated for the track loaded in the specified player.

Parameters:

player - the player whose track signature is desired

Returns:

the track signature if we have been able to compute one

Throws:

IllegalStateException - if the SignatureFinder is not running

getLatestSignatureFor

public String getLatestSignatureFor(DeviceUpdate update)

Look up the signature we have calculated for the track loaded in a player, identified by a status update received from that player.

Parameters:

update - a status update from the player for which a track signature is desired

Returns:

the track signature if we have been able to compute one

Throws:

IllegalStateException - if the SignatureFinder is not running

addSignatureListener

public void addSignatureListener(SignatureListener listener)

Adds the specified signature listener to receive updates when the track signature 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 track signature update listener to add

removeSignatureListener

public void removeSignatureListener(SignatureListener listener)

Removes the specified signature listener so that it no longer receives updates when the track signature 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 track signature update listener to remove

getSignatureListeners

public Set<SignatureListener> getSignatureListeners()

Get the set of currently-registered signature listeners.

Returns:

the listeners that are currently registered for track signature updates

computeTrackSignature

public String computeTrackSignature(String title,
                                    String artist,
                                    int duration,
                                    WaveformDetail waveformDetail,
                                    BeatGrid beatGrid)

Calculate the signature by which we can reliably recognize a loaded track.

Parameters:

title - the track title

artist - the track artist

duration - the duration of the track in seconds

waveformDetail - the monochrome waveform detail of the track

beatGrid - the beat grid of the track

Returns:

the SHA-1 hash of all the arguments supplied, or null if any arguments were null

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 WaveformFinder and BeatGridFinder in order get the other pieces of information we need for computing track signatures.

Throws:

Exception - if there is a problem starting the required components

stop

public void stop()

Stop finding signatures for all active players.

getInstance

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