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.

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

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

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

Mute.Enable(MEDIA_PLAYBACK):

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

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