Package org.deepsymmetry.beatlink.data

Class ArtFinder

  • public class ArtFinder
extends LifecycleParticipant

    Watches for new metadata to become available for tracks loaded on players, and queries the appropriate player for the album art when that happens.

    Maintains a hot cache of art 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. Also maintains a second-level in-memory cache of artwork, discarding the least-recently-used art when the cache fills, because tracks can share artwork, so the DJ may load another track with the same album art.

    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

    • Field Detail

      • DEFAULT_ART_CACHE_SIZE

        public static final int DEFAULT_ART_CACHE_SIZE
        The maximum number of artwork images we will retain in our cache.
        See Also:
        Constant Field Values

    • Method Detail

      • isRunning

        public boolean isRunning()
        Check whether we are currently running. Unless the MetadataFinder is in passive mode, we will automatically request album art from the appropriate player when a new track is loaded that is not found in the hot cache, second-level memory cache, or an attached metadata cache file.
        Specified by:
        isRunning in class LifecycleParticipant
        Returns:
        true if album art is being kept track of for all active players
        See Also:
        MetadataFinder.isPassive()

      • getLoadedArt

        public Map<DeckReference,​AlbumArt> getLoadedArt()
        Get the art available for all tracks currently loaded in any player, either on the play deck, or in a hot cue.
        Returns:
        the album art associated with all current players, including for any tracks loaded in their hot cue slots
        Throws:
        IllegalStateException - if the ArtFinder is not running

      • getLatestArtFor

        public AlbumArt getLatestArtFor​(int player)
        Look up the album art we have for the track loaded in the main deck of a given player number.
        Parameters:
        player - the device number whose album art for the playing track is desired
        Returns:
        the album art for the track loaded on that player, if available
        Throws:
        IllegalStateException - if the ArtFinder is not running

      • getLatestArtFor

        public AlbumArt getLatestArtFor​(DeviceUpdate update)
        Look up the album art 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 album art is desired
        Returns:
        the album art for the track loaded on that player, if available
        Throws:
        IllegalStateException - if the ArtFinder is not running

      • getArtCacheSize

        public long getArtCacheSize()
        Check how many album art images can be kept in the in-memory second-level cache.
        Returns:
        the maximum number of distinct album art images that will automatically be kept for reuse in the in-memory art cache.

      • setArtCacheSize

        public void setArtCacheSize​(int size)
        Set how many album art images can be kept in the in-memory second-level cache.
        Parameters:
        size - the maximum number of distinct album art images that will automatically be kept for reuse in the in-memory art cache; if you set this to a smaller number than are currently present in the cache, some of the older images will be immediately discarded so that only the number you specified remain
        Throws:
        IllegalArgumentException - if size is less than 1

      • getRequestHighResolutionArt

        public boolean getRequestHighResolutionArt()
        Check whether we are requesting high-resolution artwork when it is available.
        Returns:
        true if we attempt to obtain high-resolution versions of artwork, falling back to normal resolution when unavailable.

      • setRequestHighResolutionArt

        public void setRequestHighResolutionArt​(boolean shouldRequest)
        Set whether we should attempt to obtain high resolution art when it is available.
        Parameters:
        shouldRequest - if true we will try to obtain high-resolution art first, falling back to the ordinary resolution if it is not available.

      • requestArtworkFrom

        public AlbumArt requestArtworkFrom​(DataReference artReference,
                                   CdjStatus.TrackType trackType)
        Ask the specified player for the specified artwork from the specified media slot, first checking if we have a cached copy.
        Parameters:
        artReference - uniquely identifies the desired artwork
        trackType - the kind of track that owns the artwork
        Returns:
        the artwork, if it was found, or null
        Throws:
        IllegalStateException - if the ArtFinder is not running

      • addAlbumArtListener

        public void addAlbumArtListener​(AlbumArtListener listener)

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

      • removeAlbumArtListener

        public void removeAlbumArtListener​(AlbumArtListener listener)
        Removes the specified album art listener so that it no longer receives updates when the album art 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 album art update listener to remove

      • getAlbumArtListeners

        public Set<AlbumArtListener> getAlbumArtListeners()
        Get the set of currently-registered album art listeners.
        Returns:
        the listeners that are currently registered for album art updates

      • start

        public void start()
           throws Exception

        Start finding album art 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 art.

        Throws:
        Exception - if there is a problem starting the required components

      • stop

        public void stop()
        Stop finding album art for all active players.

      • getInstance

        public static ArtFinder getInstance()
        Get the singleton instance of this class.
        Returns:
        the only instance of this class which exists.