Package org.deepsymmetry.beatlink.data

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