< Back to Package Overview

Audio Device Management

Overview

The Vantage hardware can potentially have several different audio devices. In addition to the built-in speaker and microphone, there are the optional handsets, two different ports for plugging in headsets (RJ11 and 3.5mm), as well as support for a paired Bluetooth headset. Users of telephony applications on Vantage will have expectations of which audio device to use for calls and how to switch between them.

Support for Audio Device Management in the Communications Package

The media engine component of the communications package provides support for managing audio devices via the AudioInterface. It provides methods for getting all of the currently available audio devices and switching which one of those devices is currently active. Applications can register an AudioDeviceListener instance to be notified whenever there is a change in the list of available audio devices.

Applications written using the communications package directly can use these facilities for managing audio devices in a generic way for any hardware.

Support for Audio Device Management in the Desk Phone Services Package

As a convenience for applications written for Vantage, the desk phone services package includes an optional class that implements default audio device handling for the Vantage platform, being specialized for the audio devices that can be present on Vantage and implementing audio device switching in a way that users will expect for a desk phone. This is represented by the AudioDeviceHandler interface.

If you choose not to use the default audio device handler, your application must provide an implementation of AudioDeviceListener to the media engine and use that for driving its own audio device management logic, the same as for any other application using the communications package.

Creating the Default Audio Device Handler

To use the default audio device handler, create an instance using the provided factory method in the DefaultVantageAudioDeviceHandler class as part of initializing the communications package, specifically after having created the Client object and having initialized the desk phone services library and obtained a DeskPhoneService instance, but before creating the User object. There is no need to bind the audio device handler to the communications package, since its implementation does that automatically using the provided Client reference.

This is shown in the following code sample for initialization:

    ...
    // Create the Client object
    Client client = new Client(clientConfiguration, application, clientListener);

    // Initialize the Desk Phone Services library
    DeskPhoneService deskPhoneService = DeskPhoneServiceLibrary.initialize(
            applicationContext, myDeskPhoneEventListener, client, null);

    // Setup the default audio device handler
    AudioDeviceHandler audioDeviceHandler =
            DefaultVantageAudioDeviceHandler.createDefaultVantageAudioDeviceHandler(
                    applicationContext, client, deskPhoneServices);
    audioDeviceHandler.addListener(myAudioDeviceChangeListener);

    // Create the User object
    User user = client.createUser(userConfiguration, completionHandler);
    ...

Note that since the audio device handler is bound to a particular Client instance, it is only valid for the lifetime of that Client. If you call shutdown() on the Client and then later create a new one, you must then also create a corresponding new audio device handler. The default audio handler does not need to be refreshed if the User object changes.

Application Interaction with the Default Audio Device Handler

The AudioDeviceHandler interface has support for listeners implementing the AudioDeviceChangeListener interface. This provides a method that is called every time that the audio device handler has switched the currently active audio device, primarily intended so that the application can update its UI to reflect it.

The automatic audio device switching inside the default audio device handler is triggered by hardware-related actions such as taking a handset on or off hook, plugging or unplugging a wired headset, or pairing or unpairing a Bluetooth headset. If your application wants to provides an additional UI for switching audio devices, e.g. to provide a soft button for triggering speakerphone mode or a menu for freely switching between the various available audio devices, you can use the setUserRequestedDevice(AudioDevice) method to force selection of a particular audio device, using the available devices reported by the getAvailableAudioDevices() method.

There is also special support for picking the correct audio device at the beginning of a VoIP call via the pickAudioDeviceForCallStart(HandsetType) method. This is intended to support the case of a VoIP call being triggered by a handset going off-hook, and tells the default audio device handler to use the audio device corresponding to that handset.