diff --git a/source/_integrations/apple_tv.markdown b/source/_integrations/apple_tv.markdown index 584e160a374..aa350e296f2 100644 --- a/source/_integrations/apple_tv.markdown +++ b/source/_integrations/apple_tv.markdown @@ -10,30 +10,120 @@ ha_release: 0.49 ha_domain: apple_tv ha_codeowners: - '@postlund' + - '@wizbangcrash' ha_config_flow: true ha_zeroconf: true ha_platforms: - remote --- -The Apple TV integration allows you to control an Apple TV (any generation). See the -[remote platform](/integrations/apple_tv#remote) if you want to send remote control buttons, -e.g., arrow keys. +The Apple TV integration allows you to control an Apple TV (any generation). -There is currently support for the following device types within Home Assistant: +There is currently support for the following entities within the Apple TV device: -- Media Player +- [Media Player](#media_player) - [Remote](#remote) {% include integrations/config_flow.md %} +## Media Player + +The Apple TV media player platform will create a Media Player entity for each +Apple TV discovered on your network. +This entity will display the active app and playback controls. + +## Remote + +The Apple TV remote platform will automatically create a Remote entity for each Apple TV +configured on to your Home Assistant instance. +These entities allow you to turn the device on/off and to send control commands. + +The following commands are currently available: + +- `wakeup` +- `home` +- `home_hold` +- `top_menu` +- `menu` +- `select` +- `up` +- `down` +- `left` +- `right` +- `volume_up` +- `volume_down` + +**NOTE:** Not all commands are supported by all Apple TV versions + +### Service `send_command` + +| Service data
attribute | Optional | Description | +| ------------------------- | -------- | ------------ | +| `entity_id` | no | `entity_id` of the Apple TV | +| `command` | no | Command, or list of commands to be sent | +| `num_repeats` | yes | Number of times to repeat the commands | +| `delay_secs` | yes | Interval in seconds between one send and another
This is a `float` value e.g. 1, 1.2 etc. | + +**Examples** + +Create a script to invoke the Netflix application based on the application icon +being in a fixed place on the home screen: + +```yaml +lounge_appletv_netflix: + alias: "Select Netflix" + sequence: + - service: remote.send_command + target: + entity_id: remote.lounge_appletv + data: + delay_secs: 1.5 + command: + - top_menu + - home + - right + - select +``` + +Script using the `home_hold` command to send your Apple TV to sleep and turn off +the Media Player: + +```yaml +apple_tv_sleep: + alias: "Make the Apple TV sleep" + sequence: + - service: remote.send_command + target: + entity_id: remote.lounge_appletv + data: + delay_secs: 1 + command: + - home_hold + - select + - service: media_player.turn_off + target: + entity_id: media_player.lounge_appletv +``` + +Send 3 `left` commands with delay between each: + +```yaml +service: remote.send_command +target: + entity_id: remote.apple_tv +data: + num_repeats: 3 + delay_secs: 2.5 + command: + - left +``` ## FAQ ### My Apple TV does not turn on/off when I press on/off in the frontend -That is correct; it only toggles the power state in Home Assistant. Turning the device on or off is -currently not supported. However, support for this is in development so that it will be added at some -point in the future +That is correct; it only toggles the power state in Home Assistant. See the +example above to use the `home_hold` command. This can be used on Apple TVs +running tvOS 14.0 or later. ### Is it possible to see if a device is on without interacting with it @@ -45,7 +135,7 @@ This can happen when pairing the AirPlay protocol in case the access settings ar Apple TV, navigate to Settings, find the AirPlay menu and make sure that the access setting is set to "Everyone on the same network" and try again. -### The buttons (play, pause, etc.) does not work +### The buttons (play, pause, etc.) do not work The tvOS apps themselves decide what commands they support and when they support them. Likely, the app you are using does not support the action you are trying @@ -59,39 +149,6 @@ and include logs (see Debugging below). The Apple TV is quite picky when it comes to which formats it plays. The best bet is MP4. If it doesn't work, it's likely because of the media format. -## Remote - -The `apple_tv` remote platform allows you to send remote control buttons to an Apple TV. It is -automatically set up when an Apple TV is configured. - -At the moment, the following buttons are available (but not necessarily supported by all devices): - -- `up` -- `down` -- `left` -- `right` -- `menu` -- `top_menu` -- `select` -- `volume_up` -- `volume_down` -- `home` -- `home_hold` - -A typical service call for press several buttons looks like this. - -```yaml -service: remote.send_command -target: - entity_id: remote.apple_tv -data: - command: - - left - - left - - menu - - select -``` - ## Debugging If you have any problems and intend to write an issue, make sure you have the