BlackBerry Developer's Blog

[#1]

 

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);
        }
    }

}

Message Edited by dconeybeare on 08-17-2009 12:59 PM

Message Edited by dconeybeare on 09-24-2009 02:51 PM

Message Edited by dconeybeare on 09-24-2009 02:54 PM

[#2]

Great article. I would like to see more Media capture related content on this site. Eg, with 5.0, I would like to see code that shows how to capture video content straight from the BB device itself. Just like you can capture images directly from the camera with 4.6. Also, speaking of camera image capture, any plans to add flash control when using this approach? I use the camera image capture in all my ScreamingToaster apps for BlackBerry. I would like to learn more about video capture as I have product plans to incorporate this into apps for 5.0 that I'm working on...

Don't mean to nitpick, but why are source code listings done as screen captures? If you use Windows Live Writer as a blog editor, you can get some cool source code plugins, that will format your Java code in "pre" tags, so that it looks nice, and can be easily copied/pasted, and is syntax colored for Java. Here's a good plugin that I use for all code samples on http://developerlife.com - http://gallery.live.com/liveItemDetail.aspx?li=1f57bd9b-a692-4593-9e9e-e2962d9c0eee&bt=9&pl=8. 

Thanks

Nazmul

President

ScreamingToaster

[#3]

Namzul,

Thanks for the feedback. We're currently having an issue with the way source code is being displayed on the blog, hence the screen captures. Once we have the issue sorted, you can rest assured the code will be displayed in a more dev-friendly format.

Cheers! 

[#4]

Hi Douglas

Thanks for the fix with source code listings. It can be a pain to get it working right on blogs. 

Please let me know if you have plans for video capture examples for 5.0, and if you have plans to incorporate flash control into the multimedia capture API for camera image captures.

Thanks again

Nazmul.

[#5]

And for your questions, Nazmul...

If you download the latest JDE 5.0.0 beta (link included in this blog post) there is a sample application specifically to demonstrate the video capture new feature.  Its name is "videorecordingdemo". It is probably exactly what you're looking form.

Also, in JDE 5.0.0 the JSR 234 "Advanced Multimedia Supplements" (AMMS) has been implemented, which, as part of its feature set, allows applications to control the flash.  Although I haven't used it myself, it looks like the javax.microedition.amms.control.camera.FlashControl interface is what you're looking for.

--Denver

[#6]

Hi Denver

That is awesome! Thanks for the links and information. I will review it and write some tutorials about it on http://developerlife.com.

Take care

Nazmul. 

[#7]

The link given in the post appears to be broken. Can u please tell from where i can get JSR-234 for blackberry and how to integrate with my current system.

[#8]

@Prateek: Thanks for pointing out the broken link to "BlackBerry® Java® Development Environment v5.0 (Beta)".  I have fixed the links in the article, but in case it breaks again in the future, here is how to get there:

1. Go to http://www.blackberry.com/developers

2. Click "Development Beta Software" on the left of the page

3. You should see a link to "BlackBerry Java Application Development v5.0 Beta" listed under the "Current Beta Releases" header; click that link.

The link directly to the site is: http://na.blackberry.com/eng/developers/devbetasoftware/javasdk5.jsp