Improve Roku documentation (#36247)

* improve roku documentation

* Update roku.markdown

* Update roku.markdown

* Update roku.markdown

* Update roku.markdown

* Update roku.markdown

* Tiny tweaks

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
This commit is contained in:
Chris Talkington 2024-12-10 00:39:31 -06:00 committed by GitHub
parent 4d3af1c7c9
commit a64a38ef69
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -26,7 +26,7 @@ ha_platforms:
ha_integration_type: device
---
The Roku integration allows you to control a [Roku](https://www.roku.com/) device.
The Roku integration allows you to control a [Roku](https://www.roku.com/) media playback device. This integration only supports Roku media playback devices (such as sticks, streaming boxes, and televisions). All other smart home products (such as light bulbs and cameras) are part of a different ecosystem.
{% include integrations/config_flow.md %}
@ -34,16 +34,50 @@ When adding the integration, you will be asked to provide a {% term host %}. Unl
If you are having issues connecting, you may have to adjust the settings on your Roku device to allow local control. The common setting is: `Settings / System / Advanced / Control by mobile apps / Network access`
There is currently support for the following device types within Home Assistant:
{% include integrations/option_flow.md %}
- Media player
- Remote
{% configuration_basic %}
Play Media Application ID:
description: The application ID to use when launching media playback. The default is `15985`. This application must support the PlayOnRoku API.
{% endconfiguration_basic %}
## Remote
## Data updates
The `roku` remote platform allows you to send remote control buttons to a Roku device. It is automatically set up when a Roku is configured.
The Roku integration polls every 10 seconds to check the current state of media playback. The available applications and television channels are only fetched every 15 minutes.
At the moment, the following buttons are supported:
## Supported functionality
### Entities
The Roku integration provides the following entities.
#### Binary sensor
- **Headphones connected sensor**
- **Description**: The headphones connected sensor will tell if you if the device has headphones connected for private listening.
- **Available for devices**: All
- **Supports AirPlay sensor**
- **Description**: The supports AirPlay sensor will tell if the device is capable of accepting AirPlay connections.
- **Available for devices**: All
- **Supports Ethernet sensor**
- **Description**: The supports Ethernet sensor will tell if the device is capable of being connected via an Ethernet cable.
- **Available for devices**: All
- **Supports find remote sensor**
- **Description**: The supports find remote sensor will tell if the device is capable of the find remote feature.
- **Available for devices**: All
#### Media player
The integration allows for media playback control including power and source control. It also supports the ability to select sources such as text-to-speech and Camera via "Browse Media".
#### Remote
The integration allows you to send remote control commands. It is automatically set up for all devices.
The following commands are currently supported depending on device type and manufacturer support:
- back
- backspace
@ -64,7 +98,7 @@ At the moment, the following buttons are supported:
- left
- literal
- play
- power
- power
- replay
- reverse
- right
@ -75,7 +109,7 @@ At the moment, the following buttons are supported:
- volume_mute
- volume_up
A typical action for pressing several buttons looks like this.
##### Example
```yaml
action: remote.send_command
@ -88,27 +122,36 @@ data:
- select
```
## Media player
#### Select
When the Home Assistant Roku integration is enabled and a Roku device has been configured, in the Home Assistant UI the Roku media player will show a listing of the installed channels, or apps, under “source”. Select one and it will attempt to launch the channel on your Roku device.
- **Application control**
- **Description**: The application select control allows changing the active application.
- **Available for devices**: All
{% include integrations/option_flow.md %}
- **Channel control**
- **Description**: The channel select control allows changing the active television channel.
- **Available for devices**: Only available for Roku TV devices.
{% configuration_basic %}
Play Media Application ID:
description: The application ID to use when launching media playback. This application must support the PlayOnRoku API.
{% endconfiguration_basic %}
#### Sensor
## Source Automation
- **Active app sensor**
- **Description**: The active app sensor will tell you the name of the active application.
- **Available for devices**: All
The `media_player.select_source` action may be used to launch specific applications/streaming channels on your Roku device.
- **Active app ID sensor**
- **Description**: The active app ID sensor will tell you the ID of the active application.
- **Available for devices**: All
### Source automation
The `media_player.select_source` action may be used to launch specific applications on your Roku device.
| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | ------- |
| `entity_id` | no | Target a specific media player. |
| `source` | no | An application name or application ID. | Prime Video
### Examples
#### Examples
```yaml
actions:
@ -130,13 +173,7 @@ actions:
source: 20197
```
### Obtaining Application IDs
The currently active application ID can be found in the `Active App ID` diagnostic sensor.
Alternatively, you can make a manual HTTP request (GET) to `http://ROKU_IP:8060/query/apps`, in either your browser or terminal, to retrieve a complete list of installed applications in XML format.
## TV Channel Tuning
### TV channel tuning
The `media_player.play_media` action may be used to tune to specific channels on your Roku TV device with OTA antenna.
@ -146,7 +183,7 @@ The `media_player.play_media` action may be used to tune to specific channels on
| `media_content_id` | no | A channel number. | 5.1
| `media_content_type` | no | A media type. | `channel`
### Example
#### Example
```yaml
actions:
@ -158,11 +195,11 @@ actions:
media_content_type: channel
```
## Play on Roku
### Play on Roku
The `media_player.play_media` action may be used to send media URLs (primarily videos) for direct playback on your device.
This feature makes use of the PlayOnRoku API. If you are using an older Roku OS (pre-11.5), the defaults of this integration should just work. Alternatively, you can configure a third-party application that supports the PlayOnRoku API via the `Play Media Roku Application ID` option.
This feature makes use of the PlayOnRoku API. If you are using an older Roku OS (pre-11.5), the defaults of this integration should just work with the configuration defaults. Alternatively, you can configure a third-party application that supports the PlayOnRoku API via the `Play Media Roku Application ID` option.
The following third-party applications have been tested with this integration:
@ -178,7 +215,7 @@ The following third-party applications have been tested with this integration:
| `extra.thumbnail` | yes | A thumbnail URL for the media. |
| `extra.artist_name` | yes | The name of the media artist. | Blender
### Example
#### Example
```yaml
actions:
- action: media_player.play_media
@ -190,25 +227,11 @@ actions:
extra:
format: "mp4"
name: "Big Buck Bunny"
```
```
## Camera Stream Integration
### Content deeplinking
The `camera.play_stream` action may be used to send camera streams (HLS) directly to your device. This feature requires the [`stream` integration](/integrations/stream) and makes use of the PlayOnRoku API.
### Example
```yaml
actions:
- action: camera.play_stream
target:
entity_id: camera.camera
data:
media_player: media_player.roku
```
## Content Deeplinking
The `media_player.play_media` action may be used to deep-link to content within an application.
The `media_player.play_media` action may be used to deep-link to content within a channel application using content IDs. See [Obtaining Content IDs](#obtaining-content-ids) to learn more about content IDs.
| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | ------- |
@ -218,7 +241,7 @@ The `media_player.play_media` action may be used to deep-link to content within
| `extra.content_id` | no | A unique content identifier passed to app. | 8e06a8b7-d667-4e31-939d-f40a6dd78a88
| `extra.media_type` | no | A media type passed to app. Should be one of `movie`, `episode`, `season`, `series`, `shortFormVideo`, `special`, `live` | movie
### Example
#### Example
```yaml
actions:
@ -233,7 +256,43 @@ actions:
media_type: movie
```
### Obtaining Content IDs
### Camera stream integration
The `camera.play_stream` action may be used to send camera streams (HLS) directly to your device. This feature requires the [`stream` integration](/integrations/stream) and makes use of the PlayOnRoku API.
#### Example
```yaml
actions:
- action: camera.play_stream
target:
entity_id: camera.camera
data:
media_player: media_player.roku
```
### Additional actions
The integration exposes additional actions to control a Roku device.
#### Action `roku.search`
This action allows you to emulate opening the search screen and entering the search keyword.
| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | ------- |
| `entity_id` | yes | The entities to search on. | media_player.roku
| `keyword` | no | The keyword to search for. | Space Jam
## Tips and tricks
### Obtaining application IDs
The currently active application ID can be found in the `Active App ID` diagnostic sensor.
Alternatively, you can make a manual HTTP request (GET) to `http://ROKU_IP:8060/query/apps`, in either your browser or terminal, to retrieve a complete list of installed applications in XML format.
### Obtaining content IDs
Content IDs are unique to each streaming service and vary in format but are often part of the video webpage URL. Here are some examples:
@ -244,13 +303,14 @@ Content IDs are unique to each streaming service and vary in format but are ofte
| Spotify | 22297 | open.spotify.com/playlist/5xddIVAtLrZKtt4YGLM1SQ | spotify:playlist:5xddIVAtLrZKtt4YGLM1SQ | playlist
| YouTube | 837 | youtu.be/6ZMXE5PXPqU | 6ZMXE5PXPqU | live
## Actions
## Known limitations
### Action `roku.search`
Roku has been known to remove or restrict local control functionality as part of major Roku OS upgrades. As such devices may become less functional after an upgrade.
This action allows you to emulate opening the search screen and entering the search keyword.
Roku channels, such as YouTube, are maintained by third-parties and as such the availability of features like Content Deeplinking are subject to change without notice.
| Data attribute | Optional | Description | Example |
| ---------------------- | -------- | ----------- | ------- |
| `entity_id` | yes | The entities to search on. | media_player.roku
| `keyword` | no | The keyword to search for. | Space Jam
## Removing the integration
This integration can be removed by following these steps:
{% include integrations/remove_device_service.md %}