Skip to content

Update Plex docs for config flow changes #10238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jjlawren wants to merge 1 commit into from
Closed

Update Plex docs for config flow changes #10238

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 38 additions & 130 deletions source/_components/plex.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,108 +14,76 @@ redirect_from:
---


The `plex` platform allows you to connect to a [Plex Media Server](https://plex.tv). Once connected, [Plex Clients](https://www.plex.tv/apps-devices/) playing media from the connected Plex Media Server will show up as [Media Players](/components/media_player/) in Home Assistant. It will allow you to control media playback and see the current playing item.
The `plex` platform allows you to connect to a [Plex Media Server](https://plex.tv). Once connected, [Plex Clients](https://www.plex.tv/apps-devices/) playing media from the connected Plex Media Server will show up as [Media Players](/components/media_player/) or report playback status via a [Sensor](/components/sensor/) in Home Assistant. The Media Players will allow you to control media playback and see the current playing item.

There is currently support for the following device types within Home Assistant:

- [Media Player](#setup---media-player)
- [Sensor](#sensor)
- [Media Player](#media-player)

## Setup - Media Player
## 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. This can be found on your Plex Web App under Settings > (server Name) > settings > Network and choose "Enable local network discovery (GDM)".
Home Assistant offers Plex integration through **Configuration** -> **Integrations** -> **Plex**. Creating a Plex integration will automatically enable both the `media_player` and `sensor` platforms. For legacy support, existing `media_player` and `sensor` configurations are automatically imported and set up as new integrations.

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.
If your Plex server has been claimed by a Plex account via the [claim interface](https://plex.tv/claim), Home Assistant will require an authentication token to connect. If you don't know your token, see [Finding your account token / X-Plex-Token](https://support.plex.tv/hc/en-us/articles/204059436).

<p class='img'>
<img src='{{site_root}}/images/screenshots/plex-configure.png' />
</p>
When adding a Plex integration, providing this token is usually enough for automatic setup. If multiple servers have been claimed by the account associated with the token, you will be prompted to select one to monitor. If you would like to monitor multiple servers linked to the same account, simply set up an additional Plex integration.

To authorize your device, you'll first need to [click here to claim a token](https://plex.tv/claim).

If your server enforces SSL connections, write "`on`" or "`true`" in the _"Use SSL"_ field. If it does not have a valid SSL certificate available but you still want to use it, write "`on`" or "`true`" in the _"Do not verify SSL"_ field as well.

<p class='img'>
<img src='{{site_root}}/images/screenshots/plex-token.png' />
</p>

You can also enable the plex platform directly by adding the following lines to your `configuration.yaml`:

```yaml
# Example configuration.yaml entry
media_player:
- platform: plex
```

In the event that [discovery](/components/discovery/) does not work (GDM disabled or non-local Plex server), you can manually create a `plex.conf` file manually and place it in your [configuration directory ](/docs/configuration/) or `/config/` if you are running Hass.io. The following is an example of `plex.conf`:

```json
{"IP_ADDRESS:PORT": {"token": "TOKEN", "ssl": false, "verify": true}}
```
The Plex platform will offer to set up a local server by enabling the [discovery component](/components/discovery/) which requires GDM enabled on your Plex server. This can be enabled via your Plex Web App under **Settings** -> **(Server Name)** -> **Settings** -> **Network** and choosing "Enable local network discovery (GDM)".

{% configuration %}
IP_ADDRESS:
description: IP address of the Plex Media Server.
required: true
Host:
description: Hostname or IP address of the Plex Media Server.
type: string
PORT:
description: Port where Plex is listening.
required: true
Port:
description: Port where Plex server is listening.
default: 32400
type: integer
TOKEN:
description: Only if authentication is required. Set to `null` (without quotes) otherwise.
required: false
type: string
ssl:
description: Whether to use SSL/TLS or not.
required: false
default: "`false`"
Use SSL:
description: Enable to use HTTPS connections to the server.
default: false
type: boolean
verify:
description: Perform a verification of the certificate. To allow invalid or self-signed SSL certificates set it to `false`.
required: false
default: "`true`"
Verify SSL certificate:
description: Perform a verification of the certificate. Uncheck to allow invalid or self-signed certificates.
default: true
type: boolean
Token:
description: Provide if authentication is required. Also known as `X-Plex-Token`.
type: string
required: false
{% endconfiguration %}

### Customization

You can customize the Plex integration by adding any of the variables below to your configuration:
You can customize each Plex integration by selecting it and opening the options panel represented by the gear icon in the top-right of the interface. Here you can enable/disable each of the `media_player` and `sensor` platforms per integration.

```yaml
# Example configuration.yaml entry
media_player:
- platform: plex
show_all_controls: false
use_episode_art: true
remove_unavailable_clients: true
client_remove_interval: 600
```
Additional options for the `media_player` platform:

{% configuration %}
show_all_controls:
description: "Forces all controls to display. 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."
required: false
Use episode art:
description: Display TV episode art instead of TV show art.
default: false
type: boolean
use_episode_art:
description: Display TV episode art instead of TV show art.
required: false
Show all controls:
description: Forces all controls to display. 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.
default: false
type: boolean
remove_unavailable_clients:
description: Remove stale plex clients from UI after interval.
required: false
Remove unavailable clients:
description: Remove stale Plex clients from UI after interval.
default: true
type: boolean
client_remove_interval:
description: How long a client is to be unavailable for before it is cleaned up in seconds.
required: false
Client remove interval:
description: How long a client is to be unavailable for before it is removed. Measured in seconds.
default: 600
type: integer
{% endconfiguration %}

## Sensor

The `plex` sensor platform will monitor activity on a given [Plex Media Server](https://plex.tv/). It will create a sensor that shows the number of currently watching users as the state. If you click the sensor for more details it will show you who is watching what.

## Media Player

### Service `play_media`

Plays a song, playlist, TV episode, or video on a connected client.
Expand Down Expand Up @@ -167,7 +135,7 @@ Plays a song, playlist, TV episode, or video on a connected client.

### Notes

* At this moment, the Plex platform only supports one Plex Media Server.
* The Plex platform supports multiple Plex Media Servers via configuring multiple Plex integrations.
* It is possible to get errors that look like the following.

```
Expand All @@ -177,63 +145,3 @@ Plays a song, playlist, TV episode, or video on a connected client.

If this occurs, check the setting `Server`>`Network`>`Secure connections` on your Plex Media Server: if it is set to `Preferred` or `Required`, you may need to manually set the `ssl` and `verify` booleans in the `plex.conf` file to, respectively, `true` and `false`. See the **"Setup"** section above for details.
* Movies must be located under 'Movies' section in the Plex library to properly get 'playing' state.

## Sensor

The `plex` sensor platform will monitor activity on a given [Plex Media Server](https://plex.tv/). It will create a sensor that shows the number of currently watching users as the state. If you click the sensor for more details it will show you who is watching what.

If your Plex server is on the same local network as Home Assistant, all you need to provide in the `configuration.yaml` is the host or IP address. If you want to access a remote Plex server, you must provide the Plex username, password, and optionally the server name of the remote Plex server. If no server name is given it will use the first server listed. If you use the username and password, all servers in that account are monitored.

If you don't know your token, see [Finding your account token / X-Plex-Token](https://support.plex.tv/hc/en-us/articles/204059436).

If you want to enable the plex sensor, add the following lines to your `configuration.yaml`:

```yaml
# Example configuration.yaml entry
sensor:
- platform: plex
```

{% configuration %}
host:
description: The IP address of your Plex server.
required: false
default: localhost
type: string
port:
description: The port of your Plex Server.
required: false
default: 32400
type: integer
name:
description: Name of the Plex server.
required: false
default: Plex
type: string
username:
description: The username for the remote Plex server.
required: false
type: string
password:
description: The password for your given account on the remote Plex server.
required: false
type: string
server:
description: The name of your remote Plex server.
required: false
type: string
token:
description: X-Plex-Token of your remote Plex server.
required: false
type: string
ssl:
description: Use HTTPS to connect to Plex server, **NOTE:** host **must not** be an IP when this option is enabled.
required: false
default: false
type: boolean
verify_ssl:
description: Verify the SSL certificate of your Plex server. You may need to disable this check if your local server enforces secure connections with the default certificate.
required: false
default: true
type: boolean
{% endconfiguration %}