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 has 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
           
static int DEFAULT_SYSTEM_BUFFER_SIZE
           
 Gain out
          The root UGen.
 
Constructor Summary
AudioContext()
          Creates a new AudioContext with default settings.
AudioContext(int bufferSizeInFrames)
          Creates a new AudioContext with default settings and the specified buffer size.
AudioContext(int bufferSizeInFrames, int systemBufferSizeInFrames)
          Creates a new AudioContext with default audio format and the specified buffer size and system buffer size.
AudioContext(int bufferSizeInFrames, int systemBufferSizeInFrames, javax.sound.sampled.AudioFormat audioFormat)
          Creates a new AudioContext with the specified buffer size, system buffer size and audio format.
 
Method Summary
 void checkForDroppedFrames(boolean checkForDroppedFrames)
          Switch on/off checking for dropped frames when running in realtime.
 void chooseMixerCommandLine()
          Presents a choice of mixers on the commandline.
static javax.sound.sampled.AudioFormat defaultAudioFormat(int numChannels)
          Generates the default AudioFormat for AudioContext, with the given number of channels.
 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.
 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.
 float getSampleRate()
          Gets the sample rate for this AudioContext.
 int getSystemBufferSize()
          Gets the system buffer size 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 postSourceDataLineInfo()
          Prints SourceDataLine info to System.out.
static void printMixerInfo()
          Prints information about the current Mixer to System.out.
 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 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 selectMixer(int i)
          Select a mixer by index.
 void start()
          Starts the AudioContext running in realtime.
 void stop()
          Stops the AudioContext if running either in realtime or non-realtime.
 
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

DEFAULT_SYSTEM_BUFFER_SIZE

public static final int DEFAULT_SYSTEM_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(int bufferSizeInFrames,
                    int systemBufferSizeInFrames)
Creates a new AudioContext with default audio format and the specified buffer size and system buffer size. The default audio format is 44.1Khz, 16 bit, stereo, signed, bigEndian.

Parameters:
bufferSizeInFrames - the buffer size in samples.
systemBufferSizeInFrames - the system buffer size in samples.

AudioContext

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

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

chooseMixerCommandLine

public void chooseMixerCommandLine()
Presents a choice of mixers on the commandline.


selectMixer

public void selectMixer(int i)
Select a mixer by index.

Parameters:
i - the index of the selected mixer.

printMixerInfo

public static void printMixerInfo()
Prints information about the current Mixer to System.out.


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.

isRunning

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

Returns:
true if running.

start

public void start()
Starts the AudioContext running in realtime.


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.

getSystemBufferSize

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

Returns:
System 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.

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.

stop

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


postAudioFormatInfo

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


postSourceDataLineInfo

public void postSourceDataLineInfo()
Prints SourceDataLine info to System.out.


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.

checkForDroppedFrames

public void checkForDroppedFrames(boolean checkForDroppedFrames)
Switch on/off checking for dropped frames when running in realtime. The scheduler checks to see if audio is not being calculated quickly enough, and prints dropped-frame messages to System.out.

Parameters:
checkForDroppedFrames - set true to check for dropped frames.

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 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.