Plex Metadata agent plugin based on Subliminal
HTML Python
Switch branches/tags
Nothing to show
Clone or download
Latest commit ecb84c6 Oct 11, 2015


Plex Metadata agent plugin based on Subliminal. This agent will search on the following sites for the best matching subtitles:

  • OpenSubtitles
  • TheSubDB
  • Podnapisi.NET
  • Addic7ed

All providers can be disabled or enabled on a per provider setting. Certain preferences change the behaviour of subliminal, for instance the minimum score of subtitles to download, or whether to download hearing impaired subtitles or not. The agent stores the subtitles as metadata, but can be configured (See Configuration) to store it next to the media files.


See article on Plex website.


You can find the configuration for this plugin in Plex Media Server under Configuration, go to Server, Agents, then for Movies select Freebase and for TV series select The TVDB.

Several options are provided in the preferences of this agent.

  • Addic7ed username/password: Provide your addic7ed username here, otherwise the provider won't work. Please make sure your account is activated, before using the agent.
  • Subtitle language (1)/(2): Your preferred languages to download subtitles for.
  • Provider: Enable ...: Enable/disable this provider. Affects both movies and series.
  • Scan: Include embedded subtitles: When enabled, subliminal finds embedded subtitles that are already present within the media file.
  • Scan: Include external subtitles: When enabled, subliminal finds subtitles located near the media file on the filesystem.
  • Minimum score for download: When configured, what is the minimum score for subtitles to download them? Lower scored subtitles are not downloaded.
  • Download hearing impaired subtitles: When configured, hearing impaired subtitles will be downloaded.
  • Store subtitles next to media files (instead of metadata): See Store as metadata or on filesystem
  • Subtitle folder: See Store as metadata or on filesystem
  • Custom Subtitle folder: See Store as metadata or on filesystem

Store as metadata or on filesystem

By default, Plex stores posters, fan art and subtitles as metadata in a separate folder which is not managed by the user. This is the default behaviour of this agent. However, expert users can enable 'Store subtitles next to media files'. The agent will write the subtitle files in the media folder. The setting 'Subtitle folder' configures in which folder (current folder or other subfolder) the subtitles are stored. The expert user can also supply 'Custom Subtitle folder' which can also be an absolute path.

Please note that you need a way to pick up external subtitles to show up in the Plex Media server. When the subtitles are stored next to your media folders, it is sufficient to enable Local Media agent and place it below the Subliminal agent in the agent priorities. When a subfolder (either custom or predefined) is used, you need LocalMediaExtended.




Uses the following libraries and their LICENSE: