com.webos.service.mediacontroller
API Summary
Provides features to handle the AVRCP events regardless of application type (web app/native app) in order to remotely control the playback and handles key events such as play, pause, next, previous, mute and unmute.
Overview of the API
Provides methods to manage media sessions and get metadata/playback status of the media and routes the AVRCP events received from the remote device to corresponding media client.
Methods
registerMediaSession
Description
Registers media sessions, subscribes to receive AVRCP key events.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to be registered. |
appId | Required | String | Indicates the appId of the session to be registered. |
subscribe | Required | Boolean | Indicates if subscribe to get notifications. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
subscribed | Required | Boolean | Indicates if subscribed to get notifications. Possible values are:
Note: subscribed will always contain true since subscription ends only when the client chooses to close it. |
keyEvent | Optional | String | Indicates the key event that is operated. Possible values are:
|
mediaId | Optional | String | Indicates the mediaId of the registered session. |
errorCode | Optional | Boolean | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
subscribed | Required | Boolean | Indicates if subscribed to get notifications. Possible values are:
Note: subscribed will always contain true since subscription ends only when the client chooses to close it. |
keyEvent | Required | String | Indicates the key event that is operated. Possible values are:
|
mediaId | Required | String | Indicates the mediaId for which the key events are posted. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See API Error Codes Reference | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/registerMediaSession '{
"mediaId":"xDFNUI",
"appId":"com.webos.app.test.youtube",
"subscribe":true
}'
Response:
{
"subscribed":true,
"returnValue":true
}
activateMediaSession
Description
Activates the media session.
Recommended usage: The API is recommended to be used by the application.
Note:
- Only an active media session can receive the AVRCP key events and forward them to the application.
- To activate a media session, the client must subscribe to the mediaId using registerMediaSession() API.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to be activated. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/activateMediaSession '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true
}
deactivateMediaSession
Description
Deactivates the media session.
Recommended usage: The API is recommended to be used by the application.
Note: After the media session is deactivated, the corresponding media client cannot receive AVRCP key events.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to be deactivated. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | String | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/deactivateMediaSession '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true
}
unregisterMediaSession
Description
Unsubscribes and unregisters the media session.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to be unregistered. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/unregisterMediaSession '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true
}
getMediaMetaData
Description
Requests metadata of the media session related to the given mediaId.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId for meta data information. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
metaData | Optional | Object: mediaMetaData | Indicates details of the object mediaMetaData. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/getMediaMetaData '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true,
"metaData":{
"title":"Big Bang Theory",
"artist":"BIGBANG",
"totalDuration":"20.15",
"album":"BBT",
"genre":"drama",
"trackNumber":2
}
}
getMediaPlayStatus
Description
Gets the current playback status of the given mediaId, status such as stopped, paused, playing, buffering.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session registered. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
playStatus | Optional | String | Indicates the current play status of the media. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/getMediaPlayStatus '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true,
"playStatus":"PLAYSTATE_PLAYING"
}
getMediaSessionInfo
Description
Gets the details of a media session like app id, metadata, volume info.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId for the session registered. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
sessionInfo | Optional | Object: mediaSession | Indicates media session information details. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/getMediaSessionInfo '{
"mediaId":"xDFNUI"
}'
Response:
{
"returnValue":true,
"sessionInfo":{
"mediaId":"xDFNUI",
"appId":"com.webos.test.youtube",
"metaData":{
"title":"Big Bang Theory",
"artist":"BIGBANG",
"totalDuration":"20.15",
"album":"BBT",
"genre":"drama",
"trackNumber":2
},
"volume":100
}
}
getMediaSessionId
Description
Provides the list of mediaId of all the media sessions for a given app.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
appId | Required | String | Indicates the appId for the given media session. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
mediaId | Optional | String array | Indicates the list of all mediaId for the appId received. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/getMediaSessionId '{
"appId":"com.webos.test,youtube"
}'
Response:
{
"returnValue":true,
"mediaId":[
"XCFRHKH",
"NBFSIEOL"
]
}
getActiveMediaSessions
Description
Gets the list of all the active media sessions.
Recommended usage: The API is recommended to be used by the service.
Parameters
None
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
sessionList | Optional | String array | Indicates the list of all active sessions registered with service. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the "API Error Codes Reference" section. | See the API Error Codes Reference section. |
Example
Example code
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/getActiveMediaSessions '{}'
Response:
{
"returnValue":true,
"sessionList":[
"XCFRHKH",
"NBFSIEOL"
]
}
setMediaMetaData
Description
Sets the metadata information for the session.
Example: title, artist.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to set metadata. |
mediaMetaData | Required | Object: mediaMetaData | Indicates the meta data details for the session. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the API Error Codes Reference section | See the API Error Codes Reference section |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/setMediaMetaData '{
"mediaId":"xDFNUI",
"mediaMetaData":{
"title":"BigBangTheory",
"artist":"BigBang",
"totalDuration":"10.10",
"album":"BBT",
"genre":"drama",
"trackNumber":2,
"volume":100
}
}'
Response:
{
"returnValue":true
}
setMediaPlayStatus
Description
Sets the playStatus for the session.
Example: play, pause, stopped and so on.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session to set playStatus. |
playStatus | Required | String | Indicates the current playStatus of the media. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4 | See the API Error Codes Reference section. | See the API Error Codes Reference section |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/setMediaPlayStatus '{
"mediaId":"xQWERTY_0",
"playStatus":"PLAYSTATE_PLAYING"
}'
Response:
{
"returnValue":true
}
setMediaMuteStatus
Description
Sets the status of the media session.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session required to set the muteStatus. |
muteStatus | Required | String | Indicates the status of the media session. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4, 7 | See the API Error Codes Reference section | See the API Error Codes Reference section. |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/setMediaMuteStatus '{
"mediaId":"xDFNUI",
"muteStatus":"mute"
}'
Response:
{
"returnValue":true
}
setMediaPlayPosition
Description
Sets the play position for the media session.
Recommended usage: The API is recommended to be used by the application.
Parameters
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId of the session. |
playPosition | Required | String | Indicates the current play position of the media session. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4, 7 | See the API Error Codes Reference sectio | See the API Error Codes Reference section |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/setMediaPlayPosition '{
"mediaId":"xDFNUI",
"playPosition":"10.10"
}'
Response:
{
"returnValue":true
}
injectMediaKeyEvent
Description
Sets the keyEvent of the given displayId.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
displayId | Required | Number | Indicates the displayId for which the key event is sent Possible values are:
|
keyEvent | Required | String | Indicates the keyEvent for the display. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4, 7 | See the API Error Codes Reference section. | See the API Error Codes Reference section |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/injectMediaKeyEvent '{
"displayId":1,
"keyEvent":"play"
}'
Response:
{
"returnValue":true
}
receiveMediaPlaybackInfo
Description
Subscribes to receive the play status, mute status, play position, mediaMetaData information.
Recommended usage: The API is recommended to be used by the service.
Parameters
Name | Required | Type | Description |
---|---|---|---|
displayId | Required | Number | Indicates the displayId for which the media play status is required. Possible values are:
|
eventType | Optional | String | Indicates the status for the required subscription response. Possible values are :
Note: If not set, eventType will send all the possible values as the response. |
subscribe | Required | Boolean | Indicates if subscribed to get notifications. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
subscribed | Optional | Boolean | Indicates if subscribed to get notifications. Possible values are:
|
displayId | Optional | Number | Indicates the displayId for the required media play status. Possible values are:
|
eventType | Optional | String | Indicates the status for the required subscription response. Possible values are :
Note: If not set, eventType will send all the possible values as the response. |
playStatus | Optional | String | Indicates the current play status of the media. Possible values are:
Note: The information will be sent if the eventType is playStatus. |
muteStatus | Optional | String | Indicates the current status of the media. Possible values are:
Note: The information will be sent if the eventType is muteStatus. |
playPosition | Optional | String | Indicates the current play position of the media. Note: The information will be sent if the eventType is playPosition. |
mediaMetaData | Optional | Object: mediaMetaData | Indicates the metadata information for the playback. Note: The information will be sent if the eventType is mediaMetaData. |
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation. Possible values are:
|
subscribed | Optional | Boolean | Indicates if subscribed to get notifications. Possible values are:
|
displayId | Optional | Number | Indicates the displayId for the required media play status. Possible values are:
|
eventType | Optional | String | Indicates the status for the required subscription response. Possible values are :
Note: If not set, eventType will send all the possible values as the response. |
playStatus | Optional | String | Indicates the current play status of the media. Possible values are:
Note: The information will be sent if eventType is playStatus. |
muteStatus | Optional | String | Indicates the current status of the media. Possible values are:
Note: The information will be sent if the eventType is muteStatus |
playPosition | Optional | String | Indicates the current play position of the media playback. Note: The information will be sent if the eventType is playPosition. |
mediaMetaData | Optional | Object: mediaMetaData | Indicates the metadata information for the playback. Note: The information will be sent if the eventType is mediaMetaData. |
errorCode | Optional | Number | The error code for the failed operation |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the "Error Codes" section of this method for details. |
Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0, 1, 2, 3, 4, 6, 7 | See the API Error Codes Reference section | See the API Error Codes Reference section |
Example
Example scenario
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/receiveMediaPlaybackInfo '{
"displayId":0,
"subscribe":true
}'
Response:
{
"returnValue":true,
"displayId":0,
"playStatus":"PLAYSTATE_PLAYING",
"muteStatus":"unmute",
"playPosition":"10.10",
"metaData":{
"title":"Big Bang Theory",
"artist":"BIGBANG",
"totalDuration":"20.15",
"album":"BBT",
"genre":"drama",
"trackNumber":2
}
}
With eventType as playStatus
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/receiveMediaPlaybackInfo '{
"displayId":0,
"eventType":"playStatus",
"subscribe":true
}'
Response:
{
"returnValue":true,
"displayId":0,
"eventType":"playStatus",
"playStatus":"PLAYSTATE_PLAYING"
}
With eventType as muteStatus
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/receiveMediaPlaybackInfo '{
"displayId":0,
"eventType":"muteStatus",
"subscribe":true
}'
Response:
{
"returnValue":true,
"displayId":0,
"eventType":"muteStatus",
"muteStatus":"unmute"
}
With eventType as playPosition
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/receiveMediaPlaybackInfo '{
"displayId":0,
"eventType":"playPosition",
"subscribe":true
}'
Response:
{
"returnValue":true,
"displayId":0,
"eventType":"playPosition",
"playPosition":"10.10"
}
With eventType as metaData
# luna-send -n 1 -f luna://com.webos.service.mediacontroller/receiveMediaPlaybackInfo '{
"displayId":0,
"eventType":"mediaMetaData",
"subscribe":true
}'
Response:
{
"returnValue":true,
"displayId":0,
"eventType":"mediaMetaData",
"metaData":{
"title":"Big Bang Theory",
"artist":"BIGBANG",
"totalDuration":"20.15",
"album":"BBT",
"genre":"drama",
"trackNumber":2
}
}
Objects
mediaSession
Contains the details about mediaId, appId, and metaData.
Name | Required | Type | Description |
---|---|---|---|
mediaId | Required | String | Indicates the mediaId to be registered. |
appId | Required | String | Indicates the corresponding appId of the mediaId. |
metaData | Required | Object: mediaMetaData | Indicates the details of metaData such as title, artist, total duration, album, genre, and track number. |
mediaMetaData
Contains the mediaMetaData information.
Name | Required | Type | Description |
---|---|---|---|
title | Optional | String | Indicates the title of the media. |
artist | Optional | String | Indicates information about the artist. |
totalDuration | Optional | String | Indicates the total duration of the media. |
album | Optional | String | Indicates details about the album. |
genre | Optional | String | Indicates details about the genre. |
trackNumber | Optional | Number | Indicates the track number. |
volume | Optional | Number | Indicates the current volume level of the session. |
API Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
0 | Invalid mediaId | Indicates that the mediaId received is invalid. |
1 | MediaId registration failed | Indicates the failure of mediaId registration. |
2 | Parsing Error | Indicates parsing of data has failed. |
3 | Invalid appId | Indicates that the appId does not match the mediaId. |
4 | No active session | Indicates that no session is active. |
5 | Media Session already registered | Indicates that session is already registered |
6 | Media Session already active | Indicates that session is already activated |
7 | Media Session already decativated | Indicates that session is already deactivated |