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 IOAudioFormat 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()
          This constructor creates the default AudioContext, which means org.jaudiolibs.beads.AudioServerIO$JavaSound if it can find it, or net.beadsproject.beads.core.io.NonrealtimeIO otherwise.
AudioContext(AudioIO ioSystem)
          Creates a new AudioContext with default audio format and buffer size and the specified AudioIO.
AudioContext(AudioIO ioSystem, int bufferSizeInFrames)
          Creates a new AudioContext with default audio format and the specified buffer size and AudioIO.
AudioContext(AudioIO ioSystem, int bufferSizeInFrames, IOAudioFormat audioFormat)
          Creates a new AudioContext with the specified buffer size, AudioIO and audio format.
 
Method Summary
static IOAudioFormat defaultAudioFormat(int inputs, int outputs)
          Generates the default IOAudioFormat 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.
 IOAudioFormat getAudioFormat()
          Gets the AudioFormat for this AudioContext.
 IOAudioFormat getAudioFormat(int inputs, int outputs)
          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.
 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 reset()
          Simply resets the timeStep to zero.
 void runForNMillisecondsNonRealTime(double 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 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()
This constructor creates the default AudioContext, which means org.jaudiolibs.beads.AudioServerIO$JavaSound if it can find it, or net.beadsproject.beads.core.io.NonrealtimeIO otherwise. To get the former, link to the jaudiolibs-beads.jar file. The libraries are decoupled like this so that the core beads library doesn't depend on JavaSound, which is not supported in various contexts, such as Android. At the moment there are in fact some JavaSound dependencies still to be removed before this process is complete. Pro-users should familiarise themselves with the different IO options, particularly Jack.


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(AudioIO ioSystem,
                    int bufferSizeInFrames)
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(AudioIO ioSystem,
                    int bufferSizeInFrames,
                    IOAudioFormat 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.

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(double 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 IOAudioFormat getAudioFormat()
Gets the AudioFormat for this AudioContext.

Returns:
AudioFormat used by this AudioContext.

getAudioFormat

public IOAudioFormat getAudioFormat(int inputs,
                                    int outputs)
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 IOAudioFormat defaultAudioFormat(int inputs,
                                               int outputs)
Generates the default IOAudioFormat 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.lang.Exception
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.
java.lang.Exception
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.


reset

public void reset()
Simply resets the timeStep to zero.


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.