diff --git a/source/_components/media_player.plex.markdown b/source/_components/media_player.plex.markdown index 8ac957ebcf7..f7184f07a68 100644 --- a/source/_components/media_player.plex.markdown +++ b/source/_components/media_player.plex.markdown @@ -15,9 +15,13 @@ ha_iot_class: "Local Polling" --- -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. +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. -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. +## Setup + +The preferred way to setup the Plex platform is by enabling the [discovery component](/components/discovery/) which requires GDM enabled on your Plex server. + +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.

@@ -29,7 +33,7 @@ If you don't know your token, see [Finding your account token / X-Plex-Token](ht

-If you want to enable the plex platform directly, add the following lines to your `configuration.yaml`: +You can also enable the plex platform directly by adding the following lines to your `configuration.yaml`: ```yaml # Example configuration.yaml entry @@ -47,13 +51,82 @@ In case [discovery](/components/discovery/) does not work (GDM disabled or non-l - **PORT** (*Required*): Port where Plex is listening. Default is 32400 - **TOKEN** (*Optional*): Only if authentication is required. Set to `null` (without quotes) otherwise. -At this moment, the Plex platform only supports one Plex Media Server. - -It is possible to get errors that look like the following. - -``` -ERROR:plexapi:http://192.168.1.10:32400: ('Connection aborted.', BadStatusLine("''",)) -INFO:homeassistant.components.media_player.plex:No server found at: http://192.168.1.10:32400 +## Customization +You can customize the Plex component by adding any of the variables below to your configuration: +```yaml +# Example configuration.yaml entry +media_player: + - platform: plex + entity_namespace: 'plex' + include_non_clients: true + scan_interval: 5 + show_all_controls: false + use_custom_entity_ids: true + use_episode_art: true ``` +- **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_ +- **include_non_clients** (*Optional*): Display non-recontrollable clients (ex. remote clients, PlexConnect Apple TV's). Defaults to `false`. +- **scan_interval** (*Optional*): Amount in seconds in between polling for device’s current activity. Defaults to `10` seconds. +- **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. +- **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). +- **use_episode_art** (*Optional*): Display TV episode art instead of TV show art. Defaults to `false`. -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. +### {% linkable_title Service `play_media` %} + +Plays a song, playlist, TV episode, or video on a connected client. + +#### Music + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | ----------- | +| `entity_id` | no | `entity_id` of the client | media_player.theater_plex | +| `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\\" } | +| `media_content_type` | no | Type of media to play, in this case `MUSIC` | MUSIC | + +#### Playlist + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | ----------- | +| `entity_id` | no | `entity_id` of the client | media_player.theater_plex | +| `media_content_id` | no | Quote escaped JSON with `playlist_name`, `shuffle` (0 or 1). | { \\"playlist_name\\" : \\"The Best of Disco\\" \\"shuffle\\": \\"0\\" } | +| `media_content_type` | no | Type of media to play, in this case `PLAYLIST` | PLAYLIST | + +#### TV Episode + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | ----------- | +| `entity_id` | no | `entity_id` of the client | media_player.theater_plex | +| `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\\" } | +| `media_content_type` | no | Type of media to play, in this case `EPISODE` | EPISODE | + +#### Video + +| Service data attribute | Optional | Description | Example | +| ---------------------- | -------- | ----------- | ----------- | +| `entity_id` | no | `entity_id` of the client | media_player.theater_plex | +| `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\\" } | +| `media_content_type` | no | Type of media to play, in this case `VIDEO` | VIDEO | + +### Compatibility + +| Client | Limitations | +|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Any (when all controls disabled) | A stop button will appear but is not functional. | +| Any (when casting) | Controlling playback will work but with error logging. | +| Any (remote client) | Controls disabled. | +| Apple TV (PlexConnect) | Controls disabled. Music does not work. | +| iOS | None | +| 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 | +| Plex Web | None | +| Tivo Plex App | Only play, pause, stop/off controls enabled | + +### Notes +* At this moment, the Plex platform only supports one Plex Media Server. +* It is possible to get errors that look like the following. + + ``` + ERROR:plexapi:http://192.168.1.10:32400: ('Connection aborted.', BadStatusLine("''",)) + INFO:homeassistant.components.media_player.plex:No server found at: http://192.168.1.10:32400 + ``` + + 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.