From ddfff8d4d321d156eb5c2902f3dfee9c699d88af Mon Sep 17 00:00:00 2001
From: Kevin Ahrendt <kevin.ahrendt@nabucasa.com>
Date: Wed, 16 Oct 2024 18:47:14 -0400
Subject: [PATCH] Document Speaker volume set action (#4343)

---
 automations/all_actions.rst  |  2 +-
 components/speaker/index.rst | 25 +++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/automations/all_actions.rst b/automations/all_actions.rst
index 0e9171083..dadff78a6 100644
--- a/automations/all_actions.rst
+++ b/automations/all_actions.rst
@@ -57,7 +57,7 @@
 - **senseair:** ``abc_disable``, ``abc_enable``, ``abc_get_period``, ``background_calibration``, ``background_calibration_result``
 - **servo:** ``detach``, ``write``
 - **sim800l:** ``connect``, ``dial``, ``disconnect``, ``send_sms``, ``send_ussd``
-- **speaker:** ``play``, ``stop``
+- **speaker:** ``play``, ``stop``, ``finish``, ``volume_set``
 - **sprinkler:** ``clear_queued_valves``, ``next_valve``, ``pause``, ``previous_valve``, ``queue_valve``, ``resume``, ``resume_or_start_full_cycle``, ``set_divider``, ``set_multiplier``, ``set_repeat``, ``set_valve_run_duration``, ``shutdown``, ``start_from_queue``, ``start_full_cycle``, ``start_single_valve``
 - **sps30:** ``start_fan_autoclean``
 - **stepper:** ``report_position``, ``set_acceleration``, ``set_deceleration``, ``set_speed``, ``set_target``
diff --git a/components/speaker/index.rst b/components/speaker/index.rst
index aa9279ad9..7f4ee2151 100644
--- a/components/speaker/index.rst
+++ b/components/speaker/index.rst
@@ -71,6 +71,31 @@ Configuration variables:
 
 - **id** (*Optional*, :ref:`config-id`): The speaker to control. Defaults to the only one in YAML.
 
+.. _speaker-volume_set:
+
+``speaker.volume_set`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will set the volume of the speaker.
+
+.. code-block::
+
+    on_...:
+      # Simple
+      - speaker.volume_set: 50%
+
+      # Full
+      - speaker.volume_set:
+          id: speaker_id
+          volume: 50%
+
+      # Simple with lambda
+      -  speaker.volume_set: !lambda "return 0.5;"
+
+Configuration variables:
+
+**volume** (**Required**, percentage): The volume to set the speaker to.
+
 .. _speaker-conditions:
 
 Speaker Conditions