v4.2.6 (#2141)

update min python version for tests update docs Co-Authored-By: kuba <[email protected]> Co-Authored-By: Jayden <[email protected]> Co-Authored-By: Robert Schütz <[email protected]> Co-Authored-By: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-Authored-By: Alexis Raphaeloff <[email protected]> Co-Authored-By: Randy Blancett <[email protected]> Co-Authored-By: darcy <[email protected]> Co-Authored-By: Karan Bheda <[email protected]> Co-Authored-By: Jeremy Cutler <[email protected]> Co-Authored-By: Soiu Cristian-Ionuț <[email protected]> Co-Authored-By: Peter S <[email protected]> Co-Authored-By: Alan <[email protected]>
spotDL · Aug 24, 2024 · e4e3201 · e4e3201
1 parent bd38845
commit e4e3201
Show file tree

Hide file tree

Showing 53 changed files with 38,165 additions and 122,855 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -29,7 +29,6 @@ body:
       You can find your Python version by running `python -V` on your CLI
       If you use a different Python version, please let us know below
     options:
-      - 3.7 (CPython)
       - 3.8 (CPython)
       - 3.9 (CPython)
       - 3.10 (CPython)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -7,10 +7,46 @@ jobs:
     if: "!contains(github.event.commits[0].message, '[skip ci]')"
     runs-on: ${{ matrix.platform }}
     strategy:
-      max-parallel: 4
+      max-parallel: 1
       matrix:
-        platform: [ ubuntu-latest, macos-latest, windows-latest ]
-        python-version: [ "3.8", "3.11" ]
+        platform: [ ubuntu-latest, macos-13, windows-latest ]
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Set up Python "3.11"
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: 'poetry'
+
+      - name: Install dependencies
+        run: |
+          poetry env use "3.11"
+          poetry install
+
+      - uses: FedericoCarboni/setup-ffmpeg@v1
+        id: setup-ffmpeg
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run tests
+        run: |
+          poetry run pytest -vvv --record-mode=new_episodes --ignore tests/test_matching.py --ignore tests/utils/test_ffmpeg.py --ignore tests/utils/test_metadata.py --ignore tests/providers/lyrics/test_azlyrics.py --ignore tests/providers/lyrics/test_musixmatch.py --ignore tests/providers/audio/test_youtube.py --ignore tests/console/test_entry_point.py --ignore tests/test_init.py
+        env:
+          PLATFORM: ${{ matrix.platform }}
+
+  test:
+    if: "!contains(github.event.commits[0].message, '[skip ci]')"
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      max-parallel: 3
+      matrix:
+        platform: [ ubuntu-latest, macos-13, windows-latest ]
+        python-version: [ "3.9", "3.11" ]
 
     steps:
       - uses: actions/checkout@v3
@@ -37,17 +73,13 @@ jobs:
 
       - name: Run tests
         run: |
-          poetry run pytest -vvv --ignore tests/test_matching.py --ignore tests/utils/test_ffmpeg.py --ignore tests/utils/test_metadata.py --ignore tests/providers/lyrics/test_azlyrics.py --ignore tests/providers/lyrics/test_musixmatch.py 
+          poetry run pytest -vvv --record-mode=none --disable-recording --ignore tests/providers/lyrics --ignore tests/utils/test_github.py --ignore tests/utils/test_ffmpeg.py --ignore tests/utils/test_metadata.py --ignore tests/test_matching.py --ignore tests/providers/audio/test_youtube.py --ignore tests/console/test_entry_point.py --ignore tests/test_init.py
         env:
           PLATFORM: ${{ matrix.platform }}
 
-  test:
+  matching:
     if: "!contains(github.event.commits[0].message, '[skip ci]')"
-    runs-on: ${{ matrix.platform }}
-    strategy:
-      max-parallel: 1
-      matrix:
-        platform: [ ubuntu-latest, macos-latest, windows-latest ]
+    runs-on: "ubuntu-latest"
 
     steps:
       - uses: actions/checkout@v3
@@ -73,6 +105,4 @@ jobs:
 
       - name: Run tests
         run: |
-          poetry run pytest -vvv --record-mode=none --disable-recording --ignore tests/providers/lyrics --ignore tests/utils/test_github.py --ignore tests/utils/test_ffmpeg.py --ignore tests/utils/test_metadata.py
-        env:
-          PLATFORM: ${{ matrix.platform }}
+          poetry run pytest -vvv --record-mode=none --disable-recording tests/test_matching.py
diff --git a/.gitignore b/.gitignore
@@ -14,7 +14,9 @@
 *.m3u8
 *.ipynb
 *.lrc
+*.profile
 .spotdl-cache
+.syncedlyrics
 
 # Docs
 docs/source/_build/

diff --git a/docs/usage.md b/docs/usage.md
@@ -260,14 +260,15 @@ If you don't want config to load automatically change `load_config` option in co
 
 ```json
 {
-    "client_id": "5f573c9620494bae87890c0f08a60293",
-    "client_secret": "212476d9b0f3472eaa762d90b19b0ba8",
+    "client_id": "f8a606e5583643beaa27ce62c48e3fc1",
+    "client_secret": "f6f4c8f73f0649939286cf417c811607",
     "auth_token": null,
     "user_auth": false,
     "headless": false,
     "cache_path": "/Users/username/.spotdl/.spotipy",
     "no_cache": false,
     "max_retries": 3,
+    "use_cache_file": false,
     "audio_providers": [
         "youtube-music"
     ],
@@ -305,14 +306,33 @@ If you don't want config to load automatically change `load_config` option in co
     "add_unavailable": false,
     "generate_lrc": false,
     "force_update_metadata": false,
+    "only_verified_results": false,
+    "sync_without_deleting": false,
+    "max_filename_length": null,
+    "yt_dlp_args": null,
+    "detect_formats": null,
+    "save_errors": null,
+    "ignore_albums": null,
+    "proxy": null,
+    "skip_explicit": false,
+    "log_format": null,
+    "redownload": false,
+    "skip_album_art": false,
+    "create_skip_file": false,
+    "respect_skip_file": false,
     "web_use_output_dir": false,
     "port": 8800,
     "host": "localhost",
     "keep_alive": false,
+    "enable_tls": false,
+    "key_file": null,
+    "cert_file": null,
+    "ca_file": null,
     "allowed_origins": null,
     "keep_sessions": false,
-    "only_verified_results": false,
-    "skip_album_art": false
+    "force_update_gui": false,
+    "web_gui_repo": null,
+    "web_gui_location": null
 }
 ```
 
@@ -367,7 +387,9 @@ Main options:
                         (ie. 'album:the album name' you can mix these options to get more accurate results).
 
                         To download liked songs use 'saved' as the query, to download all user playlists
-                        use 'all-user-playlists, to download all songs from all followed artists use 'all-user-followed-artists', to download all user saved albums use 'all-user-saved-albums'
+                        use 'all-user-playlists, to download playlists that the user has created
+                        use 'all-saved-playlists', to download all user liked playlists
+                        use 'all-user-followed-artists', to download all user saved albums use 'all-user-saved-albums'
 
                         For manual audio matching, you can use the format 'YouTubeURL|SpotifyURL'
                         You can only use album/playlist/tracks urls when downloading/matching youtube urls.
@@ -376,16 +398,18 @@ Main options:
   --audio [{youtube,youtube-music,slider-kz,soundcloud,bandcamp,piped} ...]
                         The audio provider to use. You can provide more than one for fallback.
   --lyrics [{genius,musixmatch,azlyrics,synced} ...]
-                        The lyrics provider to use. You can provide more than one for fallback. Synced lyrics might not work correctly with some music players. For such cases it's better to use `--generate-lrc`
-                        option.
+                        The lyrics provider to use. You can provide more than one for fallback. Synced lyrics might not work correctly with some music players. For such cases it's better
+                        to use `--generate-lrc` option.
+  --genius-access-token GENIUS_TOKEN
+                        Lets you choose your own Genius access token.
   --config              Use the config file to download songs. It's located under C:\Users\user\.spotdl\config.json or ~/.spotdl/config.json under linux
   --search-query SEARCH_QUERY
-                        The search query to use, available variables: {title}, {artists}, {artist}, {album}, {album-artist}, {genre}, {disc-number}, {disc-count}, {duration}, {year}, {original-date}, {track-number},
-                        {tracks-count}, {isrc}, {track-id}, {publisher}, {list-length}, {list-position}, {list-name}, {output-ext}
+                        The search query to use, available variables: {title}, {artists}, {artist}, {album}, {album-artist}, {genre}, {disc-number}, {disc-count}, {duration}, {year},
+                        {original-date}, {track-number}, {tracks-count}, {isrc}, {track-id}, {publisher}, {list-length}, {list-position}, {list-name}, {output-ext}
   --dont-filter-results
                         Disable filtering results.
-  --album-type {single, album}
-                        Type of the album to filter the songs
+  --album-type {single,album}
+                        Type of the album to search for. (album, single)
   --only-verified-results
                         Use only verified results. (Not all providers support this)
 
@@ -403,44 +427,44 @@ Spotify options:
   --max-retries MAX_RETRIES
                         The maximum number of retries to perform when getting metadata.
   --headless            Run in headless mode.
-  --use-cache-file      Use the cache file to get metadata. It's located under C:\Users\user\.spotdl\.spotify_cache or ~/.spotdl/.spotify_cache under linux. It only caches tracks and gets updated whenever spotDL gets
-                        metadata from Spotify. (It may provide outdated metadata use with caution)
+  --use-cache-file      Use the cache file to get metadata. It's located under C:\Users\user\.spotdl\.spotify_cache or ~/.spotdl/.spotify_cache under linux. It only caches tracks and
+                        gets updated whenever spotDL gets metadata from Spotify. (It may provide outdated metadata use with caution)
 
 FFmpeg options:
   --ffmpeg FFMPEG       The ffmpeg executable to use.
   --threads THREADS     The number of threads to use when downloading songs.
   --bitrate {auto,disable,8k,16k,24k,32k,40k,48k,64k,80k,96k,112k,128k,160k,192k,224k,256k,320k,0,1,2,3,4,5,6,7,8,9}
-                        The constant/variable bitrate to use for the output file. Values from 0 to 9 are variable bitrates. Auto will use the bitrate of the original file. Disable will disable the bitrate option. (In
-                        case of m4a and opus files, auto and disable will skip the conversion)
+                        The constant/variable bitrate to use for the output file. Values from 0 to 9 are variable bitrates. Auto will use the bitrate of the original file. Disable will
+                        disable the bitrate option. (In case of m4a and opus files, auto and disable will skip the conversion)
   --ffmpeg-args FFMPEG_ARGS
                         Additional ffmpeg arguments passed as a string.
 
 Output options:
   --format {mp3,flac,ogg,opus,m4a,wav}
                         The format to download the song in.
   --save-file SAVE_FILE
-                        The file to save/load the songs data from/to. It has to end with .spotdl. If combined with the download operation, it will save the songs data to the file. Required for save/sync (use - to
-                        print to stdout when using save).
+                        The file to save/load the songs data from/to. It has to end with .spotdl. If combined with the download operation, it will save the songs data to the file.
+                        Required for save/sync (use - to print to stdout when using save).
   --preload             Preload the download url to speed up the download process.
-  --output OUTPUT       Specify the downloaded file name format, available variables: {title}, {artists}, {artist}, {album}, {album-artist}, {genre}, {disc-number}, {disc-count}, {duration}, {year}, {original-date},
-                        {track-number}, {tracks-count}, {isrc}, {track-id}, {publisher}, {list-length}, {list-position}, {list-name}, {output-ext}
-  --m3u [M3U]           Name of the m3u file to save the songs to. Defaults to {list[0]}.m3u8 If you want to generate a m3u for each list in the query use {list}, If you want to generate a m3u file based on the first
-                        list in the query use {list[0]}, (0 is the first list in the query, 1 is the second, etc. songs don't count towards the list number)
+  --output OUTPUT       Specify the downloaded file name format, available variables: {title}, {artists}, {artist}, {album}, {album-artist}, {genre}, {disc-number}, {disc-count},
+                        {duration}, {year}, {original-date}, {track-number}, {tracks-count}, {isrc}, {track-id}, {publisher}, {list-length}, {list-position}, {list-name}, {output-ext}
+  --m3u [M3U]           Name of the m3u file to save the songs to. Defaults to {list[0]}.m3u8 If you want to generate a m3u for each list in the query use {list}, If you want to generate
+                        a m3u file based on the first list in the query use {list[0]}, (0 is the first list in the query, 1 is the second, etc. songs don't count towards the list number)
   --cookie-file COOKIE_FILE
                         Path to cookies file.
-  --overwrite {skip,force,metadata}
-                        How to handle existing/duplicate files. (When combined with --scan-for-songs force will remove all duplicates, and metadata will only apply metadata to the latest song and will remove the
-                        rest. )
-  --restrict [{ascii,strict,none}]
+  --overwrite {skip,metadata,force}
+                        How to handle existing/duplicate files. (When combined with --scan-for-songs force will remove all duplicates, and metadata will only apply metadata to the latest
+                        song and will remove the rest. )
+  --restrict [{strict,ascii,none}]
                         Restrict filenames to a sanitized set of characters for better compatibility
   --print-errors        Print errors (wrong songs, failed downloads etc) on exit, useful for long playlist
   --save-errors SAVE_ERRORS
                         Save errors (wrong songs, failed downloads etc) to a file
   --sponsor-block       Use the sponsor block to download songs from yt/ytm.
   --archive ARCHIVE     Specify the file name for an archive of already downloaded songs
   --playlist-numbering  Sets each track in a playlist to have the playlist's name as its album, and album art as the playlist's icon
-  --scan-for-songs      Scan the output directory for existing files. This option should be combined with the --overwrite option to control how existing files are handled. (Output directory is the last directory that
-                        is not a template variable in the output template)
+  --scan-for-songs      Scan the output directory for existing files. This option should be combined with the --overwrite option to control how existing files are handled. (Output
+                        directory is the last directory that is not a template variable in the output template)
   --fetch-albums        Fetch all albums from songs in query
   --id3-separator ID3_SEPARATOR
                         Change the separator used in the id3 tags. Only supported for mp3 files.
@@ -456,15 +480,17 @@ Output options:
   --yt-dlp-args YT_DLP_ARGS
                         Arguments to pass to yt-dlp
   --detect-formats [{mp3,flac,ogg,opus,m4a,wav} ...]
-                        Detect already downloaded songs with file format different from the --format option (When combined with --m3u option, only first detected format will be added to m3u file)
+                        Detect already downloaded songs with file format different from the --format option (When combined with --m3u option, only first detected format will be added to
+                        m3u file)
   --redownload          to redownload the local song in diffrent format using --format for meta operation
-  --skip-album-art      Skip downloading album art for meta operation
+  --skip-album-art      skip downloading album art for meta operation
   --ignore-albums [IGNORE_ALBUMS ...]
                         ignores the song of the given albums
   --skip-explicit       Skip explicit songs
   --proxy PROXY         Http(s) proxy server for download song. Example: http://host:port
   --create-skip-file    Create skip file for successfully downloaded file
   --respect-skip-file   If a file with the extension .skip exists, skip download
+  --sync-remove-lrc     Remove lrc files when using sync operation when downloading songs
 
 Web options:
   --host HOST           The host to use for the web server.
@@ -474,6 +500,16 @@ Web options:
                         The allowed origins for the web server.
   --web-use-output-dir  Use the output directory instead of the session directory for downloads. (This might cause issues if you have multiple users using the web-ui at the same time)
   --keep-sessions       Keep the session directory after the web server is closed.
+  --force-update-gui    Refresh the web server directory with a fresh git checkout
+  --web-gui-repo WEB_GUI_REPO
+                        Custom web gui repo to use for the web server. Example: https://github.com/spotdl/web-ui/tree/master/dist
+  --web-gui-location WEB_GUI_LOCATION
+                        Path to the web gui directory to use for the web server.
+  --enable-tls          Enable TLS on the web server.
+  --cert-file CERT_FILE
+                        File Path to the TLS Certificate (PEM format).
+  --key-file KEY_FILE   File Path to the TLS Private Key (PEM format).
+  --ca-file CA_FILE     File Path to the TLS Certificate Authority File (PEM format).
 
 Misc options:
   --log-level {CRITICAL,FATAL,ERROR,WARN,WARNING,INFO,MATCH,DEBUG,NOTSET}