Skip to content

Commit 14ecb68

Browse files
robbiet480robbiet480
authored
Merge pull request home-assistant#2094 from JesseWebDotCom/plex-documentation
Plex improvements
2 parents 3e6bbbb + 932f8b0 commit 14ecb68

File tree

1 file changed

+83
-10
lines changed

1 file changed

+83
-10
lines changed

‎source/_components/media_player.plex.markdown

Lines changed: 83 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,13 @@ ha_iot_class: "Local Polling"
1515
---
1616

1717

18-
The `plex` platform allows you to connect a [Plex Media Server](https://plex.tv) to Home Assistant. It will allow you to control media playback and see the current playing item. The preferred way to setup the Plex platform is by enabling the [the discovery component](/components/discovery/) and requires GDM to be enabled.
18+
The `plex` platform allows you to connect a [Plex Media Server](https://plex.tv) to Home Assistant. It will allow you to control media playback and see the current playing item.
1919

20-
If local authentication is enabled or multiple users are defined, Home Assistant requires an authentication token to be entered in the frontend. Press "CONFIGURE" to do it.
20+
## Setup
21+
22+
The preferred way to setup the Plex platform is by enabling the [discovery component](/components/discovery/) which requires GDM enabled on your Plex server.
23+
24+
If your Plex server has local authentication enabled or multiple users defined, Home Assistant requires an authentication token to be entered in the frontend. Press "CONFIGURE" to do it.
2125

2226
<p class='img'>
2327
<img src='{{site_root}}/images/screenshots/plex-configure.png' />
@@ -29,7 +33,7 @@ If you don't know your token, see [Finding your account token / X-Plex-Token](ht
2933
<img src='{{site_root}}/images/screenshots/plex-token.png' />
3034
</p>
3135

32-
If you want to enable the plex platform directly, add the following lines to your `configuration.yaml`:
36+
You can also enable the plex platform directly by adding the following lines to your `configuration.yaml`:
3337

3438
```yaml
3539
# Example configuration.yaml entry
@@ -47,13 +51,82 @@ In case [discovery](/components/discovery/) does not work (GDM disabled or non-l
4751
- **PORT** (*Required*): Port where Plex is listening. Default is 32400
4852
- **TOKEN** (*Optional*): Only if authentication is required. Set to `null` (without quotes) otherwise.
4953

50-
At this moment, the Plex platform only supports one Plex Media Server.
54+
## Customization
55+
You can customize the Plex component by adding any of the variables below to your configuration:
56+
```yaml
57+
# Example configuration.yaml entry
58+
media_player:
59+
- platform: plex
60+
entity_namespace: 'plex'
61+
include_non_clients: true
62+
scan_interval: 5
63+
show_all_controls: false
64+
use_custom_entity_ids: true
65+
use_episode_art: true
66+
```
67+
- **entity_namespace** (*Optional*): Prefix for entity ID's. Defaults to `null`. Useful when using overlapping components (ex. Apple TV and Plex components when you have Apple TV's you use as Plex clients). Go from _media_player.playroom2_ to _media_player.plex_playroom_
68+
- **include_non_clients** (*Optional*): Display non-recontrollable clients (ex. remote clients, PlexConnect Apple TV's). Defaults to `false`.
69+
- **scan_interval** (*Optional*): Amount in seconds in between polling for device’s current activity. Defaults to `10` seconds.
70+
- **show_all_controls** (*Optional*): Forces all controls to display. Defaults to `false`. Ignores dynamic controls (ex. show volume controls for client A but not for client B) based on detected client capabilities. This option allows you to override this detection if you suspect it to be incorrect.
71+
- **use_custom_entity_ids** (*Optional*): Name Entity ID's by client ID's instead of friendly names. Defaults to `false`. HA assigns entity ID's on a first come first serve basis. When you have identically named devices connecting (ex. media_player.plex_web_safari, media_player.plex_web_safari2), you can't reliably distinguish and or predict which device is which. This option avoids this issue by using unique client ID's (ex. media_player.dy4hdna2drhn).
72+
- **use_episode_art** (*Optional*): Display TV episode art instead of TV show art. Defaults to `false`.
5173

52-
It is possible to get errors that look like the following.
74+
### {% linkable_title Service `play_media` %}
5375

54-
```
55-
ERROR:plexapi:http://192.168.1.10:32400: ('Connection aborted.', BadStatusLine("''",))
56-
INFO:homeassistant.components.media_player.plex:No server found at: http://192.168.1.10:32400
57-
```
76+
Plays a song, playlist, TV episode, or video on a connected client.
77+
78+
#### Music
79+
80+
| Service data attribute | Optional | Description | Example |
81+
| ---------------------- | -------- | ----------- | ----------- |
82+
| `entity_id` | no | `entity_id` of the client | media_player.theater_plex |
83+
| `media_content_id` | no | Quote escaped JSON with `library_name`, `artist_name`, `album_name`, `track_name`, `shuffle` (0 or 1). | { \\"library_name\\" : \\"My Music\\", \\"artist_name\\" : \\"Adele\\", \\"album_name\\" : \\"25\\", \\"track_name\\" : \\"hello\\", \\"shuffle\\": \\"0\\" } |
84+
| `media_content_type` | no | Type of media to play, in this case `MUSIC` | MUSIC |
85+
86+
#### Playlist
87+
88+
| Service data attribute | Optional | Description | Example |
89+
| ---------------------- | -------- | ----------- | ----------- |
90+
| `entity_id` | no | `entity_id` of the client | media_player.theater_plex |
91+
| `media_content_id` | no | Quote escaped JSON with `playlist_name`, `shuffle` (0 or 1). | { \\"playlist_name\\" : \\"The Best of Disco\\" \\"shuffle\\": \\"0\\" } |
92+
| `media_content_type` | no | Type of media to play, in this case `PLAYLIST` | PLAYLIST |
93+
94+
#### TV Episode
95+
96+
| Service data attribute | Optional | Description | Example |
97+
| ---------------------- | -------- | ----------- | ----------- |
98+
| `entity_id` | no | `entity_id` of the client | media_player.theater_plex |
99+
| `media_content_id` | no | Quote escaped JSON with `library_name`, `show_name`, `season_number`, `episode_number`, `shuffle` (0 or 1). | { \\"library_name\\" : \\"Adult TV\\", \\"show_name\\" : \\"Rick and Morty\\", \\"season_number\\" : 2, \\"episode_number\\" : 5, \\"shuffle\\": \\"0\\" } |
100+
| `media_content_type` | no | Type of media to play, in this case `EPISODE` | EPISODE |
101+
102+
#### Video
103+
104+
| Service data attribute | Optional | Description | Example |
105+
| ---------------------- | -------- | ----------- | ----------- |
106+
| `entity_id` | no | `entity_id` of the client | media_player.theater_plex |
107+
| `media_content_id` | no | Quote escaped JSON with `library_name`, `video_name`, `shuffle` (0 or 1). | { \\"library_name\\" : \\"Adult Movies\\", \\"video_name\\" : \\"Blade\\", \\"shuffle\\": \\"0\\" } |
108+
| `media_content_type` | no | Type of media to play, in this case `VIDEO` | VIDEO |
109+
110+
### Compatibility
111+
112+
| Client | Limitations |
113+
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
114+
| Any (when all controls disabled) | A stop button will appear but is not functional. |
115+
| Any (when casting) | Controlling playback will work but with error logging. |
116+
| Any (remote client) | Controls disabled. |
117+
| Apple TV (PlexConnect) | Controls disabled. Music does not work. |
118+
| iOS | None |
119+
| NVidia Shield | Mute disabled. Volume set below 2 will cause error logging. Controlling playback when the Shield is both a client and a server will work but with error logging |
120+
| Plex Web | None |
121+
| Tivo Plex App | Only play, pause, stop/off controls enabled |
122+
123+
### Notes
124+
* At this moment, the Plex platform only supports one Plex Media Server.
125+
* It is possible to get errors that look like the following.
126+
127+
```
128+
ERROR:plexapi:http://192.168.1.10:32400: ('Connection aborted.', BadStatusLine("''",))
129+
INFO:homeassistant.components.media_player.plex:No server found at: http://192.168.1.10:32400
130+
```
58131
59-
If this occurs, try changing the setting `Secure connections` in your Plex Media Server to `Preferred` (instead of `Required`). The Plex component does not currently support HTTPS.
132+
If this occurs, try changing the setting `Secure connections` in your Plex Media Server to `Preferred` (instead of `Required`). The Plex component does not currently support HTTPS.

0 commit comments

Comments
 (0)