Search This Blog

2012-03-22

Mute (an Adobe Native Extension):
The "Missing" API Doc

[UPDATE: As of AIR 3.4, you don't need an ANE to get the iOS mute switch to work -- just use the following:

import flash.media.AudioPlaybackMode;
import flash.media.SoundMixer;


and then

SoundMixer.audioPlaybackMode = AudioPlaybackMode.AMBIENT;

See this Adobe blog post for more.

(Original post follows anyway)]


In the interests of adding iOS mute switch functionality to Super Elk Murder 2012, I have begun digging into AIR Native Extensions, or "ANEs," a new feature as of AIR 3.

Basically, ANEs are little packages of native code that can be imported into a .swf just like an external .swc and may then be implemented like any other AS3 class. This is wonderful because it gives developers access to device-specific features that aren't included in AIR's platform-agnostic API.

Since I don't speak "native" and can't write the extension myself, I had to do what every programmer does from time to time: leech off the internets. And when it comes to the iOS mute switch (technically, Apple refers to it as the "Ring/Silent Switch"), the internets seem to agree on this ANE by a Spanish dude named Enrique David. ¡Muchas gracias, SeƱor David!

Mr. David was even kind enough to provide formal-looking API documentation for his ANE. As you can see, the class contains a single method, .Enable(), that takes one of three string parameters: SOLO_AMBIENT_SOUND (default), AMBIENT_SOUND, and MEDIA_PLAYBACK.

Unfortunately, Mr. David's English is terrible, and his descriptions of these parameters range between confusing and incomprehensible (hence "Missing" in this post's title). I decided I could give something back by posting the results of my own tests using these various options, with plain English explanations of what each one does -- YMMV.


Parameter Descriptions for
Mute ANE by Enrique David
(com.devilishgames.nativeextensions.Mute)


Test Platform = iPhone 4 running iOS 5.1
"App" = Super Elk Murder 2012, an Adobe AIR app written in ActionScript 3
"Music" = the iPhone's built-in music player app
"Switch" = the iPhone's hardware "Ringer/Silent" switch, located on the upper-left side of the device.

  1. Standard Operation (i.e., without Mute.Enable())
    • Switch has no effect on App audio
    • If Music is playing when App starts, Music audio plays simultaneously with App audio

  2. Mute.Enable(SOLO_AMBIENT_SOUND) (default):
    • Switch mutes/unmutes all App audio
    • If Music is playing when App starts, Music audio fades out and pauses

  3. Mute.Enable(AMBIENT_SOUND):
    • Switch mutes/unmutes App audio, but only works once -- it has no effect on the first sound generated after Switch is flipped, nor on any subsequent sounds
    • If Music is playing when App starts, Switch has no effect on Music audio, and behaves as described above for App audio

  4. Mute.Enable(MEDIA_PLAYBACK):
    • Same result as 1. Standard Operation (i.e., without Mute.Enable())

  5. Bugs:
    • Switch has no effect if app is "backgrounded" and then "foregrounded" again -- this is obviously a pretty serious bug, and at time of writing I have no idea if there is any ActionScript workaround.
    • MEDIA_PLAYBACK appears to be completely useless.
    • Switch has no effect when headphones are plugged in -- probably not really a bug, but I thought it was worth noting.



Anyway, there you have it -- I hope this info can prove useful for somebody out there.

ADDITIONAL POTENTIALLY HELPFUL LINKS:

Extending Adobe Air by Oliver Goldman
Native Extensions for Adobe Air
Google Translate