HyperHeadset/FEATURE_CAPABILITIES.md

HyperX Headset Feature Capabilities

This document summarizes which features can be controlled vs only monitored for each headset model.

Cloud II Wireless (Non-DTS)

Writable Features (Can be SET via HID commands)

• ✅ Auto Power Off - Can set automatic shutdown timer (0-30 minutes)
• ✅ Sidetone - Can enable/disable sidetone (on/off only, no volume control)

Read-Only Features (Can only monitor, not control)

• ❌ Microphone Mute - Hardware button only, cannot be controlled via HID
• ❌ Surround Sound (7.1) - Controlled via Windows DTS APO or physical button, not HID
• ❌ Battery Level - Read-only status
• ❌ Charging Status - Read-only status
• ❌ Connection Status - Read-only status
• ❌ Firmware Version - Read-only information

Cloud II Wireless DTS

Writable Features

• ✅ Auto Power Off
• ✅ Sidetone - With volume control (0-100)
• ✅ Surround Sound - Via Windows DTS APO system calls (not direct HID)

Read-Only Features

• ❌ Microphone Mute - Hardware button only
• ❌ Battery Level
• ❌ Charging Status
• ❌ Connection Status

Cloud III Wireless

Writable Features

• ✅ Auto Power Off
• ✅ Sidetone - With volume control (0-100)
• ✅ Microphone Mute - Can be controlled programmatically
• ✅ Voice Prompt - Can enable/disable voice prompts
• ✅ Playback Mute (Silent Mode) - Can mute headphone output

Read-Only Features

• ❌ Surround Sound - Not supported via HID
• ❌ Battery Level
• ❌ Charging Status
• ❌ Connection Status
• ❌ Product Color

CLI Error Handling

The CLI application now provides clear error messages when attempting to use unsupported features:

# Example: Trying to control surround sound on Cloud II Wireless
$ ./hyper_headset_cli --surround_sound true
ERROR: Surround sound control is not supported on this device
       Use the physical headset button or Windows audio settings to toggle surround sound.

# Example: Trying to mute on Cloud II Wireless
$ ./hyper_headset_cli --mute true
ERROR: Microphone mute control is not supported on this device (hardware button only)

Tray Application UI

The system tray application now displays "(read-only)" markers next to features that cannot be controlled:

Battery level:            92%
Charging status:          Not charging
Muted:                    false (read-only)
Automatic shutdown after: 20min
Side tone:                false
Surround sound:           true (read-only)
Connected:                true

Implementation Details

• Feature capabilities are checked once during device initialization via init_capabilities()
• Capability flags are stored in DeviceState structure
• CLI flags for unsupported features are hidden in the help menu
• CLI exits with error code 1 when attempting to use unsupported features
• Tray UI shows read-only markers based on device capabilities