ptolemy.actor.lib.javasound
Class AudioCapture

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.LiveSoundActor
                              extended byptolemy.actor.lib.javasound.AudioCapture
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, LiveSoundListener, ptolemy.kernel.util.ModelErrorHandler, ptolemy.kernel.util.MoMLExportable, ptolemy.kernel.util.Nameable, java.io.Serializable, ptolemy.actor.TypedActor

public class AudioCapture
extends LiveSoundActor

This actor sequentially outputs audio samples that are captured from the audio input port of the computer. The audio input port typically corresponds to either the microphone input, line-in, or cd audio from the cdrom or dvd drive. It is not possible to select the desired input port under Java. This must be done from the operating system. This actor should be fired often enough to prevent overflow of the internal audio capture buffer. Overflow should be avoided, since it will result in loss of data. Each captured audio sample is converted to a double that may range from -1.0 to 1.0. Thus, the output type of this actor is DoubleToken.

The following parameters should be set accordingly. In all cases, an exception is thrown if an illegal parameter value is used. Note that these parameters may be changed while audio playback is active. If this actor is used in conjunction with an AudioPlayer actor, changing a parameter will cause the corresponding parameter value of the AudioPlayer to automatically be set to the same value. This behavior is required because the AudioCapture and AudioPlayer actors both share access to the audio hardware, which is associated with a single sample rate, bit resolution, and number of channels.

It should be noted that at most one AudioCapture and one AudioPlayer actor may be used simultaneously. Otherwise, an exception will occur. This restriction may be lifted in a future version of this actor.

There are security issues involved with accessing files and audio resources in applets. Applets are not allowed to capture audio from the audio input port (e.g., the microphone) by default since this could present a security risk. Therefore, the actor will not run in an applet by default. 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: AudioCapture.java,v 1.32 2004/04/13 03:08:30 cxh Exp $
Author:
Brian K. Vogel, Christopher Hylands, Steve Neuendorffer
See Also:
LiveSound, AudioPlayer, SoundReader, SoundWriter, 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.actor.TypedIOPort output
          The output port.
 ptolemy.data.expr.Parameter output_tokenProductionRate
          The output rate.
 ptolemy.actor.TypedIOPort trigger
          The trigger port.
 
Fields inherited from class ptolemy.actor.lib.javasound.LiveSoundActor
_channels, _isExecuting, _transferSize, bitsPerSample, channels, sampleRate, transferSize
 
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
AudioCapture(ptolemy.kernel.CompositeEntity container, java.lang.String name)
          Construct an actor with the given container and name.
 
Method Summary
 void initialize()
          Read parameter values and begin the sound capture process.
 boolean postfire()
          Capture and output a single audio sample on each channel.
 void wrapup()
          Stop capturing audio.
 
Methods inherited from class ptolemy.actor.lib.javasound.LiveSoundActor
_initializeAudio, attributeChanged, liveSoundChanged
 
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, iterate, newReceiver, outputPortList, prefire, 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
fire, iterate, prefire, 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

trigger

public ptolemy.actor.TypedIOPort trigger
The trigger port.


output

public ptolemy.actor.TypedIOPort output
The output port. This will always produce double data, between -1.0 and 1.0.


output_tokenProductionRate

public ptolemy.data.expr.Parameter output_tokenProductionRate
The output rate.

Constructor Detail

AudioCapture

public AudioCapture(ptolemy.kernel.CompositeEntity container,
                    java.lang.String name)
             throws ptolemy.kernel.util.NameDuplicationException,
                    ptolemy.kernel.util.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:
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

initialize

public void initialize()
                throws ptolemy.kernel.util.IllegalActionException
Read parameter values and begin the sound capture process. An exception will occur if there is a problem starting the audio capture. This will occur if another AudioCapture actor has already started capturing.

Specified by:
initialize in interface ptolemy.actor.Executable
Overrides:
initialize in class LiveSoundActor
Throws:
ptolemy.kernel.util.IllegalActionException - If there is a problem starting audio capture.

postfire

public boolean postfire()
                 throws ptolemy.kernel.util.IllegalActionException
Capture and output a single audio sample on each channel. This method causes audio samples to be captured from the audio input device (e.g., the microphone or line-in). One token is written to the output port in an invocation. This method should be invoked often enough to prevent overflow of the internal audio capture buffer. Overflow should be avoided, since it will result in loss of data. This method will block until the samples have been read, so it is not possible to invoke this method too frequently.

Returns:
True
Throws:
ptolemy.kernel.util.IllegalActionException - If audio cannot be captured.

wrapup

public void wrapup()
            throws ptolemy.kernel.util.IllegalActionException
Stop capturing audio. Free up any system resources involved in the capturing process.

Specified by:
wrapup in interface ptolemy.actor.Executable
Overrides:
wrapup in class LiveSoundActor
Throws:
ptolemy.kernel.util.IllegalActionException - May be thrown by derived classes.