Skip to main content

Plex Integration Guide

Complete guide for integrating Youtarr with Plex Media Server.

Table of Contents​

Overview​

Youtarr provides full Plex integration with:

  • Automatic library refresh after downloads
  • Embedded MP4 metadata for rich display
  • Channel poster artwork
  • OAuth authentication for API token retrieval
  • Multi-library support through subfolders
  • Native playlist sync: subscribed YouTube playlists appear as Plex playlists (see Native Playlist Sync)
  • Watch status sync: Youtarr pulls who has watched what from Plex (see Watch Status Sync)

Library Setup​

There are two ways to add Youtarr content to Plex. The "Other Videos" library is the standard, recommended method: it has been in place since Youtarr's inception, is extensively tested, and works out of the box. The "TV Shows" library is an alternative you can try if you want a more series-style presentation in Plex. It requires a specific file naming convention, so you need to set the file naming before you start downloading, or re-download existing videos after changing it.

Other Videos​

Step 1: Create a New Library​

  1. In Plex, go to Settings → Manage → Libraries
  2. Click "Add Library"
  3. Configure as follows:
    • Type: Other Videos
    • Name: YouTube (or your preference)
    • Language: Your preferred language
Plex Library Type Selection

Step 2: Select Agent​

Choose the appropriate agent:

  • Agent: Personal Media
  • Scanner: Plex Video Files Scanner
Plex Agent Selection

Step 3: Configure Agent Settings​

  1. After creating the library, go to its settings
  2. Navigate to the "Agent" tab
  3. Configure "Personal Media" agent:
    • Enable "Local Media Assets"
    • Move it to the top of the agent list
    • Optional: Enable "Prefer local metadata"
Plex Agent Settings

Step 4: Add Folder​

Point the library to your Youtarr download directory:

  • Default: /path/to/youtube
  • Or specific subfolder: /path/to/youtube/__kids

TV Shows​

Step 1: Set Naming Convention​

In Youtarr, go to Settings -> Core -> Video Filename Template and select the Plex TV Series preset.

This will not rename previously downloaded videos. It is best to set this before you start downloading; otherwise, re-download videos so they pick up the new naming.

While you are there, turn off Prefix channel name in embedded video title under Settings -> Core -> Download Settings. Plex reads the embedded MP4 title as the episode title, and in a TV Shows library the channel is already the show name, so the prefix would only repeat it. This also only applies to new downloads.

Step 2: Create a New Library​

  1. In Plex, go to Settings → Manage → Libraries
  2. Click "Add Library"
  3. Configure as follows:
    • Type: TV Shows
    • Name: YouTube (or your preference)
    • Language: Your preferred language

Step 3: Advanced Settings​

Choose the appropriate agent:

  • Agent: Plex Personal Media
  • Use local assets: this must be enabled so Plex uses the local metadata

It is also recommended to disable the settings that scan shows, like intro detection, credit detection, and voice activity detection. They do not work for this content, but Plex will still spend time scanning for them if left enabled.

Youtarr Settings​

Obtaining Plex Token​

  1. In Youtarr, open Settings -> Plex
  2. Click "Get Key" next to Plex API Key field
  3. Log in with your Plex account
  4. Authorize Youtarr
  5. Token automatically populated

Method 2: Manual​

  1. Follow official Plex token guide
  2. Enter the token under Settings -> Plex

Required Settings​

Under Settings -> Plex:

  • Plex API Key: Your X-Plex-Token
  • Plex IP: Server IP or hostname
  • Plex Port: Usually 32400
  • Use HTTPS: Enable if using SSL
  • Plex YouTube Library ID: Select your library from dropdown

Library Refresh​

Youtarr automatically:

  • Triggers library scan after each download
  • Updates only the affected sections
  • Handles multi-library setups intelligently

Native Playlist Sync​

Once Plex is connected with the settings above, Youtarr can mirror your subscribed YouTube playlists into Plex as native playlists. Nothing extra is required for the common case: turn on a playlist's Plex sync chip in Youtarr and it appears under your account after the next sync.

Playlist visibility scope (advanced)​

Most people can ignore this. Under Settings -> Plex -> Advanced: playlist visibility scope, you can control which account owns Youtarr's playlists:

  • Use my Plex admin account (default): the normal claimed-server case. Playlists are created under your account and are visible to you.
  • Unclaimed server (anonymous LAN access): for an unclaimed server on your LAN, where Plex Web browses without a token. If a connection test detects an unclaimed server, Youtarr nudges you toward this option. Watch status sync also reads the anonymous session's watch state in this mode.
  • A specific Plex user account: routes the playlists through a token you paste in.

Plex playlists are always owned by a single account, so there's no automatic "public" setting. To let another Plex user see a playlist, open it in Plex Web and share it (playlist menu -> Share), or use Settings -> Manage Library Access -> [user] -> Media. Youtarr can't grant per-user access for you.

Heads up: shared playlists do not appear in the recipient's Playlists section - Plex lists playlists shared by another account under a separate sidebar source named Media. If a user reports the playlist is missing even though the share looks correct, have them check there. See Shared Playlists Don't Appear for Other Users for related gotchas (library access, content-rating restrictions).

For how syncing, ordering, and playlist updates work across all servers, see Media Server Playlists.

Watch Status Sync​

The same Plex connection you set up above also enables watch status sync: on a schedule (every 4 hours by default), Youtarr pulls per-video watch state from Plex and shows it as Watched chips and filters on its listing pages. The sync is one-way; Youtarr never marks anything watched on Plex.

A couple of Plex-specific details:

  • The server owner's account gets full detail: played, percent watched, and last watched time.
  • Other Plex accounts come from the server's play history, which only records completed plays. Those users show as watched or not, with no in-progress positions.
  • On an unclaimed server (see the playlist visibility scope above), Youtarr reads the anonymous session's watch state instead.
  • Plex decides when a video counts as played, not Youtarr: the Video Played Threshold setting under Settings -> Library (90% by default).

Settings live under Settings -> Watch Status, including a per-server toggle for syncing all users vs. just the owner. See Track Watch Status from Media Servers for the full workflow.

Multi-Library Organization​

Why Use Multiple Libraries?​

Separate content by purpose:

  • Kids content with parental controls
  • Music videos with different view modes
  • Educational content for learning
  • News/current events separately

Setting Up Multiple Libraries​

  1. Configure channel subfolders in Youtarr:

    • Click settings icon on any channel page
    • Set custom subfolder (e.g., __kids, __music)

  2. Create separate Plex libraries:

    Library: "YouTube - Kids" → /path/to/youtube/__kids
    Library: "YouTube - Music" → /path/to/youtube/__music
    Library: "YouTube - All" → /path/to/youtube

  3. Configure each library with appropriate settings:

    • Kids library: Enable parental controls
    • Music library: Use music-focused view
    • Main library: Standard video view

Directory Structure Example​

See: docs/YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md

What You'll See​

Channel View​

Plex Channel View

Video Details​

Plex Video Details

Metadata Display​

  • Title: Video title with channel prefix
  • Description: Full YouTube description
  • Studio: Channel name for grouping
  • Album: Channel name (alternative grouping)
  • Genre: YouTube categories
  • Release Date: Original upload instant (UTC), or the upload date when yt-dlp does not report a timestamp
  • Poster: Channel artwork (poster.jpg)
  • Thumbnail: Video thumbnail

For new MP4 downloads, Youtarr embeds the full UTC upload instant (for example 2026-08-03T17:11:00Z) when yt-dlp reports a usable timestamp, falling back to the date-only upload date otherwise. NFO release dates stay date-only for Jellyfin and Emby compatibility. Youtarr has no re-tagging feature, so previously downloaded files keep their date-only tag until they are downloaded again; refreshing the Plex library does not rewrite it.

Tips and Best Practices​

Library Settings​

  1. Enable "Local Media Assets" in Advanced settings
  2. Set "Prefer local metadata" for consistency
  3. Disable "Generate video preview thumbnails" to save resources
  4. Use Collections to group related channels

Performance​

  1. Disable real-time monitoring for large libraries
  2. Schedule periodic scans instead
  3. Use specific library refreshes rather than full scans

Organization​

  1. Use consistent naming for subfolders
  2. Plan structure early before adding many channels
  3. Keep subfolder names simple (no spaces or special characters)

Network Configuration​

  1. Same network: Ensure Plex and Youtarr are on same network
  2. Firewall rules: Allow port 32400 between containers
  3. Docker networking: Use bridge network or host mode

Troubleshooting​

Plex Token Issues​

Problem: Cannot connect to Plex server

Solutions:

  1. Verify token is valid: 
    curl -H "X-Plex-Token: YOUR_TOKEN" http://PLEX_IP:32400/
  2. Ensure using admin account token
  3. Try regenerating token via OAuth

Library Not Updating​

Problem: New videos don't appear

Solutions:

  1. Check Youtarr logs for scan errors
  2. Manually trigger library scan in Plex
  3. Verify library ID is correct in Youtarr
  4. Check folder permissions

Metadata Not Displaying​

Problem: Videos show without metadata

Solutions:

  1. Verify "Local Media Assets" is enabled
  2. Check embedded metadata: 
    ffprobe -v quiet -print_format json -show_format video.mp4
  3. Refresh metadata for specific items
  4. Clear Plex cache and rescan

Poster Issues​

Problem: Channel posters not showing or changing

Known Issue: Plex occasionally replaces poster.jpg with generated thumbnails

Workarounds:

  1. Refresh metadata for affected channels
  2. Lock poster in Plex (edit → poster → lock)
  3. Ensure "Local Media Assets" is prioritized

Permission Errors​

Problem: Plex cannot access files

Solutions:

  1. Check file permissions: 
    ls -la /path/to/youtube
  2. Ensure Plex user has read access
  3. For Docker: Check volume mount permissions
  4. Use same UID/GID for both containers

Multi-Library Issues​

Problem: Wrong library refreshing

Solutions:

  1. Verify each library has unique path
  2. Check library IDs in Youtarr config
  3. Ensure subfolders are correctly set
  4. Test with manual refresh first

API Usage​

Direct API calls for troubleshooting:

# Get libraries
curl -H "X-Plex-Token: TOKEN" \
  http://PLEX_IP:32400/library/sections

# Trigger scan
curl -X POST -H "X-Plex-Token: TOKEN" \
  http://PLEX_IP:32400/library/sections/LIBRARY_ID/refresh

# Get library items
curl -H "X-Plex-Token: TOKEN" \
  http://PLEX_IP:32400/library/sections/LIBRARY_ID/all