Home Assistant Guide

Simple tutorials for powerful automations

Feature: Search Your Plex Library from Home Assistant

Want to ask your Home Assistant voice assistant for a movie recommendation, or search your Plex library by genre, actor, or title? With ExtendedOpenAI and a bit of setup, you can control and search Plex using natural speech - no coding experience required! This guide explains every step in simple terms, with a focus on using safe and reliable private (internal) IP addresses on your home network.

What You'll Need

  • A running Plex Media Server on your network
  • Your Plex server's private IP address (e.g., 192.168.68.82)
  • Your Plex API token
  • Your Plex library IDs (also called "section IDs") for movies and TV shows
  • Home Assistant running on your local network, with ExtendedOpenAI installed and internet access
  • Remote access is only needed if Home Assistant is running outside your home network (explained below)

Understanding Private and Public IP Addresses

Private (internal) IP addresses look like 192.168.x.x or 10.x.x.x and are used for devices inside your home.
Public (external) IP addresses are used to reach your network from the internet. You should avoid using public IPs for Home Assistant/Plex integration whenever possible, as it's less secure and requires extra setup.

Best Practice: Use Private IPs Whenever Possible

If both Home Assistant and Plex are on the same network (most common setup), always use the private IP of your Plex server. It's safer, faster, and works even if your internet goes down.

Step 1: Find Your Plex Server's Private IP Address

  1. On the device running Plex, go to Settings > Server > Network in Plex.
  2. Find your IP address, usually something like 192.168.68.82.
  3. Alternatively, check your router's list of connected devices for your Plex server's IP.

Tip: You can assign your Plex server a static IP in your router's settings so it never changes. This prevents Home Assistant integrations from breaking if the IP changes.

Step 2: Get Your Plex API Token (Plex Token)

Your Plex API token (sometimes called your Plex key or Plex token) is needed to let other apps talk to your Plex server. Here's the beginner-friendly way to get it:

  1. Open the Plex Web App (in your browser, go to your Plex server interface).
  2. Find a movie or TV episode in your library and select it.
  3. Click the three dots (more options) next to the item and choose "Get Info".
  4. On the info page, look for the "View XML" option (usually at the bottom left) and click it.
  5. The XML data will open in a new tab. Look at the URL in your browser's address bar – you'll see something like ...&X-Plex-Token=YOUR_TOKEN.
  6. Copy just the value after X-Plex-Token= – this is your unique token!

Keep your token private: Anyone with this can access your Plex server!

Step 3: Find Your Library (Section) IDs

  1. In your browser, enter: http://YOUR_PLEX_IP:32400/library/sections?X-Plex-Token=YOUR_TOKEN
  2. The XML output lists all your libraries. Look for type="movie" or type="show" and note their key="1" or key="2" values.
  3. These numbers are your section IDs (e.g., 1 for movies, 2 for TV shows).

Tip: Section IDs may differ if you've renamed or reorganized libraries - always check to be sure!

Step 4: (Optional) Enable Remote Access (When Needed)

If Home Assistant is running outside your home network (like in the cloud), you'll need Plex remote access:

  1. In Plex, go to Settings > Server > Remote Access.
  2. Note: Remote access is a premium feature and requires an active Plex Pass subscription for the admin/owner account.
  3. If enabled, Plex shows your public IP and port (e.g., 46.7.106.69:23349).
  4. For security, only use remote access if you truly need it. Use strong passwords and two-factor authentication!

Most users should skip this step and use private IPs!

Step 5: How the Search Functions Work

With ExtendedOpenAI, you can add special functions that allow your Home Assistant voice assistant to interact with Plex using simple phrases. Here's what you can do:

  • List available genres (categories): See what types of movies or shows you have (e.g., horror, comedy).
  • Search for movies or TV shows by genre: Ask for recommendations in a specific genre.
  • General search: Find a specific title, actor, or phrase in your Plex library.

Function 1: List Available Genres (Categories)


GET http://192.168.68.82:32400/library/sections/{section}/genre?X-Plex-Token=YOUR_TOKEN
  • section: Your library's section ID (e.g., 1 for movies, 2 for TV shows)
  • Returns a list of genres and their IDs

Function 2: Search Plex Library by Category (Genre)


GET http://192.168.68.82:32400/library/sections/{section}/all?genre={genre}&X-Plex-Token=YOUR_TOKEN
  • section: Your section ID
  • genre: The genre ID obtained from the previous function
  • Use this when your voice assistant is asked for movies or shows in a certain genre (e.g., "Show me comedies")

Function 3: General Search


GET http://192.168.68.82:32400/search?X-Plex-Token=YOUR_TOKEN&query={search_term}&limit={optional_limit}
  • query: The search term (e.g., title, actor, phrase)
  • limit: (Optional) Maximum number of results
  • Use this for specific titles or general text search

When to Use Each Function

  • Want to know what genres you have? Use the list genres function.
  • Want to find movies or TV shows in a certain genre? Get the genre ID first, then use search by category.
  • Looking for a specific title, actor, or keyword? Use general search.

NEW: Plex Webhooks for Home Automation (Plex Pass Feature)

Plex webhooks are a powerful Plex Pass feature that allow Plex to automatically notify Home Assistant (or any other service) when something happens - like when a movie starts playing, is paused, or new content is added.

How Webhooks Work

  • Plex will send an HTTP POST request (with details about the event) to a URL you choose, every time a selected event happens (such as playback start, pause, stop, or new content).
  • Home Assistant can "catch" these requests and trigger automations - like dimming the lights when you start a movie!

Setting Up a Webhook in Plex

  1. In Plex, click the wrench icon (top right) to open Settings.
  2. Go to Account > Webhooks (only visible with a Plex Pass).
  3. Add your webhook URL. For Home Assistant, this will look like:
    http://YOUR_HA_IP:8123/api/webhook/UNIQUE_ID
  4. You can find or create your webhook trigger in Home Assistant (see next section).

Setting Up a Webhook Trigger in Home Assistant

In Home Assistant, you can use the webhook trigger in an automation. Here's a beginner-friendly example that triggers whenever you start playing something in Plex: 

alias: "Dim lights when Plex starts playing"
trigger:
  - platform: webhook
    webhook_id: plex_playing
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room
    data:
      brightness_pct: 20
mode: single
  • Set the webhook URL in Plex to: http://YOUR_HA_IP:8123/api/webhook/plex_playing
  • Replace YOUR_HA_IP with your Home Assistant server's address.

Example Use Cases for Plex Webhooks

  • Dim or turn off the lights when a movie starts playing
  • Turn lights back up when playback stops or pauses
  • Send a notification or message when new content is added to your library
  • Trigger scenes based on what's being played (e.g., set a "movie mode" scene)

How to Use Plex Webhook Data in Home Assistant

The webhook payload is sent as JSON. You can access this data in your automation using trigger.json. For example, to get the event type: 

{{ trigger.json.event }}

Or, to trigger only for media.play events: 


condition:
  - condition: template
    value_template: "{{ trigger.json.event == 'media.play' }}"

You can access more details, like the title or user, via trigger.json.Metadata.title or trigger.json.Account.title.

Notes & Tips

  • Webhooks are a premium feature and require an active Plex Pass subscription for the server admin/owner account.
  • You can add multiple webhooks to trigger different automations for different events.
  • Some events (like media.play) include a thumbnail image as a separate part of the POST request, but most automations will only need the JSON payload.

Troubleshooting & Tips

  • If private IP search does not work, make sure Plex is set to listen on all network interfaces (not just localhost). Check Plex settings and your firewall.
  • 127.0.0.1 (localhost) only works if Home Assistant and Plex are running on the same machine.
  • Always use the private IP unless you absolutely need remote access. This is safer and more reliable!
  • If you move Home Assistant to the cloud, you'll need Plex Pass and to use your public IP or relay address from Plex settings.

Security Tips

  • Never share your API token or internal/private IP in public places.
  • Keep Plex and Home Assistant up to date, and use strong passwords.
  • Enable two-factor authentication if available.

Summary

With this setup, your Home Assistant voice assistant powered by ExtendedOpenAI can search and recommend Plex content using natural speech. For most users, the private IP approach is the safest and best method - public/remote access is only needed if your assistant is truly remote (and requires a Plex Pass).

Don't be afraid to experiment - Home Assistant and Plex are designed to be user-friendly! If you get stuck, check your network connections, Plex settings, and token. There's always help available in the Home Assistant and Plex communities.