beets-ytimport

A beets plugin to download audio from Youtube and import it into your library.

Differences compared to the ydl plugin:

• Supports downloading liked songs into your beets library (using ytmusicapi).
• Downloading opus files from Youtube and mp3 from SoundCloud, avoiding re-encoding lossy audio (which would decrease quality).
• Uses yt-dlp instead of ytdl to download the audio files.

Installation

python3 -m pip install beets-ytimport ytmusicapi yt-dlp

Configuration

Enable the plugin and add a ytimport section to your beets config.yaml as follows:

plugins:
  - ytimport

ytimport:
  directory: /path/to/youtube/cache # required
  import: true
  reimport: false
  # Prefers opus over m4a due to higher quality and support for custom tags.
  # (You can get opus or m4a from Youtube and mp3 from SoundCloud.)
  # To prefer m4a instead, set 'm4a/bestaudio/best'.
  format: bestaudio/best
  url_file: ''
  likes: false
  max_likes: 15
  set:
    loved: true
  auth_headers: /path/to/your/http/headers
  min_length: 60 # 1m; min track length in seconds
  max_length: 7200 # 2h; max track length in seconds
  max_length_nochapter: 900 # 15m; max track length when no chapters defined
  split_tracks: true
  group_albums: true
  quiet_fallback: skip # optional; alternatively, to import as is, set 'asis'.

clutter:
  - cover.jpg

For more information, see CLI.

Usage

Once 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:

beet ytimport --likes --max-likes 3

Please note that the command prompts you for Google authentication, unless you specified the auth_headers option within your beets configuration file pointing to a file containing HTTP headers (to get the HTTP headers, see here). Import auto-tagger prompts can be disabled by specifying the -q option. You can interrupt and continue or repeat the command to synchronize likes from your Youtube account(s) into your beets library incrementally.

To download a particular track, run:

beet ytimport --no-likes https://www.youtube.com/watch?v=hC8CH0Z3L54

CLI

Usage: beet ytimport [options]

Options:
  -h, --help            show this help message and exit
  --directory=DIR       directory to download Youtube files to
  --format=FORMAT       preferred file format
  --auth-headers=FILE   path to a file containing the HTTP headers of an
                        authenticated POST request to music.youtube.com,
                        copied from your browser's development tool
  --url-file=FILE       file containing a download URL per line
  --likes               download liked songs
  --no-likes            don't download liked songs
  --max-likes=LIKES     maximum number of likes to obtain
  --split-tracks        split tracks by chapter
  --no-split-tracks     don't split tracks
  --group-albums        import split tracks as albums
  --no-group-albums     don't import split tracks as albums
  --import              import downloaded songs into beets
  --no-import           don't import downloaded songs into beets
  --reimport            re-download and re-import tracks
  --no-reimport         don't re-download and re-import tracks
  --set=KEY=VALUE       set a field on import, using KEY=VALUE format
  --min-length=SECONDS  minimum track length in seconds
  --max-length=SECONDS  maximum track length in seconds
  --max-length-nochapter=SECONDS
                        max track length in seconds when no chapters defined
  -q, --quiet           don't prompt for input when importing
  --quiet-fallback=skip|asis
                        decision in quiet mode when there is no strong match
  --pretend             don't import but print the files when importing

Development

Run the unit tests (containerized):

make test

Run the e2e tests (containerized):

make test-e2e

To test your plugin changes manually, you can run a shell within a beets docker container as follows:

make beets-sh

A temporary beets library is written to ./data. It can be removed by calling make clean-data.