Menu

Reference

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

ACG: audiofocus.operation

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

requestTypeRequiredString

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:

  • AFREQUEST_TRANSIENT: alarm, system
  • AFREQUEST_GAIN: music, radio
  • AFREQUEST_RECORD: recording
  • AFREQUEST_MIX: tts, Notifications, SMS, Calendar
  • AFREQUEST_CALL: call (Only call application should use this request type)
subscribeRequiredBoolean

Indicates if subscribed to get the notifications. 

Possible values are:

  • true: Subscribed for notifications
  • false: Not subscribed

Note: It will get the suggestion from the audiofocusmanager service to pause/stop/resume the audio playback.

displayIdRequiredNumber

Indicates the display ID from which the application is requesting for focus.

streamTypeRequiredString

Indicates what is the stream played by application once it gets the focus

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications
  • false: Do not subscribe
errorCodeOptionalNumber

Indicates the error code for the failed operation.

resultOptionalString

Indicates the result.

Possible values are:

  • AF_GRANTED - AudioFocusManager has granted the audio resource for the application and it can use the resource.
  • AF_GRANTEDALREADY - This is sent when an application which has already acquired the audio resource calls the requestFocus method. This means, audio focus manager has already granted the audio resource and the application can use the resource.
  • AF_CANNOTBEGRANTED - This means, audio resource is used by the other application which is having higher priority than the newly requested application. When this event is received the application should not use the resource.
errorTextOptionalString

Indicates the reason for the failure of the operation. See the API Error Codes Reference section for details.

Subscription Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications
  • false: Do not subscribe
resultOptionalString

Indicates the result.

Possible values are:

  • AF_GRANTED: Audio Focus Manager  has granted the audio resource for the application and it can use the resource.
  • AF_GRANTEDALREADY: This is sent when an application which has already acquired the audio resource calls the requestFocus method. This means, audio focus manager has already granted the audio resource and the application can use the resource.
  • AF_CANNOTBEGRANTED: This means, audio resource is used by the other application which is having higher priority than the newly requested application. When this event is received the application should not use the resource.

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

ACG: audiofocus.operation

Description

Releases the audio resource.

Parameters

Name

Required

Type

Description

displayIdRequiredNumber

Indicates the display ID from which the application is releasing the focus.

streamTypeRequiredString

Indicates what is the stream played by application once it gets the focus.

Possible values are:

  • palerts
  • pfeedback
  • pringtones
  • pmedia
  • pdefaultapp
  • peffects
  • pvoicerecognition
  • ptts
  • default1
  • default2
  • tts1
  • tts2

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of the operation.

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
resultOptionalString

Indicates the result.

Possible values are:

  • AF_SUCCESSFULLY_RELEASED - This means the application has released the audio resource, unsubscribed with the audiofocusmanager service and will not receive any further events from audiofocusmanager.
errorCodeOptionalNumber

Indicates the error code for the failed operation.

errorTextOptionalString

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

ACG: audiofocus.query

Description

Queries the current status of the audiofocusmanager.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications.
  • false: Not subscribed.
displayIdRequiredNumber

Indicates the audio focus information of mentioned display ID.

Call Returns

Name

Required

Type

Description

returnValueOptionalBoolean

Indicates the status of the operation.

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications
  • false: Do not subscribe
errorCodeOptionalNumber

Indicates the error code for the failed operation.

errorTextOptionalString

Describes the error. Returned only in case of execution failure.

audioFocusStatusOptionalObject 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

returnValueRequiredBoolean

Indicates the status of the operation.

  • true: Indicates that the operation was successful.
  • false: Indicates that the operation failed. Check the "errorText" field for details.
subscribedOptionalBoolean

Indicates if subscribed to get the notifications.

Possible values are:

  • true: Subscribe for notifications
  • false: Do not subscribe
audioFocusStatusOptionalObject 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

displayIdRequiredString

Indicates the audio focus information of mentioned display ID

pausedRequestsRequiredObject: pausedRequests

Provides information of all paused requests.

activeRequestsRequiredObject: activeRequests

Provides information of all active requests.

pausedRequests

Provides information of all paused requests.

Name

Required

Type

Description

appIdOptionalString

Indicates the application ID which acquire the audio resource.

requestTypeOptionalString

Indicates the request type. Possible values are: 

  • AFREQUEST_TRANSIENT:, Alarm,  system
  • AFREQUEST_GAIN: Music, radio
  • AFREQUEST_RECORD: Recording
  • AFREQUEST_TRANSIENT_MAY_DUCK: tts, Notifications, SMS, Calendar
  • AFREQUEST_CALL: Call (Only call application should use this request type)

activeRequests

Provides information of all active requests.

Name

Required

Type

Description

appIdOptionalString

Indicates the application ID which acquired the audio resource.

requestTypeOptionalString

Indicates the request type. Possible values are; 

  • AFREQUEST_TRANSIENT: Alarm, system
  • AFREQUEST_GAIN: Music, radio
  • AFREQUEST_RECORD: Recording
  • AFREQUEST_TRANSIENT_MAY_DUCK: tts, Notifications, SMS, Calendar
  • AFREQUEST_CALL: Call (Only call application should use this request type)

API Error Codes Reference

Error Code

Error Text

Error Description

1Audio focus manager invalid schema

Error occurs due to invalid json request.

2Audio focus manager Unknown request type

Error occurs due to wrong request type.

3Audio focus manager internal error

Error occurs due to insufficient resource availability in audiofocusmanager.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents