ptolemy.actor.lib.javasound
Class AudioReader

java.lang.Object
  extended byptolemy.kernel.util.NamedObj
      extended byptolemy.kernel.InstantiableNamedObj
          extended byptolemy.kernel.Entity
              extended byptolemy.kernel.ComponentEntity
                  extended byptolemy.actor.AtomicActor
                      extended byptolemy.actor.TypedAtomicActor
                          extended byptolemy.actor.lib.Source
                              extended byptolemy.actor.lib.javasound.AudioReader
All Implemented Interfaces:
Actor, Changeable, java.lang.Cloneable, Debuggable, DebugListener, Derivable, Executable, Instantiable, ModelErrorHandler, MoMLExportable, Nameable, java.io.Serializable, TypedActor

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,v 1.47 2004/04/21 14:48:13 cxh Exp $
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 inherited from class ptolemy.kernel.Entity
Entity.ContainedObjectsIterator
 
Field Summary
 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
_stopRequested
 
Fields inherited from class ptolemy.kernel.util.NamedObj
_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _elementName, _isPersistent, _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, attributeTypeChanged, clone, newPort, typeConstraintList
 
Methods inherited from class ptolemy.actor.AtomicActor
_createReceivers, clone, connectionsChanged, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, iterate, newReceiver, outputPortList, preinitialize, pruneDependencies, removeDependency, setContainer, stop, stopFire, terminate
 
Methods inherited from class ptolemy.kernel.ComponentEntity
_adjustDeferrals, _checkContainer, _getContainedObject, _propagateExistence, getContainer, instantiate, isAtomic, isOpaque, propagateExistence, setName
 
Methods inherited from class ptolemy.kernel.Entity
_description, _exportMoMLContents, _removePort, connectedPortList, connectedPorts, containedObjectsIterator, getAttribute, getPort, getPorts, linkedRelationList, linkedRelations, portList, removeAllPorts, setClassDefinition, uniqueName, validateSettables
 
Methods inherited from class ptolemy.kernel.InstantiableNamedObj
_setParent, exportMoML, getChildren, getElementName, getParent, getPrototypeList, isClassDefinition
 
Methods inherited from class ptolemy.kernel.util.NamedObj
_addAttribute, _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, getAttribute, getAttributes, getChangeListeners, getClassName, getDerivedLevel, getDerivedList, getFullName, getModelErrorHandler, getName, getName, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, message, propagateValue, propagateValues, removeChangeListener, removeDebugListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setModelErrorHandler, setPersistent, setSource, toplevel, toString, 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
iterate, preinitialize, stop, stopFire, terminate
 
Methods inherited from interface ptolemy.kernel.util.Derivable
getDerivedLevel, getDerivedList, propagateValue
 
Methods inherited from interface ptolemy.kernel.util.Nameable
description, getFullName, getName, getName
 

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
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 Executable
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 AtomicActor
Returns:
True if this actor is ready for firing, false otherwise.
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 Executable
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.