ptolemy.actor.lib.javasound
Class AudioWriter

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.Sink
                              ptolemy.actor.lib.javasound.AudioWriter

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 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.

• pathName should be set to the name of the output file. Any existing file with the same name will be silently overwritten. Relative filenames are supported. The default value is "outfile.wav". 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. For example, to write samples to a Sun AU format file with the name "test.au" in the directory "c:\tmp", this parameter should be set to the value c:\tmp\test.au. To write samples to a file with name "test.au" in the current directory, this parameter should be set to the value test.au.
• channels should be set to desired number of audio channels. Allowable values are 1 (for mono) and 2 (for stereo). The default value is 1.
• sampleRate should be set to desired sample rate, in Hz. The DoubleTokens read in by this actor will be interpreted as having this sample rate. Allowable values are 8000, 11025, 22050, 44100, and 48000. The default value is 8000.
• bitsPerSample should be set to desired bit resolution. Allowable values are 8 and 16. The default value is 16.

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 50323 2008-08-07 14:08:03Z cxh $

Author:

Brian K. Vogel

See Also:

AudioReader, AudioCapture, AudioPlayer, Serialized Form

Accepted Rating:

Yellow (chf)

Proposed Rating:

Yellow (vogel)

Nested Class Summary

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

Entity.ContainedObjectsIterator

Field Summary

private double[][]	_audioPutArray
private int	_channels
private int	_curElement
private Token[][]	_inArray
private int	_putSampleSize
private boolean	_safeToInitialize
private SoundWriter	_soundWriter
Parameter	bitsPerSample The desired number of bits per sample.
Parameter	channels The number of audio channels to use.
StringAttribute	pathName The name of the file to write to.
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

_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

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

Method Summary

private void	_initializeWriter() Initialize/Reinitialize audio resources.
void	attributeChanged(Attribute attribute) Handle change requests for all parameters.
java.lang.Object	clone(Workspace workspace) Clone the actor into the specified workspace.
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, _fireAt, _fireAt, attributeTypeChanged, clone, newPort, typeConstraintList, typeConstraints

Methods inherited from class ptolemy.actor.AtomicActor

_actorFiring, _actorFiring, addActorFiringListener, addInitializable, connectionsChanged, createReceivers, declareDelayDependency, fire, getCausalityInterface, getDirector, getExecutiveDirector, getManager, inputPortList, isFireFunctional, isStrict, newReceiver, outputPortList, prefire, 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

fire, isFireFunctional, isStrict, prefire, stop, stopFire, terminate

Methods inherited from interface ptolemy.actor.Initializable

addInitializable, 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

pathName

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

_soundWriter

private SoundWriter _soundWriter

_channels

private int _channels

_putSampleSize

private int _putSampleSize

_audioPutArray

private double[][] _audioPutArray

_curElement

private int _curElement

_inArray

private Token[][] _inArray

_safeToInitialize

private boolean _safeToInitialize

Constructor Detail

AudioWriter

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

Construct an actor with the given container and name.

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.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the actor into the specified workspace.

Overrides:

clone in class AtomicActor

Parameters:

workspace - The workspace for the new object.

Returns:

A new actor.

Throws:

java.lang.CloneNotSupportedException - If a derived class contains an attribute that cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

initialize

public void initialize()
                throws IllegalActionException

Open a new audio file for writing. Any existing file with the same name will be overwritten.

Specified by:

initialize in interface Initializable

Overrides:

initialize in class AtomicActor

Throws:

IllegalActionException - If the file cannot be opened, or if the parent class throws it.

iterate

public int iterate(int count)
            throws 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.

Specified by:

iterate in interface Executable

Overrides:

iterate in class AtomicActor

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:

IllegalActionException - If there is a problem writing the audio sample(s) to the specified file.

See Also:

Executable

postfire

public boolean postfire()
                 throws 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.

Specified by:

postfire in interface Executable

Overrides:

postfire in class AtomicActor

Returns:

True if execution can continue into the next iteration.

Throws:

IllegalActionException - If there is a problem writing the audio sample(s) to the specified file.

preinitialize

public void preinitialize()
                   throws IllegalActionException

Set up the number channels to use. for use in the postfire() method.

Specified by:

preinitialize in interface Initializable

Overrides:

preinitialize in class AtomicActor

Throws:

IllegalActionException - If the parent class throws it.

wrapup

public void wrapup()
            throws IllegalActionException

Close the specified file.

Specified by:

wrapup in interface Initializable

Overrides:

wrapup in class AtomicActor

Throws:

IllegalActionException - If there is a problem closing the file.

_initializeWriter

private void _initializeWriter()
                        throws IllegalActionException

Initialize/Reinitialize audio resources. First close any open sound files. Then reread all parameters, create a new SoundWriter object.

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

Throws:

IllegalActionException - If there is a problem initializing the SoundWriter object.