ptolemy.actor.lib.javasound
Class AudioReadBuffer

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.Transformer
                              ptolemy.actor.lib.javasound.AudioReadBuffer

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 AudioReadBuffer
extends Transformer

This actor reads a sound file into a buffer and outputs the the sample value at the specified buffer element. The sound file is read from the URL specified by the sourceURL parameter. Although the sound file must be specified as a URL, it is still possible to specify files on the local file system.

In each iteration, an IntToken is read from the input port, if there is a token available. This token specifies the address of the buffer element to read from. The address is zero-based, so address 0 corresponds to the first element and addres bufferLength -1 corresponds to the last element. The sample value at the specified buffer location is converted to a DoubleToken and sent to the output port.

If an element outside of the valid address range is specified, then a DoubleToken with value 0.0 is output. If the the specified address is greater than bufferLength -1, then this actor will return false in postfire.

This actor does not currently support multichannel sound files, so if a stereo sound file is specified, only the left channel will be used. This limitation may be lifted in a future version of this actor.

The audio samples that are read from the file are converted to DoubleTokens that may range from [-1.0, 1.0]. Thus, the output type of this actor is DoubleToken.

Usage

The sourceURL parameter should be set to the name of the file, specified as a fully qualified URL. It is possible to load a file from the local file system by using the prefix "file://" instead of "http://". Relative file paths are allowed. To specify a file relative to the current directory, use "../" or "./". For example, if the current directory contains a file called "test.wav", then sourceURL should be set to "file:./test.wav". If the parent directory contains a file called "test.wav", then sourceURL should be set to "file:../test.wav". To reference the file test.wav, located at "/tmp/test.wav", sourceURL should be set to "file:///tmp/test.wav" The default value is "file:///tmp/test.wav".

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.

FIXME: This actor should extend AudioReadBuffer?

Note: Requires Java 2 v1.3.0 or later.

Since:

Ptolemy II 2.0

Version:

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

Author:

Brian K. Vogel

See Also:

LiveSound, Serialized Form

Accepted Rating:

Red (vogel)

Proposed Rating:

Red (vogel)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private double[]	_audioBuffer
private boolean	_postfireReturn
private boolean	_safeToInitialize
private SoundReader	_soundReader
Parameter	bufferLength The length of the audio buffer to use.
StringAttribute	sourceURL The URL of the file to read from.

Fields inherited from class ptolemy.actor.lib.Transformer

input, output

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

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

Method Summary

private void	_initializeReader() Initialize/Reinitialize audio reading.
void	attributeChanged(Attribute attribute) Handle change requests for all parameters.
void	fire() Read the buffer address from the input port and output the corresponding audio sample, if there is a token available on the input port.
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.
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.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, 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, _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, 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

sourceURL

public StringAttribute sourceURL

The URL of the file to read from. The default value of this parameter is the URL "file:///tmp/test.wav". Supported file formats are WAV, AU, and AIFF. The sound file format is determined from the file extension.

An exception will occur if the path references a non-existent or unsupported sound file.

bufferLength

public Parameter bufferLength

The length of the audio buffer to use. The default value is 8000.

_soundReader

private SoundReader _soundReader

_safeToInitialize

private boolean _safeToInitialize

_audioBuffer

private double[] _audioBuffer

_postfireReturn

private boolean _postfireReturn

Constructor Detail

AudioReadBuffer

public AudioReadBuffer(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

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

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.

fire

public void fire()
          throws IllegalActionException

Read the buffer address from the input port and output the corresponding audio sample, if there is a token available on the input port.

The IntToken read from the input port specifies the buffer address to read from. The valid address range is 0 to bufferLength -1. If an invalid address is read, then the value 0.0 is output. If the the specified address is greater than bufferLength -1, then this actor will return false in postfire. The audio sample is converted to a DoubleToken with range [-1.0, 1.0] and sent to the output. Note that if a stereo sound file is specified, only the left channel will be used.

Specified by:

fire in interface Executable

Overrides:

fire in class AtomicActor

Throws:

IllegalActionException - Not thrown in this base class.

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.

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.

_initializeReader

private void _initializeReader()
                        throws java.io.IOException,
                               IllegalActionException

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

This method is synchronized since it is not safe to call other SoundReader methods while this method is executing.

Throws:

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

java.io.IOException