org.deepsymmetry.beatlink.data

Class MetadataFinder

java.lang.Object

org.deepsymmetry.beatlink.LifecycleParticipant

org.deepsymmetry.beatlink.data.MetadataFinder

public class MetadataFinder
extends LifecycleParticipant

Watches for new tracks to be loaded on players, and queries the appropriate player for the metadata information when that happens.

Maintains a hot cache of metadata about 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.

Can also create cache files containing metadata about either all tracks in a media library, or tracks from a specific play list, and attach those cache files to be used instead of actually querying the player about tracks loaded from that library. This can be used in busy performance situations where all four usable player numbers are in use by actual players, to avoid conflicting queries yet still have useful metadata available. In such situations, you may want to go into passive mode, using setPassive(boolean), to prevent metadata queries about tracks that are not available from the attached metadata cache files.

Author:

James Elliott

Field Summary

Fields

Modifier and Type	Field and Description
static String	CACHE_FORMAT_IDENTIFIER The comment string used to identify a ZIP file as one of our metadata caches.

Method Summary

Modifier and Type	Method and Description
void	addAutoAttachCacheFile(File metadataCacheFile) Add a metadata cache file to the set being automatically attached when matching media is inserted.
void	addCacheListener(MetadataCacheListener listener) Adds the specified cache update listener to receive updates when a metadata cache is attached or detached.
void	addMountListener(MountListener listener) Adds the specified mount update listener to receive updates when media is mounted or unmounted by any player.
void	addTrackMetadataListener(TrackMetadataListener listener) Adds the specified track metadata listener to receive updates when the track metadata for a player changes.
void	attachMetadataCache(SlotReference slot, File cache) Attach a metadata cache file to a particular player media slot, so the cache will be used instead of querying the player for metadata.
void	createMetadataCache(SlotReference slot, int playlistId, File cache) Creates a metadata cache archive file of all tracks in the specified slot on the specified player.
void	createMetadataCache(SlotReference slot, int playlistId, File cache, MetadataCacheCreationListener listener) Creates a metadata cache archive file of all tracks in the specified slot on the specified player.
void	detachMetadataCache(SlotReference slot) Removes any metadata cache file that might have been assigned to a particular player media slot, so metadata will be looked up from the player itself.
List<File>	getAutoAttachCacheFiles() Get the metadata cache files that are currently configured to be automatically attached when matching media is mounted in a player on the network.
int	getAutoAttachProbeCount() Get the number of tracks examined when considering auto-attaching a metadata cache file to a newly-mounted media database.
CueList	getCachedCueList(ZipFile cache, int rekordboxId) Look up a cue list in a metadata cache.
TrackMetadata	getCachedMetadata(ZipFile cache, DataReference track) Look up track metadata from a cache.
Set<MetadataCacheListener>	getCacheListeners() Get the set of currently-registered metadata cache update listeners.
long	getCachePauseInterval() Check how long we pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.
int	getCacheSourcePlaylist(ZipFile cache) Reports the ID of the playlist that was used to create the cache, or 0 of it is an all-tracks cache.
int	getCacheTrackCount(ZipFile cache) Reports the number of tracks contained in a metadata cache.
List<Integer>	getCacheTrackIds(ZipFile cache) Returns a list of the rekordbox IDs of the tracks contained in a metadata cache.
static MetadataFinder	getInstance() Get the singleton instance of this class.
TrackMetadata	getLatestMetadataFor(DeviceUpdate update) Look up the track metadata we have for a given player, identified by a status update received from that player.
TrackMetadata	getLatestMetadataFor(int player) Look up the track metadata we have for the track loaded in the main deck of a given player number.
Map<DeckReference,TrackMetadata>	getLoadedTracks() Get the metadata of all tracks currently loaded in any player, either on the play deck, or in a hot cue.
ZipFile	getMetadataCache(SlotReference slot) Finds the metadata cache file assigned to a particular player media slot, if any.
Set<SlotReference>	getMountedMediaSlots() Returns the set of media slots on the network that currently have media mounted in them.
Set<MountListener>	getMountListeners() Get the set of currently-registered mount update listeners.
Set<TrackMetadataListener>	getTrackMetadataListeners() Get the set of currently-registered track metadata update listeners.
boolean	isPassive() Check whether we are configured to use metadata only from caches, never actively requesting it from a player.
boolean	isRunning() Check whether we are currently running.
ZipFile	openMetadataCache(File cache) Open and validate a metadata cache file.
void	removeAutoAttacheCacheFile(File metadataCacheFile) Remove a metadata cache file from the set being automatically attached when matching media is inserted.
void	removeCacheListener(MetadataCacheListener listener) Removes the specified cache update listener so that it no longer receives updates when there are changes to the available set of metadata caches.
void	removeMountListener(MountListener listener) Removes the specified mount update listener so that it no longer receives updates when a player mounts or unmounts media in one of its media slots.
void	removeTrackMetadataListener(TrackMetadataListener listener) Removes the specified track metadata update listener so that it no longer receives updates when track metadata for a player changes.
TrackMetadata	requestMetadataFrom(CdjStatus status) Given a status update from a CDJ, find the metadata for the track that it has loaded, if any.
TrackMetadata	requestMetadataFrom(DataReference track) Ask the specified player for metadata about the track in the specified slot with the specified rekordbox ID, unless we have a metadata cache available for the specified media slot, in which case that will be used instead.
List<Message>	requestPlaylistItemsFrom(int player, CdjStatus.TrackSourceSlot slot, int sortOrder, int playlistOrFolderId, boolean folder) Ask the specified player for the playlist entries of the specified playlist (if folder is false, or the list of playlists and folders inside the specified playlist folder (if folder is true.
void	setAutoAttachProbeCount(int numTracks) Set the number of tracks examined when considering auto-attaching a metadata cache file to a newly-mounted media database.
void	setCachePauseInterval(long milliseconds) Set how long to pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.
void	setPassive(boolean passive) Set whether we are configured to use metadata only from caches, never actively requesting it from a player.
void	start() Start finding track metadata for all active players.
void	stop() Stop finding track metadata 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

Field Detail

CACHE_FORMAT_IDENTIFIER

public static final String CACHE_FORMAT_IDENTIFIER

The comment string used to identify a ZIP file as one of our metadata caches.

See Also:

Constant Field Values

Method Detail

requestMetadataFrom

public TrackMetadata requestMetadataFrom(CdjStatus status)

Given a status update from a CDJ, find the metadata for the track that it has loaded, if any. If there is an appropriate metadata cache, will use that, otherwise makes a query to the players dbserver.

Parameters:

status - the CDJ status update that will be used to determine the loaded track and ask the appropriate player for metadata about it

Returns:

the metadata that was obtained, if any

requestMetadataFrom

public TrackMetadata requestMetadataFrom(DataReference track)

Ask the specified player for metadata about the track in the specified slot with the specified rekordbox ID, unless we have a metadata cache available for the specified media slot, in which case that will be used instead.

Parameters:

track - uniquely identifies the track whose metadata is desired

Returns:

the metadata, if any

getCachedMetadata

public TrackMetadata getCachedMetadata(ZipFile cache,
                                       DataReference track)

Look up track metadata from a cache.

Parameters:

cache - the appropriate metadata cache file

track - identifies the track whose metadata is desired

Returns:

the cached metadata, including cue list (if available), or null

getCachedCueList

public CueList getCachedCueList(ZipFile cache,
                                int rekordboxId)

Look up a cue list in a metadata cache.

Parameters:

cache - the appropriate metadata cache file

rekordboxId - the track whose cue list is desired

Returns:

the cached cue list (if available), or null

requestPlaylistItemsFrom

public List<Message> requestPlaylistItemsFrom(int player,
                                              CdjStatus.TrackSourceSlot slot,
                                              int sortOrder,
                                              int playlistOrFolderId,
                                              boolean folder)
                                       throws Exception

Ask the specified player for the playlist entries of the specified playlist (if folder is false, or the list of playlists and folders inside the specified playlist folder (if folder is true.

Parameters:

player - the player number whose playlist entries are of interest

slot - the slot in which the playlist can be found

sortOrder - the order in which responses should be sorted, 0 for default, see Section 5.10.1 of the Packet Analysis document for details

playlistOrFolderId - the database ID of the desired playlist or folder

folder - indicates whether we are asking for the contents of a folder or playlist

Returns:

the items that are found in the specified playlist or folder; they will be tracks if we are asking for a playlist, or playlists and folders if we are asking for a folder

Throws:

Exception - if there is a problem obtaining the playlist information

createMetadataCache

public void createMetadataCache(SlotReference slot,
                                int playlistId,
                                File cache)
                         throws Exception

Creates a metadata cache archive file of all tracks in the specified slot on the specified player. Any previous contents of the specified file will be replaced.

Parameters:

slot - the slot in which the media to be cached can be found

playlistId - the id of playlist to be cached, or 0 of all tracks should be cached

cache - the file into which the metadata cache should be written

Throws:

Exception - if there is a problem communicating with the player or writing the cache file.

setCachePauseInterval

public void setCachePauseInterval(long milliseconds)

Set how long to pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.

Parameters:

milliseconds - the delay to add between each track that gets added to the metadata cache

getCachePauseInterval

public long getCachePauseInterval()

Check how long we pause between requesting metadata entries while building a cache to give the player a chance to perform its other tasks.

Returns:

the delay to add between each track that gets added to the metadata cache

createMetadataCache

public void createMetadataCache(SlotReference slot,
                                int playlistId,
                                File cache,
                                MetadataCacheCreationListener listener)
                         throws Exception

Creates a metadata cache archive file of all tracks in the specified slot on the specified player. Any previous contents of the specified file will be replaced. If a non-null listener is supplied, its MetadataCacheCreationListener.cacheCreationContinuing(TrackMetadata, int, int) method will be called after each track is added to the cache, allowing it to display progress updates to the user, and to continue or cancel the process by returning true or false. Because this takes a huge amount of time relative to CDJ status updates, it can only be performed while the MetadataFinder is in passive mode.

Parameters:

slot - the slot in which the media to be cached can be found

playlistId - the id of playlist to be cached, or 0 of all tracks should be cached

cache - the file into which the metadata cache should be written

listener - will be informed after each track is added to the cache file being created and offered the opportunity to cancel the process

Throws:

Exception - if there is a problem communicating with the player or writing the cache file

isRunning

public boolean isRunning()

Check whether we are currently running. Unless we are in passive mode, we will also automatically request metadata 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 track metadata is being kept track of for all active players

See Also:

isPassive()

isPassive

public boolean isPassive()

Check whether we are configured to use metadata only from caches, never actively requesting it from a player. Note that this will implicitly mean all of the metadata-related finders (ArtFinder, BeatGridFinder, and WaveformFinder) are in passive mode as well, because their activity is triggered by the availability of new track metadata.

Returns:

true if only cached metadata will be used, or false if metadata will be requested from a player if a track is loaded from a media slot to which no cache has been assigned

setPassive

public void setPassive(boolean passive)

Set whether we are configured to use metadata only from caches, never actively requesting it from a player. Note that this will implicitly put all of the metadata-related finders (ArtFinder, BeatGridFinder, and WaveformFinder) into a passive mode as well, because their activity is triggered by the availability of new track metadata.

Parameters:

passive - true if only cached metadata will be used, or false if metadata will be requested from a player if a track is loaded from a media slot to which no cache has been assigned

getLoadedTracks

public Map<DeckReference,TrackMetadata> getLoadedTracks()

Get the metadata of all tracks currently loaded in any player, either on the play deck, or in a hot cue.

Returns:

the track information reported by all current players, including any tracks loaded in their hot cue slots

Throws:

IllegalStateException - if the MetadataFinder is not running

getLatestMetadataFor

public TrackMetadata getLatestMetadataFor(int player)

Look up the track metadata we have for the track loaded in the main deck of a given player number.

Parameters:

player - the device number whose track metadata for the playing track is desired

Returns:

information about the track loaded on that player, if available

Throws:

IllegalStateException - if the MetadataFinder is not running

getLatestMetadataFor

public TrackMetadata getLatestMetadataFor(DeviceUpdate update)

Look up the track metadata 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 track metadata is desired

Returns:

information about the track loaded on that player, if available

Throws:

IllegalStateException - if the MetadataFinder is not running

attachMetadataCache

public void attachMetadataCache(SlotReference slot,
                                File cache)
                         throws IOException

Attach a metadata cache file to a particular player media slot, so the cache will be used instead of querying the player for metadata. This supports operation with metadata during shows where DJs are using all four player numbers and heavily cross-linking between them. If the media is ejected from that player slot, the cache will be detached.

Parameters:

slot - the media slot to which a meta data cache is to be attached

cache - the metadata cache to be attached

Throws:

IOException - if there is a problem reading the cache file

IllegalArgumentException - if an invalid player number or slot is supplied

IllegalStateException - if the metadata finder is not running

openMetadataCache

public ZipFile openMetadataCache(File cache)
                          throws IOException

Open and validate a metadata cache file.

Parameters:

cache - the file the user wants to work with

Returns:

the opened zip file, if it contains a valid cache

Throws:

IOException - if there is a problem reading the file, or it does not contain a valid metadata cache

getCacheSourcePlaylist

public int getCacheSourcePlaylist(ZipFile cache)
                           throws IOException

Reports the ID of the playlist that was used to create the cache, or 0 of it is an all-tracks cache.

Parameters:

cache - the metadata cache whose contents are of interest

Returns:

0 if the cache was created using all tracks, or the id of the playlist that it contains otherwise

Throws:

IOException - if there is a problem reading the cache file

getCacheTrackCount

public int getCacheTrackCount(ZipFile cache)
                       throws IOException

Reports the number of tracks contained in a metadata cache.

Parameters:

cache - the metadata cache whose contents are of interest

Returns:

the number of cached track metadata entries

Throws:

IOException - if there is a problem reading the cache file

getCacheTrackIds

public List<Integer> getCacheTrackIds(ZipFile cache)
                               throws IOException

Returns a list of the rekordbox IDs of the tracks contained in a metadata cache.

Parameters:

cache - the metadata cache whose contents are of interest

Returns:

a list containing the rekordbox ID for each track present in the cache, in the order they appear

Throws:

IOException - if there is a problem reading the cache file

detachMetadataCache

public void detachMetadataCache(SlotReference slot)

Removes any metadata cache file that might have been assigned to a particular player media slot, so metadata will be looked up from the player itself.

Parameters:

slot - the media slot to which a meta data cache is to be attached

addAutoAttachCacheFile

public void addAutoAttachCacheFile(File metadataCacheFile)
                            throws IOException

Add a metadata cache file to the set being automatically attached when matching media is inserted. Will try to auto-attach the new file to any already-mounted media.

Parameters:

metadataCacheFile - the file to be auto-attached when matching media is seen on the network

Throws:

IOException - if the specified file cannot be read or is not a valid metadata cache

removeAutoAttacheCacheFile

public void removeAutoAttacheCacheFile(File metadataCacheFile)

Remove a metadata cache file from the set being automatically attached when matching media is inserted. This will not detach it from a slot if it has already been attached; for that you need to use detachMetadataCache(SlotReference).

Parameters:

metadataCacheFile - the file that should no longer be auto-attached when matching media is seen

getAutoAttachCacheFiles

public List<File> getAutoAttachCacheFiles()

Get the metadata cache files that are currently configured to be automatically attached when matching media is mounted in a player on the network.

Returns:

the current auto-attache cache files, sorted by name

setAutoAttachProbeCount

public void setAutoAttachProbeCount(int numTracks)

Set the number of tracks examined when considering auto-attaching a metadata cache file to a newly-mounted media database. The more examined, the more confident we can be in the cache matching the media, but the longer it will take and the more metadata queries will be required. The smallest legal value is 1.

Parameters:

numTracks - the number of tracks that will be compared between the cache files and the media in the player

getAutoAttachProbeCount

public int getAutoAttachProbeCount()

Get the number of tracks examined when considering auto-attaching a metadata cache file to a newly-mounted media database. The more examined, the more confident we can be in the cache matching the media, but the longer it will take and the more metadata queries will be required.

Returns:

the number of tracks that will be compared between the cache files and the media in the player

getMetadataCache

public ZipFile getMetadataCache(SlotReference slot)

Finds the metadata cache file assigned to a particular player media slot, if any.

Parameters:

slot - the media slot to which a meta data cache is to be attached

Returns:

the zip file being used as a metadata cache for that player and slot, or null if no cache has been attached

getMountedMediaSlots

public Set<SlotReference> getMountedMediaSlots()

Returns the set of media slots on the network that currently have media mounted in them.

Returns:

the slots with media currently available on the network

addMountListener

public void addMountListener(MountListener listener)

Adds the specified mount update listener to receive updates when media is mounted or unmounted by any player. 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 mount update listener to add

removeMountListener

public void removeMountListener(MountListener listener)

Removes the specified mount update listener so that it no longer receives updates when a player mounts or unmounts media in one of its media slots. 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 mount update listener to remove

getMountListeners

public Set<MountListener> getMountListeners()

Get the set of currently-registered mount update listeners.

Returns:

the listeners that are currently registered for mount updates

addCacheListener

public void addCacheListener(MetadataCacheListener listener)

Adds the specified cache update listener to receive updates when a metadata cache is attached or detached. 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 cache update listener to add

removeCacheListener

public void removeCacheListener(MetadataCacheListener listener)

Removes the specified cache update listener so that it no longer receives updates when there are changes to the available set of metadata caches. 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 cache update listener to remove

getCacheListeners

public Set<MetadataCacheListener> getCacheListeners()

Get the set of currently-registered metadata cache update listeners.

Returns:

the listeners that are currently registered for metadata cache updates

addTrackMetadataListener

public void addTrackMetadataListener(TrackMetadataListener listener)

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

removeTrackMetadataListener

public void removeTrackMetadataListener(TrackMetadataListener listener)

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

getTrackMetadataListeners

public Set<TrackMetadataListener> getTrackMetadataListeners()

Get the set of currently-registered track metadata update listeners.

Returns:

the listeners that are currently registered for track metadata updates

start

public void start()
           throws Exception

Start finding track metadata for all active players. Starts the VirtualCdj if it is not already running, because we need it to send us device status updates to notice when new tracks are loaded; this starts the DeviceFinder (which is also needed by the VirtualCdj) so we can keep track of the comings and goings of players themselves. We start the ConnectionManager in order to make queries to obtain metadata.

Throws:

Exception - if there is a problem starting the required components

stop

public void stop()

Stop finding track metadata for all active players.

getInstance

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