flash.media.Sound (Flex™ 2 Language Reference)

	Property	Defined by
		bytesLoaded : uint [read-only] Returns the currently available number of bytes in this sound object.	Sound
		bytesTotal : int [read-only] Returns the total number of bytes in this sound object.	Sound
		constructor : Object A reference to the class object or constructor function for a given object instance.	Object
		id3 : ID3Info [read-only] Provides access to the metadata that is part of an MP3 file.	Sound
		isBuffering : Boolean [read-only] Returns the buffering state of external MP3 files.	Sound
		length : Number [read-only] The length of the current sound in milliseconds.	Sound
		prototype : Object [static] A reference to the prototype object of a class or function object.	Object
		url : String [read-only] The URL from which this sound was loaded.	Sound

	Method	Defined by
		Sound(stream:URLRequest = null, context:SoundLoaderContext = null) Creates a new Sound object.	Sound
		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
		close():void Closes the stream, causing any download of data to cease.	Sound
		dispatchEvent(event:Event):Boolean Dispatches an event into the event flow.	EventDispatcher
		hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event.	EventDispatcher
		load(stream:URLRequest, context:SoundLoaderContext = null):void Initiates loading of an external MP3 file from the specified URL.	Sound
		play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel Generates a new SoundChannel object to play back the sound.	Sound
		removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object.	EventDispatcher
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations.	Object
		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

Summary	Defined by
activate	Dispatched when Flash Player gains operating system focus and becomes active.	EventDispatcher
complete	Dispatched when data has loaded successfully.	Sound
deactivate	Dispatched when Flash Player loses operating system focus and is becoming inactive.	EventDispatcher
id3	Dispatched by a Sound object when ID3 data is available for an MP3 sound.	Sound
ioError	Dispatched when an input/output error occurs that causes a load operation to fail.	Sound
open	Dispatched when a load operation starts.	Sound
progress	Dispatched when data is received as a load operation progresses.	Sound

bytesLoaded:uint [read-only]

Returns the currently available number of bytes in this sound object. This is usually only useful for externally loaded files.

Implementation
public function get bytesLoaded():uint

bytesTotal:int [read-only]

Returns the total number of bytes in this sound object.

Implementation
public function get bytesTotal():int

id3:ID3Info [read-only]

Provides access to the metadata that is part of an MP3 file.

MP3 sound files can contain ID3 tags, which provide metadata about the file. If an MP3 sound that you load using the Sound.load() method contains ID3 tags, you can query these properties. Only ID3 tags that use the UTF-8 character set are supported.

Flash Player 9 and later supports ID3 2.0 tags, specifically 2.3 and 2.4. The following tables list the standard ID3 2.0 tags and the type of content the tags represent. The Sound.id3 property provides access to these tags through the format my_sound.id3.COMM, my_sound.id3.TIME, and so on. The first table describes tags that can be accessed either through the ID3 2.0 property name or the ActionScript property name. The second table describes ID3 tags that are supported but do not have predefined properties in ActionScript.

ID3 2.0 tag	Corresponding ActionScript property
COMM	Sound.id3.comment
TALB	Sound.id3.album
TCON	Sound.id3.genre
TIT2	Sound.id3.songName
TPE1	Sound.id3.artist
TRCK	Sound.id3.track
TYER	Sound.id3.year

The following table describes ID3 tags that are supported but do not have predefined properties in ActionScript. You access them by calling mySound.id3.TFLT, mySound.id3.TIME, and so on.

Property	Description
TFLT	File type
TIME	Time
TIT1	Content group description
TIT2	Title/song name/content description
TIT3	Subtitle/description refinement
TKEY	Initial key
TLAN	Languages
TLEN	Length
TMED	Media type
TOAL	Original album/movie/show title
TOFN	Original filename
TOLY	Original lyricists/text writers
TOPE	Original artists/performers
TORY	Original release year
TOWN	File owner/licensee
TPE1	Lead performers/soloists
TPE2	Band/orchestra/accompaniment
TPE3	Conductor/performer refinement
TPE4	Interpreted, remixed, or otherwise modified by
TPOS	Part of a set
TPUB	Publisher
TRCK	Track number/position in set
TRDA	Recording dates
TRSN	Internet radio station name
TRSO	Internet radio station owner
TSIZ	Size
TSRC	ISRC (international standard recording code)
TSSE	Software/hardware and settings used for encoding
TYER	Year
WXXX	URL link frame

When using this property, consider the Flash Player security model:

The id3 property of a Sound object is always permitted for SWF files that are in the same security sandbox as the sound file. For files in other sandboxes, there are security checks.
When you load the sound, using the load() method of the Sound class, you can specify a context parameter, which is a SoundLoaderContext object. If you set the checkPolicyFile property of the SoundLoaderContext object to true, Flash Player checks for a cross-domain policy file on the server from which the sound is loaded. If there is a cross-domain policy file, and the file permits the domain of the loading SWF file, then the file is allowed to access the id3 property of the Sound object; otherwise it is not.

However, in the Apollo runtime, content in the application security sandbox (content installed with the Apollo application) are not restricted by these security limitations.

For more information, see the following:

The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs

The Flash Player 9 Security white paper

Implementation
public function get id3():ID3Info

See also

SoundLoaderContext.checkPolicyFile

isBuffering:Boolean [read-only]

Returns the buffering state of external MP3 files. If the value is true, any playback is currently suspended while the object waits for more data.

Implementation
public function get isBuffering():Boolean

length:Number [read-only]

The length of the current sound in milliseconds.

Implementation
public function get length():Number

url:String [read-only]

The URL from which this sound was loaded. This property is applicable only to Sound objects that were loaded using the Sound.load() method. For Sound objects that are associated with a sound asset from a SWF's library, the value of the url property is null.

When you first call Sound.load(), the url property initially has a value of null, because the final URL is not yet known. The url property will have a non-null value as soon as an open event is dispatched from the Sound object.

The url property contains the final, absolute URL from which a sound was loaded. The value of url is usually the same as the value passed to the stream parameter of Sound.load(). However, if you passed a relative URL to Sound.load() the value of the url property will represent the absolute URL. Additionally, if the original URL request is redirected by an HTTP server, the value of the url property reflects the final URL from which the sound file was actually downloaded. This reporting of an absolute, final URL is equivalent to the behavior of LoaderInfo.url.

Implementation
public function get url():String

public function Sound(stream:URLRequest = null, context:SoundLoaderContext = null)

Creates a new Sound object. If you pass a valid URLRequest object to the Sound constructor, the constructor automatically calls the load() function for the Sound object. If you do not pass a valid URLRequest object to the Sound constructor, you must call the load() function for the Sound object yourself, or the stream will not load.

Once load() is called on a Sound object, you can't later load a different sound file into that Sound object. To load a different sound file, create a new Sound object.

Parameters

	`stream:URLRequest` (default = `null`) — The URL that points to an external MP3 file.

	`context:SoundLoaderContext` (default = `null`) — Minimum number of milliseconds of MP3 data to hold in the Sound object's buffer. The Sound object waits until it has at least this much data before beginning playback and before resuming playback after a network stall. The default value is 1000 (one second).

public function close():void

Closes the stream, causing any download of data to cease. No data may be read from the stream after the close() method is called.

Throws

IOError — The stream could not be closed, or the stream was not open.

public function load(stream:URLRequest, context:SoundLoaderContext = null):void

Initiates loading of an external MP3 file from the specified URL. If you provide a valid URLRequest object to the Sound constructor, the constructor calls Sound.load() for you. You only need to call Sound.load() yourself if you don't pass a valid URLRequest object to the Sound constructor or you pass a null value.

Once load() is called on a Sound object, you can't later load a different sound file into that Sound object. To load a different sound file, create a new Sound object.

When using this method, consider the Flash Player security model:

Calling Sound.load() is not allowed if the calling SWF file is in the local-with-file-system sandbox and the sound is in a network sandbox.
Access from the local-trusted or local-with-networking sandbox requires permission from a website through a cross-domain policy file.
You can prevent a SWF file from using this method by setting the allowNetworking parameter of the the object and embed tags in the HTML page that contains the SWF content.

However, in the Apollo runtime, content in the application security sandbox (content installed with the Apollo application) are not restricted by these security limitations.

For more information, see the following:

The security chapter in the Programming ActionScript 3.0 book and the latest comments on LiveDocs

The Flash Player 9 Security white paper

Parameters

	`stream:URLRequest` — A URL that points to an external MP3 file.

	`context:SoundLoaderContext` (default = `null`) — Minimum number of milliseconds of MP3 data to hold in the Sound object's buffer. The Sound object waits until it has at least this much data before beginning playback and before resuming playback after a network stall. The default value is 1000 (one second).

Throws

	`IOError` — A network error caused the load to fail.

	`SecurityError` — Local untrusted SWF files may not communicate with the Internet. You can work around this by reclassifying this SWF file as local-with-networking or trusted.

public function play(startTime:Number = 0, loops:int = 0, sndTransform:SoundTransform = null):SoundChannel

Generates a new SoundChannel object to play back the sound. This method returns a SoundChannel object, which you access to stop the sound and to monitor volume. (To control the volume, panning, and balance, access the SoundTransform object assigned to the sound channel.)

Parameters

	`startTime:Number` (default = `0`) — The initial position in milliseconds at which playback should start.

	`loops:int` (default = `0`) — Defines the number of times a sound loops before the sound channel stops playback.

	`sndTransform:SoundTransform` (default = `null`) — The initial SoundTransform object assigned to the sound channel.

Returns

SoundChannel — A SoundChannel object, which you use to control the sound. This method returns null if you have no sound card or if you run out of available sound channels. The maximum number of sound channels available at once is 32.

Event object type: flash.events.Event
Event.type property = flash.events.Event.COMPLETE

Dispatched when data has loaded successfully.

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

This event has the following properties:

Property	Value
`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 network object that has completed loading.

See also

Sound.load()

Event object type: flash.events.Event
Event.type property = flash.events.Event.ID3

Dispatched by a Sound object when ID3 data is available for an MP3 sound.

Defines the value of the type property of an id3 event object.

This event has the following properties:

Property	Value
`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 Sound object loading the MP3 for which ID3 data is now available. The `target` is not always the object in the display list that registered the event listener. Use the `currentTarget` property to access the object in the display list that is currently processing the event.

See also

Sound.id3

Event object type: flash.events.IOErrorEvent
IOErrorEvent.type property = flash.events.IOErrorEvent.IO_ERROR

Dispatched when an input/output error occurs that causes a load operation to fail.

Defines the value of the type property of an ioError event object.

This event has the following properties:

Property	Value
`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.
`errorID`	A reference number associated with the specific error.
`target`	The network object experiencing the input/output error.
`text`	Text to be displayed as an error message.

See also

Sound.load()

Event object type: flash.events.Event
Event.type property = flash.events.Event.OPEN

Dispatched when a load operation starts.

Defines the value of the type property of an open event object.

This event has the following properties:

Property	Value
`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 network object that has opened a connection.

See also

Sound.load()

Event object type: flash.events.ProgressEvent
ProgressEvent.type property = flash.events.ProgressEvent.PROGRESS

Dispatched when data is received as a load operation progresses.

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

This event has the following properties:

Property	Value
`bubbles`	`false`
`bytesLoaded`	The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal`	The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`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 network object reporting progress.

See also

Sound.load()

The following example displays information about sound events that take place as an MP3 file is opened and played. To run this example, place a file named MySound.mp3 in the same directory as your SWF file.

package {
    import flash.display.Sprite;
    import flash.events.*;
    import flash.media.Sound;
    import flash.media.SoundChannel;
    import flash.net.URLRequest;

    public class SoundExample extends Sprite {
        private var url:String = "MySound.mp3";
        private var song:SoundChannel;

        public function SoundExample() {
            var request:URLRequest = new URLRequest(url);
            var soundFactory:Sound = new Sound();
            soundFactory.addEventListener(Event.COMPLETE, completeHandler);
            soundFactory.addEventListener(Event.ID3, id3Handler);
            soundFactory.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
            soundFactory.addEventListener(ProgressEvent.PROGRESS, progressHandler);
            soundFactory.load(request);
            song = soundFactory.play();
        }

        private function completeHandler(event:Event):void {
            trace("completeHandler: " + event);
        }

        private function id3Handler(event:Event):void {
            trace("id3Handler: " + event);
        }

        private function ioErrorHandler(event:Event):void {
            trace("ioErrorHandler: " + event);
        }

        private function progressHandler(event:ProgressEvent):void {
            trace("progressHandler: " + event);
        }
    }
}

Adobe^® Flex™ 2 Language Reference		All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Frames No Frames
Class Sound	Properties \| Methods \| Events \| Examples

Package	flash.media
Class	public class Sound
Inheritance	Sound EventDispatcher Object
Subclasses	SoundAsset