Media Server Integration Overview
Youtarr supports integration with multiple media servers, providing rich metadata and organized content for your YouTube video collection.
Supported Media Servers
| Media Server | Integration Type | Metadata Support | Library Refresh | Guide |
|---|---|---|---|---|
| Plex | Full Integration | Embedded MP4 + NFO | Automatic | Setup Guide |
| Kodi | NFO + Artwork | NFO Files | Manual/Scheduled | Setup Guide |
| Jellyfin | NFO + Artwork | NFO Files | Automatic when connected, else Manual/Real-time | Setup Guide |
| Emby | NFO + Artwork | NFO Files + Embedded | Automatic when connected, else Manual/Real-time | Setup Guide |
Quick Comparison
Feature Support
| Feature | Plex | Kodi | Jellyfin | Emby |
|---|---|---|---|---|
| Automatic Library Refresh via Youtarr | ✅ | ❌ | ✅ (when connected) | ✅ (when connected) |
| Native Playlist Sync | ✅ | M3U only | ✅ | ✅ |
| Channel Playlist (.m3u) Auto-Import | ❌ | Manual import | Mixed or Music libraries only | Mixed-type libraries only |
| Watch Status Sync (into Youtarr) | ✅ | ❌ | ✅ | ✅ |
| NFO Metadata | ❌ | ✅ | ✅ | ✅ |
| Embedded MP4 Metadata | ✅ | Partial | ✅ | ✅ |
| Channel Posters | ❌ | ✅ | ✅ | ✅ |
| Backdrop Images | ❌ | ❌ | ✅ | ✅ |
Metadata Generated by Youtarr
All media servers receive:
- Video Files: MP4 with embedded metadata
- Thumbnails: Video preview images
- NFO Files: XML metadata for each video if enabled in Settings -> Core -> Media server files
- Poster Images: Channel artwork (poster.jpg) if enabled in Settings -> Core -> Media server files
Optional artwork, both off by default and enabled in the same Media server files section:
- Video Fanart:
<video name>-fanart.jpgbeside each video, from the video thumbnail. Some Plex clients (NVIDIA Shield, for example) use it as the background preview. - Backdrop Images:
backdrop.jpgin each channel folder (from the channel banner) plus<video name>-backdrop.jpgbeside each video, used by Emby and Jellyfin for background art.
Multi-Library Organization
Youtarr supports organizing content into separate libraries using subfolders:
See YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md for subfolder structure details.
Benefits of Multiple Libraries
- Access Control: Different permissions per library
- Organization: Easier content discovery
- Customization: Library-specific settings
- Performance: Faster targeted scanning
Setup Process
- Configure channel subfolders in Youtarr (channel settings)
- Create separate media server libraries pointing to each subfolder
- Configure library-specific settings
Configuration in Youtarr
Essential Settings
Navigate to Settings -> Core -> Media server files:
The .nfo and poster files are not used by Plex, but it is recommended to leave them enabled since they provide the best compatibility for all media servers
Disable if you are using Plex-only and want less "clutter" of files
| Setting | Default | Purpose |
|---|---|---|
| Video .nfo files | Enabled | Creates metadata for Kodi/Jellyfin/Emby |
| Channel poster.jpg | Enabled | Adds channel artwork to folders |
| Video fanart | Disabled | Writes -fanart.jpg per video; some Plex clients use it as the background preview |
| Backdrop images | Disabled | Writes backdrop.jpg per channel and -backdrop.jpg per video for Emby/Jellyfin background art |
Platform-Specific Settings
Plex
- Plex API Key: Required for automatic library refresh
- Library ID: Select your YouTube library
- Server Details: IP address and port
Jellyfin and Emby
- For metadata only, no Youtarr-side settings are needed. Just point the server at your download directory and the NFO and poster files are picked up automatically.
- For native playlist sync, you do need to connect the server in Youtarr: enable it under Settings, then enter the server URL, an API key, and the user account that should own the playlists. See Media Server Playlists for the full setup.
- A connected server is also refreshed after each download job that adds videos, so new videos appear without waiting for the server's own scan. Fill in Video Library IDs to refresh only the libraries that hold your Youtarr videos; left blank, every library is refreshed.
Kodi
- No specific configuration needed for metadata; point Kodi at the download directory.
- Kodi has no native playlist sync, but Youtarr writes a
.m3ufile you can import. See Media Server Playlists.
File Structure
See Youtarr Downloads Folder Structure
Metadata Contents
NFO Files Include:
| Field | Description |
|---|---|
<title> | Video title as it appears on YouTube (no channel prefix) |
<plot> | Full description of video from YouTube |
<premiered> | Original upload/release date |
<year> | Year of the upload/release date |
<dateadded> | Date the video was downloaded by Youtarr |
<studio> | Channel name |
<credits> | Channel name |
<genre> | YouTube categories |
<tag> | YouTube tags |
<runtime> | Video duration in minutes |
<durationinseconds> | Video duration in seconds |
<uniqueid> | YouTube ID with type="youtube" |
<youtubeid> | YouTube ID |
<mpaa> / <ratings> | Content rating when one applies (download override, channel/playlist default, or YouTube age rating) |
<trailer> | Link back to the video on YouTube |
Embedded MP4 Metadata:
| Field | Description |
|---|---|
title | Channel - Title by default; just the title when Channel name in embedded title (Settings -> Core -> Naming) is off |
artist | Channel name |
studio | Channel name |
album | Channel name (for collection grouping) |
keyword | YouTube tags |
description | Full description of video from YouTube |
genre | YouTube Categories |
comment | Link to video on YouTube |
Content Create Date | Original upload/release date |
Native Playlist Sync
Youtarr can mirror subscribed YouTube playlists into Plex, Jellyfin, and Emby as native playlists, plus emit a universal .m3u fallback. Per-server setup, visibility model, and replace semantics are documented separately in Media Server Playlists.
Watch Status Sync
Youtarr can pull per-video, per-user watch status from Plex, Jellyfin, and Emby, show a Watched chip on its listing pages, and let you filter your library by watched state. The sync is one-way; nothing is written back to your servers. See Track Watch Status from Media Servers for the workflow and the Configuration Reference for the config keys.
Quick Start Guides
For New Users
-
Choose Your Media Server:
-
Enable Metadata Generation in Youtarr (Settings -> Core -> Media server files)
-
Add Channels and let Youtarr download with metadata
-
Configure Media Server following the specific guide
For Existing Users
If you already have downloaded videos:
- Enable metadata generation in Settings -> Core -> Media server files
- New downloads will include metadata
- Existing videos won't be retroactively updated
- Consider deleting and re-downloading if metadata is important
Troubleshooting
Common Issues
| Problem | Solution | Affects |
|---|---|---|
| Metadata not showing | Enable "Local Media Assets" or NFO reader | All |
| Posters missing | Check poster.jpg exists, verify permissions | All |
| Library not updating | Check the API key and connection in Settings, or trigger a manual scan | Plex, Jellyfin, Emby |
| Special characters broken | Ensure UTF-8 encoding, update media server | All |
| Duplicate entries | Check for overlapping library paths | All |
Getting Help
- Check the specific media server guide
- Review Troubleshooting Guide
- Check media server logs
- Verify file permissions
Best Practices
General Recommendations
- Plan Your Structure: Decide on organization before adding many channels
- Test First: Start with one channel to verify setup
- Enable Metadata Early: Configure before downloading
- Use Subfolders: Organize content from the start
- Regular Maintenance: Periodically clean and optimize libraries