Requirements
Prerequisite knowledge
Basic familiarity of ActionScript and building of apps with flash content
Required products
Adobe Animate CC
Sample files
User level
Intermediate
 

 

Introduction

The Audio Device Manager ActionScript API was introduced in Flash Player 27 and AIR 28. It provides the capability to select any audio device connected to the system for output.
 

 

Working with the AudioDeviceManager API

This API introduces the following properties and event:

  • AudioDeviceManager.isSupported checks whether AudioDeviceManager is enabled.
  • AudioDeviceManager.audioDeviceManager is used to get a reference to the instance of AudioDeviceManager object.
  • AudioDeviceManager.deviceNames is used to return an array of strings of all the audio output devices connected to the system.
  • AudioDeviceManager.selectedDeviceIndex contains the index of the currently selected device.
  • AudioOutputChangeEvent.AUDIO_OUTPUT_CHANGE event has been introduced with this API. This event is fired when:
    o AudioDeviceManager.selectedDeviceIndex is updated.
    o Any audio device is added or removed from the system.
  • There are two reasons for the event AudioOutputChangeEvent.AUDIO_OUTPUT_CHANGE to be triggered:
    o AudioOutputChangeReason.USER_SELECTION: when user selects an audioDevice
    o AudioOutputChangeReason.DEVICE_CHANGE: when there is addition/removal of device.
  • The User Invoked Action(UIA) restriction is applied to this API.
 
 

Workflows of this API

There are two workflows associated with this API:
  • User selection
  • Device addition/ removal
 
User selection workflow and device addition/removal workflow
 

 

Storage of user selection

Flash Player and AIR can store the user preference of the audio device system. However, user selection is not stored in Flash Player or AIR runtime by itself. It needs to be stored according to the application requirements by using Local Shared Objects(LSO) in Flash content and using LSO or ApplicationStorageDirectory in AIR application.

The locations of LSOs for various browsers on various operating systems are:
 
  • NPAPI plugin
Windows XP
%APPDATA%\Macromedia\Flash Player\#SharedObjects\<random code>\<domain>\<path-maybe°\<object name>.sol
Windows Vista and Later %APPDATA%\Macromedia\Flash Player\#SharedObjects\<random code>\<domain>\<path - maybe\<object name>.sol
Mac OS ~/Library/Preferences/Macromedia/Flash Player/#SharedObjects/<random code>/<domain>/<path - maybe°/<object name>.sol
Linux/Unix ~/.macromedia/Flash_Player/#SharedObjects/<random id>/<domain>/<path maybe°>/<flash filename>.swf/<object name>.sol
  • PPAPI plugin
Windows XP %localappdata%\Google\Chrome\User Data\Default\Pepper Data\Shockwave Flash\WritableRoot\#SharedObjects
Windows Vista and Later %localappdata%\Google\Chrome\User Data\Default\Pepper Data\Shockwave Flash\WritableRoot\#SharedObjects
Mac OS ~/Library/Application Support/Google/Chrome/Default/Pepper Data/Shockwave Flash/WritableRoot/#SharedObjects/
Linux/Unix ~/.config/google-chrome/Default/Pepper Data/Shockwave Flash/WritableRoot/#SharedObjects/
 
  • ActiveX
Windows XP %APPDATA%\Macromedia\Flash Player\#SharedObjects\<random code>\<domain>\<path - maybe°>\<object name>.sol
Windows Vista and Later %APPDATA%\Macromedia\Flash Player\#SharedObjects\<random code>\<domain>\<path - maybe>\<object name>.sol

 

The locations of AIR LSOs for different operating systems are:
Windows         
Users\%USER%\AppData\Roaming\<AIR Application Name>\Local Store\#SharedObjects\<flash filename>.swf\<object name>.sol
Mac OS                       ~/Library/Preferences/<AIR Application Name>/Local Store/#SharedObjects/<flash filename>.swf/<object name>.sol

 

The locations for the ApplicationStorageDirectory for AIR in different operating systems are:
Windows               
C:\Users\userName\AppData\Roaming\applicationID\Local Store
Mac OS /Users/userName/Library/Application Support/applicationid/Local Store
 

 

ActionScript snippets for storing user preference

The basic steps for using the AudioDeviceManager API and storing the user selection are:
  1. Import the necessary classes
  2. Check whether the AudioDeviceManager is supported
  3. Read the LSO file
  4. List the devices
  5. Change the device as per the user selection
  6. Check the reason code.

 

The following code sample provide snippets of the ActionScript code required to store the user preference of audio output device in LSO.

The complete code is provided in OutputSelection_persist.as
 
Import the necessary classes
  • flash.media.AudioDeviceManager
  • flash.media.AudioOutputChangeReason
  • flash.events.AudioOutputChangeEvent
  • flash.net.SharedObject;

 

Check whether the AudioDeviceManager is supported
Confirm whether the AudioDeviceManager is supported or not.
 

if (AudioDeviceManager.isSupported) { trace("AudioDeviceManager is supported"); } else{ trace("AudioDeviceManager not supported"); }

 
Read the LSO
Load the LSO file. In the sample example SavedData.sol file is used. “audio” attribute is used to store the device name. If there is no audio device listed, then the output plays through default device.

var audio_device_manager: AudioDeviceManager; var selected_device_index: int; var obj:SharedObject = SharedObject.getLocal("SavedData"); if (AudioDeviceManager.isSupported) { trace("AudioDeviceManager is supported"); audio_device_manager = AudioDeviceManager.audioDeviceManager; selected_device_index = audio_device_manager.selectedDeviceIndex; if (obj.data.audio != null) { for (var i: int = 0; i < audio_device_manager.deviceNames.length; i++) { if (obj.data.audio == audio_device_manager.deviceNames[i]) audio_device_manager. selectedDeviceIndex = i; } } }else{ trace("AudioDeviceManager is not supported"); }

 
List the devices
The audio devices attached to the system are displayed using deviceNames.

function populate_audio_devices(): void { device_names = audio_device_manager.deviceNames; for (var i = 0; i < device_names.length; i++) { listbox.addItem({label: device_names[i],data: i}); } }

 
Change the device as per the user selection
The device is changed by clicking on its name in the list.

audio_device_manager.selectedDeviceIndex = event.target.selectedItem.data;

 

Check the reason code
The reason code is checked to determine whether the device was changed due to user selection or device addition or removal from the system by listening to the event AudioOutputChangeEvent.AUDIO_OUTPUT_CHANGE. If the device is changed due to user selection then the SavedData.sol file is update to reflect the changes.

function audioOutputChangeHandler(evt: AudioOutputChangeEvent): void { if (evt.reason == AudioOutputChangeReason.USER_SELECTION) { trace("Reason code: USER SELECTION"); try { obj.data.audio = audio_device_manager.deviceNames[audio_device_manager.selectedDeviceIndex]; obj.flush(); } catch (e: SharedObjectFlushStatus) { trace("write operation failed"); } } else if (evt.reason == AudioOutputChangeReason.DEVICE_CHANGE) { trace("Reason code: DEVICE CHANGE"); } }

The ActionScript code provided along with the UI will be displayed as below:
 
Sample App UI
“Click to load audio” button is used to load the audio and read the LSO file. Click the “Change Audio Output Device” button to display the list of available audio devices connected to the system. SelectedDeviceIndex displays the index of the currently selected device. The reason for the audio output device change is displayed under the Event Generated field.
 

Where to go from here

Hopefully this article will help you in developing applications using AudioDeviceManager API. For more details on the API, use the following resource: AudioDeviceManager