Agents

"Metadata Agents" (or just "agents") are the server component that's responsible for taking the information from the scanner and then acting on it to help bring in the rich metadata (plot summary, cast info, cover art, music album reviews, etc.) that brings your media libraries to life. In most cases, this metadata is retrieved from online resources (such as The Internet Movie Database, The TVDB, Last.fm, etc.).

Metadata Agent Types

There are several types of metadata agent, which correlate to the different Library types:

  • Movie
  • Music (both for Artists and Albums)
  • Shows
  • Photos

Movie Agents

Movie metadata agents can fetch information from local or online resources for information about your movie media. There are multiple available:

  • Plex Movie: This is the default (and most flexible) movie agent and can gather data from a variety of online resources (The Movie Database, IMDb, Rotten Tomatoes, and more)
  • The Movie Database: This agent gathers data only from The Movie Database. (We encourage users to instead use the regular "Plex Movie" agent and simply adjust the agent options to pull desired information from The Movie Database.)
  • Personal Media: The Personal Media agent is designed for media that won't appear in any online database and so has no need to try to retrieve metadata from such online resources. This is primarily used for "Other Videos" libraries (home movies, corporate videos, etc.)

TV Show Agents

There are several metadata agents available for TV Shows:

  • TheTVDB: This is the default agent for television libraries and gathers content from TheTVDB.
  • The Movie Database: The Movie Database agent gathers metadata from The Movie Database and local assets. We generally encourage users to use TheTVDB agent for television content instead, but some users may prefer the metadata available from The Movie Database for television.
  • Personal Media Shows: The Personal Media Shows agent is used to identify media files that haven't been broadcast and so don't appear in online databases. Shows scanned using this agent will be presented like a TV series. This is useful if you have a set of videos from a single event, like a wedding. If Local Media Assets is enabled for the agent, any embedded metadata in the files will be used for that show.

Related PageNaming Home Series Media

Music Agents

There are several metadata agents available for music:

  • Plex Premium Music: This agent is automatically used if you create a Premium Music library (available to Plex Pass subscribers). This agent includes sonic fingerprint matching and premium metadata via Gracenote, among others.
  • Last.fm: Last.fm is the default agent used for non-premium music libraries. Note that if you choose Last.fm for your music library, it will be used as the primary agent for both artist and album metadata, but you can choose the relative priority of Personal Media and Last.fm for artists and albums independently in your server agent settings.
  • Personal Media Artists/Albums: The Personal Media Artists/Albums agent is designed to recognize albums that have not been released commercially and so won't appear in online music databases. Metadata embedded in most music file formats will be read and used if Local Media Assets is enabled.

Related PagePlex Pass > Premium Music Libraries

Photos Agents

There is a only a single agent available for Photos. It cannot be altered and is used to recognize image files and add them to the library.

Metadata Agent Settings

Each library has a metadata agent set when it is created. Generally, it's not necessary to change the settings for these agents, but you can if you like. Changing agent settings lets you influence which online resources are used to gather information.

These settings are accessed under Settings > Server > Agents in the Plex Web App.

  1. Library type
  2. Primary Metadata agents for the selected library type
  3. Available sources for the selected primary metadata agent

Adjusting Agent Settings

Once you choose the library type (1) and select a particular primary metadata agent (2), you'll see a list of the sources available for that primary metadata agent (3). Here, you can adjust their priority as well as alter individual metadata source options where applicable.

Tip!: If you adjust the agent settings here and wish for the changes to apply to existing library content, you must Refresh All Metadata for the library. (See Updating vs Refreshing a Library)

Source Priority

You can adjust the order of the metadata sources, which sets their priority. To do so, grab the "handle" indicator on the left and drag up or down to re-arrange the source order. The priority helps determine from where you get your metadata.

For example, in the "Plex Movie" metadata agent for movies, both Fanart.tv and CineMaterial are included as possible sources for artwork. If you prefer artwork from Fanart.tv more, then you can put that as a higher priority. If a piece of metadata isn't available from your first source, then the agent will fallback down the priority list until it finds a source with that information.

In most situations, people will prefer to have Local Media Assets as the first metadata source so that things like local artwork files will be used.

Related PageLocal Media Assets - Movies
Related PageLocal Media Assets - TV Shows
Related PageIdentifying Music Media Using Embedded Metadata

Source Options

Some metadata agent sources have preferences you can set. To set the preferences:
  • Choose the metadata agent
  • If a source has preferences that can be set, a "gear" icon will appear to the right
  • Click 
  • Adjust the preferences


Not all sources have options. Most users should simply leave the default values for the sources.

Local Media Assets

Most agents will contain the Local Media Assets source. This source looks for local files like poster images, subtitles, etc. as well as embedded metadata inside certain media files. For example:
  • Metadata like plot, release year, etc. embedded in a file (typically MP4, M4V, MP3, and more)
  • Local poster artwork, subtitles, and more files
  • TV Show theme tunes
To make sure the files and embedded metadata are used rather than metadata from online sources:
  • The Local Media Assets source is enabled (checked)
  • The Local Media Assets is topmost in the list of sources

Changing a Library Agent

In cases where there are multiple metadata agents available for the library type, the agent used can be changed when the library is first created, or when editing it. Note that some library types such as Photo libraries only have one scanner so there will not be a drop-down to change it.

To change the metadata agent:

When Creating a Library

  • Open the creation window for a new library
  • Before completing the process, select the Advanced tab in the sidebar
  • Choose the metadata agent to use from the Agent drop-down (only visible if there is more than one agent available for the library type)
  • Finish configuring the library

Related PageCreating Libraries

When Editing a Library

If a library has already been created, you can change the metadata agent from the Edit Library screen:

  • Open the Edit window for the library
  • Click the Advanced tab
  • Choose the metadata agent to use from the Agent drop-down (only visible if there is more than one agent available for the library type)
  • Click Save Changes

Tip!: Changing the metadata agent for an existing library will only affect future content. It does not retroactively change the agent used for existing library content.