net.beadsproject.beads.core
Class AudioContext

java.lang.Object
  extended by net.beadsproject.beads.core.AudioContext

public class AudioContext
extends java.lang.Object

AudioContext provides the core audio set up for running audio in a Beads project. An AudioContext determines the JavaSound AudioFormat used, the IO device, the audio buffer size and the system IO buffer size. An AudioContext also provides a UGen called out, which is the output point for networks of UGens in a Beads project.

Author:
ollie

Field Summary
static int DEFAULT_BUFFER_SIZE
           
 Gain out
          The root UGen.
 
Constructor Summary
AudioContext()
          Creates a new AudioContext with default settings.
AudioContext(javax.sound.sampled.AudioFormat audioFormat)
          Creates a new AudioContext with default buffer size, default AudioIO and the specified audio format.
AudioContext(AudioIO ioSystem)
          Creates a new AudioContext with default audio format and buffer size and the specified AudioIO.
AudioContext(int bufferSizeInFrames)
          Creates a new AudioContext with default settings and the specified buffer size.
AudioContext(int bufferSizeInFrames, javax.sound.sampled.AudioFormat audioFormat)
          Creates a new AudioContext with the default AudioIO and the specified audio format and buffer size.
AudioContext(int bufferSizeInFrames, AudioIO ioSystem)
          Creates a new AudioContext with default audio format and the specified buffer size and AudioIO.
AudioContext(int bufferSizeInFrames, AudioIO ioSystem, javax.sound.sampled.AudioFormat audioFormat)
          Creates a new AudioContext with the specified buffer size, AudioIO and audio format.
 
Method Summary
static javax.sound.sampled.AudioFormat defaultAudioFormat(int numChannels)
          Generates the default AudioFormat for AudioContext, with the given number of channels.
static AudioIO defaultAudioIO()
          produces the default AudioIO which is a JavaSoundAudioIO with noargs constructor.
 TimeStamp generateTimeStamp(int index)
          Generates a TimeStamp with the current time step and the given index into the time step.
 javax.sound.sampled.AudioFormat getAudioFormat()
          Gets the AudioFormat for this AudioContext.
 javax.sound.sampled.AudioFormat getAudioFormat(int numChannels)
          Generates a new AudioFormat with the same everything as the AudioContext's AudioFormat except for the number of channels.
 UGen getAudioInput()
          Returns a UGen which can be used to grab audio from the audio input, as specified by the AudioIO.
 UGen getAudioInput(int[] channels)
          Returns a UGen which can be used to grab audio from the audio input, as specified by the AudioIO.
 AudioIO getAudioIO()
           
 float[] getBuf()
          Gets a buffer from the buffer reserve.
 int getBufferSize()
          Gets the buffer size for this AudioContext.
 float[] getCleanBuf()
          Gets a zero initialised buffer from the buffer reserve.
 javax.sound.sampled.AudioFormat getInputAudioFormat()
          Gets the input AudioFormat for this AudioContext.
 float getSampleRate()
          Gets the sample rate for this AudioContext.
 double getTime()
          Get the runtime (in ms) since starting.
 long getTimeStep()
          Gets the current time step of this AudioContext.
 float[] getZeroBuf()
          Gets a pointer to a buffer of length bufferSize, full of zeros.
 boolean isRunning()
          Checks if this AudioContext is running.
 void logTime(boolean logTime)
          Switch on/off logging of time when running in realtime.
 double msToSamples(double msTime)
          Converts samples to milliseconds at the current sample rate.
 void postAudioFormatInfo()
          Prints AudioFormat information to System.out.
 void printCallChain()
          Prints the entire call chain to System.out (equivalent to AudioContext.printCallChain(this.out, 0);)
static void printCallChain(UGen current, int depth)
          Prints a representation of the audio signal chain stemming upwards from the specified UGen to System.out, indented by the specified depth.
 void quickie(UGen ugen)
          Convenience method to quickly audition a UGen.
 void record(double timeMS, java.lang.String filename)
          Tells the AudioContext to record all output for the given millisecond duration, kill the AudioContext, and save the recording to the given file path.
 void runForNMillisecondsNonRealTime(float n)
          Runs the AudioContext in non-realtime for n milliseconds (that's n non-realtime milliseconds).
 void runNonRealTime()
          Starts the AudioContext running in non-realtime.
 double samplesToMs(double sampleTime)
          Converts milliseconds to samples at the current sample rate.
 void setInputAudioFormat(javax.sound.sampled.AudioFormat inputAudioFormat)
          Set the input AudioFormat for this AudioContext.
 void start()
          Starts the AudioContext running in realtime.
 void stop()
          Stops the AudioContext if running either in realtime or non-realtime.
protected  void update()
          callback from AudioIO.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE
See Also:
Constant Field Values

out

public final Gain out
The root UGen.

Constructor Detail

AudioContext

public AudioContext()
Creates a new AudioContext with default settings. The default buffer size is 512 and the default system buffer size is 5000. The default audio format is 44.1Khz, 16 bit, stereo, signed, bigEndian.


AudioContext

public AudioContext(int bufferSizeInFrames)
Creates a new AudioContext with default settings and the specified buffer size. The default system buffer size is determined by the JVM. The default audio format is 44.1Khz, 16 bit, stereo, signed, bigEndian.

Parameters:
bufferSizeInFrames - the buffer size in samples.

AudioContext

public AudioContext(AudioIO ioSystem)
Creates a new AudioContext with default audio format and buffer size and the specified AudioIO. The default audio format is 44.1Khz, 16 bit, stereo, signed, bigEndian.

Parameters:
ioSystem - the AudioIO system.

AudioContext

public AudioContext(int bufferSizeInFrames,
                    AudioIO ioSystem)
Creates a new AudioContext with default audio format and the specified buffer size and AudioIO. The default audio format is 44.1Khz, 16 bit, stereo, signed, bigEndian.

Parameters:
bufferSizeInFrames - the buffer size in samples.
ioSystem - the AudioIO system.

AudioContext

public AudioContext(int bufferSizeInFrames,
                    javax.sound.sampled.AudioFormat audioFormat)
Creates a new AudioContext with the default AudioIO and the specified audio format and buffer size.

Parameters:
bufferSizeInFrames - the buffer size in samples.
audioFormat - the audio format, which specifies sample rate, bit depth, number of channels, signedness and byte order.

AudioContext

public AudioContext(javax.sound.sampled.AudioFormat audioFormat)
Creates a new AudioContext with default buffer size, default AudioIO and the specified audio format.

Parameters:
audioFormat - the audio format, which specifies sample rate, bit depth, number of channels, signedness and byte order.

AudioContext

public AudioContext(int bufferSizeInFrames,
                    AudioIO ioSystem,
                    javax.sound.sampled.AudioFormat audioFormat)
Creates a new AudioContext with the specified buffer size, AudioIO and audio format.

Parameters:
bufferSizeInFrames - the buffer size in samples.
ioSystem - the AudioIO system.
audioFormat - the audio format, which specifies sample rate, bit depth, number of channels, signedness and byte order.
Method Detail

getAudioInput

public UGen getAudioInput(int[] channels)
Returns a UGen which can be used to grab audio from the audio input, as specified by the AudioIO.

Parameters:
channels - an array of ints indicating which channels are required.
Returns:
a UGen which can be used to access audio input.

getAudioInput

public UGen getAudioInput()
Returns a UGen which can be used to grab audio from the audio input, as specified by the AudioIO. This method returns a UGen with one out for each input channel of the audio input device. For access to specific channels see getAudioInput(int[]).

Returns:
a UGen which can be used to access audio input.

defaultAudioIO

public static AudioIO defaultAudioIO()
produces the default AudioIO which is a JavaSoundAudioIO with noargs constructor.

Returns:
a new JavaSoundAudioIO with noargs constructor.

update

protected void update()
callback from AudioIO.


getBuf

public float[] getBuf()
Gets a buffer from the buffer reserve. This buffer will be owned by you until the next time step, and you shouldn't attempt to use it outside of the current time step. The length of the buffer is bufferSize, but there is no guarantee as to its contents.

Returns:
buffer of size bufSize, unknown contents.

getCleanBuf

public float[] getCleanBuf()
Gets a zero initialised buffer from the buffer reserve. This buffer will be owned by you until the next time step, and you shouldn't attempt to use it outside of the current time step. The length of the buffer is bufferSize, and the buffer is full of zeros.

Returns:
buffer of size bufSize, all zeros.

getZeroBuf

public float[] getZeroBuf()
Gets a pointer to a buffer of length bufferSize, full of zeros. Changing the contents of this buffer would be completely disastrous. If you want a buffer of zeros that you can actually do something with, use getCleanBuf().

Returns:
buffer of size bufSize, all zeros.

runNonRealTime

public void runNonRealTime()
Starts the AudioContext running in non-realtime. This occurs in the current Thread.


runForNMillisecondsNonRealTime

public void runForNMillisecondsNonRealTime(float n)
Runs the AudioContext in non-realtime for n milliseconds (that's n non-realtime milliseconds).

Parameters:
n - number of milliseconds.

getBufferSize

public int getBufferSize()
Gets the buffer size for this AudioContext.

Returns:
Buffer size in samples.

getSampleRate

public float getSampleRate()
Gets the sample rate for this AudioContext.

Returns:
sample rate in samples per second.

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat()
Gets the AudioFormat for this AudioContext.

Returns:
AudioFormat used by this AudioContext.

getInputAudioFormat

public javax.sound.sampled.AudioFormat getInputAudioFormat()
Gets the input AudioFormat for this AudioContext.

Returns:
AudioFormat used by this AudioContext for input.

setInputAudioFormat

public void setInputAudioFormat(javax.sound.sampled.AudioFormat inputAudioFormat)
Set the input AudioFormat for this AudioContext.

Parameters:
inputAudioFormat - AudioFormat used by this AudioContext for input.

getAudioFormat

public javax.sound.sampled.AudioFormat getAudioFormat(int numChannels)
Generates a new AudioFormat with the same everything as the AudioContext's AudioFormat except for the number of channels.

Parameters:
numChannels - the number of channels.
Returns:
a new AudioFormat with the given number of channels, all other properties coming from the original AudioFormat.

defaultAudioFormat

public static javax.sound.sampled.AudioFormat defaultAudioFormat(int numChannels)
Generates the default AudioFormat for AudioContext, with the given number of channels. The default values are: sampleRate=44100, sampleSizeInBits=16, signed=true, bigEndian=true.

Parameters:
numChannels - the number of channels to use.
Returns:
the generated AudioFormat.

postAudioFormatInfo

public void postAudioFormatInfo()
Prints AudioFormat information to System.out.


printCallChain

public static void printCallChain(UGen current,
                                  int depth)
Prints a representation of the audio signal chain stemming upwards from the specified UGen to System.out, indented by the specified depth.

Parameters:
current - UGen to start from.
depth - depth by which to indent.

printCallChain

public void printCallChain()
Prints the entire call chain to System.out (equivalent to AudioContext.printCallChain(this.out, 0);)


msToSamples

public double msToSamples(double msTime)
Converts samples to milliseconds at the current sample rate.

Parameters:
msTime - duration in milliseconds.
Returns:
number of samples.

samplesToMs

public double samplesToMs(double sampleTime)
Converts milliseconds to samples at the current sample rate.

Parameters:
sampleTime - number of samples.
Returns:
duration in milliseconds.

getTimeStep

public long getTimeStep()
Gets the current time step of this AudioContext. The time step begins at zero when the AudioContext is started and is incremented by 1 for each update of the audio buffer.

Returns:
current time step.

generateTimeStamp

public TimeStamp generateTimeStamp(int index)
Generates a TimeStamp with the current time step and the given index into the time step.

Parameters:
index - the index into the current time step.
Returns:
a TimeStamp.

getTime

public double getTime()
Get the runtime (in ms) since starting.


logTime

public void logTime(boolean logTime)
Switch on/off logging of time when running in realtime. The time is printed to System.out every 100 time steps.

Parameters:
logTime - set true to log time.

record

public void record(double timeMS,
                   java.lang.String filename)
            throws java.io.IOException
Tells the AudioContext to record all output for the given millisecond duration, kill the AudioContext, and save the recording to the given file path. This is a convenient way to make quick recordings, but may not suit every circumstance.

Parameters:
timeMS - the time in milliseconds to record for.
filename - the filename to save the recording to.
Throws:
java.io.IOException - Signals that an I/O exception has occurred.
See Also:
recorder, sample

quickie

public void quickie(UGen ugen)
Convenience method to quickly audition a UGen.

Parameters:
ugen - the UGen to audition.

start

public void start()
Starts the AudioContext running in realtime. Only happens if not already running. Resets time.


stop

public void stop()
Stops the AudioContext if running either in realtime or non-realtime.


isRunning

public boolean isRunning()
Checks if this AudioContext is running.

Returns:
true if running.

getAudioIO

public AudioIO getAudioIO()
Returns:
The AudioIO used by this context.