Package org.deepsymmetry.beatlink.data

Class WaveformDetailComponent

  • All Implemented Interfaces:
    ImageObserver, MenuContainer, Serializable
    public class WaveformDetailComponent
extends JComponent
    Provides a convenient way to draw waveform detail in a user interface, including annotations like the location at the current time, and cue point markers and loops (if you supply TrackMetadata so their location can be determined), and beat markers (if you also supply a BeatGrid). Can also be configured to automatically update itself to reflect the state of a specified player, showing the current track, playback state, and position, as long as it is able to load appropriate metadata. When tracking a live player, if that player is a CDJ-3000, dynamic loops (set up on the fly by the DJ) are also displayed, and inactive loops from the track metadata are drawn in gray rather than orange.
    See Also:
    Serialized Form

    • Constructor Detail

      • WaveformDetailComponent

        public WaveformDetailComponent​(int player)
        Create a view which updates itself to reflect the track loaded on a particular player, and that player's playback progress.
        Parameters:
        player - the player number to monitor, or zero if it should start out monitoring no player

      • WaveformDetailComponent

        public WaveformDetailComponent​(WaveformDetail waveform,
                               TrackMetadata metadata,
                               BeatGrid beatGrid)
        Create a view which draws a specific waveform, even if it is not currently loaded in a player.
        Parameters:
        waveform - the waveform detail to display
        metadata - information about the track whose waveform we are drawing, so we can draw cues and memory points
        beatGrid - the locations of the beats, so they can be drawn

      • WaveformDetailComponent

        public WaveformDetailComponent​(WaveformDetail waveform,
                               CueList cueList,
                               BeatGrid beatGrid)
        Create a view which draws a specific waveform, even if it is not currently loaded in a player.
        Parameters:
        waveform - the waveform detail to display
        cueList - used to draw cues and memory points
        beatGrid - the locations of the beats, so they can be drawn

    • Method Detail

      • setAutoScroll

        public void setAutoScroll​(boolean auto)
        Control whether the component should automatically center itself on the playback position of the player that is furthest into the track. This is the default behavior of the component, and will allow it to be useful at any size, showing a currently-relevant portion of the waveform. If set to false the component must be inside a scroll pane so the user can control what portion of the waveform is visible.
        Parameters:
        auto - should the waveform be centered on the playback position

      • getAutoScroll

        public boolean getAutoScroll()
        Check whether the component should automatically center itself on the playback position of the player that is furthest into the track. This is the default behavior of the component, and will allow it to be useful at any size, showing a currently-relevant portion of the waveform. If set to false the component must be inside a scroll pane so the user can control what portion of the waveform is visible.
        Returns:
        true if the waveform will be centered on the playback position

      • getBackgroundColor

        public Color getBackgroundColor()
        Examine the color to which the background is cleared before drawing the waveform. The default is black, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Returns:
        the color used to draw the component background

      • setBackgroundColor

        public void setBackgroundColor​(Color color)
        Change the color to which the background is cleared before drawing the waveform. The default is black, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Parameters:
        color - the color used to draw the component background

      • getIndicatorColor

        public Color getIndicatorColor()
        Examine the color with which the playback position and tick markers are drawn. The default is white, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Returns:
        the color used to draw the playback and tick markers

      • setIndicatorColor

        public void setIndicatorColor​(Color color)
        Change the color with which the playback position and tick markers are drawn. The default is white, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Parameters:
        color - the color used to draw the playback marker when actively playing

      • getEmphasisColor

        public Color getEmphasisColor()
        Examine the color with which the playback position is drawn when playback is active. The default is red, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Returns:
        the color used to draw the playback and tick markers

      • setEmphasisColor

        public void setEmphasisColor​(Color color)
        Change the color with which the playback position is drawn when playback is active. The default is red, but can be changed (including to a transparent color) for use in other contexts, like the OBS overlay.
        Parameters:
        color - the color used to draw the playback marker when actively playing

      • setLabelFont

        public void setLabelFont​(Font font)
        Specify the font to be used when drawing hot cue, memory point, and loop labels. If null, do not draw them at all. The default is the standard label font defined by the current Swing look and feel.
        Parameters:
        font - if not null, draw labels for hot cues and named memory points and loops, and use this font

      • getLabelFont

        public Font getLabelFont()
        Check the font being used to draw hot cue, memory point, and loop labels. If null, they are not being drawn at all.
        Returns:
        if not null, labels are being drawn for hot cues and named memory points and loops, in this font

      • setSongStructure

        public void setSongStructure​(RekordboxAnlz.SongStructureTag songStructure)
        Establish a song structure (phrase analysis) to be displayed on the waveform. If we are configured to monitor a player, then this will be overwritten the next time a track loads.
        Parameters:
        songStructure - the phrase information to be painted at the bottom of the waveform, or null to display none

      • setFetchSongStructures

        public void setFetchSongStructures​(boolean fetchSongStructures)
        Determine whether we should try to obtain the song structure for tracks that we are displaying, and paint the phrase information at the bottom of the waveform. Only has effect if we are monitoring a player.
        Parameters:
        fetchSongStructures - true if we should try to obtain and display phrase analysis information

      • getFetchSongStructures

        public boolean getFetchSongStructures()
        Check whether we are supposed to obtain the song structure for tracks we are displaying when we are monitoring a player.
        Returns:
        true if we should try to obtain and display phrase analysis information

      • setPlaybackState

        public void setPlaybackState​(int player,
                             long position,
                             boolean playing)

        Set the current playback state for a player.

        Will cause part of the component to be redrawn if the player state has changed (and we have the TrackMetadata we need to translate the time into a position in the component). This will be quickly overruled if a player is being monitored, but can be used in other contexts.
        Parameters:
        player - the player number whose playback state is being recorded
        position - the current playback position of that player in milliseconds
        playing - whether the player is actively playing the track
        Throws:
        IllegalStateException - if the component is configured to monitor a player, and this is called with state for a different player
        IllegalArgumentException - if player is less than one
        Since:
        0.5.0

      • clearPlaybackState

        public void clearPlaybackState​(int player)
        Clear the playback state stored for a player, such as when it has unloaded the track.
        Parameters:
        player - the player number whose playback state is no longer valid
        Since:
        0.5.0

      • clearPlaybackState

        public void clearPlaybackState()
        Removes all stored playback state.
        Since:
        0.5.0

      • getPlaybackState

        public PlaybackState getPlaybackState​(int player)
        Look up the playback state recorded for a particular player.
        Parameters:
        player - the player number whose playback state information is desired
        Returns:
        the corresponding playback state, if any has been stored
        Since:
        0.5.0

      • getPlaybackState

        public Set<PlaybackState> getPlaybackState()
        Look up all recorded playback state information.
        Returns:
        the playback state recorded for any player
        Since:
        0.5.0

      • setScale

        public void setScale​(int scale)
        Set the zoom scale of the view. a value of 1 (the smallest allowed) draws the waveform at full scale. Larger values combine more and more segments into a single column of pixels, zooming out to see more at once.
        Parameters:
        scale - the number of waveform segments that should be averaged into a single column of pixels
        Throws:
        IllegalArgumentException - if scale is less than 1 or greater than 256

      • getScale

        public int getScale()
        Check the zoom scale of the view. a value of 1 (the smallest allowed) draws the waveform at full scale. Larger values combine more and more segments into a single column of pixels, zooming out to see more at once.
        Returns:
        the current zoom scale.

      • setWaveform

        public void setWaveform​(WaveformDetail waveform,
                        TrackMetadata metadata,
                        BeatGrid beatGrid)
        Change the waveform preview being drawn. This will be quickly overruled if a player is being monitored, but can be used in other contexts.
        Parameters:
        waveform - the waveform detail to display
        metadata - information about the track whose waveform we are drawing, so we can draw cue and memory points
        beatGrid - the locations of the beats, so they can be drawn

      • setWaveform

        public void setWaveform​(WaveformDetail waveform,
                        CueList cueList,
                        BeatGrid beatGrid)
        Change the waveform preview being drawn. This will be quickly overruled if a player is being monitored, but can be used in other contexts.
        Parameters:
        waveform - the waveform detail to display
        cueList - used to draw cue and memory points
        beatGrid - the locations of the beats, so they can be drawn

      • getWaveform

        public WaveformDetail getWaveform()
        Obtain the waveform detail being drawn.
        Returns:
        the waveform detail being displayed by this component.

      • setMonitoredPlayer

        public void setMonitoredPlayer​(int player)
        Configures the player whose current track waveforms and status will automatically be reflected. Whenever a new track is loaded on that player, the waveform and metadata will be updated, and the current playback position and state of the player will be reflected by the component.
        Parameters:
        player - the player number to monitor, or zero if monitoring should stop

      • getMonitoredPlayer

        public int getMonitoredPlayer()
        See which player is having its state tracked automatically by the component, if any.
        Returns:
        the player number being monitored, or zero if none

      • getFurthestPlaybackState

        public PlaybackState getFurthestPlaybackState()
        Look up the playback state that has reached furthest in the track, but give playing players priority over stopped players. This is used to choose the scroll center when auto-scrolling is active.
        Returns:
        the playback state, if any, with the highest playing PlaybackState.position value

      • getFurthestPlaybackPosition

        public long getFurthestPlaybackPosition()
        Look up the furthest position, in milliseconds, that has been reached, giving playing players priority over stopped players. If there are no playback positions, returns 0.
        Returns:
        The position in milliseconds of the furthest playback state reached, or 0 if there are no playback states

      • getTimeForX

        public long getTimeForX​(int x)
        Determine the playback time that corresponds to a particular X coordinate in the component given the current scale.
        Parameters:
        x - the horizontal position within the component coordinate space
        Returns:
        the number of milliseconds into the track this would correspond to (may fall outside the actual track)

      • getBeatForX

        public int getBeatForX​(int x)
        Determine the beat that corresponds to a particular X coordinate in the component, given the current scale. Clicks past the end of the track will return the final beat, clicks before the first beat (or if there is no beat grid) will return -1.
        Parameters:
        x - the horizontal position within the component coordinate space
        Returns:
        the beat number being played at that point, or -1 if the point is before the first beat

      • getXForBeat

        public int getXForBeat​(int beat)
        Determine the X coordinate within the component at which the specified beat begins.
        Parameters:
        beat - the beat number whose position is desired
        Returns:
        the horizontal position within the component coordinate space where that beat begins
        Throws:
        IllegalArgumentException - if the beat number exceeds the number of beats in the track.

      • millisecondsToX

        public int millisecondsToX​(long milliseconds)
        Converts a time in milliseconds to the appropriate x coordinate for drawing something at that time.
        Parameters:
        milliseconds - the time at which something should be drawn
        Returns:
        the component x coordinate at which it should be drawn

      • cueColor

        @Deprecated
public static Color cueColor​(CueList.Entry entry)
        Deprecated.
        use CueList.Entry.getColor() instead
        Determine the color to use to draw a cue list entry. Hot cues are green, ordinary memory points are red, and loops are orange.
        Parameters:
        entry - the entry being drawn
        Returns:
        the color with which it should be represented

      • isDynamicLoopDataAvailable

        public boolean isDynamicLoopDataAvailable()
        Checks whether any players we are tracking are capable of sending information about current loop status. This is safe to call even when not online, and will simply return false in that circumstance.
        Returns:
        whether we have seen a status packet from a tracked player that is a CDJ-3000 or equivalent