{"id":14979870,"url":"https://github.com/mgoltzsche/beets-ytimport","last_synced_at":"2025-10-18T19:02:05.878Z","repository":{"id":200618842,"uuid":"705926680","full_name":"mgoltzsche/beets-ytimport","owner":"mgoltzsche","description":"A beets plugin to import music from Youtube and SoundCloud","archived":false,"fork":false,"pushed_at":"2024-08-25T18:46:04.000Z","size":127,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-09-29T03:41:03.017Z","etag":null,"topics":["beets","beets-plugin","python","youtube","youtube-dl","youtube-downloader","youtube-likes","yt-dlp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mgoltzsche.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}},"created_at":"2023-10-17T01:11:41.000Z","updated_at":"2024-08-25T18:46:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"c6c55b82-7cf8-4bbf-95f0-bb1ad1b5c8c0","html_url":"https://github.com/mgoltzsche/beets-ytimport","commit_stats":{"total_commits":69,"total_committers":1,"mean_commits":69.0,"dds":0.0,"last_synced_commit":"9bfe9f0fe58117113b689ce722878b6c03d75e41"},"previous_names":["mgoltzsche/beets-youtube","mgoltzsche/beets-ytimport"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fbeets-ytimport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fbeets-ytimport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fbeets-ytimport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoltzsche%2Fbeets-ytimport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgoltzsche","download_url":"https://codeload.github.com/mgoltzsche/beets-ytimport/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219858899,"owners_count":16556039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["beets","beets-plugin","python","youtube","youtube-dl","youtube-downloader","youtube-likes","yt-dlp"],"created_at":"2024-09-24T14:00:49.119Z","updated_at":"2025-10-18T19:02:05.866Z","avatar_url":"https://github.com/mgoltzsche.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# beets-ytimport\n\nA [beets](https://github.com/beetbox/beets) plugin to download audio from [Youtube](https://www.youtube.com/) and import it into your library.\n\nDifferences compared to the [ydl plugin](https://github.com/vmassuchetto/beets-ydl):\n* Supports downloading liked songs into your beets library (using [ytmusicapi](https://github.com/sigma67/ytmusicapi)).\n* Uses [yt-dlp](https://github.com/yt-dlp/yt-dlp) instead of [ytdl](https://github.com/ytdl-org/youtube-dl) to download the audio files.\n* Prefers to download Opus files, avoiding re-encoding lossy audio (which would decrease quality).\n\n## Installation\n\n```sh\npython3 -m pip install beets-ytimport ytmusicapi yt-dlp\n```\n\n## Configuration\n\nEnable the plugin and add a `ytimport` section to your beets `config.yaml` as follows:\n```yaml\nplugins:\n  - ytimport\n\nimport:\n  move: true\n# Alternatively, you can declare left-over cover art within the import source dir as clutter:\n#clutter:\n#  - cover.jpg\n\nytimport:\n  directory: /path/to/youtube/cache # required\n  import: true\n  reimport: false\n  # Prefers opus over m4a due to higher quality and support for custom tags.\n  # (You can get opus or m4a from Youtube and mp3 from SoundCloud.)\n  # To prefer m4a instead, set 'm4a/bestaudio/best'.\n  format: bestaudio/best\n  url_file: ''\n  likes: false\n  max_likes: 15\n  set:\n    loved: true\n  oauth_client_id: ''\n  oauth_client_secret: ''\n  auth_headers: ''\n  cookiefile: path/to/your/cookies\n  min_length: 60 # 1m; min track length in seconds\n  max_length: 7200 # 2h; max track length in seconds\n  max_length_nochapter: 900 # 15m; max track length when no chapters defined\n  split_tracks: true\n  group_albums: true\n  quiet_fallback: skip # optional; alternatively, to import as is, set 'asis'.\n```\n\n### Authentication\n\nIn case the `likes` option is enabled and no `auth_headers` configured, ytimport prompts for Google authentication which requires OAuth client credentials (`oauth_client_id`, `oauth_client_secret`) to be configured (requres a Google Cloud Console account, see [here](https://ytmusicapi.readthedocs.io/en/stable/setup/oauth.html)).\n\nTo configure `auth_headers` specify a path to a file containing HTTP headers (to get the HTTP headers, see [here](https://ytmusicapi.readthedocs.io/en/stable/setup/browser.html#copy-authentication-headers)).\n\nTo download premium quality audio, let `cookiefile` point to a file that holds the HTTP cookies for a logged in premium user on music.youtube.com in Netscape format. To create the cookies file, you can use a browser extension, e.g. [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/) for Firefox.\n\nFor more information, see [CLI](#cli).\n\n## Usage\n\nOnce you enabled the `ytimport` plugin within your beets configuration, you can download your liked songs from Youtube and import them into your beets library as follows:\n```sh\nbeet ytimport --likes --max-likes 3\n```\nPlease note that the command prompts you for Google authentication which requires you to have OAuth client credentials configured, unless you specified the `auth_headers` option within your beets configuration file, see [authentication](#authentication).\n\nImport auto-tagger prompts can be disabled by specifying the `-q` option.\nYou can interrupt and continue or repeat the command to synchronize likes from your Youtube account(s) into your beets library incrementally.\n\nTo download a particular track, run:\n```sh\nbeet ytimport --no-likes https://www.youtube.com/watch?v=hC8CH0Z3L54\n```\n\n### CLI\n\n```\nUsage: beet ytimport [options]\n\nOptions:\n  -h, --help            show this help message and exit\n  --directory=DIR       directory to download Youtube files to\n  --format=FORMAT       preferred file format\n  --auth-headers=FILE   path to a file containing the HTTP headers of an\n                        authenticated POST request to music.youtube.com,\n                        copied from your browser's development tool\n  --url-file=URL        URL/path to a file containing a download URL per line\n  --likes               download liked songs\n  --no-likes            don't download liked songs\n  --max-likes=LIKES     maximum number of likes to obtain\n  --split-tracks        split tracks by chapter\n  --no-split-tracks     don't split tracks\n  --group-albums        import split tracks as albums\n  --no-group-albums     don't import split tracks as albums\n  --import              import downloaded songs into beets\n  --no-import           don't import downloaded songs into beets\n  --reimport            re-download and re-import tracks\n  --no-reimport         don't re-download and re-import tracks\n  --set=KEY=VALUE       set a field on import, using KEY=VALUE format\n  --min-length=SECONDS  minimum track length in seconds\n  --max-length=SECONDS  maximum track length in seconds\n  --max-length-nochapter=SECONDS\n                        max track length in seconds when no chapters defined\n  -q, --quiet           don't prompt for input when importing\n  --quiet-fallback=skip|asis\n                        decision in quiet mode when there is no strong match\n  --pretend             don't import but print the files when importing\n  --cookiefile          path to a file containing the cookies for a logged in\n                        user on music.youtube.com in Netscape format\n```\n\n## Development\n\nRun the unit tests (containerized):\n```sh\nmake test\n```\n\nRun the e2e tests (containerized):\n```sh\nmake test-e2e\n```\n\nTo test your plugin changes manually, you can run a shell within a beets docker container as follows:\n```sh\nmake beets-sh\n```\n\nA temporary beets library is written to `./data`.\nIt can be removed by calling `make clean-data`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoltzsche%2Fbeets-ytimport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgoltzsche%2Fbeets-ytimport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoltzsche%2Fbeets-ytimport/lists"}