com.webos.service.audio

API Summary

Provides methods to control the volume.

Overview of the API

(click to expand)

The Audio Setting service enables applications to control volume with following methods.

  • Volume up
  • Volume down
  • Mute volume

Open All


media/broadcastEvent

Description

Announce an event to audiod.

Parameters

Name

Required

Type

Description

eventRequiredString

The event to be passed to audiod by the application. It can be simple string agreed between audiod and application.

For example, if audiod requires an event when call is received by caller (i.e., application), it will ask the caller to send an event using this method and the event will be "callreceived".

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2Missing event string parameter.

Mandatory parameter event is missing from input arguments.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/broadcastEvent '{"event":"test"}'


media/disableScenario

Description

Disable the specified scenario.

Note: This method is added for future-use. Do not use it to disable any of the scenarios.

Parameters

Name

Required

Type

Description

scenario Required string

Scenario to be disabled.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for 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 Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2 Missing ‘scenario’ string parameter.

Mandatory parameter Scenario is missing from input arguments.

3 Could not disable requested scenario.

Request Scenario is valid. But could not be disabled.

3 "Invalid 'scenario' string parameter value or file not found.

Request scenario for disabling is not valid scenario.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/disableScenario '{"scenario":"media_test"}'


media/enableScenario

Description

Enable the specified scenario.

Parameters

Name

Required

Type

Description

scenarioRequiredstring

Scenario to be enabled.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2Missing ‘scenario’ string parameter.

Mandatory parameter Scenario is missing from input arguments.

3Invalid 'scenario' string parameter value

Request Scenario for enabling is not a valid scenario.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/enableScenario '{"scenario":"media__default"}'


media/getCurrentScenario

Description

Get a current scenario.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation.

scenarioOptionalString

Scenario currently selected.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/getCurrentScenario '{}'

Returns:
{
    "scenario": "media__default",
    "returnValue": true
}


media/getMicGain

Description

Get mic gain of the current or specified scenario.

Parameters

Name

Required

Type

Description

scenarioOptionalString

Scenario to get the mic gain for. If not specified, currently selected scenatio will be used.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

mic_gainOptionalNumber

Mic gain [0 -100] of current or specified scenario.

scenarioOptionalString

Either the scenario specified in the input of this method or the currently selected scenario.

Error References

Error Code

Error Text

Error Description

3failed to get parameter (invalid scenario name?)"

Failed to get the Mic Gain. Check for Scenario Name.

Example

luna-send -n 1 luna://com.webos.service.audio/media/getMicGain '{}'

Returns:

{

"returnValue":true,

"scenario":"media__default",

"mic_gain":-1

}


media/getVolume

Description

Get the volume level of the current or specified scenario.

Parameters

Name

Required

Type

Description

scenarioOptionalstring

Scenario for which to get the volume level. If not specified, the volume is retrieved from currently selected scenario.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

scenarioOptionalString

Scenario from which volume level is obtained.

volumeOptionalNumber

Current volume [0, 100].

Example

luna-send -n 1 luna://com.webos.service.audio/media/getVolume '{}'

Returns:

{

    "returnValue":true,

    "scenario":"media_default",

    "volume":8,

}


media/listScenarios

Description

Get a list of available (enabled/disabled) scenarios.

Parameters

Name

Required

Type

Description

enabledOptionalBoolean
  • To list enabled scenarios, set enabled to true.
  • To hide enabled scenarios, set enabled to false.
  • The default value of enabled is true.
disabledOptionalBoolean
  • To list disabled scenarios, set disabled to true.
  • To hide disabled scenarios, set disabled to false.
  • The default value of disabled is false.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

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

Indicates the reason for the failure of the operation.

scenariosOptionalString array

An array of scenarios.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/listScenarios '{"enabled":true,"disabled":true}'

Returns:
{
    "returnValue": true,
    "scenarios": [
        "media__default"        
    ]
}


media/offsetMicGain

Description

Offset mic gain of the current or specified scenario, by an absolute value or by a number of ticks.

Parameters

Name

Required

Type

Description

offsetRequiredNumber

If unit is percent, set offset in the range [-100, 100].

If unit is step or not specified, set offset in the range [-20, 20]. 

scenarioOptionalString

Scenario to apply the offset. If not specified, the offset is applied to the currently selected scenario.

unitOptionalString

This is used to interpret the offset argument. The value will be one of the followings:

  • step
  • percent

The default value of unit is step.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"Missing 'offset' integer parameter."

Mandatory parameter Offset is missing from input arguments.

3"failed to set parameter (invalid scenario name?)"

Failed to set Offset. Check for Validity of Scenario

3"Invalid 'offset' integer parameter value or file not found."

Offset parameter value is invalid. Check for offset range.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/offsetMicGain '{"offset":12,"unit":"step"}'

Returns:
{
    "returnValue": true
}


media/offsetVolume

Description

Offset volume of the current or specified scenario, by an absolute value or by a number of ticks.

Parameters

Name

Required

Type

Description

unitOptionalString

The manner in which to offset the volume. Possible values are:

  • percent - The percentage by which the volume is increased or decreased.
  • step - The step (in increments of 11) by which the volume is increased or decreased.

Default value : step

Note: Check offset parameter for further details.

offsetRequiredNumber

The offset by which the volume should be increased or decreased.

  • If unit is percent, possible values are in the range of [-100, 100].
    • Scenario:
      Increase volume by 50%
      Values: unit: percent ; offset: 50%

 

  • If unit is step, possible values are in the range of [-20, 20]. 
     
    • Scenario: Increase volume by 2 steps.
      Parameters: unit: step ; offset: 2
      Result: If current volume is 20, the volume will be increased to 20 +11 + 11 = 42
       
    • Scenario: Decrease volume by 3 steps.
      Parameters: unit: step; offset: -3
      Result: If current volume is 42, the volume will be decreased to 42 - 11 - 11 - 11 = 9
       
    • Scenario: Increase volume by 10 steps.
      Parameters: unit: step and offset: 10
      Result: If current volume is 42, the volume is limited to 100 (maximum volume limit).
       
    • Scenario: Decrease volume by 10 steps.
      Parameters: unit: step and offset: -10
      Result: If current volume is 42, the volume is reduced to 0 (minimum volume limit).
scenarioOptionalString

Scenario to apply the offset. If not specified, the offset is applied to the currently selected scenario.

Call Returns

Name

Required

Type

Description

returnValueOptionalBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"Missing 'offset' integer parameter."

Mandatory parameter offset is missing from input arguments.

3"failed to set parameter (invalid scenario name?)"

Failed to set offset. Check for validity of scenario.

3"Invalid 'offset' integer parameter value or file not found."

Offset parameter value is invalid. Check for offset range.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/offsetVolume '{"scenario":"media_back_speaker","offset":70,"unit":"percent"}'

{

"returnValue": true

}


media/setCurrentScenario

Description

Designate a scenario as a current scenario.

Parameters

Name

Required

Type

Description

scenarioRequiredString

Scenario to set as the current scenario.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"Missing 'scenario' string parameter."

Mandatory parameter "scenario" is missing from input arguments.

3"Could not set current scenario."

Scenario requested could not be set. Check for Validity of Scenario.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/setCurrentScenario '{"scenario":"media_back_speaker"}'

{

"returnValue": true

}


media/setMicGain

Description

Set mic gain of the current or specified scenario.

Parameters

Name

Required

Type

Description

mic_gainRequiredNumber

Set mic_gain in range [0, 100].

scenarioOptionalString

Scenario for which mic gain is to be set. If not specified, the mic gain is set to the currently selected scenario.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"Missing 'mic_gain' integer parameter."

Mandatory Parameter  mic gain has to be specified

3"failed to set parameter (invalid scenario name?)"

Mic Gain for the scenario could not be set. Check for the validity of scenario

3"Invalid 'mic_gain' integer parameter value or file not found."

Mic Gain value is not valid. It should be  between 0 and 100

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/setMicGain '{"mic_gain":10}'

{

"returnValue": true

}


media/setVolume

Description

Set the volume level of the current or specified scenario.

Parameters

Name

Required

Type

Description

volumeRequiredNumber

Volume level to be set

scenarioOptionalString

Scenario for which the volume is to be set.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"Missing 'volume' integer parameter."

Mandatory Parameter  Volume  has to be specified

3"failed to set parameter (invalid scenario name?)"

Volume for the scenario could not be set. Check for the validity of scenario

3Invalid 'volume' integer parameter value or file not found.

Volume value is not valid. It should be  between 0 and 100.

Example

luna-send -n 1 -f luna://com.webos.service.audio/media/setVolume '{"volume":10}'

{

"returnValue": true

}


media/status

Description

Get a current state of audiod.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Indicates whether to subscribe for related events.

  • true: Subscribe
  • false: Do not subscribe

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

subscribedOptionalBoolean

Indicates if subscribed to get notified when a connection is closed.

  • true - Subscribed for changes
  • false - Not subscribed
mic_gainOptionalNumber

Mic gain [0 -100] of current or specified scenario.

ringtoneWithVibrationOptionalBoolean

Vibrates along with Ringtone.

scenarioOptionalString

The currently selected scenario.

mutedOptionalBoolean

Indicates whether current module is muted.

hacOptionalBoolean

Indicates hac status. Possible values are:

  • true: hac is enabled
  • false: hac is disabled
volumeOptionalNumber

Current volume [0, 100].

actionOptionalString

Update information. The value will be one of the following:

  • changed
  • enabled
  • disabled
  • requested
ringer switchOptionalBoolean

Ringer switch state. True for on (should ring).

sliderOptionalBoolean

Indicates state of the slider.

  • true: slider is open
  • false: slider is closed
activeOptionalBoolean

Indicates if current module is actively used. Possible values are:

  • true: Actively used.
  • false: Not actively used.

Example

luna-send -i -f luna://com.webos.service.audio/media/status '{"subscribe" : false}'

{

    "mic_gain": 10,

    "returnValue": true,

    "ringtoneWithVibration": true,

    "scenario": "media_back_speaker",

    "muted": false,

    "hac": false,

    "subscribed": false,

    "volume": 10,

    "action": "requested",

    "ringer switch": true,

    "slider": false,

    "active": true

}


state/get

Description

Get the state.

Parameters

Name

Required

Type

Description

nameOptionalString

Parameter name whose status has to be obtained

namesOptionalString array

Array of names for which status has to be obtained

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
forceMicOnOptionalBoolean

Indicates whether mic is enabled or disabled

  • true: mic is enabled
  • false: mic is disabled
adjustMicGainOptionalBoolean

Indicates whether mic gain can be adjusted

  • true: mic gain can be adjusted
  • false: mic gain cannot be adjusted
sliderStateOptionalBoolean

Indicates state of the slider

  • true: slider is open
  • false: slider is closed
displayOnOptionalBoolean

Indicates whether display is on or off

  • true: display is on
  • false: display is off
headsetStateOptionalString

Indicates whether headset is connected or not

  • <None> : No headset connected
  • Headset : headset is connected
  • Headset Mic: headset with mic is connected
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

Error References

Error Code

Error Text

Error Description

2"no setting found"

Mandatory to specify at least one parameter.

Example

Example 1:

# luna-send -n 1 -f luna://com.webos.service.audio/state/get '{"name" : "all"}'

{

"headsetState": "<None>",

"forceMicOn": false,

"adjustMicGain": false,

"returnValue": true,

"displayOn": false,

"sliderState": false

}

 

Example 2:

# luna-send -n 1 -f luna://com.webos.service.audio/state/get '{"names" : ["forceMicOn"]}'

{

"forceMicOn": false,

"returnValue": true

}


state/pulse/sinkStatus

Description

List down the status of a pulseaudio sink.

Parameters

Name

Required

Type

Description

sink Optional String

Name of sink. If not specified, the status of all the sinks are listed.

Call Returns

Name

Required

Type

Description

returnValue Required Boolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
errorCode Optional Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

errorText Optional String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

filter Optional Number

Pulse filter status.

Note: For webOS Open Source Edition, this parameter is for future use.

sink Optional String

Name of the sink.

destination Optional String

Physical destination.

volume Optional Number

Current volume set for the sink.

openStreams Optional String

Streams opened for the sink.

latency Optional Number

Current latency set for sink.

Note: For webOS Open Source Edition, this parameter is for future use.

Error References

Error Code

Error Text

Error Description

3 "Invalid 'sink' string parameter value or file not found."

Invalid 'sink' parameter is provided.

Example

luna-send -n 1 -f luna://com.webos.service.audio/state/pulse/sinkStatus '{"sink" : "pmedia"}'

Returns:
{
    "filter": 0,
    "sink": "pmedia",
    "destination": "pcm_output",
    "volume": 0,
    "openStreams": 0,
    "returnValue": true,
    "latency": 65536
}


state/set

Description

Setter for state.

Remark

  • At least more than one parameter should be passed. Otherwise, the method will fail.

Parameters

Name

Required

Type

Description

adjustMicGainOptionalBoolean

Indicates whether mic gain can be adjusted

  • true: mic gain can be adjusted
  • false: mic gain cannot be adjusted

At least one or both of adjustMicGain and forceMicOn must be passed.

forceMicOnOptionalBoolean

Indicates whether mic can be enabled or disabled

  • true: mic can be enabled
  • false: mic can be disabled

At least one or both of adjustMicGain and forceMicOn must be passed.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean
  • If the method succeeds, returnValue will contain true.
  • If the method fails, returnValue will contain false.
errorCodeOptionalNumber

errorCode contains the error code if the method fails. The method will return errorCode only if it fails

errorTextOptionalString

errorText contains the error text if the method fails. The method will return errorText only if it fails

Example

luna-send -n 1 -f luna://com.webos.service.audio/state/set '{"adjustMicGain" : true}'


state/setSoundProfile

Description

Sets a particular sound profile.

Remark

This method allows an application to set the following profiles:

  • Sound [Only Ringing]
  • Silent [No Ringing and Vibration] (default profile)
  • Vibrate [Only Vibration]
  • Sound + Vibrate [Ringing and Vibration]

Parameters

Name

Required

Type

Description

ringerRequiredString

Specify whether to enable ringing to notify a user.

  • "ON" or "on": enable ringing
  • "OFF" or "off": disable ringing

Default value: OFF

Note: Combination of upper case and lower case in these values (like "On" / "Off" / "oFF") are not supported and treated as errors.

vibrateRequiredString

Specify whether to enable vibration to notify a user.

  • "ON" or "on": enable vibration
  • "OFF" or "off": disable vibration

Note: Combination of upper case and lower case in these values (like "On" or "Off") are not supported and treated as errors.

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates whether the execution succeeded.

- true: Success

- false: Failure

errorTextOptionalString

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

errorCodeOptionalNumber

Identifies the error. Returned only in case of execution failure

Error References

Error Code

Error Text

Error Description

2profile setting failed: missing parameters ?

Mandatory parameters are missing from input arguments

3profile setting failed: Invalid value for ringer

Invalid value of "ringer". Valid values are "ON" or "on" , "OFF" or "off"

3profile setting failed: Invalid value for vibrate

Invalid value of "vibrate". Valid values are "ON" or "on" , "OFF" or "off"

1Could not validate json message against schema

Invalid number of input parameters against defined schema of the API

1Not a valid json message

Wrong JSON message format

Example

# luna-send -n 1 -f luna://com.webos.service.audio/state/setSoundProfile

'{

    "ringer" : "on",

    "vibrate" : "on"

}'


state/getSoundProfile

Description

Subscribe to this API to get notifications when the sound profile is changed.

Parameters

Name

Required

Type

Description

subscribeOptionalBoolean

Subscribe for notifications when a profile is changed. Possible values are:

  • true - Get notifications
  • false - Notifications are not required

Default value: false

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
subscribedOptionalBoolean

Indicates if subscribed to get notified.

  • true - Subscribed for changes
  • false - Not subscribed
SoundProfileOptionalString

Gives the current sound profile.

errorTextOptionalString

Indicates the reason for the failure of the operation. See the "Error Codes Reference" section of this method for details.

errorCodeOptionalNumber

The error code for the failed operation.

Subscription Returns

Name

Required

Type

Description

returnValueRequiredBoolean

Indicates the status of operation. Possible values are:

  • true - Indicates that the operation was successful.
  • false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
SoundProfileOptionalString

Returns the updated sound profile value.

Error References

Error Code

Error Text

Error Description

1Could not validate json message against schema

Invalid number of input parameters against defined schema of the API

1Not a valid json message

Wrong JSON message format

Example

# luna-send -i -f luna://com.webos.service.audio/state/getSoundProfile

'{

    "subscribe": true

}'

Returns:

{

    "subscribed": true,

    "SoundProfile": "Vibrate only",

    "returnValue": true

}

Subscription Return:

{

    "SoundProfile": "Silent",

    "returnValue": true

}


ERROR REFERENCES

Error Code

Error Text

Error Description

1Could not validate json message against schema

Invalid number of input parameters against defined schema of the method

1Not a valid json message

Wrong JSON message format


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