ptolemy.actor.lib.javasound
Class AudioReader

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.Source
                              ptolemy.actor.lib.javasound.AudioReader

All Implemented Interfaces:

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

public class AudioReader
extends Source

This actor outputs samples from a sound file as doubles in the range [-1.0, 1.0]. If the file has multiple channels of output data, then the separate channels are sent on successive output channels. If the output has more channels than there are channels in the audio file, then nothing will be send on the output channels where there is no corresponding output data.

The fileOrURL parameter should be set to the name of the file or a URL, in any form accepted by FileParameter. The default initial value is $CLASSPATH/ptolemy/actor/lib/javasound/voice.wav, which refers to a file that is found relative to the classpath.

Supported file formats are WAV, AU, and AIFF. The sound file format is determined from the file extension.

When the end of the file is reached, postfire() return false, which in some domains will cause the model to stop executing (e.g. SDF), and in some will prevent further firings of this actor (e.g. DE).

There are security issues involved with accessing files and audio resources in applets. Applets are only allowed access to files specified by a URL and located on the machine from which the applet is loaded. The .java.policy file may be modified to grant applets more privileges.

Note: Requires Java 2 v1.3.0 or later.

Since:

Ptolemy II 1.0

Version:

$Id: AudioReader.java 57040 2010-01-27 20:52:32Z cxh $

Author:

Brian K. Vogel, Christopher Hylands, Edward A. Lee, Steve Neuendorffer

See Also:

LiveSound, SoundWriter, SoundPlayback, Serialized Form

Accepted Rating:

Yellow (chf)

Proposed Rating:

Green (eal)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private double[][]	_audioIn Most recently read audio data.
private DoubleToken[]	_audioSendArray Buffer of tokens to send.
private int	_channels The number of channels.
private boolean	_firedSinceWrapup Indicator that the fire() method has been called, but wrapup has not.
private java.lang.String	_previousFileOrURL Previous value of fileOrURL parameter.
private boolean	_reachedEOF Indicator that we have reached the end of the file.
private int	_sampleIndex Index of the next output to produce from _audioIn.
private SoundReader	_soundReader The current reader for the input file.
FileParameter	fileOrURL The file name or URL from which to read.

Fields inherited from class ptolemy.actor.lib.Source

output, trigger

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

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

Method Summary

protected void	_openReader() Initialize/Reinitialize audio reading.
void	attributeChanged(Attribute attribute) If the specified attribute is fileOrURL and there is an open file being read, then close that file and open the new one; do nothing if the file name is the same as the previous value of this attribute.
void	initialize() Open the sound file specified by the URL for reading.
boolean	postfire() This method causes one audio sample per channel to be read from the specified file.
boolean	prefire() Return false if there is no more data available in the file.
void	wrapup() Free up any system resources involved in the audio reading process and close any open sound files.

Methods inherited from class ptolemy.actor.lib.Source

fire

Methods inherited from class ptolemy.actor.TypedAtomicActor

_addPort, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, clone, connectionsChanged, createReceivers, declareDelayDependency, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, iterate, newReceiver, outputPortList, 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, _recordDecoratedAttributes, _removeAttribute, _splitName, _stripNumericSuffix, addChangeListener, addDebugListener, attributeList, attributeList, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, 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

createReceivers, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, newReceiver, outputPortList

Methods inherited from interface ptolemy.actor.Executable

isFireFunctional, isStrict, iterate, 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

fileOrURL

public FileParameter fileOrURL

The file name or URL from which to read. This is a string with any form accepted by FileParameter.

See Also:

FileParameter

_audioIn

private double[][] _audioIn

Most recently read audio data.

_audioSendArray

private DoubleToken[] _audioSendArray

Buffer of tokens to send.

_channels

private int _channels

The number of channels.

_firedSinceWrapup

private boolean _firedSinceWrapup

Indicator that the fire() method has been called, but wrapup has not. That is, we are in the middle of a run.

_previousFileOrURL

private java.lang.String _previousFileOrURL

Previous value of fileOrURL parameter.

_reachedEOF

private boolean _reachedEOF

Indicator that we have reached the end of the file.

_sampleIndex

private int _sampleIndex

Index of the next output to produce from _audioIn.

_soundReader

private SoundReader _soundReader

The current reader for the input file.

Constructor Detail

AudioReader

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

Construct an actor with the given container and name. In addition to invoking the base class constructors, construct the parameters and initialize them to their default values.

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

If the specified attribute is fileOrURL and there is an open file being read, then close that file and open the new one; do nothing if the file name is the same as the previous value of this attribute.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that has changed.

Throws:

IllegalActionException - If the specified attribute is fileOrURL and the file cannot be opened, or the previously opened file cannot be closed.

initialize

public void initialize()
                throws IllegalActionException

Open the sound file specified by the URL for reading.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If there is a problem opening the specified URL, or if the file has an unsupported audio format.

postfire

public boolean postfire()
                 throws IllegalActionException

This method causes one audio sample per channel to be read from the specified file. Each sample is converted to a double token, with a maximum range of -1.0 to 1.0. One double token per channel is written to the output port.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if there are samples available from the audio source. False if there are no more samples (end of sound file reached).

Throws:

IllegalActionException - If there is a problem reading from the specified sound file.

prefire

public boolean prefire()
                throws IllegalActionException

Return false if there is no more data available in the file. Otherwise, return whatever the superclass returns.

Specified by:

prefire in interface Executable

Overrides:

prefire in class Source

Returns:

True, unless the trigger input is connected and has no input.

Throws:

IllegalActionException - If the superclass throws it.

wrapup

public void wrapup()
            throws IllegalActionException

Free up any system resources involved in the audio reading process and close any open sound files.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If there is a problem closing the file.

_openReader

protected void _openReader()
                    throws IllegalActionException

Initialize/Reinitialize audio reading. First close any open files. Then read the fileOrURL parameter and open the file specified by this parameter.

Throws:

IllegalActionException - If there is a problem initializing the audio reader.