ptolemy.actor.lib.jjs.modules.audio

Class AudioHelper

java.lang.Object

ptolemy.actor.lib.jjs.HelperBase

ptolemy.actor.lib.jjs.VertxHelperBase

ptolemy.actor.lib.jjs.modules.audio.AudioHelper

public class AudioHelper
extends VertxHelperBase

Helper for the audio.js JavaScript module. See the module for documentation. This class is based on the LiveSoundJavaSE class in Ptolemy II, written by Brian K. Vogel, Neil E. Turner, Steve Neuendorffer, and Edward A. Lee, with contributions from Dennis Geurts, Ishwinder Singh.

Since:

Ptolemy II 11.0

Version:

$Id$

Author:

Edward A. Lee

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Yellow (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.actor.lib.jjs.VertxHelperBase

VertxHelperBase.AccessorVerticle

Nested classes/interfaces inherited from class ptolemy.actor.lib.jjs.HelperBase

HelperBase.DATA_TYPE

Field Summary

Fields inherited from class ptolemy.actor.lib.jjs.VertxHelperBase

_verticle, _vertx

Fields inherited from class ptolemy.actor.lib.jjs.HelperBase

_actor, _currentObj

Constructor Summary

Constructors

Constructor and Description
AudioHelper(java.lang.Object actor, jdk.nashorn.api.scripting.ScriptObjectMirror currentObj) Create an audio helper.

Method Summary

Modifier and Type	Method and Description
static java.lang.String[]	byteFormats() Return an array of supported byte formats for audio.
void	putBytes(byte[] audioData, java.lang.Runnable callback) Play an array of audio samples given as a byte array.
void	putSamples(double[][] samplesArray, java.lang.Runnable callback) Play an array of audio samples.
void	setCaptureParameters(java.util.Map<java.lang.String,java.lang.Integer> captureOptions, int captureTime, java.lang.String outputFormat) Set the capture parameters for audio.
void	setPlaybackParameters(java.util.Map<java.lang.String,java.lang.Integer> playbackOptions, java.lang.String playbackFormat) Set the playback parameters for audio.
void	startCapture() Start audio capture if it is not already active.
void	startPlayback() Start audio playback if it is not already active.
void	stopCapture() Stop audio capture if it is active.
void	stopPlayback() Stop audio playback if it is active.

Methods inherited from class ptolemy.actor.lib.jjs.VertxHelperBase

_issueOrDeferResponse, _processPendingJob, _setBusy, closeVertx, getHelper, getImageTypes, reset, submit, supportedReceiveTypes, supportedSendTypes, undeploy

Methods inherited from class ptolemy.actor.lib.jjs.HelperBase

_appendNumericToBuffer, _appendToBuffer, _error, _error, _error, _error, _extractFromBuffer, _issueResponse, _removeDuplicates, _sizeOfType, _toJavaBytes, _toJSArray, getHelping

Methods inherited from class java.lang.Object

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

Constructor Detail

AudioHelper

public AudioHelper(java.lang.Object actor,
                   jdk.nashorn.api.scripting.ScriptObjectMirror currentObj)

Create an audio helper.

Parameters:

actor - The actor associated with this helper.

currentObj - The JavaScript object that this is helping.

Method Detail

byteFormats

public static java.lang.String[] byteFormats()

Return an array of supported byte formats for audio.

Returns:

An array of strings.

putSamples

public void putSamples(double[][] samplesArray,
                       java.lang.Runnable callback)
                throws java.lang.IllegalStateException,
                       java.io.IOException

Play an array of audio samples. This method returns immediately and invokes the specified callback function when the samples have been successfully queued into the audio system. This method should not be called again before the callback has been invoked.

The samples should be in the range (-1, 1). Samples that are outside this range will be hard-clipped so that they fall within this range.

The first index of the specified array represents the channel number (0 for first channel, 1 for second channel, etc.). The number of channels is set by the setChannels() method. The second index represents the sample index within a channel. For example, putSamplesArray[n][m] contains the (m+1)th sample of the (n+1)th channel.

Parameters:

samplesArray - A two dimensional array containing the samples to play.

callback - A callback function to invoke when the samples have been queued into the audio system.

Throws:

java.io.IOException - If the calling program does not have permission to access the audio playback resources.

java.lang.IllegalStateException - If audio playback is currently inactive. That is, If startPlayback() has not yet been called or if stopPlayback() has already been called.

putBytes

public void putBytes(byte[] audioData,
                     java.lang.Runnable callback)
              throws java.lang.IllegalStateException,
                     java.io.IOException,
                     javax.sound.sampled.UnsupportedAudioFileException

Play an array of audio samples given as a byte array. This method returns immediately and invokes the specified callback function when the samples have been successfully queued into the audio system. This method should not be called again before the callback has been invoked.

Parameters:

audioData - Byte array to play.

callback - A callback function to invoke when the samples have been queued into the audio system.

Throws:

java.io.IOException - If the calling program does not have permission to access the audio playback resources.

java.lang.IllegalStateException - If audio playback is currently inactive. That is, If startPlayback() has not yet been called or if stopPlayback() has already been called.

javax.sound.sampled.UnsupportedAudioFileException - If the audioData provided is not in a supported format.

setCaptureParameters

public void setCaptureParameters(java.util.Map<java.lang.String,java.lang.Integer> captureOptions,
                                 int captureTime,
                                 java.lang.String outputFormat)
                          throws java.io.IOException,
                                 javax.sound.sampled.LineUnavailableException

Set the capture parameters for audio. This will stop any active capture and restart it. The captureOptions argument contains the following entries:

1. bigEndian: 1 if big endian, 0 if little endian. The default is big endian.
2. bitsPerSample: The number of bits per sample.
3. channels: The number of channels.
4. sampleRate: Sample rate in Hz.

Allowable values for sampleRate are (most likely) 8000, 11025, 22050, 44100, and 48000 Hz. If this method is not invoked, then the default value of 8000 Hz is used. WAVE (aka .wav) is 16 bits, 1 channel, little endian, 44100 Hz.

Parameters:

captureOptions - The parameters for capture.

captureTime - The amount of time (in ms) per capture.

outputFormat - The requested output format.

Throws:

java.io.IOException - If the specified sample rate is not supported by the audio hardware or by Java.

javax.sound.sampled.LineUnavailableException - If the audio line is not available.

setPlaybackParameters

public void setPlaybackParameters(java.util.Map<java.lang.String,java.lang.Integer> playbackOptions,
                                  java.lang.String playbackFormat)
                           throws java.io.IOException,
                                  javax.sound.sampled.LineUnavailableException

Set the playback parameters for audio. This will stop any active playback and restart it. The playbackOptions argument contains the following entries:

1. bigEndian: 1 if big endian, 0 if little endian. The default is big endian.
2. bitsPerSample: The number of bits per sample.
3. channels: The number of channels.
4. sampleRate: Sample rate in Hz.

Allowable values for sampleRate are (most likely) 8000, 11025, 22050, 44100, and 48000 Hz. If this method is not invoked, then the default value of 8000 Hz is used. WAVE (aka .wav) is 16 bits, 1 channel, little endian, 44100 Hz.

Parameters:

playbackOptions - The parameters for playback.

playbackFormat - The expected format of the input data.

Throws:

java.io.IOException - If the specified sample rate is not supported by the audio hardware or by Java.

javax.sound.sampled.LineUnavailableException - If the audio line is not available.

startCapture

public void startCapture()
                  throws java.io.IOException

Start audio capture if it is not already active.

Throws:

java.io.IOException - If the audio target line cannot be acquired.

startPlayback

public void startPlayback()
                   throws java.io.IOException

Start audio playback if it is not already active.

Throws:

java.io.IOException - If the audio target line cannot be acquired.

stopCapture

public void stopCapture()

Stop audio capture if it is active.

stopPlayback

public void stopPlayback()

Stop audio playback if it is active.