Class 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 Detail

      • 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,
                                            SearchableItem 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, or null if there is no 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 either waveFormDetail or beatGrid 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.