Package ca.corbett.extras.audio

Class AudioWaveformPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
ca.corbett.extras.audio.AudioWaveformPanel
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public final class AudioWaveformPanel extends JPanel
Presents a JPanel that encapsulates an audio clip, and can visually present a graphical waveform of that clip, along with controls for playback and editing. This component relies heavily on AudioUtil as well as ImagePanel. Audio controls can optionally be displayed, to allow user input for playback, recording, and editing functions. If the controls are hidden, these functions are only available programmatically.
Since:
2018-01-08
Author:
scorbo2
See Also:

  • Constructor Details

    • AudioWaveformPanel

      public AudioWaveformPanel()
      Creates a new AudioWaveformPanel with no audio clip, and with default properties. Use setWaveformProperties to set cosmetic properties for the waveform display, or the other setters to set general behavioural properties.

  • Method Details

    • getWaveformPreferences

      public WaveformConfig getWaveformPreferences()
      Returns a copy of the current WaveformConfig, which describe cosmetic attributes for the audio waveform display. A copy of the properties object is returned to prevent client modification. To change the properties, use setWaveformPreferences.
      Returns:
      A copy of the current WaveformProperties object.

    • setWaveformPreferences

      public void setWaveformPreferences(WaveformConfig prefs)
      Sets the WaveformConfig, which control cosmetic attributes of the audio waveform display. A copy of the given object is made to prevent client modification after this method is invoked.
      Parameters:
      prefs - The WaveformConfig to use. If null, default prefs will be used.

    • addAudioPanelListener

      public void addAudioPanelListener(AudioPanelListener listener)
      Registers an AudioPanelListener to receive events from this panel.
      Parameters:
      listener - The new listener to register.

    • removeAudioPanelListener

      public void removeAudioPanelListener(AudioPanelListener listener)
      Unregisters a listener from this panel.
      Parameters:
      listener - The listener to unregister.

    • getAudioData

      public int[][] getAudioData()
      Returns the raw audio data contained by this panel.
      Returns:
      Raw audio data, suitable for manipulation by AudioUtil methods.

    • setAudioClip

      public void setAudioClip(File file) throws UnsupportedAudioFileException, IOException
      Sets the audio clip to represent in this panel using the given File, which must be in a format supported by the javax.sound package. Any previous clip in this panel is discarded.
      Parameters:
      file - A File containing an audio clip. Must be in a format supported by javax.sound.
      Throws:
      UnsupportedAudioFileException - If the file format is not supported.
      IOException - on general I/O error.

    • setAudioClip

      public void setAudioClip(BufferedInputStream stream) throws UnsupportedAudioFileException, IOException
      Sets the audio clip to represent in this panel using the given input stream. Any previous clip in this panel is discarded.
      Parameters:
      stream - A stream containing an audio clip. Must be in a format supported by javax.sound.
      Throws:
      UnsupportedAudioFileException - If the file format is not supported.
      IOException - on general I/O error.

    • setAudioClip

      public void setAudioClip(int[][] data) throws UnsupportedAudioFileException, IOException
      Sets the audio clip to represent in this panel using the given audio data array. Any previous clip in this panel is discarded.
      Parameters:
      data - The array of audio data.
      Throws:
      UnsupportedAudioFileException - If the file format is not supported.
      IOException - on general I/O error.

    • play

      public void play()
      Plays the current audio clip, if any, or does nothing if there isn't one. Does nothing if audio is currently playing or recording. This can be invoked programmatically, and is also invoked by the user from the play button, if the control panel is visible and the user clicks it.

    • stop

      public void stop()
      Stops playing, if playback was in progress, or does nothing if it wasn't. This can be invoked programmatically, and is also invoked from the stop button, if the control panel is visible and the user clicks it.

    • record

      public void record()
      Starts recording a new audio clip. Will prompt the user if an existing clip would be overwritten. If playback was in progress, it is stopped.

    • doCut

      public void doCut()
      Cuts the selected portion of the audio clip, and places it on the clipboard. Does nothing if there is no selection, or if audio is currently playing or recording.

    • doCopy

      public void doCopy()
      Copies the selected portion of the audio clip, and places it on the clipboard. Does nothing if there is no selection, or if audio is currently playing or recording.

    • doPaste

      public void doPaste()
      Pastes the contents of the clipboard into the current mark position. Does nothing if there is no audio data, or if audio is currently playing or recording. If the mark position is not set, the paste happens at the start of the clip.

    • getPanelState

      public AudioWaveformPanel.PanelState getPanelState()
      Returns the current state of this panel.
      • IDLE - neither playing nor recording.
      • PLAYING - currently playing audio.
      • RECORDING - currently recording audio.
      Returns:
      One of the PanelState enum values as described above.

    • isRecordingAllowed

      public boolean isRecordingAllowed()
      Reports whether the "record" button is visible - if true, user can click it to record a new audio clip, which will overwrite the current one if any.
      Returns:
      Whether recording is allowed.

    • setControlType

      public void setControlType(AudioWaveformPanel.ControlType controlType)

    • getControlType

      public AudioWaveformPanel.ControlType getControlType()

    • getControlPanelPosition

      public AudioWaveformPanel.ControlPosition getControlPanelPosition()
      Returns the current control panel position.
      Returns:
      The control panel position. See ControlPanelPosition enum in this class.

    • setControlPanelPosition

      public void setControlPanelPosition(AudioWaveformPanel.ControlPosition pos)
      Sets the control panel position using one of the ControlPanelPosition constants:
      • TOP_LEFT: cpanel across the top, controls on the left.
      • TOP_CENTER: cpanel across the top, controls centered horizontally.
      • TOP_RIGHT: cpanel across the top, controls on the right.
      • SIDE_EDGES: cpanel split to left/right edges; playback on left, edit on right.
      • BOTTOM_LEFT: cpanel across the bottom, controls on the left.
      • BOTTOM_CENTER: cpanel across the bottom, controls centered horizontally.
      • BOTTOM_RIGHT: cpanel across the bottom, controls on the right.
      • HIDDEN: Control panel is not shown. Playback must be controlled programmatically.
      Parameters:
      pos - One of the ControlPanelPosition constants as described above.

    • getControlPanelSize

      public AudioWaveformPanel.ControlSize getControlPanelSize()
      Returns the current control panel size, as one of the ControlPanelSize enum values. Note that this will return the last value that was set even if the control panel is not currently visible.
      Returns:
      The current or last set control panel size.

    • setControlPanelSize

      public void setControlPanelSize(AudioWaveformPanel.ControlSize size)
      Sets the size of the control panel, using one of the ControlPanelSize enum values:
      • XSMALL
      • SMALL
      • NORMAL
      • LARGE
      • XLARGE
      These values are interpolated internally. Note that this has no effect if the control panel is not currently visible.
      Parameters:
      size - One of the ControlPanelSize constants listed above.

    • getWaveformDimensions

      public Dimension getWaveformDimensions()
      Returns the pixel dimensions of the current audio waveform image, if there is one, or null otherwise.
      Returns:
      A Dimension object representing the size of the waveform image, or null.

    • clear

      public void clear()
      Clears the current waveform image.

    • regenerateWaveformImage

      public void regenerateWaveformImage()

    • buildToolBarButton

      public JButton buildToolBarButton(String iconResourceName, String description, int btnSize, int iconSize)
      Builds and returns a button with the specified icon loaded from resources, and with the icon and button set to the given pixel size.
      Parameters:
      iconResourceName - The path of the image icon resource for the button.
      description - The text description of this button.
      btnSize - The desired pixel dimensions of the button icon (assumes square icon).
      iconSize - The desired pixel dimensions of the button icon (assumes square button).
      Returns:
      A JButton that can be added to a toolbar.