jm.audio

## Class RTMixer

- java.lang.Object
- - jm.audio.RTMixer

- All Implemented Interfaces:
    AudioChainListener

      public class RTMixer
      extends java.lang.Object
      implements AudioChainListener

  RTMixer is responsible for convolving the audio signals being pulled from n number of RTLines. RTMixer uses a single JMF Java Sound SourceDataLine object for writing the newly convolved signal to the audio device. Buffers of audio sample data are passed to the SourceDataLine at a rate set by the Control Rate value. The contol rate sets the size of the audio buffers used by RTMixer, SourceDataLine and Instrument. Information about sample rate and channels is retrieved from the first audio object of the first instrument of the first RTLine. Therefore, there is an assumption that all instruments have the same sample rate and number of channels.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `channels` The number of channels to be used when setting up SourceDataLine
    `protected double` | `controlRate` The control rate is used to set how often in instrument returns a full buffer of audio samples.
    `long` | `currentTime` A Timer which keeps track of how many samples have been written since this object started
    `protected int` | `sampleRate` The sampleRate to be used when establishing the JMF SourceDataLine

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RTMixer(RTLine[] rtlines)` The RTMixer constructor sets a number of attributes and opens a JMF java sound sourceDataLine.
    `RTMixer(RTLine[] rtlines, double controlRate)` The RTMixer constructor sets a number of attributes and opens a JMF java sound sourceDataLine.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `actionLines(java.lang.Object obj, int actionNumber)` This method passes on external action requests (i.e.
    `void` | `addLines(RTLine[] lines)`
    `void` | `begin()` Begin starts RTMixer.
    `void` | `controlChange(float[] buffer, int returned, boolean finished)` The controlChange method is called every time an instrument fills a sample buffer.
    `void` | `finalize()`
    `void` | `pause()` Pauses RTMixer playback.
    `void` | `stop()` Stops RTMixer playback.
    `void` | `unPause()` Continues the RTMixer playback.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### sampleRate

          protected int sampleRate

      The sampleRate to be used when establishing the JMF SourceDataLine

    - #### channels

          protected int channels

      The number of channels to be used when setting up SourceDataLine

    - #### currentTime

          public long currentTime

      A Timer which keeps track of how many samples have been written since this object started

    - #### controlRate

          protected double controlRate

      The control rate is used to set how often in instrument returns a full buffer of audio samples. This is acheived by changing the size of the instrument buffers. It is critical to the audio performance and can be tuned to the suit the different computers. Smaller values are prefereable because they give jMusic audio less latency, but values that are too small will cause the audio system to choke and splutter.

  - ### Constructor Detail

    - #### RTMixer

          public RTMixer(RTLine[] rtlines)

      The RTMixer constructor sets a number of attributes and opens a JMF java sound sourceDataLine.
      Parameters:
        `inst` - the Instruments to be processed by this object.

    - #### RTMixer

          public RTMixer(RTLine[] rtlines,
                 double controlRate)

      The RTMixer constructor sets a number of attributes and opens a JMF java sound sourceDataLine.
      Parameters:
        `inst` - - The Instruments to be processed by this object.
        `controlRate` - - Sets the regularity of audio parameter change. The control rate is used to set how often in instrument returns a full buffer of audio samples. This is acheived by changing the size of the instrument buffers.

        Control rate is critical to the audio performance and can be tuned to the suit different computers. Smaller values are prefereable because the resulting smaller buffer equates to a less latency, but values that are too small will cause the audio system to choke and splutter. Values typically fall in the rage 0.01 - 0.005.

  - ### Method Detail

    - #### addLines

          public void addLines(RTLine[] lines)

    - #### controlChange

          public void controlChange(float[] buffer,
                           int returned,
                           boolean finished)

      The controlChange method is called every time an instrument fills a sample buffer. This method is responsible for receiving the sample buffer and convolving it with the data in sampleArray.
      Specified by:
        `controlChange` in interface `AudioChainListener`
      Parameters:
        `buffer` - a sample array filled by an instrument
        `returned` - the number of samples in the buffer
        `finished` - indicates whether the instruments current note is finished or not.

    - #### begin

          public void begin()

      Begin starts RTMixer.

    - #### pause

          public void pause()

      Pauses RTMixer playback.

    - #### unPause

          public void unPause()

      Continues the RTMixer playback.

    - #### stop

          public void stop()

      Stops RTMixer playback.

    - #### actionLines

          public void actionLines(java.lang.Object obj,
                         int actionNumber)

      This method passes on external action requests (i.e. gui based action events) to each RTLine's externalAction method).
      Parameters:
        `obj` - an unspecified object type (externalAction will cast)
        `actionNumber` - an indentifyer for the originator of the action request (i.e. if there are three buttons there would actionNumbers 1,2 and 3)

    - #### finalize

          public void finalize()

      Overrides:
        `finalize` in class `java.lang.Object`