From 04e247ec9ab14a323c8cdf88a4becdcb146d1e97 Mon Sep 17 00:00:00 2001
From: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
Date: Mon, 13 Jun 2022 13:29:35 +1200
Subject: [PATCH] Add volume actions for media player (#2124)

---
 components/media_player/index.rst | 57 ++++++++++++++++++++++++++++---
 guides/automations.rst            |  1 +
 2 files changed, 54 insertions(+), 4 deletions(-)

diff --git a/components/media_player/index.rst b/components/media_player/index.rst
index 48fc9d368..fa7a241ad 100644
--- a/components/media_player/index.rst
+++ b/components/media_player/index.rst
@@ -38,10 +38,21 @@ Configuration variables:
   See https://developers.home-assistant.io/docs/core/entity/#generic-properties
   for a list of available options. Set to ``""`` to remove the default entity category.
 
+Media Player Actions
+--------------------
+
+All ``media_player`` actions can be used without specifying an ``id`` if you have only one ``media_player`` in
+your configuration YAML.
+
+Configuration variables:
+
+**id** (*Optional*, :ref:`config-id`): The media player to control. Defaults to the only one in YAML.
+
+
 .. _media_player-play:
 
 ``media_player.play`` Action
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This action will resume playing the media player.
 A future change will allow specifying the ``media_url`` for starting
@@ -50,24 +61,62 @@ a new stream.
 .. _media_player-pause:
 
 ``media_player.pause`` Action
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This action pauses the current playback.
 
 .. _media_player-stop:
 
 ``media_player.stop`` Action
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This action stops the current playback.
 
 .. _media_player-toggle:
 
 ``media_player.toggle`` Action
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This action will pause or resume the current playback.
 
+.. _media_player-volume_up:
+
+``media_player.volume_up`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will increase the volume of the media player.
+
+.. _media_player-volume_down:
+
+``media_player.volume_down`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will decrease the volume of the media player.
+
+.. _media_player-volume_set:
+
+``media_player.volume_set`` Action
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This action will set the volume of the media player.
+
+.. code-block::
+
+    on_...:
+      # Simple
+      - media_player.volume_set: 50%
+
+      # Full
+      - media_player.volume_set:
+          id: media_player_id
+          volume: 50%
+
+      # Simple with lambda
+      - media_player.volume_set: !lambda "return 0.5;"
+
+Configuration variables:
+
+**volume** (**Required**, percentage): The volume to set the media player to.
 
 See Also
 --------
diff --git a/guides/automations.rst b/guides/automations.rst
index ca1aada8c..fb457796b 100644
--- a/guides/automations.rst
+++ b/guides/automations.rst
@@ -393,6 +393,7 @@ All Actions
 - :ref:`number.set <number-set_action>` / :ref:`number.to_min <number-to-min_action>` / :ref:`number.to_max <number-to-max_action>` / :ref:`number.decrement <number-decrement_action>` / :ref:`number.increment <number-increment_action>` / :ref:`number.operation <number-operation_action>`
 - :ref:`select.set <select-set_action>` / :ref:`select.set_index <select-set_index_action>` / :ref:`select.first <select-first_action>` / :ref:`select.last <select-last_action>` / :ref:`select.previous <select-previous_action>`  / :ref:`select.next <select-next_action>`  / :ref:`select.operation <select-operation_action>`
 - :ref:`media_player.play <media_player-play>` / :ref:`media_player.pause <media_player-pause>` / :ref:`media_player.stop <media_player-stop>` / :ref:`media_player.toggle <media_player-toggle>`
+  / :ref:`media_player.volume_up <media_player-volume_up>` / :ref:`media_player.volume_down <media_player-volume_down>` / :ref:`media_player.volume_set <media_player-volume_set>`
 
 .. _config-condition: