Using the Dolby API in the Intel XDK

Music To Your Ears

When I think of Dolby technology, I usually think of movie theaters and high end stereos, adding life to soundtracks and music. It turns out that they've also been working on bringing some of that clever technology to hand-held devices. This technology is designed to enhance different sorts of audio, including games, movies and music. This is cool if you own one of these devices and can experience better audio, but it's also interesting to developers.

As an app developer, you want to be able to take advantage of this technology to maximum effect. If you're designing a game, you want to enhance it by ensuring that the Dolby game profile is active. If you're playing music or video, you'll want to activate the appropriate profile. Fortunately the Dolby Cordova Plugin makes that easy.

The Dolby API consists of three parts:

  • dolby.dap - contains various functions you'll want to call, like initialize and setProfile
  • dolby.DapProfile - contains the available profiles (GAME, MUSIC, VOICE and MOVIE)
  • dolby.DapError - various error codes, provided as parameters to onFail callbacks

If all you want to do is enable Dolby functionality, that's easy. The API relies on a Cordova Plugin which is available as a featured plugin in the Intel XDK. To access it, just go to the projects page, expand the "Plugins And Permissions" pane and check "Dolby Audio API". This will cause the plugin to be loaded in your app, exposed as a global variable dolby. For example, if you want to enable the feature for your game, you just need to add this to your initialization code:

var onDsConnected = function() {
    console.log("Dolby started successfully");
};
var onFail = function(err) {
    console.log("Dolby failed due to ", err);
};
dolby.dap.initialize(dolby.DapProfile.GAME, onDsConnected, onFail);

Now, if all you care about is enabling it, this will be fine. But you probably want something more sophisticated, say if you want to switch to the music profile for interstitial music while loading a new level:

dolby.setProfile(dolby.DapProfile.Music);

Aside from initializing and setting profiles, there are a few other convenient capabilities. Suppose you've got things set up for your App, with the profile set for your wicked action packed game, but then the user gets a phone call. The user, no doubt saavy about these things, has his phone set to use the VOICE profile, the better to hear his phone conversations. You don't want to mess with that, so when the game is interrupted, you want to defer to whatever the system setting is, and then go back to the GAME profile when it resumes. The Dolby API allows for that with the suspendSession() and restartSession() functions:

onPause = function () {
    dolby.dap.suspendSession();
};
document.addEventListener("pause", onPause, false);


onResume = function () {
    var success = function () {
        console.log("Resuming OK");
    }
    var err = function () {
        console.log("Problem resuming");
    }

    dolby.dap.restartSession(success, err);
};
document.addEventListener("resume", onResume, false);

There are a couple other functions, like getSelectedProfile() to check the current setting, and release() to release control and go back to the system settings. All the details can be found in the documentation available at the github site - https://github.com/DolbyDev/Dolby-Audio-Plugin-for-Cordova or at Dolby's developer site - http://developer.dolby.com. I've also got a working demo app at https://github.com/oldgeeksguide/dolby-cordova-plugin-example that you can grab and import into the Intel XDK.

And if you get a chance to try a device with this capability, check it out. It makes the builtin speakers sound better, and works great with headphones!

Para obtener información más completa sobre las optimizaciones del compilador, consulte nuestro Aviso de optimización.