Skip to main content

Plex integration for Gladys Assistant

Plex integration for Gladys Assistant

Control your Plex players: playback, now playing, activity and library sensors.

View on GitHubAll external integrations

Connect your Plex Media Server to Gladys Assistant: control your Plex players from Gladys, and use what is playing in your automations (dim the lights when a movie starts, bring them back up when the credits roll...).

What you get​

One "server" device with monitoring sensors:

  • Active streams — how many sessions are playing right now;
  • Transcode sessions — how many of them the server is transcoding;
  • Streaming bandwidth — total streaming bandwidth, in kbps;
  • Now playing — a one-line summary of who watches what;
  • One item counter per library (can be disabled): movies, TV shows (plus an episode counter), music artists (plus a track counter)...

One device per Plex player (TV app, mobile app, Chromecast... any player your server can control):

  • Playback controls: Play, Pause, Stop, Previous, Next, Rewind, Forward;
  • Volume (0–100) and Mute;
  • Playback state (playing or not) — compatible with the Music dashboard widget of Gladys;
  • Now playing — the formatted title of the current media (Show S01E02 - Episode, Artist - Track, Movie (year));
  • Remaining time, in minutes;
  • In intro and In credits — binary sensors that turn on while the playhead is inside the intro or the end credits of the current episode/movie (uses the markers detected by your Plex server). Perfect automation triggers.

Playback states update every few seconds (configurable), and the integration also listens to the real-time notification stream of your server, so a play, pause or stop is reflected in Gladys within a second.

Configuration​

  1. Find the URL of your Plex Media Server, usually http://<ip-of-the-server>:32400. Use the local address whenever Gladys and Plex share the same network.
  2. Find your Plex token (X-Plex-Token): open the Plex web app, play any media, click Get Info → View XML, and copy the X-Plex-Token value at the end of the URL. See the official article linked in the configuration screen for the detailed walkthrough.
  3. Fill both fields in the Configuration tab of the integration and save.
  4. Use the Test the Plex connection button: it reports the server name, its version and how many libraries and players were found.
  5. Open the Discovery tab: the server device and your players are waiting to be added.

If your server only answers over https with a Plex-issued or self-signed certificate, either use the http local address (recommended) or enable Accept self-signed certificate.

Options​

  • Playback refresh interval — how often the active sessions are polled (10 s by default). Real-time notifications make the usual case faster; this is the fallback pace.
  • Library refresh interval — how often the library counters are refreshed (5 min by default).
  • Library sensors — disable it if you do not want one counter feature per library on the server device.

Players discovery​

Players show up automatically:

  • players registered to the server (the /clients list) are found at startup and by the Scan for Plex players button;
  • any player that starts streaming is discovered on the fly and published to the Discovery tab, even if it is not remotely controllable.

Which players can be controlled?​

Seeing a player and controlling it are two different things: the sensors (now playing, state, remaining time) work for every player, but the buttons only act on those that accept remote control.

  • ✅ TV / set-top box / console apps (Android TV, Apple TV, Roku…) advertise themselves as players by default: everything works.
  • ⚠️ Mobile apps, Plexamp and Plex Web usually do not. Enable "Advertise as player" in their settings (often under "Remote control") — without it the app listens to no command at all, and no software can drive it, Gladys or the Plex app itself.

The integration tries two routes before giving up: through the server (for the players it discovered), then straight to the player on its LAN address (port 32500) — the route Plex uses to cast. Stop has an extra safety net: it interrupts the playback server-side, which works with any player.

Automation ideas​

  • When In credits turns on in the living room → raise the lights;
  • When Playback state turns on after 10 pm → dim the lights to 20 %;
  • When Active streams goes above 3 → send a notification (bandwidth!);
  • One button on the dashboard to Pause every player at dinner time.

Troubleshooting​

The integration logs everything it does: check the integration logs from the Gladys UI (or docker logs on the host) with LOG_LEVEL=debug for the full detail.

  • "Plex authentication failed" — the token is wrong or expired. Fetch a fresh X-Plex-Token and update the configuration.
  • "Plex server unreachable" — check the URL (scheme, IP, port 32400) and that Gladys can reach the server's network.
  • A player does not react to commands — commands are proxied through the server, which must be able to reach the player. If nothing happens, enable "Advertise as player" in that Plex app (a setting some apps do not have), then run Scan for Plex players again. When the server refuses a command, Gladys shows an explicit error — except for Stop, which then interrupts the playback server-side (session termination), and works with any player.
  • Intro/credits sensors never turn on — your Plex server must have the intro/credits detection enabled (Settings → Library) and the markers only exist for analyzed items.

Configuration settings​

These are the settings Plex asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect to your Plex Media ServersectionNoEnter the local address of your Plex Media Server (for example http://192.168.1.20:32400) and a Plex authentication token (X-Plex-Token). The linked article explains how to find your token from the Plex web app.
Plex server URLstringYesBase URL of the Plex Media Server, including the port (32400 by default).
Plex token (X-Plex-Token)secretYes
Playback refresh interval (s)numberNoHow often active playback sessions are refreshed, in seconds. Real-time notifications from the server speed this up when something starts, pauses or stops.
Library refresh interval (s)numberNoHow often library statistics (item counts) are refreshed, in seconds.
Library sensorsbooleanNoAdd one item-count sensor per Plex library on the server device (plus episodes for TV shows and tracks for music).
Accept self-signed certificatebooleanNoOnly for https URLs: accept the self-signed certificate of the Plex server. Leave off for http URLs.

How to install Plex in Gladys​

  1. In Gladys, open Integrations: Plex appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-plex:1.0.3), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-plex.

Plex requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Plex is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on