ptolemy.actor.lib.javasound
Class AudioWriteBuffer

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.javasound.AudioWriteBuffer
All Implemented Interfaces:
ptolemy.actor.Actor, ptolemy.kernel.util.Changeable, java.lang.Cloneable, ptolemy.kernel.util.Debuggable, ptolemy.kernel.util.DebugListener, ptolemy.kernel.util.Derivable, ptolemy.actor.Executable, ptolemy.kernel.util.Instantiable, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.actor.TypedActor

public class AudioWriteBuffer
extends ptolemy.actor.TypedAtomicActor

This actor writes audio samples to a buffer and saves the buffer to a sound file on wrapup. In each iteration, if there is a token available on the data and address ports, then the data DoubleToken is written to the buffer location specified by the address IntToken. The valid address range is 0 to bufferLength -1. If an invalid address is specified, then the data value will be ignored and no data will be written. The audio samples in the buffer will be written to the sound file specified by the pathName parameter on wrapup. Any existing file with the same name will be silently overwritten. The data port is of type DoubleToken. Each DoubleToken read from the data port represents one sample of the audio data and should be in the range [-1.0, 1.0]. Any samples that are outside of this range will be hard-clipped to fall within this range before they are written to the sound file. Single channel (mono) audio is supported but stereo is not supported.

The following parameters should be set to specify the format of the file to write. In all cases, an exception is thrown if an illegal parameter value is used. Note that if a parameter is changed while audio writing is active, all data written so far will be saved, and the sound file will be closed. Subsequent audio samples will then be written to a new sound file with the new parameter values.

There are security issues involved with accessing files and audio resources in applets. By default, applets are not allowed to write files. The .java.policy file may be modified to grant applets more privileges.

Note: Requires Java 2 v1.3.0 or later.

FIXME: this should extend AudioWriter

Since:
Ptolemy II 2.0
Version:
$Id: AudioWriteBuffer.java,v 1.19 2004/04/13 03:08:38 cxh Exp $
Author:
Brian K. Vogel
See Also:
Serialized Form
Accepted Rating:
Red (vogel)
Proposed Rating:
Red (vogel)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
 ptolemy.actor.TypedIOPort address
          The address port, which is a multiport.
 ptolemy.data.expr.Parameter bitsPerSample
          The desired number of bits per sample.
 ptolemy.data.expr.Parameter bufferLength
          The length of the audio buffer to use.
 ptolemy.data.expr.Parameter channels
          The number of audio channels to use.
 ptolemy.actor.TypedIOPort data
          The data port, which is a multiport.
 ptolemy.data.expr.Parameter overwrite
          The write mode to use.
 ptolemy.kernel.util.StringAttribute pathName
          The name of the file to write to.
 ptolemy.data.expr.Parameter sampleRate
          The desired sample rate to use, in Hz.
 
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
AudioWriteBuffer(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void attributeChanged(ptolemy.kernel.util.Attribute attribute)
          Handle change requests for all parameters.
 void fire()
          If there is a token available on the data and address ports, then the data DoubleToken is written to the buffer location specified by the address IntToken.
 void initialize()
          Open a new audio file for writing.
 boolean postfire()
          Return true.
 void preinitialize()
          Set up the number channels to use.
 void wrapup()
          Close the specified file.
 
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, prefire, 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, prefire, 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

address

public ptolemy.actor.TypedIOPort address
The address port, which is a multiport.


data

public ptolemy.actor.TypedIOPort data
The data port, which is a multiport.


bufferLength

public ptolemy.data.expr.Parameter bufferLength
The length of the audio buffer to use. The default value is 8000.


overwrite

public ptolemy.data.expr.Parameter overwrite
The write mode to use. If this parameter is set to true, then a write to a buffer element overwrites the old value in the buffer. Otherwise, a write adds the new value to the old value of the buffer element.


pathName

public ptolemy.kernel.util.StringAttribute pathName
The name of the file to write to. The default value of this parameter is "test.wav", which creates a file called test.wav in the current directory and writes samples to this file.

The audio format to use is determined by the file extension. E.g., "outfile.wav" will create a WAV format file. The supported file formats are AU, WAV, and, AIFF.

An exception will be occur if the path references an unsupported sound file.


sampleRate

public ptolemy.data.expr.Parameter sampleRate
The desired sample rate to use, in Hz. Valid values include: 8000, 11025, 22050, 44100, and 48000. The default value of the sample rate is an IntToken equal to 8000.

An exception will be thrown if an illegal value is used.


bitsPerSample

public ptolemy.data.expr.Parameter bitsPerSample
The desired number of bits per sample. The default value is an IntToken equal to 16. Supported values are 8 and 16. An exception will be thrown if an illegal value is used.


channels

public ptolemy.data.expr.Parameter channels
The number of audio channels to use. Supported values are 1 (single channel) and 2 (stereo). The default value is an IntToken equal to 1. An exception will be thrown if an illegal value is used.

Constructor Detail

AudioWriteBuffer

public AudioWriteBuffer(ptolemy.kernel.CompositeEntity container,
                        java.lang.String name)
                 throws ptolemy.kernel.util.IllegalActionException,
                        ptolemy.kernel.util.NameDuplicationException
Construct an actor with the given container and name.

Parameters:
container - The container.
name - The name of this actor.
Throws:
ptolemy.kernel.util.IllegalActionException - If the actor cannot be contained by the proposed container.
ptolemy.kernel.util.NameDuplicationException - If the container already has an actor with this name.
Method Detail

attributeChanged

public void attributeChanged(ptolemy.kernel.util.Attribute attribute)
                      throws ptolemy.kernel.util.IllegalActionException
Handle change requests for all parameters. An exception is thrown if the requested change is not allowed.

Throws:
ptolemy.kernel.util.IllegalActionException - If the change is not allowed.

initialize

public void initialize()
                throws ptolemy.kernel.util.IllegalActionException
Open a new audio file for writing. Any existing file with the same name will be overwritten.

Throws:
ptolemy.kernel.util.IllegalActionException - If the file cannot be opened, or if the parent class throws it.

fire

public void fire()
          throws ptolemy.kernel.util.IllegalActionException
If there is a token available on the data and address ports, then the data DoubleToken is written to the buffer location specified by the address IntToken. The valid address range is 0 to bufferLength -1. If an invalid address is specified, then the data value will be ignored and no data will be written. The audio samples in the buffer will be written to the sound file specified by the pathName parameter on wrapup.

Throws:
ptolemy.kernel.util.IllegalActionException

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
Return true.

Throws:
ptolemy.kernel.util.IllegalActionException - Not thrown in this base class.

preinitialize

public void preinitialize()
                   throws ptolemy.kernel.util.IllegalActionException
Set up the number channels to use. for use in the postfire() method.

Throws:
ptolemy.kernel.util.IllegalActionException - If the parent class throws it.

wrapup

public void wrapup()
            throws ptolemy.kernel.util.IllegalActionException
Close the specified file.

Throws:
ptolemy.kernel.util.IllegalActionException - If there is a problem closing the file.