flash.media

# SoundLoaderContext - AS3

Package | flash.media
Class | public class SoundLoaderContext
Inheritance | SoundLoaderContext Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The SoundLoaderContext class provides security checks for files that load sound. SoundLoaderContext objects are passed as an argument to the constructor and the `load()` method of the Sound class.

When you use this class, consider the following security model:

- Loading and playing a sound is not allowed if the calling file is in a network sandbox and the sound file to be loaded is local.
- By default, loading and playing a sound is not allowed if the calling is local and tries to load and play a remote sound. A user must grant explicit permission to allow this.
- Certain operations dealing with sound are restricted. The data in a loaded sound cannot be accessed by a file in a different domain unless you implement a URL policy file. Sound-related APIs that fall under this restriction are the `Sound.id3` property and the `SoundMixer.computeSpectrum()`, `SoundMixer.bufferTime`, and `SoundTransform()` methods.

However, in Adobe AIR, content in the `application` security sandbox (content installed with the AIR application) are not restricted by these security limitations.

For more information related to security, see the Flash Player Developer Center Topic: Security.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bufferTime : Number = 1000 The number of milliseconds to preload a streaming sound into a buffer before the sound starts to stream. | SoundLoaderContext
|  | checkPolicyFile : Boolean = false Specifies whether the application should try to download a URL policy file from the loaded sound's server before beginning to load the sound. | SoundLoaderContext
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | SoundLoaderContext(bufferTime:Number = 1000, checkPolicyFile:Boolean = false) Creates a new sound loader context object. | SoundLoaderContext
|  | 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
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

### bufferTime

property

`public var bufferTime:Number = 1000`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The number of milliseconds to preload a streaming sound into a buffer before the sound starts to stream.

Note that you cannot override the value of `SoundLoaderContext.bufferTime` by setting the global `SoundMixer.bufferTime` property. The `SoundMixer.bufferTime` property affects the buffer time for embedded streaming sounds in a SWF file and is independent of dynamically created Sound objects (that is, Sound objects created in ActionScript).

### checkPolicyFile

property

`public var checkPolicyFile:Boolean = false`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Specifies whether the application should try to download a URL policy file from the loaded sound's server before beginning to load the sound. This property applies to sound that is loaded from outside the calling file's own domain using the `Sound.load()` method.

Set this property to `true` when you load a sound from outside the calling file's own domain and code in the calling file needs low-level access to the sound's data. Examples of low-level access to a sound's data include referencing the `Sound.id3` property to get an ID3Info object or calling the `SoundMixer.computeSpectrum()` method to get sound samples from the loaded sound. If you try to access sound data without setting the `checkPolicyFile` property to `true` at loading time, you may get a SecurityError exception because the required policy file has not been downloaded.

If you don't need low-level access to the sound data that you are loading, avoid setting `checkPolicyFile` to `true`. Checking for a policy file consumes network bandwidth and might delay the start of your download, so it should only be done when necessary.

When you call `Sound.load()` with `SoundLoaderContext.checkPolicyFile` set to `true`, Flash Player or AIR must either successfully download a relevant URL policy file or determine that no such policy file exists before it begins downloading the specified sound. Flash Player or AIR performs the following actions, in this order, to verify the existence of a policy file:

- Flash Player or AIR considers policy files that have already been downloaded.
- Flash Player or AIR tries to download any pending policy files specified in calls to `Security.loadPolicyFile()`.
- Flash Player or AIR tries to download a policy file from the default location that corresponds to the sound's URL, which is `/crossdomain.xml` on the same server as `URLRequest.url`. (The sound's URL is specified in the `url` property of the URLRequest object passed to `Sound.load()` or the Sound() constructor function.)

In all cases, Flash Player or AIR requires that an appropriate policy file exist on the sound's server, that it provide access to the sound file at `URLRequest.url` by virtue of the policy file's location, and that it allow the domain of the calling file to access the sound, through one or more `<allow-access-from>` tags.

If you set `checkPolicyFile` to `true`, Flash Player or AIR waits until the policy file is verified before loading the sound. You should wait to perform any low-level operations on the sound data, such as calling `Sound.id3` or `SoundMixer.computeSpectrum()`, until `progress` and `complete` events are dispatched from the Sound object.

If you set `checkPolicyFile` to `true` but no appropriate policy file is found, you will not receive an error until you perform an operation that requires a policy file, and then Flash Player or AIR throws a `SecurityError` exception. After you receive a `complete` event, you can test whether a relevant policy file was found by getting the value of `Sound.id3` within a `try` block and seeing if a `SecurityError` is thrown.

Be careful with `checkPolicyFile` if you are downloading sound from a URL that uses server-side HTTP redirects. Flash Player or AIR tries to retrieve policy files that correspond to the `url` property of the URLRequest object passed to `Sound.load()`. If the final sound file comes from a different URL because of HTTP redirects, then the initially downloaded policy files might not be applicable to the sound's final URL, which is the URL that matters in security decisions.

If you find yourself in this situation, here is one possible solution. After you receive a `progress` or `complete` event, you can examine the value of the `Sound.url` property, which contains the sound's final URL. Then call the `Security.loadPolicyFile()` method with a policy file URL that you calculate based on the sound's final URL. Finally, poll the value of `Sound.id3` until no exception is thrown.

This does not apply to content in the AIR application sandbox. Content in the application sandbox always has programatic access to sound content, regardless of its origin.

For more information related to security, see the Flash Player Developer Center Topic: Security.

Learn more

Loading display content dynamically
Specifying loading context

Related API Elements

flash.media.Sound.load()
flash.media.Sound.id3
flash.media.SoundMixer.computeSpectrum()
flash.media.Sound.url
flash.system.Security.loadPolicyFile()
Constructor Detail

### SoundLoaderContext

()
Constructor

`public function SoundLoaderContext(bufferTime:Number = 1000, checkPolicyFile:Boolean = false)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Creates a new sound loader context object.

Parameters

| `bufferTime:Number` (default = `1000`)`` — The number of seconds to preload a streaming sound into a buffer before the sound starts to stream.
| `checkPolicyFile:Boolean` (default = `false`)`` — Specifies whether the existence of a URL policy file should be checked upon loading the object (`true`) or not.

Example ( How to use this example )
In the following example, the buffer for the sound that will be loaded is set to three seconds.

The first parameter of a SoundLoaderContext object (`context`) is used to increase the default buffer value of one second to three seconds. (The value is in milliseconds.) If the second parameter of the SoundLoaderContext object is set to `true`, Flash Player will check for a cross-domain policy file upon loading the object. Here it is set to the default value `false`, so no policy file will be checked. The `load()` method of the sound object will use the context setting to make sure it will take three seconds to preload the streaming sound into a buffer before the sound starts to stream. The `URLRequest` object determines the location of the file, which is a podcast from Adobe. If an `IOErrorEvent.IO_ERROR` error occurs during the loading of the sound file, the `errorHandler()` method is invoked.

Copy

    package {
        import flash.display.Sprite;
        import flash.net.URLRequest;
        import flash.media.Sound;
        import flash.media.SoundLoaderContext;
        import flash.events.IOErrorEvent;

        public class SoundLoaderContextExample extends Sprite {

            public function SoundLoaderContextExample() {
                var snd:Sound = new Sound();
                var req:URLRequest = new URLRequest("http://av.adobe.com/podcast/csbu_dev_podcast_epi_2.mp3");
                var context:SoundLoaderContext = new SoundLoaderContext(3000, false);

                snd.load(req, context);
                snd.play();

                snd.addEventListener(IOErrorEvent.IO_ERROR, errorHandler);
            }

            private function errorHandler(errorEvent:IOErrorEvent):void {
                trace("The sound could not be loaded: " + errorEvent.text);
            }

        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00