DOCSEARCHbyAlgolia
Submit Docs

YouTube-Agent.bundle

repository·master·Indexed 20 days ago

https://github.com/zeroqi/youtube-agent.bundle

A Plex Metadata Agent that fetches metadata for downloaded YouTube videos using video, playlist, or channel IDs embedded in filenames or folder structures. It supports YoutubeMovie and YouTubeSeries agents, custom YouTube API key configuration, and local metadata lookup via .info.json files generated by youtube-dl.

Tokens
1.3K
Snippets
3
Records
6
Agent score
19%

What's inside YouTube-Agent.bundle

  1. Naming conventions for YouTube-Agent metadata matching

    master

    The agent identifies videos using YouTube IDs embedded in filenames or folder names. It supports the following formats:

    • [xxxxxxxx]
    • [youtube-xxx]
    • [YouTube-xxx]
    • [Youtube-xxx]

    Movie/Home Video Library

    • Option 1: Filename (without extension) matches the YouTube video title exactly.
    • Option 2: Filename contains the YouTube video ID in brackets, e.g., Video Title [ID].mp4.

    TV Series Library

    • Folders: Movies must be in a folder named exactly like the video title or containing the video ID.
    • Series/Season Folders: The series folder name must contain either the YouTube Playlist ID [PLxxxxxxxxxxxxxxxx] or the YouTube Channel ID [UCxxxxxxxxxxxxxxxx].
    • Alternative: You can place a file named youtube.id containing the ID at the root of the series folder.

  2. Configure a custom YouTube API key

    master

    It is highly recommended to use your own YouTube API key to avoid depleting the shared quota, which can block metadata requests for all users.

    1. Go to the Google Developer Console.
    2. Create or select a project.
    3. Enable the YouTube Data API for that project.
    4. Create credentials to obtain an API key.
    5. In the Youtube-Agent.bundle plugin directory, create a file named youtube-key.txt and paste your API key into it.

    Note: If you are using the Absolute Series Scanner, you must also replace the API_KEY variable within its codebase with your own key.

    # Contents of Youtube-Agent.bundle/youtube-key.txt
AIzaSyC2q8yjciNdlYRNdvwbb7NEcDxBkv1Cass

  3. Enable YouTube-Agent in Plex Libraries

    master

    Once the plugin is installed, you must manually assign it to your libraries:

    1. Create a new library or select an existing one.
    2. Go to Manage Library -> Edit.
    3. Navigate to the Advanced tab.
    4. Select the appropriate agent based on your library type:
      • Use YoutubeMovie for Movie/Home Video libraries.
      • Use YouTubeSeries for TV Series libraries.
    5. Repeat this for every library you want to use with this agent.

  4. Install YouTube-Agent.bundle for Plex

    master

    To install the metadata agent, follow these steps:

    1. Download the code: Download the master zip from GitHub.
    2. Prepare the folder: Unpack the zip and rename the resulting folder to Youtube-Agent.bundle (remove the -master suffix).
    3. Deploy: Place the Youtube-Agent.bundle folder into your Plex Plug-ins directory.
    4. Restart: Restart your Plex Media Server to load the plugin.

    Common Plug-in folder locations:

    • Windows: %LOCALAPPDATA%\Plex Media Server\Plug-ins
    • Mac OS: $HOME/Library/Application Support/Plex Media Server/Plug-ins
    • Linux: $HOME/Library/Application Support/Plex Media Server/Plug-ins or /var/lib/plexmediaserver/Library/Application Support/Plex Media Server/Plug-ins
    • Synology/Asustor: /volume1/Plex/Library/Application Support/Plex Media Server/Plug-ins
    # Example of moving the bundle to a Linux Plex directory
mv Youtube-Agent.bundle "$HOME/Library/Application Support/Plex Media Server/Plug-ins/"

  5. Troubleshoot missing metadata

    master

    If your files appear in Plex with the correct season/structure (meaning the Scanner worked) but are missing posters, summaries, or correct titles, the Agent is failing.

    Steps to resolve:

    1. Update to the latest version of both Absolute Series Scanner and YouTube-Agent.
    2. Delete all existing Plex logs (keep the folders).
    3. Restart Plex Media Server.
    4. Trigger a 'Refresh Metadata' on the series in Plex.

    Required logs for support: If the issue persists, provide the following logs:

    • .../Plex Media Server/Logs/PMS Plugin Logs/com.plexapp.agents.Youtube-Agent.log
    • .../Plex Media Server/Logs/PMS Plugin Logs/com.plexapp.system.log

  6. Download YouTube content with youtube-dl for Plex

    master

    To prepare files for this agent, use youtube-dl. It is recommended to use the --write-info.json flag so the agent can load metadata locally, reducing API requests.

    Recommended command pattern for playlists/channels: Use a naming template that includes the channel ID and video ID to ensure the agent can match them correctly.

    # Example command to download a playlist with metadata and restricted filenames
youtube-dl --restrict-filenames --write-info-json -i -o "%(uploader)s [%(channel_id)s]/%(playlist_index)s - %(title)s [%(id)s].%(ext)s" https://www.youtube.com/watch?v=VIDEO_ID&list=PLAYLIST_ID

    Flags used:

    • --restrict-filenames: Restricts filenames to ASCII to prevent crashes on Windows filesystems.
    • --write-info-json: Writes a .info.json file which the agent uses for local metadata lookup.
    youtube-dl --restrict-filenames --write-info-json -i -o "%(uploader)s [%(channel_id)s]/%(playlist_index)s - %(title)s [%(id)s].%(ext)s" https://www.youtube.com/watch?v=f-wWBGo6a2w&list=PL22J3VaeABQD_IZs7y60I3lUrrFTzkpat