diff --git a/source/_components/media_player.yamaha.markdown b/source/_components/media_player.yamaha.markdown
index cebbd62f3ab..8ab1d511144 100644
--- a/source/_components/media_player.yamaha.markdown
+++ b/source/_components/media_player.yamaha.markdown
@@ -32,18 +32,37 @@ media_player:
 ```
 Configuration variables:
 
-- **name** (*Optional*): Name of the device
+- **name** (*Optional*): Name of the device. This overrides the
+  default name (often model number) that is returned by the device.
 - **host** (*Optional*): IP address or hostname of the device
 - **source_ignore** (*Optional*): List of sources to hide in the front-end
 - **source_names** (*Optional*): Mapping of internal AVR source names to custom ones, allowing to rename e.g. `HDMI1` to `ChromeCast`
 
-A few notes:
+### {% linkable_title Discovery notes %}
 
-- Not specifying the host variable will result in automatically searching your network for Yamaha Receivers. It will add a media player device for each one.
-- For receivers that support more than one zone, Home Assistant will add one media player per zone supported by the player, named "$name Zone 2" and "$name Zone 3".
-- In some cases, auto-discovery fails due to a known bug in the receiver's firmware. It is possible to manually specify the receiver's IP address or via it's hostname (if it is discoverable by your DNS) then.
-- Please note: If adding the IP address or hostname manually, you **must** enable network standby on your receiver, or else startup of Home Assistant will hang if you have your receiver switched off.
-- Currently, this component supports powering on/off, mute, volume control and source selection. Playback controls, for instance play and stop are available for sources that supports it.
+- If the `discovery` component is enabled, all units on the network
+  will be discovered using UPNP.
+- For receivers that support more than one zone, Home Assistant will
+  add one media player per zone supported by the player, named "$name
+  Zone 2" and "$name Zone 3".
+- If you specify `host` manually, you **must** enable network standby
+  on your receiver, or else startup of Home Assistant will hang if you
+  have your receiver switched off.
+- In some cases, auto-discovery fails due to a known bug in the
+  receiver's firmware. It is possible to manually specify the
+  receiver's IP address or via it's hostname (if it is discoverable by
+  your DNS) then.
+
+### {% linkable_title Supported operations %}
+
+- Media players created by yamaha support powering on/off, mute,
+  volume control and source selection. Playback controls, for instance
+  play and stop are available for sources that supports it.
+- The `play_media` service is implemented for `NET RADIO` source
+  only. The `media_id` is a `>` separted string of the menu path on
+  the vtuner service. For instance `Bookmarks>Internet>WAMC 90.3 FM`.
+
+### {% linkable_title Example configuration %}
 
 A full configuration example will look like the sample below:
 ```yaml
@@ -58,3 +77,33 @@ media_player:
       HDMI1: "ChromeCast"
       AV4: "Vinyl"
 ```
+
+### {% linkable_title Example `play_media` script %}
+
+The `play_media` function can be used in scripts easily to build media
+player presets. When done in scripts, the sequence will also allow you
+to set volume per source.
+
+```yaml
+# Example play_media script
+#
+# This is for an environment where Zone 2 of the receiver named
+# `Living Room Stereo` drives outdoor speakers on the porch.
+script:
+ rp_porch:
+    alias: "Radio Paradise Porch"
+    sequence:
+      - service: media_player.turn_on
+        data:
+          entity_id: media_player.living_room_stereo_zone_2
+      - service: media_player.volume_set
+        data:
+          entity_id: media_player.living_room_stereo_zone_2
+          volume_level: 0.48
+      - service: media_player.play_media
+        data:
+          entity_id: media_player.living_room_stereo_zone_2
+          media_content_type: "NET RADIO"
+          media_content_id: "Bookmarks>Internet>Radio Paradise"
+
+```