Module org.deepsymmetry.beatlink
Package org.deepsymmetry.beatlink.data

Class WaveformDetail

  • @API(status=STABLE)
public class WaveformDetail
extends Object
    Gives a detail view of the audio content of a track, and offers a Swing component for rendering that view as part of a user interface, along with annotations showing the current playback position, beats, and cue points, if the appropriate metadata is available.
    Author:
    James Elliott

    • Field Detail

      • LEADING_DBSERVER_JUNK_BYTES

        @API(status=STABLE)
public static final int LEADING_DBSERVER_JUNK_BYTES
        The number of bytes at the start of the waveform data which do not seem to be valid or used when it is served by the dbserver protocol. They are not present when the ANLZ.EXT file is loaded directly by Crate Digger.
        See Also:
        Constant Field Values

      • LEADING_DBSERVER_COLOR_JUNK_BYTES

        @API(status=STABLE)
public static final int LEADING_DBSERVER_COLOR_JUNK_BYTES
        The number of bytes at the start of the color waveform data to be skipped when that was loaded using the nxs2 ANLZ tag request. We actually know what these mean, now that we know how to parse EXT files, but we can simply skip them anyway.
        See Also:
        Constant Field Values

      • dataReference

        @API(status=STABLE)
public final DataReference dataReference
        The unique identifier that was used to request this waveform detail.

      • rawMessage

        @API(status=STABLE)
public final Message rawMessage
        The message holding the detail as it was read over the network. This can be used to analyze fields that have not yet been reliably understood, and is also used for storing the cue list in a file. This will be null if the data was obtained from Crate Digger.

      • isColor

        @API(status=DEPRECATED)
public final boolean isColor
        Deprecated.
        since 8.0.0
        Indicates whether this is an NXS2-style color waveform, or a monochrome (blue) waveform (use predates the existence of style). Has no meaning if style is WaveformFinder.WaveformStyle.THREE_BAND.

      • COLOR_MAP

        @API(status=STABLE)
public static final Color[] COLOR_MAP
        The different colors the monochrome (blue) waveform can be based on its intensity.

    • Constructor Detail

      • WaveformDetail

        @API(status=DEPRECATED)
public WaveformDetail​(DataReference reference,
                      Message message)
        Deprecated.
        since 8.0.0
        Constructor when reading from the network or a file, for code that predates 3-band support. Assumes the current preferred style is what has been requested.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        message - the response that contains the detail

      • WaveformDetail

        @API(status=STABLE)
public WaveformDetail​(DataReference reference,
                      Message message,
                      WaveformFinder.WaveformStyle style)
        Constructor when reading from the network or a file.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        message - the response that contains the detail
        style - the style of waveform that was requested, since this can no longer be determined from the message alone

      • WaveformDetail

        public WaveformDetail​(DataReference reference,
                      RekordboxAnlz.TaggedSection section)
        Constructor from a raw analysis file tagged section, independent of the current preferred style.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        section - the parsed rekordbox track analysis file section containing the waveform detail

      • WaveformDetail

        @API(status=STABLE)
public WaveformDetail​(DataReference reference,
                      RekordboxAnlz anlzFile)
        Deprecated.
        since 8.0.0
        Constructor when received from Crate Digger, for code that predates 3-band support. Assumes the current preferred style is what is being loaded.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        anlzFile - the parsed rekordbox track analysis file containing the waveform detail (we rely on the correct file for the current preferred style being passed: ANLZ for blue, EXT for RGB, and 2EX for 3-band)

      • WaveformDetail

        @API(status=STABLE)
public WaveformDetail​(DataReference reference,
                      RekordboxAnlz anlzFile,
                      WaveformFinder.WaveformStyle style)
        Constructor when received from Crate Digger.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        anlzFile - the parsed rekordbox track analysis file containing the waveform detail (we rely on the correct file for the requested style being passed: ANLZ for blue, EXT for RGB, and 2EX for 3-band)
        style - indicates the style of the waveform desired

      • WaveformDetail

        @API(status=DEPRECATED)
public WaveformDetail​(DataReference reference,
                      ByteBuffer data,
                      boolean isColor)
        Deprecated.
        since 8.0.0
        Constructor for use with external caching mechanisms, for code that predates 3-band support.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        data - the waveform data as will be returned by getData()
        isColor - indicates whether the data represents a color waveform

      • WaveformDetail

        @API(status=EXPERIMENTAL)
public WaveformDetail​(DataReference reference,
                      ByteBuffer data,
                      WaveformFinder.WaveformStyle style)
        Constructor for use with external caching mechanisms.
        Parameters:
        reference - the unique database reference that was used to request this waveform detail
        data - the waveform data as will be returned by getData()
        style - indicates the style of the waveform

    • Method Detail

      • getData

        @API(status=STABLE)
public ByteBuffer getData()
        Get the raw bytes of the waveform detail data
        Returns:
        the bytes from which the detail can be drawn, as described in the Packet Analysis document.

      • getFrameCount

        @API(status=STABLE)
public int getFrameCount()
        Count the half-frames of waveform available.
        Returns:
        the number of half-frames (pixel columns) that make up the track

      • getTotalTime

        @API(status=STABLE)
public long getTotalTime()
        Determine how long the track plays, in milliseconds. This provides a more accurate value than the track metadata, which is accurate only to the second, because we know how many half-frames (1/150 of a second) the track is composed of.
        Returns:
        the number of milliseconds it will take to play all half-frames that make up the track

      • createViewComponent

        @API(status=STABLE)
public JComponent createViewComponent​(TrackMetadata metadata,
                                      BeatGrid beatGrid)
        Create a standard Swing component which can be added to a user interface that will draw this waveform detail, optionally including annotations like the current playback position and minute markers (if you supply TrackMetadata so the total length can be determined), and cue markers (if you also supply a CueList). The playback position can be
        Parameters:
        metadata - Information about the track whose waveform we are drawing, so we can translate times into positions
        beatGrid - The locations of all the beats in the track, so they can be drawn
        Returns:
        the component which will draw the annotated waveform detail

      • segmentHeight

        @API(status=STABLE)
public int segmentHeight​(int segment,
                         int scale)
        Determine the height of the waveform given an index into it. If scale is larger than 1 we are zoomed out, so we determine an average height of scale segments starting with the specified one.
        Parameters:
        segment - the index of the first waveform byte to examine
        scale - the number of wave segments being drawn as a single pixel column
        Returns:
        a value from 0 to 31 representing the height of the waveform at that segment, which may be an average of a number of values starting there, determined by the scale
        Throws:
        UnsupportedOperationException - for three-band waveforms since each band has a different height

      • segmentHeight

        public int segmentHeight​(int segment,
                         int scale,
                         WaveformFinder.ThreeBandLayer band)
        Determine the height of a three-band preview given an index into it.
        Parameters:
        segment - the index of the waveform preview segment to examine
        scale - the number of wave segments being drawn as a single pixel column
        band - the band whose height is wanted
        Returns:
        a value from 0 to 31 representing the height of the waveform at that segment, which may be an average of a number of values starting there, determined by the scale
        Throws:
        UnsupportedOperationException - if called on a non three-band waveform

      • segmentColor

        @API(status=STABLE)
public Color segmentColor​(int segment,
                          int scale)
        Determine the color of the waveform given an index into it. If scale is larger than 1 we are zoomed out, so we determine an average color of scale segments starting with the specified one.
        Parameters:
        segment - the index of the first waveform byte to examine
        scale - the number of wave segments being drawn as a single pixel column
        Returns:
        the color of the waveform at that segment, which may be based on an average of a number of values starting there, determined by the scale
        Throws:
        UnsupportedOperationException - if called on a three-band waveform, colors are fixed for each band