Implement command_volume_level_step notification command for relative volume adjustments

[marazmarci]

Summary

This PR adds a new command_volume_level_step notification command (alongside the existing command_volume_level) to add support for relative volume adjustments. It enables users to create responsive volume up/down control automations, for example for physical media control buttons through HA (eg. this Zigbee device). Currently the best option for implementing such automation is to first read the current state of the music volume sensor, then add/subtract the desired adjustment value, and then fire a command_volume_level notification command to set the new volume. The problem with this approach is slowness. Quick successive button presses would result in most of the button presses to be seemingly ignored, because the music volume sensor doesn't update quickly enough.

The parameters of the new command are exactly the same as for command_volume_level. The only difference is in behavior of the command key. Here's an example service call YAML to decrease music volume by 2 steps:

service: notify.mobile_app_<device_name>
data:
  message: command_volume_level_step
  data:
    media_stream: music_stream
    command: -2

Checklist

• New or updated tests have been added to cover the changes following the testing guidelines.
  • No, as MessagingManager didn't have any unit tests to begin with.
• The code follows the project's code style and best_practices.
• The changes have been thoroughly tested, and edge cases have been considered.
• Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.

Link to pull request in documentation repositories

Documentation: home-assistant/companion.home-assistant#

I'll open the doc update PR and the PR for adding the new notification command in the mobile-apps-fcm-push repo when this PR is getting close to be merged ⏳

Any other notes

This is a reworked & rethought version of a PR I opened (and abandoned) a while ago: #4056 (closed without merging)
In that PR, I implemented the same functionality with a different approach: I extended the existing command_volume_level notification command with a relative: true/false property. Now I changed my mind, because I think adding a separate notification command feels cleaner, expresses the distinction more clearly, and is more similar to existing patterns in HA, like the brightness_step key for the light.turn_on command.

[Copilot]

Pull request overview

This PR extends the Android companion app’s notification “device command” handling to support relative volume adjustments by introducing a new command_volume_level_step command, enabling faster volume up/down automations without relying on sensor round-trips.

Changes:

• Added command_volume_level_step to the supported notification command set and permission request flow
• Implemented step-based volume adjustment behavior alongside existing absolute volume setting
• Updated the user-facing changelog entry for the new command

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
app/src/main/res/xml/changelog_master.xml	Adds a changelog entry for the new relative volume notification command
app/src/main/kotlin/io/homeassistant/companion/android/notifications/MessagingManager.kt	Adds new command constant and routes it through volume handling with “step vs absolute” behavior
app/src/main/kotlin/io/homeassistant/companion/android/ApplicationModule.kt	Provides AudioManager via Hilt for use by MessagingManager

Comments suppressed due to low confidence (1)

app/src/main/kotlin/io/homeassistant/companion/android/notifications/MessagingManager.kt:707

• audioManager is injected as nullable but is force-unwrapped here. Since ApplicationModule currently provides AudioManager?, this can crash at runtime if the service is unavailable (or in certain test/preview contexts). Consider guarding for null before calling processRingerMode.

                if (notificationManager?.isNotificationPolicyAccessGranted == false) {
                    notifyMissingPermission(message, serverId)
                } else {
                    processRingerMode(audioManager!!, command)
                }

[TimoPtr]

@marazmarci thanks for pushing this through. I've made some changes that you'll have to add to your PR. Is it an option to extend the existing command with more parameters to achieve the same goals as what you are trying to achieve?