-
-
Notifications
You must be signed in to change notification settings - Fork 173
API ‐ Building Applications on top of HeadsetControl
HeadsetControl supports output in multiple formats. JSON, YAML and as Environment Variables.
HeadsetControl currently only supports querying one device (the first it finds). However the structure is already prepared in a way that multiple are supported (for example we could include querying the battery of a mouse in future), so you should keep that in mind.
With the --test-device setting, HeadsetControl will simulate a testing device. You can also use a number after that for some predefined variation (and simulated errors) in output. For example --test-device 2. The value 10 --test-device 10 is special and will display a device with only some capabilities.
On default, it will query all capabilities. So you do not have to specify them.
The following examples are outputting JSON.
Example:
❯ ./headsetcontrol --test-device -o json{
"name": "HeadsetControl",
"version": "2.7.0-9-ga95a015-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"device_count": 1,
"devices": [
{
"status": "success",
"device": "HeadsetControl Test device",
"vendor": "HeadsetControl",
"product": "Test device",
"id_vendor": "0xf00b",
"id_product": "0xa00c",
"capabilities": [
"CAP_SIDETONE",
"CAP_BATTERY_STATUS",
"CAP_NOTIFICATION_SOUND",
"CAP_LIGHTS",
"CAP_INACTIVE_TIME",
"CAP_CHATMIX_STATUS",
"CAP_VOICE_PROMPTS",
"CAP_ROTATE_TO_MUTE",
"CAP_EQUALIZER_PRESET",
"CAP_EQUALIZER",
"CAP_MICROPHONE_MUTE_LED_BRIGHTNESS",
"CAP_MICROPHONE_VOLUME"
],
"capabilities_str": [
"sidetone",
"battery",
"notification sound",
"lights",
"inactive time",
"chatmix",
"voice prompts",
"rotate to mute",
"equalizer preset",
"equalizer",
"microphone mute led brightness",
"microphone volume"
],
"battery": {
"status": "BATTERY_AVAILABLE",
"level": 42
},
"chatmix": 42
}
]
}If the device does not support something - like battery - then the (battery) section will not exist.
If there are no devices connected, the devices section will simply be empty and device_count 0:
{
"name": "HeadsetControl",
"version": "2.7.0-9-ga95a015-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"device_count": 0,
"devices": [
]
}Battery can have following (successful) states (but not all implementations have all of them!):
- BATTERY_AVAILABLE: Default state, will always display a level of the battery
- BATTERY_UNAVAILABLE: The command was successful, but the Battery is unavailable for some reason (for example dongle connected but headset offline)
- BATTERY_CHARGING: The battery is charging. If a level is not available, level will be
-1. If a level is displayed, it might be unreliable (fluctuating etc. because it is based on voltage). Only some devices report that state when charging (otherwise Available or Unavailable)
Also there are following errors states, which are however not exposed currently, just in text (see next section):
- BATTERY_HIDERROR,
- BATTERY_TIMEOUT
You can simply check for errors by looking if there is an errors section. It will then display which section errored out and why.
Also the status of the device will be either partial (some things failed) or failure (currently not used, but consider in your app).
❯ ./headsetcontrol --test-device 1 -o json{
"name": "HeadsetControl",
"version": "2.7.0-19-g19dd4ae-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"device_count": 1,
"devices": [
{
"status": "partial",
"device": "HeadsetControl Test device",
"vendor": "HeadsetControl",
"product": "Test device",
"id_vendor": "0xf00b",
"id_product": "0xa00c",
"capabilities": [
"CAP_SIDETONE",
"CAP_BATTERY_STATUS",
"CAP_NOTIFICATION_SOUND",
"CAP_LIGHTS",
"CAP_INACTIVE_TIME",
"CAP_CHATMIX_STATUS",
"CAP_VOICE_PROMPTS",
"CAP_ROTATE_TO_MUTE",
"CAP_EQUALIZER_PRESET",
"CAP_EQUALIZER",
"CAP_MICROPHONE_MUTE_LED_BRIGHTNESS",
"CAP_MICROPHONE_VOLUME"
],
"capabilities_str": [
"sidetone",
"battery",
"notification sound",
"lights",
"inactive time",
"chatmix",
"voice prompts",
"rotate to mute",
"equalizer preset",
"equalizer",
"microphone mute led brightness",
"microphone volume"
],
"battery": {
"status": "BATTERY_CHARGING",
"level": 50
},
"errors": {
"chatmix": "Error retrieving chatmix status"
}
}
]
}❯ ./headsetcontrol --test-device 1 -o json{
"name": "HeadsetControl",
"version": "2.7.0-19-g19dd4ae-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"device_count": 1,
"devices": [
{
"status": "partial",
"device": "HeadsetControl Test device",
"vendor": "HeadsetControl",
"product": "Test device",
"id_vendor": "0xf00b",
"id_product": "0xa00c",
"capabilities": [
"CAP_SIDETONE",
"CAP_BATTERY_STATUS",
"CAP_NOTIFICATION_SOUND",
"CAP_LIGHTS",
"CAP_INACTIVE_TIME",
"CAP_CHATMIX_STATUS",
"CAP_VOICE_PROMPTS",
"CAP_ROTATE_TO_MUTE",
"CAP_EQUALIZER_PRESET",
"CAP_EQUALIZER",
"CAP_MICROPHONE_MUTE_LED_BRIGHTNESS",
"CAP_MICROPHONE_VOLUME"
],
"capabilities_str": [
"sidetone",
"battery",
"notification sound",
"lights",
"inactive time",
"chatmix",
"voice prompts",
"rotate to mute",
"equalizer preset",
"equalizer",
"microphone mute led brightness",
"microphone volume"
],
"errors": {
"battery": "Error retrieving battery status",
"chatmix": "Error retrieving chatmix status"
}
}
]
}You can query and send actions (like change sidetone) at the same time. If you specify an action, an actions section will be simply added. You can also do multiple actions.
Actions are outside of devices (there is currently no way to specify which device)
❯ ./headsetcontrol --test-device 0 -o json -s 128{
"name": "HeadsetControl",
"version": "2.7.0-19-g19dd4ae-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"actions": [
{
"capability": "CAP_SIDETONE",
"device": "HeadsetControl Test device",
"status": "success"
}
],
"device_count": 1,
"devices": [
{
"status": "success",
"device": "HeadsetControl Test device",
"vendor": "HeadsetControl",
"product": "Test device",
"id_vendor": "0xf00b",
"id_product": "0xa00c",
"capabilities": [
"CAP_SIDETONE",
"CAP_BATTERY_STATUS",
"CAP_NOTIFICATION_SOUND",
"CAP_LIGHTS",
"CAP_INACTIVE_TIME",
"CAP_CHATMIX_STATUS",
"CAP_VOICE_PROMPTS",
"CAP_ROTATE_TO_MUTE",
"CAP_EQUALIZER_PRESET",
"CAP_EQUALIZER",
"CAP_MICROPHONE_MUTE_LED_BRIGHTNESS",
"CAP_MICROPHONE_VOLUME"
],
"capabilities_str": [
"sidetone",
"battery",
"notification sound",
"lights",
"inactive time",
"chatmix",
"voice prompts",
"rotate to mute",
"equalizer preset",
"equalizer",
"microphone mute led brightness",
"microphone volume"
],
"battery": {
"status": "BATTERY_AVAILABLE",
"level": 42
},
"chatmix": 42
}
]
}Errors are directly included in the actions response, so you have to check the status:
❯ ./headsetcontrol --test-device 1 -o json -s 128{
"name": "HeadsetControl",
"version": "2.7.0-19-g19dd4ae-modified",
"api_version": "1.0",
"hidapi_version": "0.13.1",
"actions": [
{
"capability": "CAP_SIDETONE",
"device": "HeadsetControl Test device",
"status": "failure",
"error_message": "Failed to set/request sidetone. Error: -1"
}
],
"device_count": 1,
"devices": [
{
"status": "partial",
"device": "HeadsetControl Test device",
"vendor": "HeadsetControl",
"product": "Test device",
"id_vendor": "0xf00b",
"id_product": "0xa00c",
"capabilities": [
"CAP_SIDETONE",
"CAP_BATTERY_STATUS",
"CAP_NOTIFICATION_SOUND",
"CAP_LIGHTS",
"CAP_INACTIVE_TIME",
"CAP_CHATMIX_STATUS",
"CAP_VOICE_PROMPTS",
"CAP_ROTATE_TO_MUTE",
"CAP_EQUALIZER_PRESET",
"CAP_EQUALIZER",
"CAP_MICROPHONE_MUTE_LED_BRIGHTNESS",
"CAP_MICROPHONE_VOLUME"
],
"capabilities_str": [
"sidetone",
"battery",
"notification sound",
"lights",
"inactive time",
"chatmix",
"voice prompts",
"rotate to mute",
"equalizer preset",
"equalizer",
"microphone mute led brightness",
"microphone volume"
],
"errors": {
"battery": "Error retrieving battery status",
"chatmix": "Error retrieving chatmix status"
}
}
]
}The API has its own versioning. The API feature started with 1.0. The first number will increase on breaking changes, the second number if new things or so are added without breaking current things.