ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
Microphone

Package | flash.media
Class | public final class Microphone
Inheritance | Microphone EventDispatcher Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Use the Microphone class to capture audio from a microphone attached to a computer running Flash Player. 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 Flash Player.

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; this is the minimum size required to display the dialog box.

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

View the examples

See also

flash.media.Camera
Basics of working with sound

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | activityLevel : Number [read-only] The amount of sound the microphone is detecting. | Microphone
|  | codec : String The codec to use for compessing audio. | Microphone
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | encodeQuality : int Encoded speech quality. | Microphone
|  | framesPerPacket : int Number of speex speech frames transmitted in a packet (message). | Microphone
|  | gain : Number The microphone gain—that is, the amount by which the microphone should multiply the signal before transmitting it. | 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
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | rate : int The rate at which the microphone captures 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 : 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
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | 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
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | getMicrophone(index:int = -1):Microphone [static] Returns a reference to a Microphone object for capturing audio. | Microphone
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | 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
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 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
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | Dispatched when Flash Player gains operating system focus and becomes active. | EventDispatcher
|  | activity | Dispatched when a microphone begins or ends a session. | Microphone
|  | deactivate | Dispatched when Flash Player loses operating system focus and is becoming inactive. | EventDispatcher
|  | status | Dispatched when a microphone reports its status. | Microphone

Property Detail

activityLevel | property

`activityLevel:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.getMicrophone()
flash.media.Microphone.setSilenceLevel()
flash.media.Microphone.gain

codec | property |

`codec:String` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The codec to use for compessing audio. The default is Nelly Moser if you don't otherwise the the compression type. The enumeration class `SoundCodec` contains the various values that are valid for the `codec` property.

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

encodeQuality | property |

`encodeQuality:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Encoded speech quality. This value is in the range of 0 and 10 with 5 is default. Higher number means better quality at the price of higher bandwidth. Speex quality bitrate ------------------------------ 0 3.95 kbit/s 1 5.75 kbit/s 2 7.75 kbit/s 3 9.80 kbit/s 4 12.8 kbit/s 5 16.8 kbit/s 6 20.6 kbit/s 7 23.8 kbit/s 8 27.8 kbit/s 9 34.2 kbit/s 10 42.2 kbit/s Please note that the above values represent net bitrates and does not include packetization overhead.

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

framesPerPacket | property |

`framesPerPacket:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

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

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

gain | property |

`gain:Number` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The microphone gain—that is, the amount by which the microphone should multiply the signal before transmitting it. A value of 0 tells Flash Player to multiply by 0; that is, the microphone transmits no sound.

You can think of this setting like a volume knob on a stereo: 0 is no volume and 50 is normal volume. Numbers below 50 specify lower than normal volume, while numbers above 50 specify higher than normal volume. Valid values are 0 through 100, and 50 is the default value. The user can change this value in the Flash Player Microphone Settings panel.

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

See also

flash.media.Microphone.setUseEchoSuppression()

index | property |

`index:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.getMicrophone()
flash.media.Microphone.names

muted | property |

`muted:Boolean` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.getMicrophone()
flash.media.Microphone.status

name | property |

`name:String` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.getMicrophone()
flash.media.Microphone.names

names | property |

`names:Array` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

Array
flash.media.Microphone.name
flash.media.Microphone.getMicrophone()

rate | property |

`rate:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The rate at which the microphone captures sound, in kHz. The allowed values are any of the following your sound device supports: 5, 8, 11, 22, or 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.

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

silenceLevel | property |

`silenceLevel:Number` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.gain
flash.media.Microphone.setSilenceLevel()

silenceTimeout | property |

`silenceTimeout:int` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.setSilenceLevel()

soundTransform | property |

`soundTransform:SoundTransform` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

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

Implementation
`public function get soundTransform():SoundTransform`
`public function set soundTransform(value:SoundTransform):void`

useEchoSuppression | property |

`useEchoSuppression:Boolean` [read-only]

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.setUseEchoSuppression()
Method Detail

getMicrophone | () | method

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

Language Version : | ActionScript 3.0

Player Version : | 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.get()` method to return a reference to the default microphone. By using the Microphone Settings panel, the user can specify the default microphone Flash Player 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.get()` —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.get()` 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.get`, 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

Microphone.status
flash.net.NetStream.attachAudio()
flash.system.Security.showSettings()

setLoopBack | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | 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

Player Version : | 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 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 to use 2000.)

See also

flash.media.Camera.setMotionLevel()
flash.media.Microphone.activityLevel
flash.media.Microphone.activity
flash.media.Microphone.gain
flash.media.Microphone.silenceLevel
flash.media.Microphone.silenceTimeout

setUseEchoSuppression | () | method |

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

Language Version : | ActionScript 3.0

Player Version : | 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

flash.media.Microphone.setUseEchoSuppression()
flash.media.Microphone.useEchoSuppression
Event Detail

activity | Event

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

Language Version : | ActionScript 3.0

Player Version : | 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:

Property | Value
--- | ---
`activating` | `true` if the device is activating or `false` if it is deactivating.
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object beginning or ending a session, such as a Camera or Microphone object.

See also

setSilenceLevel()

status | Event |

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

Language Version : | ActionScript 3.0

Player Version : | 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:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`code` | A description of the object's status.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`level` | The category of the message, such as `"status"`, `"warning"` or `"error"`.
`target` | The object reporting its status.

See also

Microphone.getMicrophone()
Examples How to use examples
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);
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00