Package com.adonax.audiocue

Class AudioMixer

java.lang.Object
com.adonax.audiocue.AudioMixer
All Implemented Interfaces:
AutoCloseable
public class AudioMixer extends Object implements AutoCloseable
An AudioMixer mixes the media content of all the members of a AudioMixerTrack collection into a single output line. Classes implementing AudioMixerTrack can be added and removed from the mix asynchronously, with the operation occurring at the next iteration of the read buffer. Unlike a mixer used in sound studios, the AudioMixer does not provide functions such as panning or volume controls.

An SourceDataLine can be in one of two states: (1) running, or (2) not running. When running, audio data is read from the constituent tracks, mixed and written as a single stream using a javax.sound.sampled.SourceDataLine. The mixer imposes a simple floor/ceiling of -1, 1, to guard against volume overflows. When not running, the SourceDataLine is allowed to drain and close. A new SourceDataLine is instantiated if/when this AudioMixer is reopened.

Values used to configure the media output are provided in the constructor, and are held as immutable. These include a javax.sound.sampled.Mixer used to provide the SourceDataLine, the size of the buffer used for iterative reads of the PCM data, and the thread priority. Multiple constructors are provided to facilitate the use of default values. These configuration values override those associated with the constituent tracks.

Since:
2.0.0
Version:
2.0.0
Author:
Philip Freihofner
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final int
    bufferFrames
    An immutable number of PCM frames held in array buffers, set during instantiation.
    final int
    readBufferSize
    An immutable number describing the size of an internal array buffer, set during instantiation.
    final int
    sdlByteBufferSize
    An immutable number describing the size of an internal array buffer, set during instantiation.
    final int
    threadPriority
    A value that holds the priority level of the thread that that handles the media output, set upon instantiation of the class.

  • Constructor Summary

    Constructors
    Constructor
    Description
    AudioMixer()
    Constructor for AudioMixer, using default settings: Mixer = system default Buffer size = 8192 frames Thread priority = 10.
    AudioMixer(Mixer mixer, int bufferFrames, int threadPriority)
    Constructor for AudioMixer.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addTrack(AudioMixerTrack track)
    Designates an AudioMixerTrack to be staged for addition into the collection of tracks actively being mixed.
    void
    close()
     
    int
    getTracksCount()
    Returns the number of tracks being mixed.
    void
    removeTrack(AudioMixerTrack track)
    Designates an AudioMixerTrack to be staged for removal from the collection of tracks actively being mixed.
    void
    start()
    Starts the operation of the AudioMixer.
    void
    stop()
    Sets a flag that will signal the AudioMixer to stop media writes and release resources.
    void
    updateTracks()
    Signals the internal media writer to load an updated AudiomixerTrack collection at the next opportunity.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • bufferFrames

      public final int bufferFrames
      An immutable number of PCM frames held in array buffers, set during instantiation.

    • readBufferSize

      public final int readBufferSize
      An immutable number describing the size of an internal array buffer, set during instantiation. The readBufferSize has two PCM values per each frame being handled, corresponding to the left and right stereo channels, and is calculated by multiplying bufferFrames by 2.

    • sdlByteBufferSize

      public final int sdlByteBufferSize
      An immutable number describing the size of an internal array buffer, set during instantiation. The sdlBufferSize has four bytes per frame, as each of the two PCM values per frame is encoded into two constituent bytes. The sdlByteBufferSize is calculated by multiplying bufferFrames by 4.

    • threadPriority

      public final int threadPriority
      A value that holds the priority level of the thread that that handles the media output, set upon instantiation of the class. The value is clamped to the range java.lang.Thread.MIN_PRIORITY to java.lang.Thread.MAX_PRIORITY.

  • Constructor Details

    • AudioMixer

      public AudioMixer()
      Constructor for AudioMixer, using default settings: Mixer = system default Buffer size = 8192 frames Thread priority = 10. The buffer size pertains to the frames collected in a single while loop iteration. A buffer that corresponds to the same number of frames converted to bytes is assigned to the SourceDataLine.

    • AudioMixer

      public AudioMixer(Mixer mixer, int bufferFrames, int threadPriority)
      Constructor for AudioMixer. The buffer size is the number of frames collected in a single while loop iteration. A buffer with a corresponding frame count, calculated in bytes, is assigned to the SourceDataLine. A thread priority of 10 is recommended, in order to help prevent sound drop outs. Note that a well designed and properly running sound thread should spend the vast majority of its time in a blocked state, and thus have a minimal impact in terms of usurping cpu cycles from other threads.
      Parameters:
      mixer - javax.sound.sampled.Mixer to be used
      bufferFrames - int specifying the number of frames to process with each iteration
      threadPriority - int ranging from 1 to 10 specifying the priority of the sound thread

  • Method Details

    • getTracksCount

      public int getTracksCount()
      Returns the number of tracks being mixed.
      Returns:
      integer number of tracks being mixed.

    • addTrack

      public void addTrack(AudioMixerTrack track)
      Designates an AudioMixerTrack to be staged for addition into the collection of tracks actively being mixed. If the AudioMixer is running, actual addition occurs when the updateTracks method is executed. If the AudioMixer is not running, the addition will occur automatically when the start method is called.
      Parameters:
      track - - an AudioMixerTrack to be added to the mix
      See Also:

    • removeTrack

      public void removeTrack(AudioMixerTrack track)
      Designates an AudioMixerTrack to be staged for removal from the collection of tracks actively being mixed. If the AudioMixer is running, actual removal occurs when the updateTracks method is executed. If the AudioMixer is not running, the removal will occur automatically when the start method is called.
      Parameters:
      track - - an AudioMixerTrack to be removed from the mix
      See Also:

    • updateTracks

      public void updateTracks()
      Signals the internal media writer to load an updated AudiomixerTrack collection at the next opportunity. Tracks to be added or removed are first staged using the methods addTrack and removeTrack.
      See Also:

    • start

      public void start() throws LineUnavailableException
      Starts the operation of the AudioMixer. A running AudioMixer iteratively sums a buffer's worth of frames of sound data from a collection of AudioMixerTracks, and writes the resulting array to a SourceDataLine.
      Throws:
      IllegalStateException - is thrown if the AudioMixer is already running.
      LineUnavailableException - is thrown if there is a problem securing a SourceDataLine

    • stop

      public void stop()
      Sets a flag that will signal the AudioMixer to stop media writes and release resources.
      Throws:
      IllegalStateException - if the AudioMixer is already in a stopped state.

    • close

      public void close() throws Exception
      Specified by:
      close in interface AutoCloseable
      Throws:
      Exception