Package org.deepsymmetry.beatlink.data

Class WaveformPreviewComponent

  • All Implemented Interfaces:
    ImageObserver, MenuContainer, Serializable
    public class WaveformPreviewComponent
extends JComponent
    Provides a convenient way to draw a waveform preview in a user interface, including annotations like the current time and minute markers (if you supply TrackMetadata so the total length can be determined), and cue markers (if you also supply a CueList). 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, which includes beat grids for translating beat numbers into track time.
    See Also:
    Serialized Form

    • Field Detail

      • MIN_WAVEFORM_WIDTH

        public static final int MIN_WAVEFORM_WIDTH
        The minimum acceptable width for the waveform.
        See Also:
        Constant Field Values

      • BRIGHT_PLAYED

        public static final Color BRIGHT_PLAYED
        The color for brighter sections of the already-played section of the playback progress bar. Note that if the indicator color has been changed, only the transparency (alpha) channel of this is used.

      • DIM_PLAYED

        public static final Color DIM_PLAYED
        The color for darker sections of the already-played section of the playback progress bar. Note that if the indicator color has been changed, only the transparency (alpha) channel of this is used.

      • DIM_UNPLAYED

        public static final Color DIM_UNPLAYED
        The color for the darker sections of the not-yet-played sections of the playback progress bar. Note that if the indicator color has been changed, only the transparency (alpha) channel of this is used.

    • Constructor Detail

      • WaveformPreviewComponent

        public WaveformPreviewComponent​(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

      • WaveformPreviewComponent

        public WaveformPreviewComponent​(WaveformPreview preview,
                                TrackMetadata metadata)
        Create a view which draws a specific waveform, even if it is not currently loaded in a player.
        Parameters:
        preview - the waveform preview to display
        metadata - information about the track whose waveform we are drawing, so we can translate times into positions

      • WaveformPreviewComponent

        public WaveformPreviewComponent​(WaveformPreview preview,
                                int duration,
                                CueList cueList)
        Create a view which draws a specific waveform, even if it is not currently loaded in a player.
        Parameters:
        preview - the waveform preview to display
        duration - the playback duration, in seconds, of the track whose waveform we are drawing, so we can translate times into positions
        cueList - the hot cues and memory points stored for the track, if any, so we can draw them

    • Method Detail

      • setBeatGrid

        public void setBeatGrid​(BeatGrid beatGrid)
        Establish a beat grid to use when translating between times and beat numbers, for example to paint the phrase bars. If we are configured to monitor a player, then this will be overwritten the next time a track loads.
        Parameters:
        beatGrid - the beat grid information for the displayed waveform, or null if none is available

      • getCueList

        public CueList getCueList()
        Get the cue list associated with this track.
        Returns:
        the cues defined for the track.

      • 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

      • 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 active playback marker

      • 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

      • getFurthestPlaybackState

        public PlaybackState getFurthestPlaybackState()
        Look up the playback state that has reached furthest in the track. This is used to render the “played until” graphic below the preview.
        Returns:
        the playback state, if any, with the highest PlaybackState.position value

      • setRepaintDelegate

        public void setRepaintDelegate​(RepaintDelegate delegate)
        Establish a host component to which all Component.repaint(int, int, int, int) calls should be delegated, presumably because we are being soft-loaded in a large user interface to save on memory.
        Parameters:
        delegate - the permanent component that can actually accumulate repaint regions, or null if we are being hosted normally in a container, so we should use the normal repaint process.

      • 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

      • setWaveformPreview

        public void setWaveformPreview​(WaveformPreview preview,
                               TrackMetadata metadata)
        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:
        preview - the waveform preview to display
        metadata - information about the track whose waveform we are drawing, so we can translate times into positions and display hot cues and memory points

      • setWaveformPreview

        public void setWaveformPreview​(WaveformPreview preview,
                               int duration,
                               CueList cueList)
        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:
        preview - the waveform preview to display
        duration - the playback duration, in seconds, of the track whose waveform we are drawing, so we can translate times into positions
        cueList - the hot cues and memory points stored for the track, if any, so we can draw them

      • getWaveformPreview

        public WaveformPreview getWaveformPreview()
        Obtain the waveform preview being drawn.
        Returns:
        the waveform preview 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

      • 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. Can only be called when we have TrackMetadata.
        Parameters:
        milliseconds - the time at which something should be drawn
        Returns:
        the component x coordinate at which it should be drawn

      • 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)

      • toolTipText

        public String toolTipText​(Point point)
        Checks whether we have anything that could reasonably be displayed as a tool tip when the mouse is hovering over the specified point, for programs that want to offer such a feature in their user interface.
        Parameters:
        point - the point where the mouse has been detected
        Returns:
        the text of a tool tip to describe that area of this component, or null if there's nothing to say about that point