com.webos.service.audiofocusmanager
API Summary
Provides an interface that allows the user to access and gain audio controls through a specific application to use audio resources.
Overview of the API
Audio Focus Manager is a middleware service in webOS. It does the following operations:
- Suggests applications to follow instructions to avoid conflicts among multiple applications using audio resources at the same time.
- Instructs applications, whether they can use the audio resources or not.
- Maintains the applications history if applicable, based on their request arrival.
- Grants the resources for the recent requested application based on its priority (if incoming application has higher priority than current using application it grants else it does not grant) and suggests other application(s) that is/are using audio resources to stop or pause.
Once the application has done with the resource, audio focus manager will grant the resources to the paused application if any.
Audio Focus Manager expects the following instructions to be followed by applications to use audio resources.
- Applications shall subscribe with Audio Focus Manager in order to get the instructions
- Applications shall request Audio Focus Manager for gaining the resource access
- Applications shall subscribe to callback functions to get to know whether they need to stop using the resources(pause/stop audio playback) or can re-gain the resources(resume audio playback)
Methods
requestFocus
Description
Requests audio focus to access the audio resource
On subscription, applications get the following suggestions:
- gain the resources (start audio playback)
- lost the resources permanently (stop audio playback)
- lost the resources temporarily (pause audio playback)
Parameters
Name | Required | Type | Description |
---|---|---|---|
requestType | Required | String | Indicates the priority of application and acts accordingly. Audio Focus Manager expects the applications to come with any one of the following request types based on applications behavior:
|
subscribe | Required | Boolean | Indicates if subscribed to get the notifications. Possible values are:
Note: It will get the suggestion from the audiofocusmanager service to pause/stop/resume the audio playback. |
displayId | Required | Number | Indicates the display ID from which the application is requesting for focus. |
streamType | Required | String | Indicates what is the stream played by application once it gets the focus |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation.
|
subscribed | Optional | Boolean | Indicates if subscribed to get the notifications. Possible values are:
|
errorCode | Optional | Number | Indicates the error code for the failed operation. |
result | Optional | String | Indicates the result. Possible values are:
|
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference section for details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation.
|
subscribed | Optional | Boolean | Indicates if subscribed to get the notifications. Possible values are:
|
result | Optional | String | Indicates the result. Possible values are:
|
Example
Example : Requesting audio focus
# luna-send -a "com.webos.app.ml4" -i luna://com.webos.service.audiofocusmanager/requestFocus '{
"requestType":"AFREQUEST_GAIN",
"subscribe":true,
"streamType":"pmedia",
"displayId":0
}'
Response:
{
"subscribed":true,
"returnValue":true,
"result":"AF_GRANTED"
}
releaseFocus
Description
Releases the audio resource.
Parameters
Name | Required | Type | Description |
---|---|---|---|
displayId | Required | Number | Indicates the display ID from which the application is releasing the focus. |
streamType | Required | String | Indicates what is the stream played by application once it gets the focus. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation.
|
result | Optional | String | Indicates the result. Possible values are:
|
errorCode | Optional | Number | Indicates the error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference section for details. |
Example
Example : Releasing audio focus
# luna-send -a "com.webos.app.notification" -n 1 -f luna://com.webos.service.audiofocusmanager/releaseFocus '{
"displayId":0,
"streamType":"pmedia"
}'
Response:
{
"returnValue":true,
"result":"AF_SUCCESSFULLY_RELEASED"
}
getStatus
Description
Queries the current status of the audiofocusmanager.
Parameters
Name | Required | Type | Description |
---|---|---|---|
subscribe | Optional | Boolean | Indicates if subscribed to get the notifications. Possible values are:
|
displayId | Required | Number | Indicates the audio focus information of mentioned display ID. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Optional | Boolean | Indicates the status of the operation.
|
subscribed | Optional | Boolean | Indicates if subscribed to get the notifications. Possible values are:
|
errorCode | Optional | Number | Indicates the error code for the failed operation. |
errorText | Optional | String | Describes the error. Returned only in case of execution failure. |
audioFocusStatus | Optional | Object array: audioFocusStatus | Contains the information of all granted request types per session in their request types (paused and active). |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of the operation.
|
subscribed | Optional | Boolean | Indicates if subscribed to get the notifications. Possible values are:
|
audioFocusStatus | Optional | Object array: audioFocusStatus | Contains information of all granted request types per session in their request types (paused and active). |
Example
Example : Gets status when there are NO active requests
# luna-send -i luna://com.webos.service.audiofocusmanager/getStatus '{"displayId":0, "subscribe":true}'
Response:
{
"subscribed":true,
"returnValue":true,
"audioFocusStatus":[
{
"pausedRequests":[
],
"displayId":0,
"activeRequests":[
]
}
]
}
Example : Gets status when there are active requests
# luna-send -n 1 luna://com.webos.service.audiofocusmanager/getStatus '{"subscribe":true, "displayId":0}'
Response:
{
"subscribed":true,
"returnValue":true,
"audioFocusStatus":[
{
"pausedRequests":[
],
"displayId":0,
"activeRequests":[
{
"appId":"com.webos.app.ml4",
"requestType":"AFREQUEST_GAIN",
"streamType":"pmedia"
}
]
}
]
}
Objects
audioFocusStatus
Provides information of all granted request types per session in their request types (paused and active).
Name | Required | Type | Description |
---|---|---|---|
displayId | Required | String | Indicates the audio focus information of mentioned display ID |
pausedRequests | Required | Object: pausedRequests | Provides information of all paused requests. |
activeRequests | Required | Object: activeRequests | Provides information of all active requests. |
pausedRequests
Provides information of all paused requests.
Name | Required | Type | Description |
---|---|---|---|
appId | Optional | String | Indicates the application ID which acquire the audio resource. |
requestType | Optional | String | Indicates the request type. Possible values are:
|
activeRequests
Provides information of all active requests.
Name | Required | Type | Description |
---|---|---|---|
appId | Optional | String | Indicates the application ID which acquired the audio resource. |
requestType | Optional | String | Indicates the request type. Possible values are;
|
API Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1 | Audio focus manager invalid schema | Error occurs due to invalid json request. |
2 | Audio focus manager Unknown request type | Error occurs due to wrong request type. |
3 | Audio focus manager internal error | Error occurs due to insufficient resource availability in audiofocusmanager. |