# 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](media-servers/plex.md) |
| **Kodi** | NFO + Artwork | NFO Files | Manual/Scheduled | [Setup Guide](media-servers/kodi.md) |
| **Jellyfin** | NFO + Artwork | NFO Files | Manual/Real-time | [Setup Guide](media-servers/jellyfin.md) |
| **Emby** | NFO + Artwork | NFO Files + Embedded | Manual/Real-time | [Setup Guide](media-servers/emby.md) |

## Quick Comparison

### Feature Support

| Feature | Plex | Kodi | Jellyfin | Emby |
|---------|------|------|----------|------|
| Automatic Library Refresh via Youtarr | ✅ | ❌ | ❌ | ❌ |
| Native Playlist Sync | ✅ | M3U only | ✅ | ✅ |
| NFO Metadata | ❌ | ✅ | ✅ | ✅ |
| Embedded MP4 Metadata | ✅ | Partial | ✅ | ✅ |
| Channel Posters | ❌ | ✅ | ✅ | ✅ |

### 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 Configuration -> Kodi, Emby and Jellyfin compatibility
- **Poster Images**: Channel artwork (poster.jpg) if enabled in Configuration -> Kodi, Emby and Jellyfin compatibility

## Multi-Library Organization

Youtarr supports organizing content into separate libraries using subfolders:

See [YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md](YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md) for subfolder structure details.

### Benefits of Multiple Libraries

1. **Access Control**: Different permissions per library
2. **Organization**: Easier content discovery
3. **Customization**: Library-specific settings
4. **Performance**: Faster targeted scanning

### Setup Process

1. Configure channel subfolders in Youtarr (channel settings)
2. Create separate media server libraries pointing to each subfolder
3. Configure library-specific settings

## Configuration in Youtarr

### Essential Settings

Navigate to Configuration → Media Server Compatibility:

*Although these are not used by Plex, it is recommended to leave these enabled since it provides the best compatibility for all media servers*

Disable if you are using Plex-only and want less "clutter" of files

| Setting | Default | Purpose |
|---------|---------|---------|
| **Generate video .nfo files** | Enabled | Creates metadata for Kodi/Jellyfin/Emby |
| **Copy channel poster.jpg files** | Enabled | Adds channel artwork to folders |

### 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](MEDIA_SERVER_PLAYLISTS.md) for the full setup.

#### Kodi
- No specific configuration needed for metadata; point Kodi at the download directory.
- Kodi has no native playlist sync, but Youtarr writes a `.m3u` file you can import. See [Media Server Playlists](MEDIA_SERVER_PLAYLISTS.md#m3u-fallback).

## File Structure

See [Youtarr Downloads Folder Structure](YOUTARR_DOWNLOADS_FOLDER_STRUCTURE.md)

### Metadata Contents

**NFO Files Include**:
| Field                | Description                               |
| -------------------- | ----------------------------------------- |
| `<title>`            | Title with channel prefix                 |
| `<plot>`             | Full description of video from YouTube    |
| `<premiered>`        | Original upload/release date              |
| `<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                                |

**Embedded MP4 Metadata**:
| Field                | Description                               |
| -------------------- | ----------------------------------------- |
| `title`              | Title with channel prefix                 |
| `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](MEDIA_SERVER_PLAYLISTS.md).

## Quick Start Guides

### For New Users

1. **Choose Your Media Server**:
   - [Plex Guide](media-servers/plex.md)
   - [Jellyfin Guide](media-servers/jellyfin.md)
   - [Kodi Guide](media-servers/kodi.md)
   - [Emby Guide](media-servers/emby.md)

2. **Enable Metadata Generation** in Youtarr Configuration

3. **Add Channels** and let Youtarr download with metadata

4. **Configure Media Server** following the specific guide

### For Existing Users

If you already have downloaded videos:
1. Enable metadata generation in Configuration
2. New downloads will include metadata
3. Existing videos won't be retroactively updated
4. 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 API key (Plex) or trigger manual scan | Plex |
| Special characters broken | Ensure UTF-8 encoding, update media server | All |
| Duplicate entries | Check for overlapping library paths | All |

### Getting Help

1. Check the specific media server guide
2. Review [Troubleshooting Guide](TROUBLESHOOTING.md)
3. Check media server logs
4. Verify file permissions

## Best Practices

### General Recommendations

1. **Plan Your Structure**: Decide on organization before adding many channels
2. **Test First**: Start with one channel to verify setup
3. **Enable Metadata Early**: Configure before downloading
4. **Use Subfolders**: Organize content from the start
5. **Regular Maintenance**: Periodically clean and optimize libraries