Thursday, May 22, 2014

Using the Dolby Audio API in Xamarin.Android

This is a continuation of my previous post on creating a Java Bindings Library for the Dolby Audio API.  If you haven’t already, you can read it here:

Xamarin Java Bindings Library Example using the Dolby Audio API for Android

Now I’d like to take a look at leveraging the Dolby Audio API from within a Xamarin.Android App.

About the Dolby Audio API 

The Dolby Audio API enables mobile developers to access, enable, and benefit from the Dolby technology incorporated in licensed mobile devices.  The enhanced capability is royalty free to an application developer.

A developer can set one of four predefined profiles: Movie, Music, Game and Voice. Each of these profiles is tuned to achieve the the best audio quality in its particular use case.

*From the Dolby Audio API documentation

Requirements

Xamarin.Android: www.xamarin.com

Dolby Audio API for Android: developer.dolby.com

Visual Studio 2012/2013 (optional): www.visualstudio.com

And finally, you’ll need to download the binding project from GitHub:

https://github.com/adrianstevens/Dolby-Audio-Plug-in-for-Xamarin

You’ll very likely also want an Android device with Dolby hardware for testing, you won’t be able to enable Dolby Audio Processing without one.  The new Kindle Fire HD & HDX devices are Dolby enabled.

Getting Started

To get started, download the binding project from GitHub, and open the solution in either Visual Studio or Xamarin Studio. 

You’ll need a business license of Xamarin.Android to use Visual Studio.  Officially, VS 2012 & VS 2013 are supported, but this project will also work in Visual Studio 2010.

Next, extract the contents of the Dolby Audio API zip, open the “Library” folder, and drag/copy “dolby_audio_processing.jar” into the Jars folder of the “DolbyAudioAPI” project, which is the binding project itself.

jar_to_jars

You should now be able to build the binding project (DolbyAudioAPI).  If it builds successfully, can either reference the project in a new Xamarin.Android project, or find the compiled “DolbyAudioAPI.dll” in the “bin” folder and reference it directly.

Using the Dolby Audio API for Android in C#

Fortunately, the binding project does a pretty good job of encapsulating the java properties and methods. So we can read Dolby’s own Java documentation and follow along.  However, there are some subtle differences.

In order to use the Dolby Audio API, you really just need two things:

an instance of DolbyAudioProcessing

and a class that implements IDolbyAudioProcessingEventListener

Let’s setup a simple Android Activity that also implements IDolbyAudioProcessingEventListener

using Com.Dolby.Dap;
...
public class Activity1 : Activity, IOnDolbyProcessingEventListener
{
   static DolbyAudioProcessing mDolbyAudioProcessing;
   ...

Next we’ll instantiate mDolbyAudioProcessing in OnCreate

protected override void OnCreate(Bundle bundle)
{
    base.OnCreate(bundle)
    mDolbyAudioProcessing = DolbyAudioProcessing.GetDolbyAudioProcessing(this, DolbyAudioProcessing.PROFILE.Music, this);
    ...

 

To get a DolbyAudioProcessing instance, we call the static method GetDolbyAudioProcessing(..) on the DolbyAudioProcessing class which takes three arguments:

Context p0 – the application context, or simply, the current Activity (this).
DolbyAudioProcessing.PROFILE p1 - Profile used to initialize the Dolby audio processing instance, the DolbyAudioProcessing.PROFILE.MOVIE profile will be used by default if it is null.
IOnDolbyAudioProcessingEventListener p3 - a class the implements IDolbyAudioProcessingEventListener for receiving events from the Dolby audio processing background service.  In our case, again its our current activity (this).
DolbyAudioProcessing should not be instantiated directly, and you should only call GetDolbyAudioProcessing(..) once during the lifetime of your application.  If you call it a 2nd time without first releasing, an exception will be thrown.

Implementing IDolbyAudioProcessingEventListener

You’ll need to create four methods that will called allow you to monitor the state of the Dolby Processing hardware:

void OnDolbyAudioProcessingClientConnected();
Will be called when a connection has been made to the Dolby audio processing background service.

void OnDolbyAudioProcessingClientDisconnected();
Will be called when an abnormal disconnection from the Dolby audio processing service occurs.

void OnDolbyAudioProcessingEnabled(bool p0);
Will be called when an external application has enables or disabled Dolby Audio processing.  The bool p0 will indicate on (true) or off (false).

void OnDolbyAudioProcessingProfileSelected(DolbyAudioProcessing.PROFILE p0);
Will be called when an external application has selected one of the Dolby Audio processing profiles.

Changing Dolby Audio Profiles

After you’ve called GetDolbyProcessing (…) you can change the Processing mode by calling SetProfile ().  SetProfile takes a PROFILE enum in the DolbyAudioProcessing namespace as an argument and can be one of the following:

DolbyAudioProcessing.PROFILE.Game
DolbyAudioProcessing.PROFILE.Movie
DolbyAudioProcessing.PROFILE.Music
DolbyAudioProcessing.PROFILE.Voice

if( mDolbyAudioProcessing != null)
    mDolbyAudioProcessing.SetProfile     (DolbyAudioProcessing.PROFILE.Game);

Enabling and Disabling Dolby Audio Processing:

The Dolby Audio processing is a hardware feature of your mobile device, and when enabled, will process all audio playback on your mobile device.

Because of this, you should check and save the state of the Dolby Audio Processing when your application starts, and restore this state when your app or game is pushed to the background.

To enable or disable Dolby Audio Processing, you can directly set the public property Enabled

mDolbyAudioProcessing.enabled = false;

Further Information

Take a look at the two sample projects included with the Java Bindings project.

DolbyTest1 is an example of implementing IOnDolbyAudioProcessingEventListener in the activity.

DolbyText2 uses a separate class for IOnDolbyAudioProcessingEventListener

As well, be sure to take a look at Dolby’s Java documentation included with the API for further details as well as some suggested best practices.

Dolby Audio API Component in the Xamarin Store

If you don’t want to download and build the binding project yourself, there will be a Xamarin component coming soon!

https://components.xamarin.com