Beginner developers, beware! This guide isn't beginner-friendly at all and it's targeted at developers who have some knowledge about Android development.
Or you can use my new library - Remote Metadata Provider, it's MUCH simplier to use.
0. The Introduction
You guys probably seen my apps - Floating Music Widget and Android Control Center.
They both share one feature - good music player integration. They can show you metadata and Floating Music Widget even shows album art. While some players provide API for external music controls(like PowerAmp), the others just somehow integrate with lockscreen. How? Sit down, get a cup of tea, and listen to me.
With the API Level 14 Google introduced class called RemoteControlClient. Citing Google API Reference:
I won't explain how this works - you may go and read some tutorials around the web, there are plenty of them.
Or check API Reference here.
But. Well, we send metadata and album art. Oh, and on 4.3 we can even send playback position. However...how do we receive it? Well, by some reason, I don't know exactly why, Google has hidden this part of API. Maybe they think it's unsere to let you consume other app data, or maybe they just forgot about it. I've asked them multiple times, why did they hid this part of API, but they just ignored me.
So, by posting this article, I hope to maybe somehow make them change their minds and publish this API after all.
1. Getting started
Please note that this guide won't give you Activity examples, or any other things. It will give you the bare bones of the implementation of your own media controls. It's NOT intended to be used by Android/Java newbies.
PLEASE NOTE THAT IT'S A CLOSED API! IT MAY MALFUNCTION OR NOT WORK AT ALL!
Of course, you will need Eclipse IDE.
Also you will need modified Android build platform with hidden and internal API enabled.
There's an excellent guide on how to do this:
Using internal (com.android.internal) and hidden (@hide) APIs
Read it, do all five steps, then come back here for a read.
Please note that you will need to enable hidden APIs for API Level 18(4.3) and one API from 14 to 17. I recommend doing 17.
So, you've enabled hidden and internal API, hacked your ADT plugin, and you're craving for knowledge? Good.
Now some theory.
When the metadata is sent by RemoteControlClient, it is consumed by object called RemoteControlDisplay.
But the problem is, there's no explicit RemoteControlDisplay class, but there is only AIDL interface called IRemoteControlDisplay.
2. Understanding IRemoteControlDisplay
So, let's check which methods this interface has.
void setCurrentClientId(int clientGeneration, in PendingIntent clientMediaIntent, boolean clearing);
This method is used to connect music player to your RemoteControlDisplay.
First parameter is an internal ID of current player.
Second parameter is PendingIntent which will be used for controlling the playback - this is the "address" where you will send commands like "stop playback", "switch to next", etc.
About third parameter...my guess is that it's used when the RemoteControlDisplay is disconnected from current music player. You don't really ned this one.
For next methods I will explain only useful parameters.
void setPlaybackState(int generationId, int state, long stateChangeTimeMs);
This method is called when playback state has changed. For example, it's called when you pause your music.
"state" is obviously the current state of your music player.
It can be one of the following values:
Rarely used:
RemoteControlClient.PLAYSTATE_ERROR - well, there was some kind of error. Normally, you won't get this one.
RemoteControlClient.PLAYSTATE_BUFFERING - the music is buffering and will start playing very-very soon.
Normally used:
RemoteControlClient.PLAYSTATE_PAUSED - the music is paused
RemoteControlClient.PLAYSTATE_PLAYING - the music is playing.
You can check other PLAYSTATE_ constant in RemoteControlClient API reference.
void setTransportControlFlags(int generationId, int transportControlFlags);
In lockscreen it is used for toggling the widget visibility. I couldn't find any appliance for this method in my apps. Well, it sets flags
void setMetadata(int generationId, in Bundle metadata);
Well, that's obvious. It is called when RemoteControlDisplay have to update current track metadata.
The Bundle which we are receiving containing some metadata.
The keys for them are all in class MediaMetadataRetriever.
So, for example, to extract song title, you have to do it this way:
From my research I've found that this Bundle can have the following entries:
Those are for "String" entries:
MediaMetadataRetriever.METADATA_KEY_ALBUMARTIST
MediaMetadataRetriever.METADATA_KEY_ARTIST
MediaMetadataRetriever.METADATA_KEY_ALBUM
MediaMetadataRetriever.METADATA_KEY_TITLE
And this one is "long":
MediaMetadataRetriever.METADATA_KEY_DURATION
void setArtwork(int generationId, in Bitmap artwork);
This one is way too obvious. It gives you the Bitmap with artwork of current song. If there is no artwork, the "artwork" parameter will be null.
void setAllMetadata(int generationId, in Bundle metadata, in Bitmap artwork);
This call just combines previous two.
3. Implementing IRemoteControlDisplay
Hey, I now know everything about RemoteControlDisplay, I will implement my own in split second.
Please note that IT WON'T WORK THIS WAY!
As IRemoteControlDisplay is actually a AIDL interface, we need to somehow handle marshalling and unmarshalling of data. But luckily, we don't need to think about it. There is a class which handles basic IPC operations - IRemoteControlDisplay$Stub. We just need to extend it.
So, the right way to implement your own RemoteControlDisplayClass is:
Then you will have to implement methods of IRemoteControlDisplay. However, now listen to me carefully. Please, don't try to write your own super-cool implementation.
Just copy and paste the following code
Why we have to implement it this way?
Well, it's because those methods calls arrive asynchronously, so, to correctly process them all, we need a Handler. Then we send messages to this Handler with necessary parameters, and it processes them.
But why use this weird WeakReference? Well, I can't explain it better than Google Developers. Citing the source code comment:
So, my congratulations! We've implemented hidden IRemoteControlDisplay interface. But now it doesn't actually do anything.
4. Using our RCD implementation
As you can see, the constructor requires a Handler to be passed to it.
But any Handler just won't do, as we have to process messages.
So, you can't just write
Then, let's implement our Handler.
Again, I recommend you to use the following code, as it's doing it's job fine. This is the code used by default lockscreen with slight modifications. You can try and implement your own Handler, but this is strongly discouraged, as it can get glitchy. Don't worry, we'll soon get to the part where you can use your imagination
I think you can probably guess what do we do here, but I'll explain anyway.
updatePlayPauseState(msg.arg2) - it's the method where you actually handle the change of playstate.
msg.arg2 is an Integer(or, more correcly, int), which indicates current play state. Please refer to section 2 to see possible play states. For example, you may do check like this:
setArtwork(mArtwork);
It's pretty obvious, do whatever you like with this bitmap, just remember that it can be null.
updateMetadata((Bundle) msg.obj)
That one isn't very easy to handle. There is a bundle containing all of available metadata. So, you can deal with it as you please(you know how to extract data from Bundle, right?), but here's how I do it(modified Google version):
You've got the idea.
Okay. So you've implemented your Handler, and created MyRemoteControlDisplayObject. What's next?
5. Registering and unregistering RemoteControlDisplay
In order for your RemoteControlDisplay to be able to receive metadata and album arts, it has to be registered via AudioManager.
You have to get the instance of AudioManager and then call Audiomanager#registerRemoteControlDisplay().
So, that's it. You've succesfully registered your display. Now it will receive metadata and album art.
However, that's not all.
When the metadata isn't visible to user, you should unregister your RemoteControlDisplay by using this code:
This way you will unregister your RemoteControlDisplay, destroy it(or, actually, just give it garbage collector), and remove all unprocessed messages. This is the correct way to unregister your RemoteControlDisplay.
Please note! You must register your RemoteControlDisplay every time when the View which displays metadata is shown to the user. This is because 4.2.2 and lower versions support only one RemoteControlDisplay, and if system will decide to register it's own RCD, your RCD will be unregistered automatically.
When you're compiling, you have to compile with 4.2.2 modified library for 4.2.2 and lower, and compile with 4.3 modified library for 4.3. That is very important, because if you'll try to launch 4.2.2 implementation on device running 4.3, it will give you AbstractMethodError.
If you have any question regarding the implementation, please ask here. Don't ask "How do I start Eclipse", or anything like that.
And please, if you use this, at least give me a credit. Finding this out was a really hard job.
To understand how it works, I've used source code from Android GitHub repository:
KeyguardTransportControlView.java
Or donate to me, whatever you like more. However, it would be the best if you give me credit and donate to me
Or you can use my new library - Remote Metadata Provider, it's MUCH simplier to use.
0. The Introduction
You guys probably seen my apps - Floating Music Widget and Android Control Center.
They both share one feature - good music player integration. They can show you metadata and Floating Music Widget even shows album art. While some players provide API for external music controls(like PowerAmp), the others just somehow integrate with lockscreen. How? Sit down, get a cup of tea, and listen to me.
With the API Level 14 Google introduced class called RemoteControlClient. Citing Google API Reference:
I won't explain how this works - you may go and read some tutorials around the web, there are plenty of them.
Or check API Reference here.
But. Well, we send metadata and album art. Oh, and on 4.3 we can even send playback position. However...how do we receive it? Well, by some reason, I don't know exactly why, Google has hidden this part of API. Maybe they think it's unsere to let you consume other app data, or maybe they just forgot about it. I've asked them multiple times, why did they hid this part of API, but they just ignored me.
So, by posting this article, I hope to maybe somehow make them change their minds and publish this API after all.
1. Getting started
Please note that this guide won't give you Activity examples, or any other things. It will give you the bare bones of the implementation of your own media controls. It's NOT intended to be used by Android/Java newbies.
PLEASE NOTE THAT IT'S A CLOSED API! IT MAY MALFUNCTION OR NOT WORK AT ALL!
Of course, you will need Eclipse IDE.
Also you will need modified Android build platform with hidden and internal API enabled.
There's an excellent guide on how to do this:
Using internal (com.android.internal) and hidden (@hide) APIs
Read it, do all five steps, then come back here for a read.
Please note that you will need to enable hidden APIs for API Level 18(4.3) and one API from 14 to 17. I recommend doing 17.
So, you've enabled hidden and internal API, hacked your ADT plugin, and you're craving for knowledge? Good.
Now some theory.
When the metadata is sent by RemoteControlClient, it is consumed by object called RemoteControlDisplay.
But the problem is, there's no explicit RemoteControlDisplay class, but there is only AIDL interface called IRemoteControlDisplay.
2. Understanding IRemoteControlDisplay
So, let's check which methods this interface has.
void setCurrentClientId(int clientGeneration, in PendingIntent clientMediaIntent, boolean clearing);
This method is used to connect music player to your RemoteControlDisplay.
First parameter is an internal ID of current player.
Second parameter is PendingIntent which will be used for controlling the playback - this is the "address" where you will send commands like "stop playback", "switch to next", etc.
About third parameter...my guess is that it's used when the RemoteControlDisplay is disconnected from current music player. You don't really ned this one.
For next methods I will explain only useful parameters.
void setPlaybackState(int generationId, int state, long stateChangeTimeMs);
This method is called when playback state has changed. For example, it's called when you pause your music.
"state" is obviously the current state of your music player.
It can be one of the following values:
Rarely used:
RemoteControlClient.PLAYSTATE_ERROR - well, there was some kind of error. Normally, you won't get this one.
RemoteControlClient.PLAYSTATE_BUFFERING - the music is buffering and will start playing very-very soon.
Normally used:
RemoteControlClient.PLAYSTATE_PAUSED - the music is paused
RemoteControlClient.PLAYSTATE_PLAYING - the music is playing.
You can check other PLAYSTATE_ constant in RemoteControlClient API reference.
void setTransportControlFlags(int generationId, int transportControlFlags);
In lockscreen it is used for toggling the widget visibility. I couldn't find any appliance for this method in my apps. Well, it sets flags
void setMetadata(int generationId, in Bundle metadata);
Well, that's obvious. It is called when RemoteControlDisplay have to update current track metadata.
The Bundle which we are receiving containing some metadata.
The keys for them are all in class MediaMetadataRetriever.
So, for example, to extract song title, you have to do it this way:
Code:
String title=metadata.getString(Integer.toString(MediaMetadataRetriever.METADATA_KEY_TITLE));Those are for "String" entries:
MediaMetadataRetriever.METADATA_KEY_ALBUMARTIST
MediaMetadataRetriever.METADATA_KEY_ARTIST
MediaMetadataRetriever.METADATA_KEY_ALBUM
MediaMetadataRetriever.METADATA_KEY_TITLE
And this one is "long":
MediaMetadataRetriever.METADATA_KEY_DURATION
void setArtwork(int generationId, in Bitmap artwork);
This one is way too obvious. It gives you the Bitmap with artwork of current song. If there is no artwork, the "artwork" parameter will be null.
void setAllMetadata(int generationId, in Bundle metadata, in Bitmap artwork);
This call just combines previous two.
3. Implementing IRemoteControlDisplay
Hey, I now know everything about RemoteControlDisplay, I will implement my own in split second.
Code:
public class MyRemoteControlDisplay implements IRemoteControlDisplayAs IRemoteControlDisplay is actually a AIDL interface, we need to somehow handle marshalling and unmarshalling of data. But luckily, we don't need to think about it. There is a class which handles basic IPC operations - IRemoteControlDisplay$Stub. We just need to extend it.
So, the right way to implement your own RemoteControlDisplayClass is:
Code:
public class MyRemoteControlDisplay extends IRemoteControlDisplay.StubThen you will have to implement methods of IRemoteControlDisplay. However, now listen to me carefully. Please, don't try to write your own super-cool implementation.
Just copy and paste the following code
Why we have to implement it this way?
Well, it's because those methods calls arrive asynchronously, so, to correctly process them all, we need a Handler. Then we send messages to this Handler with necessary parameters, and it processes them.
But why use this weird WeakReference? Well, I can't explain it better than Google Developers. Citing the source code comment:
Tl;dr it's just a clever usage of memory resources.
So, my congratulations! We've implemented hidden IRemoteControlDisplay interface. But now it doesn't actually do anything.
4. Using our RCD implementation
As you can see, the constructor requires a Handler to be passed to it.
But any Handler just won't do, as we have to process messages.
So, you can't just write
Code:
MyRemoteControlDisplay display=new MyRemoteControlDisplay(new Handler());Then, let's implement our Handler.
Again, I recommend you to use the following code, as it's doing it's job fine. This is the code used by default lockscreen with slight modifications. You can try and implement your own Handler, but this is strongly discouraged, as it can get glitchy. Don't worry, we'll soon get to the part where you can use your imagination
I think you can probably guess what do we do here, but I'll explain anyway.
updatePlayPauseState(msg.arg2) - it's the method where you actually handle the change of playstate.
msg.arg2 is an Integer(or, more correcly, int), which indicates current play state. Please refer to section 2 to see possible play states. For example, you may do check like this:
Code:
updatePlayState(int state) {
if(state==RemoteControlClient.PLAYSTATE_PLAYING) {
setButtonImage(R.drawable.play);
} else {
setButtonImage(R.drawable.pause);
}
}setArtwork(mArtwork);
It's pretty obvious, do whatever you like with this bitmap, just remember that it can be null.
updateMetadata((Bundle) msg.obj)
That one isn't very easy to handle. There is a bundle containing all of available metadata. So, you can deal with it as you please(you know how to extract data from Bundle, right?), but here's how I do it(modified Google version):
You've got the idea.
Okay. So you've implemented your Handler, and created MyRemoteControlDisplayObject. What's next?
5. Registering and unregistering RemoteControlDisplay
In order for your RemoteControlDisplay to be able to receive metadata and album arts, it has to be registered via AudioManager.
You have to get the instance of AudioManager and then call Audiomanager#registerRemoteControlDisplay().
Code:
MyHandler myHandler=new MyHandler();
MyRemoteControlDisplay remoteDisplay=new MyRemoteControlDisplay(myHandler);
AudioManager manager=((AudioManager)mContext.getSystemService("audio"));
mAudioManager.registerRemoteControlDisplay(remoteDisplay);So, that's it. You've succesfully registered your display. Now it will receive metadata and album art.
However, that's not all.
When the metadata isn't visible to user, you should unregister your RemoteControlDisplay by using this code:
Code:
audioManager.unregisterRemoteControlDisplay(remoteDisplay);
remoteDisplay=null;
mHandler.removeMessages(MSG_SET_GENERATION_ID);
mHandler.removeMessages(MSG_SET_METADATA);
mHandler.removeMessages(MSG_SET_TRANSPORT_CONTROLS);
mHandler.removeMessages(MSG_UPDATE_STATE);This way you will unregister your RemoteControlDisplay, destroy it(or, actually, just give it garbage collector), and remove all unprocessed messages. This is the correct way to unregister your RemoteControlDisplay.
Please note! You must register your RemoteControlDisplay every time when the View which displays metadata is shown to the user. This is because 4.2.2 and lower versions support only one RemoteControlDisplay, and if system will decide to register it's own RCD, your RCD will be unregistered automatically.
When you're compiling, you have to compile with 4.2.2 modified library for 4.2.2 and lower, and compile with 4.3 modified library for 4.3. That is very important, because if you'll try to launch 4.2.2 implementation on device running 4.3, it will give you AbstractMethodError.
If you have any question regarding the implementation, please ask here. Don't ask "How do I start Eclipse", or anything like that.
And please, if you use this, at least give me a credit. Finding this out was a really hard job.
To understand how it works, I've used source code from Android GitHub repository:
KeyguardTransportControlView.java
Or donate to me, whatever you like more. However, it would be the best if you give me credit and donate to me
Last edited:
