Skip to content

Commit a55f959

Browse files
azoguefrenck
azogue
authored and
frenck
committed
Add state_template docs and example for the universal media player (home-assistant#3907)
* Add state_template docs and example * fix template and adjust to doc standards * ✏️ Some minor changes
1 parent 19ae9c8 commit a55f959

File tree

1 file changed

+114
-5
lines changed

1 file changed

+114
-5
lines changed

‎source/_components/media_player.universal.markdown

+114-5
Original file line numberDiff line numberDiff line change
@@ -51,18 +51,26 @@ Configuration variables:
5151
5252
- **name** (*Required*): The name to assign the player
5353
- **children** (*Required*): Ordered list of child media players this entity will control
54+
- **state_template** (*Optional*): A [template](/topics/templating/) can be specified to render the state of the media player. This way, the state could depend on entities different from media players, like Switches or Input Booleans.
5455
- **commands** (*Optional*): Commands to be overwritten. Possible entries are *turn_on*, *turn_off*, *select_source*, *volume_set*, *volume_up*, *volume_down*, and *volume_mute*.
5556
- **attributes** (*Optional*): Attributes that can be overwritten. Possible entries are *is_volume_muted*, *state*, *source*, *source_list, and *volume_level*. The values should be an entity id and state attribute separated by a bar (\|). If the entity id's state should be used, then only the entity id should be provided.
5657
57-
The universal media player will primarily imitate one of its *children*. The first child in the list that is active (not idle/off) will be controlled the universal media player. The universal media player will also inherit its state from the first active child. Entities in the *children* list must be media players.
58+
The Universal Media Player will primarily imitate one of its *children*. The Universal Media Player will control the first child on the list that is active (not idle/off). The Universal Media Player will also inherit its state from the first active child if a `state_template` is not provided. Entities in the *children* list must be media players, but the state template can contain any entity.
5859

59-
It is recommended that the command *turn_on*, the command *turn_off*, and the attribute *state* all be provided together. The *state* attribute indicates if the Media Player is on or off. If *state* indicates the media player is off, this status will take precedent over the states of the children. If all the children are idle/off and *state* is on, the universal media player's state will be on.
60+
It is recommended that the command *turn_on*, the command *turn_off*, and the attribute *state* all be provided together. The *state* attribute indicates if the Media Player is on or off. If *state* indicates the media player is off, this status will take precedence over the states of the children. If all the children are idle/off and *state* is on, the Universal Media Player's state will be on.
6061

6162
It is also recommended that the command *volume_up*, the command *volume_down*, the command *volume_mute*, and the attribute *is_volume_muted* all be provided together. The attribute *is_volume_muted* should return either True or the on state when the volume is muted. The *volume_mute* service should toggle the mute setting.
6263

6364
When providing *select_source* as a command, it is recommended to also provide the attributes *source*, and *source_list*. The *source* attribute is the currently select source, while the *source_list* attribute is a list of all available sources.
6465

65-
Below is an example configuration.
66+
## {% linkable_title Usage examples %}
67+
68+
#### {% linkable_title Chromecast & Kodi control with switches %}
69+
70+
In this example, a switch is available to control the power of the television. Switches are also available to turn the volume up, turn the volume down, and mute the audio. These could be command line switches or any other entity in Home Assistant. The *turn_on* and *turn_off* commands will be redirected to the television, and the volume commands will be redirected to an audio receiver. The *select_source* command will be passed directly to an A/V receiver.
71+
72+
The children are a Chromecast and a Kodi player. If the Chromecast is playing, the Universal Media Player will reflect its status. If the Chromecast is idle and Kodi is playing, the Universal Media player will change to reflect its status.
73+
6674

6775
```yaml
6876
media_player:
@@ -112,6 +120,107 @@ media_player:
112120
113121
```
114122

115-
In this example, a switch is available to control the power of the television. Switches are also available to turn the volume up, turn the volume down, and mute the audio. These could be command line switches or any other entity in Home Assistant. The *turn_on* and *turn_off* commands will be redirected to the television and the volume commands will be redirected to an audio receiver. The *select_source* command will be passed directly to an A/V receiver.
123+
#### {% linkable_title Kodi CEC-TV control %}
116124

117-
The children are a Chromecast and a Kodi player. If the Chromecast is playing, the Universal Media Player will reflect its status. If the Chromecast is idle and Kodi is playing, the Universal Media player will change to reflect its status.
125+
In this example, a [Kodi Media Player](/components/media_player.kodi/) runs in a CEC capable device (OSMC/OpenElec running in a Raspberry Pi 24/7, for example), and, with the JSON-CEC Kodi addon installed, it can turn on and off the attached TV.
126+
127+
We store the state of the attached TV in a hidden [Input Boolean](/components/input_boolean/), so we can differentiate the TV being on or off, while Kodi is always 'idle', and use the Universal Media Player to render its state with a template. We can hide the Kodi Media Player too, and only show the universal one, which now can differentiate between the 'idle' and the 'off' state (being the second when it is idle and the TV is off).
128+
129+
Because the Input Boolean used to store the TV state is only changing when using the Home Assistant `turn_on` and `turn_off` actions, and Kodi could be controlled by so many ways, we also define some automations to update this Input Boolean when needed.
130+
131+
In an Apple HomeKit scene, we can now expose this Universal Media Player as an on/off switch in Homebridge, and, that way, use Siri to turn on and off the TV.
132+
133+
The complete yaml config is:
134+
135+
```yaml
136+
homeassistant:
137+
customize:
138+
input_boolean.kodi_tv_state:
139+
hidden: true
140+
homebridge_hidden: true
141+
media_player.kodi:
142+
hidden: true
143+
homebridge_hidden: true
144+
media_player.kodi_tv:
145+
friendly_name: Kodi
146+
homebridge_name: Kodi
147+
homebridge_media_player_switch: on_off
148+
149+
input_boolean:
150+
kodi_tv_state:
151+
152+
media_player:
153+
- platform: universal
154+
name: Kodi TV
155+
state_template: >
156+
{% raw %}{% if (is_state('media_player.kodi', 'idle') and (is_state('input_boolean.kodi_tv_state', 'off') %}
157+
off
158+
{% else %}
159+
{{ states('media_player.kodi') }}
160+
{% endif %}{% endraw %}
161+
children:
162+
- media_player.kodi
163+
commands:
164+
turn_on:
165+
service: media_player.turn_on
166+
data:
167+
entity_id: media_player.kodi
168+
turn_off:
169+
service: media_player.turn_off
170+
data:
171+
entity_id: media_player.kodi
172+
attributes:
173+
is_volume_muted: media_player.kodi|is_volume_muted
174+
volume_level: media_player.kodi|volume_level
175+
176+
- platform: kodi
177+
name: Kodi
178+
host: 192.168.1.10
179+
turn_on_action:
180+
- service: input_boolean.turn_on
181+
data:
182+
entity_id: input_boolean.kodi_tv_state
183+
- service: media_player.kodi_call_method
184+
data:
185+
entity_id: media_player.kodi
186+
method: Addons.ExecuteAddon
187+
addonid: script.json-cec
188+
params:
189+
command: activate
190+
turn_off_action:
191+
- service: input_boolean.turn_off
192+
data:
193+
entity_id: input_boolean.kodi_tv_state
194+
- service: media_player.media_stop
195+
data:
196+
entity_id: media_player.kodi
197+
- service: media_player.kodi_call_method
198+
data:
199+
entity_id: media_player.kodi
200+
method: Addons.ExecuteAddon
201+
addonid: script.json-cec
202+
params:
203+
command: standby
204+
205+
automation:
206+
- alias: Turn on the TV when Kodi is activated
207+
trigger:
208+
platform: state
209+
entity_id: media_player.kodi_tv
210+
from: 'off'
211+
to: 'playing'
212+
action:
213+
- service: media_player.turn_on
214+
entity_id: media_player.kodi_tv
215+
216+
- alias: Turn off the TV when Kodi is in idle > 15 min
217+
trigger:
218+
platform: state
219+
entity_id: media_player.kodi_tv
220+
to: 'idle'
221+
for:
222+
minutes: 15
223+
action:
224+
- service: media_player.turn_off
225+
entity_id: media_player.kodi_tv
226+
```

0 commit comments

Comments
 (0)