| Package | com.myflashlab.air.extensions.volume |
| Class | public class Volume |
| Inheritance | Volume  flash.events.EventDispatcher |
This air native extension is a must have ANE for you in every game you are developing. The basic features of this ANE lets you control the device music steam volume level and you can also listen to the device's hardware volume button changes. Considering that in AdobeAir games, you will need access to the music stream audio channel of the device, we included support for this channel only. Example of other channels is the ringtone channel which we intentially did not include in this ANE as being able to control that feature does not seem useful to the majority of Air game developers
But what is making this ANE a must have add-on in your games is that this air native extension can help you answer the folloiwng two questions.
With this air native extension, you can listen to device's silence event to know when the device goes muted and when it backs to normal mode and then you can decide if you wish to stop musics or sound effects in your game.
Moreover, this ANE let's you set audio focus of the device to your app if you wish to, so you can easily stop any background music that might be playing.
These two features will surely make your game look a lot more professional.
Make sure to take care of the permissions manually if you are targeting AIR SDK 24+: https://github.com/myflashlab/VolumePro-ANE/#permissions
See also
| Property | Defined By | ||
|---|---|---|---|
| service : Launcher [static]
Use this property to add event listeners to different events found in VolumeEvent class. | Volume | ||
| value : Number [static]
Indicates the volume value of the music stream channel of the device
There are other channels like ringtone which you wouldn't need when developing a game, so we didn't add
support for them at all. | Volume | ||
| Method | Defined By | ||
|---|---|---|---|
abandonFocus():Boolean [static]
This method will abandon the audio focus from your app to any other app that might have been using it
before in the background.
IMPORTANT: This feature does not work on iOS because of the bug in Adobe Air SDK explained in the
documentations of the requestFocus method.
| Volume | ||
dispose():void [static]
It is very important to dispose the ANE by calling this method when you are closing your app. | Volume | ||
disposeAllNativeSounds():void [static]
Call this method to dispose ALL the currently loaded native sound effects. | Volume | ||
getNativeSoundObject($file:File):void [static]
Use this method to preload your sound files. | Volume | ||
[static]
Call this static method to have access to all other Volume features. | Volume | ||
initNativeSoundObject():void [static]
Call this method to initialize native sound object operations. | Volume | ||
requestFocus():Boolean [static]
Call this method to tell the device Audio manager to grant the audio focus of the device to your app. | Volume | ||
stopAllNativeSounds():void [static]
Call this method to stop ALL the currently playing native sound effects. | Volume | ||
| Constant | Defined By | ||
|---|---|---|---|
| EXTENSION_ID : String = com.myflashlab.air.extensions.volume [static] | Volume | ||
| VERSION : String = 2.0.51 [static] | Volume | ||
| service | property |
public static var service:Launcher
Use this property to add event listeners to different events found in VolumeEvent class.
See also
| value | property |
value:Number
Indicates the volume value of the music stream channel of the device
There are other channels like ringtone which you wouldn't need when developing a game, so we didn't add support for them at all. If you really need them for something special you are working on, do feel free to email us and let us know. we might be able to help you.
public static function get value():Number public static function set value(value:Number):void| abandonFocus | () | method |
public static function abandonFocus():Boolean
This method will abandon the audio focus from your app to any other app that might have been using it before in the background.
IMPORTANT: This feature does not work on iOS because of the bug in Adobe Air SDK explained in the
documentations of the requestFocus method.
Boolean — true if the audio focus has been successfully abandoned
|
See also
| dispose | () | method |
public static function dispose():voidIt is very important to dispose the ANE by calling this method when you are closing your app. This method will stop and unregister the listeners you might have added for listening to the volume changes or mute status.
| disposeAllNativeSounds | () | method |
public static function disposeAllNativeSounds():void
Call this method to dispose ALL the currently loaded native sound effects.
Notice: Unlike Android side, disposing native sound objects on the iOS side may seem not to be working, but it does when there's too many objects in cache.
| getNativeSoundObject | () | method |
public static function getNativeSoundObject($file:File):void
Use this method to preload your sound files. Your sound files must be very short. (less than 30 seconds
and less than 1MB). When calling this method, you must be listening to VolumeEvent.SOUND_LOADED
to know when the file is ready to be used.
You must call this method only after Volume.initNativeSoundObject();
Parameters
$file:File — The sound file to be loaded. The recommended file type on iOS is caf and it MUST be in the
root of your application package. (next to your app's main .swf file: File.applicationDirectory)
|
var _nativeSound1:NativeSound;
var _nativeSound2:NativeSound;
Volume.initNativeSoundObject();
Volume.service.addEventListener(VolumeEvent.SOUND_LOADED, onSoundLoaded);
Volume.getNativeSoundObject(File.applicationDirectory.resolvePath("sound01.mp3"));
Volume.getNativeSoundObject(File.applicationDirectory.resolvePath("sound02.mp3"));
function onSoundLoaded(e:VolumeEvent):void
{
switch(e.nativeSound.file)
{
case "sound01.mp3":
_nativeSound1 = e.nativeSound;
break;
case "sound02.mp3":
_nativeSound2 = e.nativeSound;
break;
}
}
| init | () | method |
public static function init():VolumeCall this static method to have access to all other Volume features.
ReturnsVolume — |
| initNativeSoundObject | () | method |
public static function initNativeSoundObject():void
Call this method to initialize native sound object operations. Only after calling this method, you will be
able to call getNativeSoundObject()
Native sound Objects are used for your game sound effects. First you need to preload your sound files then use them in your game when you need them. The ANE will play the sound effect with almost NO LATENCY.
Note that you are limited to only 32 sound objects at a time.
| requestFocus | () | method |
public static function requestFocus():Boolean
Call this method to tell the device Audio manager to grant the audio focus of the device to your app. This means that any other app that might be playing in the background will be stopped.
IMPORTANT: On Android side, you can call this method anytime you wish in the lifetime of your
application and it will successfully stop any background music. when this happens, you can use
abandonFocus method to resume the bg music playback. BUT, on the iOS, unfortunately this is
not the case. There's a bug in AdobeAir SDK on iOS which is preventing these features to work correctly
like how they work on the Android side.
The problem on the iOS side is that as soon as ANY sound is played in your app using the standard AS3
APIs, you will no longer be able to use the requestFocus or the abandonFocus
methods. So, what you need to do to make sure you can stop bg music from being played and actually grant
the focus to your own game, is to call the requestFocus method BEFORE playing ANY sound in
your game. This way, the focus will be granted to your app successfully.
Boolean — true if the audio focus has been granted to your app successfully
|
See also
| stopAllNativeSounds | () | method |
public static function stopAllNativeSounds():voidCall this method to stop ALL the currently playing native sound effects.
| EXTENSION_ID | Constant |
public static const EXTENSION_ID:String = com.myflashlab.air.extensions.volume| VERSION | Constant |
public static const VERSION:String = 2.0.51
import com.myflashlab.air.extensions.volume.Volume;
import com.myflashlab.air.extensions.volume.VolumeEvent;
Volume.init();
// you may use the Volume.value property to read/write volume values. it must be a number between 0 and 1
// It is VERY important to Volume.dispose(); or at least remove the listener when you're closing your app
Volume.service.addEventListener(VolumeEvent.VOLUME_CHANGE, onDeviceVolumeChanged);
function onDeviceVolumeChanged(e:VolumeEvent):void
{
trace("volume = " + e.param);
}
// you can also set a listener to know when the device goes silenced and when it comes back to normal
// It is VERY important to Volume.dispose(); or at least remove the listener when you're closing your app
Volume.service.addEventListener(VolumeEvent.MUTE_STATE, onDeviceMuteChanged);
function onDeviceMuteChanged(e:VolumeEvent):void
{
trace("is device mute? " + e.param);
}
// You can also request audio focus to your app or even abandon it from your app with the following command:
// But make sure to read the documentations to know how different iOS and Android would react on this method.
// Volume.requestFocus();
// Volume.abandonFocus();
// And finally, you can listen to possible error messages which may happen on iOS side.
Volume.service.addEventListener(VolumeEvent.ERROR, onError);
function onError(e:VolumeEvent):void
{
trace("onError = " + e.param);
}