Package ca.corbett.extras.audio

Class AudioUtil

java.lang.Object
ca.corbett.extras.audio.AudioUtil
public class AudioUtil extends Object
A utility class that can be used to interact with audio files. This is an abstraction over the javax.sound utility classes, but also adds some additional features.
Since:
2018-01-03
Author:
scorbo2

  • Method Details

    • play

      public static PlaybackThread play(File audioFile, PlaybackListener listener) throws UnsupportedAudioFileException, IOException, LineUnavailableException
      Loads and plays the given audio file. If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      audioFile - A file containing audio. Must be in a format supported by javax.sound.
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • play

      public static PlaybackThread play(BufferedInputStream inStream, PlaybackListener listener) throws UnsupportedAudioFileException, IOException, LineUnavailableException
      Loads and plays the given audio stream. If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      inStream - A stream containing audio. Must be in a format supported by javax.sound.
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • play

      public static PlaybackThread play(int[][] audioData, PlaybackListener listener) throws IOException, LineUnavailableException
      Loads and plays the given audio data. If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      audioData - An int array containing audio data (from one of the parseAudio methods).
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • play

      public static PlaybackThread play(File audioFile, long offset, long limit, PlaybackListener listener) throws UnsupportedAudioFileException, IOException, LineUnavailableException
      Loads and plays the given audio file, starting from the given offset and ending at the given limit (all times in milliseconds). If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      audioFile - A file containing audio. Must be in a format supported by javax.sound.
      offset - An offset, in milliseconds, where to start playing. 0 means play from start.
      limit - An offset, in milliseconds, where to stop playing. 0 means play to end of stream.
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • play

      public static PlaybackThread play(BufferedInputStream inStream, long offset, long limit, PlaybackListener listener) throws UnsupportedAudioFileException, IOException, LineUnavailableException
      Loads and plays the given audio stream, starting from the given offset and ending at the given limit (all times in milliseconds). If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      inStream - A stream containing audio. Must be in a format supported by javax.sound.
      offset - An offset, in milliseconds, where to start playing. 0 means play from start.
      limit - An offset, in milliseconds, where to stop playing. 0 means play to end of stream.
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • play

      public static PlaybackThread play(int[][] audioData, long offset, long limit, PlaybackListener listener) throws IOException, LineUnavailableException
      Loads and plays the given audio data, starting from the given offset and ending at the given limit (all times in milliseconds). If you specify a PlaybackListener, it will receive events during playback and when playback ends. A PlaybackThread instance is returned which can be used to control playback. Playback starts immediately, but this method does not block - it returns immediately. Your code can continue processing as normal, and playback will end naturally when the end of the audio stream is reached. You can also use the facilities within PlaybackThread to control playback.
      Parameters:
      audioData - An int array containing audio data (from one of the parseAudio methods).
      offset - An offset, in milliseconds, where to start playing. 0 means play from start.
      limit - An offset, in milliseconds, where to stop playing. 0 means play to end of stream.
      listener - An optional PlaybackListener to receive playback events. Can be null.
      Returns:
      A PlaybackThread instance.
      Throws:
      IOException - On general i/o error.
      LineUnavailableException - On audio system error.

    • parseAudioFile

      public static int[][] parseAudioFile(File file) throws UnsupportedAudioFileException, IOException
      Attempts to parse the given audio file to return the raw PCM audio samples, returned as a multi-dimensional int array. The outer array is by channel (one for monaural, two for stereo, more for 5.1 or whatever). The inner array is for the actual audio samples themselves.
      Parameters:
      file - The File containing the audio data. Must be in a format supported by javax.sound.
      Returns:
      A multi-dimensional array as described above.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general I/O error.

    • parseAudioStream

      public static int[][] parseAudioStream(BufferedInputStream inStream) throws UnsupportedAudioFileException, IOException
      Attempts to parse the given audio stream to return the raw PCM audio samples, returned as a multi-dimensional int array. The outer array is by channel (one for monoraul, two for stereo, more for 5.1 or whatever). The inner array is for the actual audio samples themselves. The given stream will be closed before return, unless some exception is thrown.
      Parameters:
      inStream - An InputStream containing the audio data. Must be in a supported format.
      Returns:
      A multi-dimensional int array as described above.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general I/O error.

    • saveAudioFile

      public static void saveAudioFile(File file, int[][] audioData) throws IOException
      Writes the given channel/sample array to the specified file. The multi-dimensional array is structured the same as the return from parseAudioFile() - that is, the outer array is by channel, the inner arrays are for actual audio samples. We assume 16 bit samples and a rate of 44.1Khz for the output.
      Parameters:
      file - The File to which to save the audio data. Will be overwritten if it exists.
      audioData - A multi-dimensional array of audio data as outlined above.
      Throws:
      IOException - on general i/o problem.

    • getAudioInputStream

      public static AudioInputStream getAudioInputStream(int[][] audioData)
      Constructs an AudioInputStream based on the parsed audio data. This is mainly used to play a clip that has been parsed by one of the parseAudio methods in this class.
      Parameters:
      audioData - Audio data as parsed by one of the parseAudio methods in this class.
      Returns:
      An AudioInputStream ready to be read.

    • generateWaveform

      public static BufferedImage generateWaveform(File file) throws UnsupportedAudioFileException, IOException
      Parses the given audio file and returns a BufferedImage containing a graphical waveform representing the contained audio. All WaveformConfig are set to their default values - if this is not acceptable, use generateWaveform(WaveformConfig) instead.
      Parameters:
      file - An audio file.
      Returns:
      A BufferedImage containing a graphical waveform of the given audio file.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.

    • generateWaveform

      public static BufferedImage generateWaveform(BufferedInputStream audioStream) throws UnsupportedAudioFileException, IOException
      Parses the given audio stream and returns a BufferedImage containing a graphical waveform representing the contained audio. All WaveformConfig are set to their default values - if this is not acceptable, use generateWaveform(WaveformConfig) instead.
      Parameters:
      audioStream - An InputStream containing audio data. Must be in a supported format.
      Returns:
      A BufferedImage containing a graphical waveform of the given audio file.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.

    • generateWaveform

      public static BufferedImage generateWaveform(File file, WaveformConfig prefs) throws UnsupportedAudioFileException, IOException
      Parses the given audio file and returns a BufferedImage containing a graphical waveform from the contained audio. See WaveformConfig for options around controlling what the output looks like.
      Parameters:
      file - An audio file.
      prefs - A WaveformConfig instance containing desired preferences.
      Returns:
      A BufferedImage containing a graphical waveform of the given audio file.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.

    • generateWaveform

      public static BufferedImage generateWaveform(BufferedInputStream audioStream, WaveformConfig prefs) throws UnsupportedAudioFileException, IOException
      Parses the given audio stream and returns a BufferedImage containing a graphical waveform from the contained audio. See WaveformConfig for options around controlling what the output looks like.
      Parameters:
      audioStream - An InputStream containing audio data. Must be in a supported format.
      prefs - A WaveformConfig instance containing desired preferences.
      Returns:
      A BufferedImage containing a graphical waveform of the given audio file.
      Throws:
      UnsupportedAudioFileException - On unsupported audio.
      IOException - On general i/o error.

    • generateWaveform

      public static BufferedImage generateWaveform(int[][] audioData, WaveformConfig prefs)
      Generates a BufferedImage containing a graphical waveform representing the audio in the given multidimensional int array. This is primarily inovked from the other generateWaveform methods in this class, but can be invoked by clients also if they have parsed the audio already.
      Parameters:
      audioData - The parsed audio data, presumably from one of the parseAudio methods.
      prefs - A WaveformConfig instance describing what the waveform should look like.
      Returns:
      A BufferedImage containing a graphical representation of the audio data.