/pps/services/audio/control

The Audio Manager listens for commands on this control object

Publishers
Any app
Subscribers
Audio Manager
Note: This type of object is known as a server object, a special PPS object designed for point-to-point communication between a server and one or more clients. For details, see "Server objects" in the Persistent Publish/Subscribe Developer's Guide.

Audio Manager library

Besides reading from and writing to the PPS audio objects directly, you may also choose to use the Audio Manager library, which allows your apps to set up and process events from audio devices. This library provides a C/C++ interface to audio devices that are accessible through the underlying PPS framework. Using this library, you can get and set properties for audio device status, volume, routing, and concurrency. You can also add and remove device events to notify clients that are using audio devices. For more information, see the Audio Manager Library Reference.

Message/response format

Commands sent to the /pps/services/audio/control object are of the form:

msg::command_string\nid::ID_number\ndat:json:{JSON_data}

Responses always reflect the command_string and ID_number that were sent in the message, along with any errors:

res::command_string\nid::ID_number\ndat:json:{JSON_data}\n error::error_description

Commands

Command Parameters Data type Description
adjust_input_level name String The device name, which is listed under /pps/services/audio/devices/ (e.g., headset).
level Double Percentage representing the desired adjustment of the input volume level.
adjust_output_level name String The device name. The device's volumecontrol must be percentage.
level Double Percentage representing the adjustment of the output volume level.
adjust_voice_output_level name String Name of the device to adjust the output volume level of when a voice call is activated.
level Double Percentage representing the change of the output volume level.
decrease_output_level name String The device name. The device's volumecontrol can be percentage or simple.
get_a2dp_status supported Boolean Indicates whether the paired device supports A2DP.
connected Boolean Indicates whether the A2DP stream is connected.
numchans Number Number of channels that the A2DP stream supports (1 or 2).
volumecontrol String Type of volume control that the current device supports for A2DP:
  • unavailable (no volume control)
  • simple (supports only increase and decrease)
  • percentage (supports full control, including mute, specific steps, etc.)

Default is unavailable.

state String State of the A2DP stream:
  • closed
  • idle
  • open
  • streaming
get_device_property name String The device name.
property String Name of the device's attribute.
value String Value of the given attribute.
get_hdmi_info numchans Number Number of audio channels supported by the connected HDMI device.
hdmiorder String Audio channel order of the connected HDMI device (e.g., FL,FR).
audioconfig String Configuration of the audio output channels (e.g., "2.0", "5.1"). Note that this is used only by the hdmi device.
mirror Boolean Indicates whether mirror mode is enabled.
keep_alive Boolean Indicates whether the hdmi driver is to be kept alive when no audio stream is active.
enabled Boolean Indicates whether the HDMI device is enabled.
volumecontrol String Type of volume control supported by the attached HDMI device. Values:
  • unavailable (no volume control)
  • simple (supports only increase and decrease)
  • percentage (supports full control, including mute, specific steps, etc.)
get_headphone_enable name String The device name.
get_hfpg_sco_state supported Boolean Indicates whether the paired device supports HFP.
connected Boolean Indicates whether the handsfree connection can be established.
volumecontrol String Type of volume control that the current device supports for A2DP:
  • unavailable (no volume control)
  • simple (supports only increase and decrease)
  • percentage (supports full control, including mute, specific steps, etc.)

Default is unavailable.

audioprocessing Boolean Indicates whether the paired device needs audio processing by the handset or modem.
state String State of the handsfree connection:
  • closed
  • idle
  • open
  • streaming
suspended Boolean Whether HFP is suspended as requested by the device. Default is false.
remoteVAD Boolean Whether HFP also supports VAD and voice recording.
get_input_level name String The device name.
Note: If an invalid name is given, the level of the currently selected input device is returned. If the given device is output only, the level of the corresponding input device when the output device is selected is returned.
get_input_mute name String The device name.
get_output_level name String The device name. The device's volumecontrol must be percentage.
get_output_mute name String The device name. The device's volumecontrol must be percentage.
get_voice_output_level name String The device to get the output volume level of when a voice call is activated.
level Double Percentage representing the current output volume level.
get_voice_output_mute name String The device name.
muted Boolean Indicates whether the device output is muted.
increase_output_level name String The device name. The device's volumecontrol can be percentage or simple.
keep_output_alive name String The device name.
keep_alive Boolean Indicates whether the given output device is to be kept alive when no audio stream is active.
set_audio_mode (may be deprecated) audiomode String Tunings to apply to the hardware codec:
  • audio
  • video
  • voice
  • record
set_hac_enabled enabled Boolean Indicates whether HAC (Hearing Aid Compatibility) is enabled for voice handset mode.
set_hdmi_enable enabled Boolean Indicates whether an HDMI device is connected.
Note: The HDMI device is activated only when these conditions are met:
  1. No higher-priority device is active.
  2. Mirror mode is set for the HDMI device.
  3. The numchans, hdmiorder, and audioconfig parameters for set_hdmi_info are set correctly.
set_hdmi_info numchans Number Number of audio channels supported by the connected HDMI device.
hdmiorder String Audio channel order of the connected HDMI device (e.g., FL,FR).
audioconfig String Configuration of the audio output channels (e.g., "2.0", "5.1"). Note that this is used only by the hdmi device.
volumecontrol String Type of volume control supported by the attached HDMI device:
  • unavailable (no volume control)
  • simple (supports only increase and decrease)
  • percentage (supports full control, including mute, specific steps, etc.)
Note: The hdmi audio driver sends HDMI info to the Audio Manager before the HDMI handler calls set_hdmi_enable. This is to prevent set_hdmi_enable from publishing inaccurate HDMI info.
set_hdmi_mode mirror Boolean Indicates whether mirror mode is enabled.
set_headphone_enable (may be deprecated) name String Name of the device to be activated as the default because of this event.
enabled Boolean Indicates whether the headphone is enabled as the output.
set_headphone_override hpoverride Boolean Indicates whether headphone volume boost is enabled. If enabled, volume >92% is allowed.
set_input_level name String The device name.
Note: If an invalid name is given, the level of the currently selected input device is returned. If the given device is output only, the level of the corresponding input device when the output device is selected is returned.
level Double Percentage representing the desired input volume level.
set_input_mute name String The device name.
muted Boolean Indicates whether the given device input is muted.
set_output_level name String The device name. The device's volumecontrol must be percentage.
level Double Percentage representing the desired output volume level.
set_output_mute name String The device name. The device's volumecontrol must be percentage.
muted Boolean Indicates whether the given device output is muted.
set_toslink_enable enabled Boolean Indicates whether a TOSLINK connection is used.
set_tty_enabled enabled Boolean Indicates whether TTY mode is selected for voice headset mode. The Audio Manager automatically picks TTY mode only when a headset is connected and TTY is enabled during a voice call.
set_voice_output_level name String The device to set the output volume level of when a voice call is activated.
level Double Percentage representing the desired output volume level.
set_voice_output_mute name String The device to mute/unmute.
muted Boolean Indicates whether the device output is muted.
toggle_input_mute name String The device name.
Note: If an invalid name is given, the level of the currently selected input device is updated. If the given device is output only, the corresponding input device when the output device is selected is updated.
toggle_output_mute name String The device name. The device's volumecontrol must be percentage.
toggle_voice_output_mute name String The device to toggle the mute status of when a voice call is activated.

Examples

Set the volume level of the headset to 75%:

msg::set_output_level\nid::1\ndat:json:{"name":"headset", "level":75}
Note: The "level" field is a double, so its value doesn't have quotes.

Mute the speaker:

msg::set_output_mute\nid::2\ndat:json:{"name":"speaker", "muted":"true"}