ptolemy.actor.lib.javasound
Class SoundActor

java.lang.Object
  ptolemy.kernel.util.NamedObj
      ptolemy.kernel.InstantiableNamedObj
          ptolemy.kernel.Entity
              ptolemy.kernel.ComponentEntity
                  ptolemy.actor.AtomicActor
                      ptolemy.actor.TypedAtomicActor
                          ptolemy.actor.lib.javasound.SoundActor

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

SoundPlayer

public class SoundActor
extends TypedAtomicActor

This actor forms a base class for actors that interact with real-time sound through sampled data. This replaces an older and more limited actor LiveSoundActor.

Note: Requires Java 5.0.

Since:

Ptolemy II 6.1

Version:

$Id: SoundActor.java,v 1.6 2007/12/06 21:56:55 cxh Exp $

Author:

Edward A. Lee (based on code by Steve Neuendorffer)

See Also:

LiveSound, AudioPlayer, AudioCapture, Serialized Form

Accepted Rating:

Red (chf)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested classes/interfaces inherited from class ptolemy.kernel.Entity

Entity.ContainedObjectsIterator

Field Summary

protected int	_bufferSize The requested buffer size.
protected int	_bytesPerSample Value of the bytesPerSample parameter.
protected int	_channels The number of channels.
protected boolean	_isExecuting True if this actor is executing.
protected int	_sampleRate The value of the sampleRate parameter.
SharedParameter	bufferSize The requested buffer size for transferring samples.
SharedParameter	bytesPerSample The number of bytes per sample.
SharedParameter	channels The number of audio channels.
SharedParameter	sampleRate The sample rate in samples per second.

Fields inherited from class ptolemy.actor.AtomicActor

_actorFiringListeners, _initializables, _notifyingActorFiring, _stopRequested

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Fields inherited from interface ptolemy.actor.Executable

COMPLETED, NOT_READY, STOP_ITERATING

Constructor Summary

SoundActor(CompositeEntity container, java.lang.String name)
Construct an actor with the given container and name.

Method Summary

protected void	_doubleArrayToByteArray(double[][] doubleArray, byte[] playbackData) Convert a double array of audio samples into a byte array of audio samples in linear signed PCM big endian format.
void	attributeChanged(Attribute attribute) Handle change requests for all parameters.
void	initialize() Initialize this actor.
void	wrapup() Wrapup execution.

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, attributeTypeChanged, clone, newPort, typeConstraintList

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, _createReceivers, addActorFiringListener, addInitializable, clone, connectionsChanged, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, postfire, prefire, preinitialize, pruneDependencies, recordFiring, removeActorFiringListener, removeDependency, removeInitializable, setContainer, stop, stopFire, terminate

Methods inherited from class ptolemy.kernel.ComponentEntity

_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, propagateExistence, setName

Methods inherited from class ptolemy.kernel.Entity

_description, _exportMoMLContents, _removePort, _validateSettables, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName

Methods inherited from class ptolemy.kernel.InstantiableNamedObj

_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition, isWithinClassDefinition

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _debug, _debug, _debug, _debug, _debug, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.actor.Actor

getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

fire, isFireFunctional, isStrict, iterate, postfire, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, preinitialize, removeInitializable

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Methods inherited from interface ptolemy.kernel.util.Derivable

getDerivedLevel, getDerivedList, propagateValue

Field Detail

bytesPerSample

public SharedParameter bytesPerSample

The number of bytes per sample. This is an integer that defaults to 2. This parameter is shared by all instances of this class and subclasses in the model, so changing it in one of those actors will cause it to change in all. An exception will be thrown if this parameter is set to an unsupported bit resolution. Changing the value of this parameter will have an effect only when the model is next initialized.

bufferSize

public SharedParameter bufferSize

The requested buffer size for transferring samples. This affects how far ahead of real time the model can get. A larger buffer size may limit the responsivity of the model because changes in the model will be heard only after the buffer has been flushed. This is an integer that defaults to 1024, representing a buffer with 1024 samples per channel. At an 8 kHz sample rate, this means a worst-case latency of about 1/8 seconds. This parameter is shared by all instances of this class and subclasses in the model, so changing it in one of those actors will cause it to change in all. Changing the value of this parameter will have an effect only when the model is next initialized.

channels

public SharedParameter channels

The number of audio channels. This is an integer that defaults to 1. This parameter is shared by all instances of this class and subclasses in the model, so changing it in one of those actors will cause it to change in all. An exception will be thrown if this parameter is set to an an unsupported channel number. Changing the value of this parameter will have an effect only when the model is next initialized.

sampleRate

public SharedParameter sampleRate

The sample rate in samples per second. This is an integer that defaults to 8000. This parameter is shared by all instances of this class and subclasses in the model, so changing it in one of those actors will cause it to change in all. An exception will be thrown if this parameter is set to an unsupported sample rate. Changing the value of this parameter will have an effect only when the model is next initialized.

_bytesPerSample

protected int _bytesPerSample

Value of the bytesPerSample parameter.

_bufferSize

protected int _bufferSize

The requested buffer size.

_channels

protected int _channels

The number of channels. Initialized from the channels parameter.

_sampleRate

protected int _sampleRate

The value of the sampleRate parameter.

_isExecuting

protected boolean _isExecuting

True if this actor is executing. Set to true by initialize(), set to false by wrapup().

Constructor Detail

SoundActor

public SoundActor(CompositeEntity container,
                  java.lang.String name)
           throws IllegalActionException,
                  NameDuplicationException

Construct an actor with the given container and name.

Parameters:

container - The container.

name - The name of this actor.

Throws:

IllegalActionException - If the actor cannot be contained by the proposed container.

NameDuplicationException - If the container already has an actor with this name.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

Handle change requests for all parameters. An exception is thrown if the requested change is not allowed.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not allowed.

initialize

public void initialize()
                throws IllegalActionException

Initialize this actor. Derived classes should extend this method to initialize the appropriate audio resource.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If there is a problem beginning audio playback.

wrapup

public void wrapup()
            throws IllegalActionException

Wrapup execution. Derived classes should override this method to release access to the audio resources.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - May be thrown by derived classes.

_doubleArrayToByteArray

protected void _doubleArrayToByteArray(double[][] doubleArray,
                                       byte[] playbackData)
                                throws java.lang.IllegalArgumentException

Convert a double array of audio samples into a byte array of audio samples in linear signed PCM big endian format. The samples contained in doubleArray should be in the range (-1, 1). Samples outside this range will be hard clipped to the range (-1, 1). The result is put into the byte array given by playbackData, which is required to be big enough (or an ArrayIndexOutOfBounds exception will be thrown).

Parameters:

doubleArray - Two dimensional array holding audio samples. For each channel, m, doubleArray[m] is a single dimensional array containing samples for channel m. All channels are required to have the same number of samples, but this is not checked.

playbackData - An array into which to put the results, which have bytes representing linear signed PCM big endian formatted audio data.

Throws:

java.lang.IllegalArgumentException - Not thrown in this base class.