ptolemy.actor.lib.javasound
Class AudioWriter

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.Sink
                              extended byptolemy.actor.lib.javasound.AudioWriter
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 AudioWriter
extends Sink

This actor reads audio samples from the input port and writes the samples to the specified sound file. Any existing file with the same name will be silently overwritten. The input port is of type DoubleToken. Each DoubleToken read from the input 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) and two channel (stereo) formats are supported. For single channel audio, tokens are written to channel 0 of the output port. For stereo , tokens are written to channel 0 (left) and channel 1 (right) of the output port.

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.

Since:
Ptolemy II 1.0
Version:
$Id: AudioWriter.java,v 1.24 2004/04/13 03:08:40 cxh Exp $
Author:
Brian K. Vogel
See Also:
AudioReader, AudioCapture, AudioPlayer, Serialized Form
Accepted Rating:
Yellow (chf)
Proposed Rating:
Yellow (vogel)

Nested Class Summary
 
Nested classes inherited from class ptolemy.kernel.Entity
ptolemy.kernel.Entity.ContainedObjectsIterator
 
Field Summary
 ptolemy.data.expr.Parameter bitsPerSample
          The desired number of bits per sample.
 ptolemy.data.expr.Parameter channels
          The number of audio channels 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.lib.Sink
input
 
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
AudioWriter(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 initialize()
          Open a new audio file for writing.
 int iterate(int count)
          Invoke count iterations of this actor.
 boolean postfire()
          If there is at least 1 token on channel 0 (and also on channel 1 if stereo mode is used), then read 1 token from the corresponding channels and write the token values to the specified sound file.
 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, fire, getDirector, getExecutiveDirector, getFunctionDependency, getManager, inputPortList, 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
fire, 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

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

AudioWriter

public AudioWriter(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.

iterate

public int iterate(int count)
            throws ptolemy.kernel.util.IllegalActionException
Invoke count iterations of this actor. If there at least count tokens on channel 0 (and also on channel 1 if stereo mode is used), then read count tokens from the corresponding channels and write the token values to the specified sound file. Otherwise, do nothing, and return a value of NOT_READY. Note that at most one token is read from each channel in an iteration.

This method should be called instead of the prefire(), fire(), and postfire() methods when this actor is used in a domain that supports vectorized actors.

Parameters:
count - The number of iterations to perform.
Returns:
COMPLETED if the actor was successfully iterated the specified number of times. Otherwise, return NOT_READY if there are not enough tokens on the input port, or throw an exception if there is a problem writing audio samples to the specified file.
Throws:
ptolemy.kernel.util.IllegalActionException - If there is a problem writing the audio sample(s) to the specified file.
See Also:
Executable

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
If there is at least 1 token on channel 0 (and also on channel 1 if stereo mode is used), then read 1 token from the corresponding channels and write the token values to the specified sound file. Otherwise, do nothing, and return a value of false.

Throws:
ptolemy.kernel.util.IllegalActionException - If there is a problem writing the audio sample(s) to the specified file.

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.