Adobe® Flex® 4 Language Reference
Hide Packages and Classes List |  Packages  |  Classes  |  Index  |  Appendixes
flash.media 
Microphone 
Packageflash.media
Classpublic final class Microphone
InheritanceMicrophone Inheritance EventDispatcher Inheritance Object

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Use the Microphone class to capture audio from a microphone attached to a computer running Adobe AIR. Use the Microphone class to monitor the audio locally. Use the NetConnection and NetStream classes to transmit the audio to Flash Media Server. Flash Media Server can send the audio to other servers and broadcast it to other clients running Adobe AIR.

For information about capturing video, see the Camera class.

Important: Flash Player displays a Privacy dialog box that lets the user choose whether to allow or deny access to the microphone. Make sure that your application window size is at least 215 x 138 pixels, which is the minimum size required to display the dialog box.

To create or reference a Microphone object, use the Microphone.getMicrophone() method.

Caution: For content outside of the application sandbox, a Privacy dialog box is displayed that lets the user choose whether to allow or deny access to the microphone. This dialog box requires a minimum application window size of at least 215 x 138 pixels. For Adobe AIR content inside the application sandbox, access is allowed and the dialog box will not be displayed.

View the examples

See also



Public Properties
 PropertyDefined By
  activityLevel : Number
[read-only] The amount of sound the microphone is detecting.
Microphone
  codec : String
The codec to use for compessing audio.
Microphone
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  encodeQuality : int
The encoded speech quality when using the Speex codec.
Microphone
  framesPerPacket : int
Number of Speex speech frames transmitted in a packet (message).
Microphone
  gain : Number
The amount by which the microphone boosts the signal.
Microphone
  index : int
[read-only] The index of the microphone, as reflected in the array returned by Microphone.names.
Microphone
  muted : Boolean
[read-only] Specifies whether the user has denied access to the microphone (true) or allowed access (false).
Microphone
  name : String
[read-only] The name of the current sound capture device, as returned by the sound capture hardware.
Microphone
  names : Array
[static] [read-only] An array of strings containing the names of all available sound capture devices.
Microphone
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
  rate : int
The rate at which the microphone is capturing sound, in kHz.
Microphone
  silenceLevel : Number
[read-only] The amount of sound required to activate the microphone and dispatch the activity event.
Microphone
  silenceTimeout : int
[read-only] The number of milliseconds between the time the microphone stops detecting sound and the time the activity event is dispatched.
Microphone
  soundTransform : flash.media:SoundTransform
Controls the sound of this microphone object when it is in loopback mode.
Microphone
  useEchoSuppression : Boolean
[read-only] Set to true if echo suppression is enabled; false otherwise.
Microphone
Public Methods
 MethodDefined By
 Inherited
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
EventDispatcher
 Inherited
Dispatches an event into the event flow.
EventDispatcher
  
[static] Returns a reference to a Microphone object for capturing audio.
Microphone
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
setLoopBack(state:Boolean = true):void
Routes audio captured by a microphone to the local speakers.
Microphone
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
  
setSilenceLevel(silenceLevel:Number, timeout:int = -1):void
Sets the minimum input level that should be considered sound and (optionally) the amount of silent time signifying that silence has actually begun.
Microphone
  
setUseEchoSuppression(useEchoSuppression:Boolean):void
Specifies whether to use the echo suppression feature of the audio codec.
Microphone
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 Event Summary Defined By
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
  Dispatched when a microphone begins or ends a session.Microphone
 Inherited[broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
  Dispatched when a microphone reports its status.Microphone
Property Detail

activityLevel

property
activityLevel:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The amount of sound the microphone is detecting. Values range from 0 (no sound is detected) to 100 (very loud sound is detected). The value of this property can help you determine a good value to pass to the Microphone.setSilenceLevel() method.

If the microphone is available but is not yet being used because Microphone.getMicrophone() has not been called, this property is set to -1.



Implementation
    public function get activityLevel():Number

See also

codec

property 
codec:String

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

The codec to use for compessing audio. Available codecs are Nellymoser (the default) and Speex. The enumeration class SoundCodec contains the various values that are valid for the codec property.

If you use the Nellymoser codec, you can set the sample rate using Microphone.rate(). If you use the Speex codec, the sample rate is set to 16 kHz.

Speex includes voice activity detection (VAD) and automatically reduces bandwidth when no voice is detected. When using the Speex codec, Adobe recommends that you set the silence level to 0. To set the silence level, use the Microphone.setSilenceLevel() method.



Implementation
    public function get codec():String
    public function set codec(value:String):void

See also

encodeQuality

property 
encodeQuality:int

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

The encoded speech quality when using the Speex codec. Possible values are from 0 to 10. The default value is 6. Higher numbers represent higher quality but require more bandwidth, as shown in the following table. The bit rate values that are listed represent net bit rates and do not include packetization overhead.

Quality valueRequired bit rate (kilobits per second)
0 3.95
15.75
27.75
39.80
412.8
516.8
620.6
723.8
827.8
934.2
1042.2



Implementation
    public function get encodeQuality():int
    public function set encodeQuality(value:int):void

See also

framesPerPacket

property 
framesPerPacket:int

Language Version: ActionScript 3.0
Runtime Versions: Flash Player 10, AIR 1.5

Number of Speex speech frames transmitted in a packet (message). Each frame is 20 ms long. The default value is two frames per packet.

The more Speex frames in a message, the lower the bandwidth required but the longer the delay in sending the message. Fewer Speex frames increases bandwidth required but reduces delay.



Implementation
    public function get framesPerPacket():int
    public function set framesPerPacket(value:int):void

gain

property 
gain:Number

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The amount by which the microphone boosts the signal. Valid values are 0 to 100. The default value is 50.



Implementation
    public function get gain():Number
    public function set gain(value:Number):void

See also

index

property 
index:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The index of the microphone, as reflected in the array returned by Microphone.names.



Implementation
    public function get index():int

See also

muted

property 
muted:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Specifies whether the user has denied access to the microphone (true) or allowed access (false). When this value changes, a status event is dispatched. For more information, see Microphone.getMicrophone().



Implementation
    public function get muted():Boolean

See also

name

property 
name:String  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The name of the current sound capture device, as returned by the sound capture hardware.



Implementation
    public function get name():String

See also

names

property 
names:Array  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

An array of strings containing the names of all available sound capture devices. The names are returned without having to display the Flash Player Privacy Settings panel to the user. This array provides the zero-based index of each sound capture device and the number of sound capture devices on the system, through the Microphone.names.length property. For more information, see the Array class entry.

Calling Microphone.names requires an extensive examination of the hardware, and it may take several seconds to build the array. In most cases, you can just use the default microphone.

Note: To determine the name of the current microphone, use the name property.



Implementation
    public static function get names():Array

See also

rate

property 
rate:int

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The rate at which the microphone is capturing sound, in kHz. Acceptable values are 5, 8, 11, 22, and 44. The default value is 8 kHz if your sound capture device supports this value. Otherwise, the default value is the next available capture level above 8 kHz that your sound capture device supports, usually 11 kHz. Flash Player 10 and AIR 1.5 or later support a 16kHz rate value.

Note: If you are using the Speex codec (Microphone.codec = SoundCodec.SPEEX) for Flash Player 10 and AIR 1.5 or later, the default rate value is 16kHz. If you use the Speex codec and then change the codec value to Nellymoser (Microphone.codec = SoundCodec.NELLYMOSER), the rate continues to be set to 16kHz until you explicitly set the rate to a new value. To receive audio using Flash Player releases before Flash Player 10 and AIR releases before AIR 1.5, change both the codec and the rate values when you publish the audio.



Implementation
    public function get rate():int
    public function set rate(value:int):void

See also

silenceLevel

property 
silenceLevel:Number  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The amount of sound required to activate the microphone and dispatch the activity event. The default value is 10.



Implementation
    public function get silenceLevel():Number

See also

silenceTimeout

property 
silenceTimeout:int  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

The number of milliseconds between the time the microphone stops detecting sound and the time the activity event is dispatched. The default value is 2000 (2 seconds).

To set this value, use the Microphone.setSilenceLevel() method.



Implementation
    public function get silenceTimeout():int

See also

soundTransform

property 
soundTransform:flash.media:SoundTransform

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Controls the sound of this microphone object when it is in loopback mode.



Implementation
    public function get soundTransform():flash.media:SoundTransform
    public function set soundTransform(value:flash.media:SoundTransform):void

useEchoSuppression

property 
useEchoSuppression:Boolean  [read-only]

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Set to true if echo suppression is enabled; false otherwise. The default value is false unless the user has selected Reduce Echo in the Flash Player Microphone Settings panel.



Implementation
    public function get useEchoSuppression():Boolean

See also

Method Detail

getMicrophone

()method
public static function getMicrophone(index:int = -1):Microphone

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Returns a reference to a Microphone object for capturing audio. To begin capturing the audio, you must attach the Microphone object to a NetStream object (see NetStream.attachAudio()).

Multiple calls to Microphone.get() reference the same microphone. Thus, if your code contains the lines mic1 = Microphone.get() and mic2 = Microphone.get(), both mic1 and mic2 reference the same (default) microphone.

If you want to get the default microphone, you need to call getMicrophone() with -1. If you call it without parameters, it will return the first microphone in the list.

Use the index property to get the index value of the current Microphone object. You can then pass this value to other methods of the Microphone class.

In general, you should not pass a value for index. Simply use the Microphone.getMicrophone() method to return a reference to the default microphone. By using the Microphone Settings panel, the user can specify the default microphone the application should use. If you pass a value for index, you might reference a microphone other than the one the user chooses. You can use index in rare cases—for example, if your application is capturing audio from two microphones at the same time.

When a SWF file tries to access the object returned by Microphone.getMicrophone() —for example, when you call NetStream.attachAudio()— Flash Player displays a Privacy dialog box that lets the user choose whether to allow or deny access to the microphone. (Make sure your Stage size is at least 215 x 138 pixels; this is the minimum size Flash Player requires to display the dialog box.)

When the user responds to this dialog box, a status event is dispatched that indicates the user's response. You can also check the Microphone.muted property to determine if the user has allowed or denied access to the microphone.

If Microphone.getMicrophone() returns null, either the microphone is in use by another application, or there are no microphones installed on the system. To determine whether any microphones are installed, use Microphones.names.length. To display the Flash Player Microphone Settings panel, which lets the user choose the microphone to be referenced by Microphone.getMicrophone, use Security.showSettings().

Parameters

index:int (default = -1) — The index value of the microphone.

Returns
Microphone — A reference to a Microphone object for capturing audio.

Events
status:StatusEvent — Dispatched when a microphone reports its status. If the value of the code property is "Microphone.Muted", the user has refused to allow the SWF file access to the user's microphone. If the value of the code property is "Microphone.Unmuted", the user has allowed the SWF file access to the user's microphone.

See also

setLoopBack

()method 
public function setLoopBack(state:Boolean = true):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Routes audio captured by a microphone to the local speakers.

Parameters

state:Boolean (default = true)

setSilenceLevel

()method 
public function setSilenceLevel(silenceLevel:Number, timeout:int = -1):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Sets the minimum input level that should be considered sound and (optionally) the amount of silent time signifying that silence has actually begun.

  • To prevent the microphone from detecting sound at all, pass a value of 100 for silenceLevel; the activity event is never dispatched.
  • To determine the amount of sound the microphone is currently detecting, use Microphone.activityLevel.

Activity detection is the ability to detect when audio levels suggest that a person is talking. When someone is not talking, bandwidth can be saved because there is no need to send the associated audio stream. This information can also be used for visual feedback so that users know they (or others) are silent.

Silence values correspond directly to activity values. Complete silence is an activity value of 0. Constant loud noise (as loud as can be registered based on the current gain setting) is an activity value of 100. After gain is appropriately adjusted, your activity value is less than your silence value when you're not talking; when you are talking, the activity value exceeds your silence value.

This method is similar to Camera.setMotionLevel(); both methods are used to specify when the activity event is dispatched. However, these methods have a significantly different impact on publishing streams:

  • Camera.setMotionLevel() is designed to detect motion and does not affect bandwidth usage. Even if a video stream does not detect motion, video is still sent.
  • Microphone.setSilenceLevel() is designed to optimize bandwidth. When an audio stream is considered silent, no audio data is sent. Instead, a single message is sent, indicating that silence has started.

Parameters

silenceLevel:Number — The amount of sound required to activate the microphone and dispatch the activity event. Acceptable values range from 0 to 100.
 
timeout:int (default = -1) — The number of milliseconds that must elapse without activity before Flash Player or Adobe AIR considers sound to have stopped and dispatches the dispatch event. The default value is 2000 (2 seconds). (Note: The default value shown in the signature, -1, is an internal value that indicates to Flash Player or Adobe AIR to use 2000.)

See also

setUseEchoSuppression

()method 
public function setUseEchoSuppression(useEchoSuppression:Boolean):void

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Specifies whether to use the echo suppression feature of the audio codec. The default value is false unless the user has selected Reduce Echo in the Flash Player Microphone Settings panel.

Echo suppression is an effort to reduce the effects of audio feedback, which is caused when sound going out the speaker is picked up by the microphone on the same computer. (This is different from echo cancellation, which completely removes the feedback.)

Generally, echo suppression is advisable when the sound being captured is played through speakers — instead of a headset — on the same computer. If your SWF file allows users to specify the sound output device, you may want to call Microphone.setUseEchoSuppression(true) if they indicate they are using speakers and will be using the microphone as well.

Users can also adjust these settings in the Flash Player Microphone Settings panel.

Parameters

useEchoSuppression:Boolean — A Boolean value indicating whether echo suppression should be used (true) or not (false).

See also

Event Detail

activity

Event
Event Object Type: flash.events.ActivityEvent
property ActivityEvent.type = flash.events.ActivityEvent.ACTIVITY

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Dispatched when a microphone begins or ends a session.

To specify the amount of sound required to trigger this event with an activating property of true, or the amount of time that must elapse without sound to trigger this event with an activating property of false, use Microphone.setSilenceLevel().

The ActivityEvent.ACTIVITY constant defines the value of the type property of an activity event object.

This event has the following properties:

PropertyValue
activatingtrue if the device is activating or false if it is deactivating.
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object beginning or ending a session, such as a Camera or Microphone object.

See also

status

Event  
Event Object Type: flash.events.StatusEvent
property StatusEvent.type = flash.events.StatusEvent.STATUS

Language Version: ActionScript 3.0
Runtime Versions: AIR 1.0 Flash Player 9

Dispatched when a microphone reports its status. If the value of the code property is "Microphone.Muted", the user has refused to allow the SWF file access to the microphone. If the value of the code property is "Microphone.Unmuted", the user has allowed the SWF file access to the microphone.

Defines the value of the type property of a status event object.

This event has the following properties:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
codeA description of the object's status.
currentTargetThe object that is actively processing the Event object with an event listener.
levelThe category of the message, such as "status", "warning" or "error".
targetThe object reporting its status.

See also

MicrophoneExample.as

The following example captures sound using echo suppression from a microphone after the user allows access to their computer's microphone. The Security.showSettings() method displays the Flash Player dialog box, which requests permission to access the user's microphone. The call to setLoopBack(true) reroutes input to the local speaker, so you can hear the sound while you run the example.

Two listeners listen for activity and status events. The activity event is dispatched at the start and end (if any) of the session and is captured by the activityHandler() method, which traces information on the event. The status event is dispatched if the attached microphone object reports any status information; it is captured and traced using the statusHandler() method.

Note: A microphone must be attached to your computer for this example to work correctly.


package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.media.Microphone;
    import flash.system.Security;

    public class MicrophoneExample extends Sprite {
        public function MicrophoneExample() {
            var mic:Microphone = Microphone.getMicrophone();
            Security.showSettings("2");
            mic.setLoopBack(true);
                    
            if (mic != null) {
                mic.setUseEchoSuppression(true);
                mic.addEventListener(ActivityEvent.ACTIVITY, activityHandler);
                mic.addEventListener(StatusEvent.STATUS, statusHandler);
            }
        }

        private function activityHandler(event:ActivityEvent):void {
            trace("activityHandler: " + event);
        }

        private function statusHandler(event:StatusEvent):void {
            trace("statusHandler: " + event);
        }
    }
}