Media Actions API in BlackBerry JDE v5.0.0 How-To

How-to

I would like to talk about a new API feature in the BlackBerry® Java® Development Environment v5.0 (Beta) I worked on called the Media Actions API. In this article I will discuss how to use this API to respond to media key presses in the same way that the built-in media player does: respond to media key presses while in the background, and respond to key presses on connected wired headsets and paired Bluetooth® headsets. I will also discuss some things to keep in mind when using this API, as well as some implementation details. Finally, I will explain how to use this functionality from MIDlets, even without using non-standard APIs. Included within the BlackBerry JDE v5.0.0 beta is a great sample media player application that demonstrates how to use the API and I would encourage you to look at this demo and play with it. There is also a simple application included at the end of this article for reference.

The key to the Media Actions API is the new interface net.rim.device.api.media.MediaActionHandler, which defines a single method:

public boolean mediaAction(int action, int source, Object context)

The implementation of this method is expected to respond to the specified “action”, which will be equal to one of the MEDIA_ACTION_ constants defined in the interface. These action constants represent common media player actions, such as play/pause, next/previous track, and volume up/down. The “source” and “context” parameters contain additional information about where the action came from and may be used by the implementation to behave differently depending on their values. Examples of values for the “action” parameter are MEDIA_ACTION_PLAYPAUSE_TOGGLE and MEDIA_ACTION_NEXT_TRACK. Examples of values for the “source” parameter are SOURCE_BACKGROUND_KEY and SOURCE_WIRED_HEADSET.

The first use of the MediaActionHandler interface is to respond to media key presses while the application is in the foreground. A new abstract class has been created that implements KeyListener and provides standard mappings from key presses to media actions: net.rim.device.api.media.MediaKeyListener. These mappings depend on the hardware keys available on each BlackBerry smartphone and are the exact mappings used by the built-in BlackBerry Media Player application. For example, if the BlackBerry smartphone does not have dedicated “next” and “previous” keys then pressing-and-holding the volume keys will generate “next track” and “previous track” media actions; however, on devices that do have dedicated “next” and “previous” keys these buttons will be used to generate the next/previous track actions and pressing-and-holding the volume keys will do nothing. The MediaKeyListener class implements all methods defined by KeyListener but does not implement the method defined by MediaActionHandler, as it is left to a subclass. An instance of MediaKeyListener can be registered by invoking addKeyListener(KeyListener) on the Application instance for the application.

The second use of this interface is to respond to media key presses while the application is in the background. Normally, applications are only able to respond to key presses while in the foreground; to respond to key presses while in the background an application must register an instance of MediaActionHandler using the new method addMediaActionHandler(MediaActionHandler), defined in the Application class. After registration, the MediaActionHandler will be notified of media actions resulting from media key presses even when it is in the background. The mappings from key presses to media actions are identical to the standard mappings implemented by MediaKeyListener and cannot be modified.

The third use of the MediaActionHandler interface is to respond to key presses on a connected wired headset and/or paired Bluetooth® headset. In fact, this functionality comes for free when registering a MediaActionHandler. This is because the mediaAction() method is invoked when buttons are pressed on one of these headsets, just like it is invoked when media keys on the BlackBerry smartphone itself are pressed. The only difference is that the “source” parameter will be equal to the SOURCE_ constants defined in MediaActionHandler and the “context” parameter will be non-null, as documented in the javadocs for the SOURCE_ constants. Note, however, that media actions from all sources are delivered even if audio is being played through only one of the sources. For example, if an application is playing audio through a wired headset and the user presses a button on a paired Bluetooth headset, then the corresponding media action will still be delivered to the application; it is up to the application to choose whether or not to respond to it.

Care was taken during implementation to ensure that when multiple applications register a MediaActionHandler only one of them is actually notified, and the choice of which one is notified is made in a fair way. The rationale was that if multiple media player applications were running in the background and the user presses the play/pause button they would want to pause the current song; but if both applications were notified then it would pause one and begin playback in the other, an annoying user experience. Therefore, only the most-recently-foregrounded application that has registered a MediaActionHandler will be notified. This heuristic was chosen because it is assumed that the background media player application that the user wants to control is most likely to be the one that was most recently used explicitly. If that application exits, then the one that was most-recently-foregrounded before it will be the one that gets notified, and so on. Effectively, a “stack” of applications is maintained and only the application on the top of the stack gets notified of media actions, and an application is moved to the top of the stack when it comes to the foreground.

So far, this article has only discussed how to use the Media Actions API in CLDC applications, those that extend net.rim.device.api.system.Application; however, this feature is also available in MIDlet applications, those that extend javax.microedition.midlet.MIDlet. A MIDlet is free to register a MediaActionHandler just like a CLDC application and will receive callbacks in exactly the same way. But the Canvas class has been modified for native support of media keys. Already, applications can override the keyPressed(), keyReleased(), and keyRepeated() methods of Canvas to respond to key presses while in the foreground and the keyCode for volume up and volume down are already documented to be -150 and -151, respectively. In BlackBerry JDE v5.0.0 keyCodes for mute/speakerphone, next, and previous keys were added: -2731, -4100, and -4101, respectively. But one problem with simply implementing keyXXX() to handle these new keyCodes is that another media player application that is in the background will also be notified of these key presses. To fix this problem, the concept of “media player mode” for MIDlets was introduced. If media player mode is enabled then two things change: background applications are not notified of media key presses that occur while the MIDlet is in the foreground and the MIDlet is notified of media key presses that occur while it is in the background. The MIDlet application will be inserted into and moved around in the application “stack” just like CLDC applications to contend for receiving notifications of background media keys. By default, media player mode is disabled and it can be enabled by using the new interface net.rim.device.api.lcdui.control.MediaBehaviourControl, whose instance can be obtained from the Display object (see javadocs for details). Alternately, the JAD attribute RIM-MIDlet-MediaPlayerModeEnabled can be set to “1” for media player mode to instead be enabled by default, thus avoiding the use of any non-standard APIs.

I really hope that media player application developers will find this API easy to use and of value to their applications. Also, I hope to see some creative uses of this API that I could never have foreseen, which always impresses me! Please comment on this article with feedback, both positive and negative, about the API. You can try it out in the BlackBerry 5.0.0 JDE beta that is available at the link below.

BlackBerry® Java® Development Environment v5.0 (Beta)

Below is a very simple application that demonstrates how an application can respond to media actions.

import net.rim.device.api.media.MediaKeyListener;
import net.rim.device.api.ui.Field;
import net.rim.device.api.ui.Screen;
import net.rim.device.api.ui.UiApplication;
import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.component.SeparatorField;
import net.rim.device.api.ui.container.MainScreen;

public class MediaActionsAPIDemo extends UiApplication {

private static final String INSTRUCTION_TEXT =
“Press a media key, even when in the background, “
+ “and the corresponding action will be logged “
+ “to the screen and standard output.”;

private final MainScreen _screen;

public MediaActionsAPIDemo() {
this._screen = new MainScreen();
this._screen.setTitle(“Media Actions API Demo”);
this._screen.add(new LabelField(INSTRUCTION_TEXT));

this._screen.add(new SeparatorField());
this.pushScreen(this._screen);

final MyMediaKeyListener myMediaKeyListener =
new MyMediaKeyListener(this._screen);
this.addKeyListener(myMediaKeyListener);
this.addMediaActionHandler(myMediaKeyListener);
}

public static void main(String[] args) {
new MediaActionsAPIDemo().enterEventDispatcher();
}

private static class MyMediaKeyListener extends
MediaKeyListener {

private final Screen _logScreen;

public MyMediaKeyListener(Screen logScreen) {
this._logScreen = logScreen;
}

public boolean mediaAction(int action, int source,
Object context) {
final StringBuffer sb = new StringBuffer(200);
sb.append(“mediaAction(action=”);
sb.append(getActionName(action));
sb.append(“, source=”);
sb.append(getSourceName(source));
sb.append(“, context=”);
sb.append(context);
sb.append(‘)’);

final String message = sb.toString();
System.out.println(message);
final LabelField field =
new LabelField(message, Field.FOCUSABLE);
this._logScreen.add(field);

return true;
}

public static String getActionName(int action) {
switch (action) {
case MEDIA_ACTION_NEXT_TRACK:
return “NEXT_TRACK”;
case MEDIA_ACTION_PLAYPAUSE_TOGGLE:
return “PLAYPAUSE_TOGGLE”;
case MEDIA_ACTION_PREV_TRACK:
return “PREV_TRACK”;
case MEDIA_ACTION_VOLUME_DOWN:
return “VOLUME_DOWN”;
case MEDIA_ACTION_VOLUME_UP:
return “VOLUME_UP”;
}
return Integer.toString(action);
}

public static String getSourceName(int source) {
switch (source) {
case SOURCE_BACKGROUND_KEY:
return “BACKGROUND_KEY”;
case SOURCE_BLUETOOTH_HEADSET:
return “BLUETOOTH_HEADSET”;
case SOURCE_FOREGROUND_KEY:
return “FOREGROUND_KEY”;
case SOURCE_WIRED_HEADSET:
return “WIRED_HEADSET”;

}
return Integer.toString(source);
}
}

}

About Denver C.

Denver Coneybeare has worked for RIM since graduating from University of Waterloo in Waterloo, Ontario, Canada in 2005 with an Honors Computer Science degree. His roles at RIM have included automated API test developer, API designer and developer, and currently, Team Lead - Java Device APIs. Denver was drawn to API development by the unique challenges that public API design present, that simply are not there when developing code for one's own consumption. With a natural eye for usability, compatibility, and quality, the APIs that Denver has been in charge of are (in his own humble opinion) the best in the world... well, maybe not, but he thinks they're pretty good :)

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus