{"id":13522199,"url":"https://github.com/jmbannon/ytdl-sub","last_synced_at":"2026-04-01T18:17:09.226Z","repository":{"id":37016994,"uuid":"404588188","full_name":"jmbannon/ytdl-sub","owner":"jmbannon","description":"Lightweight tool to automate downloading and metadata generation with yt-dlp","archived":false,"fork":false,"pushed_at":"2026-03-26T20:50:18.000Z","size":31326,"stargazers_count":2763,"open_issues_count":119,"forks_count":99,"subscribers_count":12,"default_branch":"master","last_synced_at":"2026-03-27T08:48:53.982Z","etag":null,"topics":["emby","jellyfin","kodi","lidarr","nfo","plex","radarr","servarr","sonarr","youtube","yt-dlp","yt-dlp-wrapper","ytdl"],"latest_commit_sha":null,"homepage":"https://ytdl-sub.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jmbannon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-09-09T04:44:33.000Z","updated_at":"2026-03-26T20:50:19.000Z","dependencies_parsed_at":"2023-10-15T20:35:45.077Z","dependency_job_id":"5cab0859-075a-4c06-a2b0-3444d0a10348","html_url":"https://github.com/jmbannon/ytdl-sub","commit_stats":{"total_commits":724,"total_committers":25,"mean_commits":28.96,"dds":0.09116022099447518,"last_synced_commit":"18d0d743269e75a199df5800a578b70c1512665f"},"previous_names":[],"tags_count":374,"template":false,"template_full_name":null,"purl":"pkg:github/jmbannon/ytdl-sub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmbannon%2Fytdl-sub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmbannon%2Fytdl-sub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmbannon%2Fytdl-sub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmbannon%2Fytdl-sub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jmbannon","download_url":"https://codeload.github.com/jmbannon/ytdl-sub/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jmbannon%2Fytdl-sub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emby","jellyfin","kodi","lidarr","nfo","plex","radarr","servarr","sonarr","youtube","yt-dlp","yt-dlp-wrapper","ytdl"],"created_at":"2024-08-01T06:00:43.953Z","updated_at":"2026-04-01T18:17:09.171Z","avatar_url":"https://github.com/jmbannon.png","language":"Python","funding_links":[],"categories":["Python","👾 Companion Apps \u0026 Tools","Download utilities"],"sub_categories":["📥 Content Import","General"],"readme":"# ytdl-sub\n## Automate downloading and metadata generation with YoutubeDL.\n[\u003cimg src=\"https://img.shields.io/badge/readthedocs-link-blue?logo=readthedocs\"\u003e](https://ytdl-sub.readthedocs.io/en/latest/index.html)\n[\u003cimg src=\"https://img.shields.io/discord/994270357957648404?logo=Discord\"\u003e](https://discord.gg/v8j9RAHb4k)\n[![codecov](https://img.shields.io/codecov/c/github/jmbannon/ytdl-sub)](https://app.codecov.io/gh/jmbannon/ytdl-sub)\n![Code Qaulity](https://img.shields.io/badge/pylint-10%2F10-brightgreen)\n![Checks](https://img.shields.io/github/checks-status/jmbannon/ytdl-sub/master)\n![License](https://img.shields.io/github/license/jmbannon/ytdl-sub?color=blue)\n\n`ytdl-sub` is a command-line tool that downloads media via \n[yt-dlp](https://github.com/yt-dlp/yt-dlp)\nand prepares it for your favorite media player, including\n[Kodi](https://github.com/xbmc/xbmc), \n[Jellyfin](https://github.com/jellyfin/jellyfin), \n[Plex](https://github.com/plexinc/pms-docker),\n[Emby](https://emby.media/),\nand modern music players. No additional plugins or external scrapers are needed.\n\nWe recognize that everyone stores their \nmedia differently. Our approach for file and metadata formatting is to provide\nmaximum flexibility while maintaining simplicity.\n\n### YouTube Channels as TV Shows\n#### Plex\n![unknown](https://user-images.githubusercontent.com/10107080/202107286-d8f38c7b-7caf-413a-b9a3-0bbbaded3646.png)\n\n#### Jellyfin\n![jellyfin](https://user-images.githubusercontent.com/10107080/182677243-b4184e51-9780-4094-bd40-ea4ff58555d0.PNG)\n\n### Music Videos and Concerts\n#### Kodi\n![kodi](https://user-images.githubusercontent.com/10107080/182677268-d1bf2ff0-9b9c-4a04-98ec-443a67ada734.png)\n#### Jellyfin\n![jelly_mv](https://user-images.githubusercontent.com/10107080/182677256-43aeb029-0c3f-4648-9fd2-352b9666b262.PNG)\n\n### SoundCloud Discography\n#### Writes proper music-tags via beets API\n![sc_mb](https://user-images.githubusercontent.com/10107080/182685415-06adf477-3dd3-475d-bbcd-53b0152b9f0a.PNG)\n\n### Bandcamp Discography\n![bc_nav](https://user-images.githubusercontent.com/10107080/212503861-1d8748e6-6f6d-4043-b543-84226cd1f662.png)\n\n## How it Works\n`ytdl-sub` uses YAML files to define subscriptions. Each subscription imports _presets_ that\ndefine how to handle and output media files. `ytdl-sub` comes packaged with many _prebuilt presets_\nthat do the work of config-building, so you can start downloading immediately.\n\n```yaml\n# subscriptions.yaml:\n# Everything in here can be downloaded using the command:\n#   ytdl-sub sub subscriptions.yaml\n\n# __preset__ is a place to define global overrides for all subscriptions\n__preset__:\n  overrides:\n    # Root folder of all ytdl-sub TV Shows\n    tv_show_directory: \"/tv_shows\"\n    \n    # Root folder of all ytdl-sub Music\n    music_directory: \"/music\"\n    \n    # Root folder of all ytdl-sub Music Videos\n    music_video_directory: \"/music_videos\"\n    \n    # For 'Only Recent' preset, only keep vids within this range and limit\n    only_recent_date_range: \"2months\"\n    only_recent_max_files: 30\n    \n  # Pass any arg directly to yt-dlp's Python API\n  ytdl_options:\n    cookiefile: \"/config/ytdl-sub-configs/cookie.txt\"\n\n###################################################################\n# TV Show Presets. Can replace Plex with Plex/Jellyfin/Emby/Kodi\n\nPlex TV Show by Date:\n\n  # Sets genre tag to \"Documentaries\"\n  = Documentaries:\n    \"NOVA PBS\": \"https://www.youtube.com/@novapbs\"\n    \"National Geographic\": \"https://www.youtube.com/@NatGeo\"\n    \"Cosmos - What If\": \"https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U\"\n\n  # Sets genre tag to \"Kids\", \"TV-Y\" for content rating\n  = Kids | = TV-Y:\n    \"Jake Trains\": \"https://www.youtube.com/@JakeTrains\"\n    \"Kids Toys Play\": \"https://www.youtube.com/@KidsToysPlayChannel\"\n\n  = Music:\n    # TV show subscriptions can support multiple urls and store in the same TV Show\n    \"Rick Beato\":\n      - \"https://www.youtube.com/@RickBeato\"\n      - \"https://www.youtube.com/@rickbeato240\"\n\n  # Set genre tag to \"News\", use `Only Recent` preset to only store videos uploaded recently\n  = News | Only Recent:\n    \"BBC News\": \"https://www.youtube.com/@BBCNews\"\n\nPlex TV Show Collection:\n  = Music:\n    # Prefix with ~ to set specific override variables\n    \"~Beyond the Guitar\":\n      s01_name: \"Videos\"\n      s01_url: \"https://www.youtube.com/c/BeyondTheGuitar\"\n      s02_name: \"Covers\"\n      s02_url: \"https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W\"\n\n###################################################################\n# Music Presets.\n\nYouTube Releases:\n  = Jazz:  # Sets genre tag to \"Jazz\"\n    \"Thelonious Monk\": \"https://www.youtube.com/@theloniousmonk3870/releases\"\n\nYouTube Full Albums:\n  = Lofi:\n    \"Game Chops\": \"https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i\"\n\nSoundCloud Discography:\n  = Chill Hop:\n    \"UKNOWY\": \"https://soundcloud.com/uknowymunich\"\n  = Synthwave:\n    \"Lazerdiscs Records\": \"https://soundcloud.com/lazerdiscsrecords\"\n    \"Earmake\": \"https://soundcloud.com/earmake\"\n\nBandcamp:\n  = Lofi:\n    \"Emily Hopkins\": \"https://emilyharpist.bandcamp.com/\"\n\n###################################################################\n# Music Video Presets. Can replace Plex with Plex/Jellyfin/Kodi\n\"Plex Music Videos\":\n  = Pop:  # Sets genre tag to \"Pop\"\n    \"Rick Astley\": \"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc\"\n    \"Michael Jackson\": \"https://www.youtube.com/playlist?list=OLAK5uy_mnY03zP6abNWH929q2XhGzWD_2uKJ_n8E\"\n```\n\nAll of this can be downloaded and ready to import to your favorite player \nusing the command\n```commandline\nytdl-sub sub subscriptions.yaml\n```\nSee our\n[example subscriptions](https://github.com/jmbannon/ytdl-sub/tree/master/examples)\nfor more detailed examples and use-cases.\n\n### Output\nAfter `ytdl-sub` runs, the end result will download and format the files into something ready \nto be consumed by your favorite media player/server.\n```\ntv_shows/\n  Jake Trains/\n    Season 2021/\n      s2021.e031701 - Pattys Day Video-thumb.jpg\n      s2021.e031701 - Pattys Day Video.mp4\n      s2021.e031701 - Pattys Day Video.nfo\n      s2021.e031702 - Second Pattys Day Video-thumb.jpg\n      s2021.e031702 - Second Pattys Day Video.mp4\n      s2021.e031702 - Second Pattys Day Video.nfo\n    Season 2022/\n      s2022.e122501 - Merry Christmas-thumb.jpg\n      s2022.e122501 - Merry Christmas.mp4\n      s2022.e122501 - Merry Christmas.nfo\n    poster.jpg\n    fanart.jpg\n    tvshow.nfo\n\nmusic/\n  Artist/\n    [2022] Some Single/\n      01 - Some Single.mp3\n      folder.jpg\n    [2023] Latest Album/\n      01 - Track Title.mp3\n      02 - Another Track.mp3\n      folder.jpg\n\nmusic_videos/\n  Elton John/\n    Elton John - Rocketman.jpg\n    Elton John - Rocketman.mp4\n```\n\n## Custom Configs\nAny part of this process is modifiable by using custom configs. See our\n[walk-through guide](https://ytdl-sub.readthedocs.io/en/latest/guides/index.html)\non how to build your first config from scratch. Ready-to-use\n[example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples)\ncan be found here alongside our\n[readthedocs](https://ytdl-sub.readthedocs.io/en/latest/index.html)\nfor detailed information on all config fields.\n\n## Installation\n`ytdl-sub` can be installed on the following platforms.\n\n- [Docker Compose](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)\n  - [Web-GUI](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)\n  - [Headless](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)\n  - [CPU / GPU Passthrough](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#device-passthrough)\n- [Docker CLI](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#docker-cli)\n- [Windows](https://ytdl-sub.readthedocs.io/en/latest/guides/install/windows.html)\n- [Unraid](https://ytdl-sub.readthedocs.io/en/latest/guides/install/unraid.html)\n- [Linux](https://ytdl-sub.readthedocs.io/en/latest/guides/install/linux.html)\n- [Linux ARM](https://ytdl-sub.readthedocs.io/en/latest/guides/install/linux.html)\n- [PIP](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#pip-install)\n- [Local Install](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#local-install)\n- [Local Docker Build](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#local-docker-build)\n\n### Docker Installation\nDocker installs can be either headless or use the Web-GUI image, which comprises\n[LSIO's](https://www.linuxserver.io/)\n[code-server](https://hub.docker.com/r/linuxserver/code-server)\nDocker image with `ytdl-sub` preinstalled. This is the recommended way to use ``ytdl-sub``.\n\n![image](https://github.com/jmbannon/ytdl-sub/assets/10107080/c2aac8a1-5443-4345-b438-be4b17187c80)\n\n\n## Contributing\nThere are many ways to contribute, even without coding. Please take a look in\nour [GitHub Issues](https://github.com/jmbannon/ytdl-sub/issues) to submit a feature request, or \npick up a bug.\n\n## Support\nWe are pretty active in our\n[Discord channel](https://discord.gg/v8j9RAHb4k)\nif you have any questions. Also see our\n[FAQ](https://ytdl-sub.readthedocs.io/en/latest/faq/index.html)\nfor commonly asked questions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmbannon%2Fytdl-sub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjmbannon%2Fytdl-sub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjmbannon%2Fytdl-sub/lists"}