Merge branch 'dev' into datastar

Author: Silverarmor

README.md

@@ -117,9 +117,9 @@ For a list of all **options** use ```spotdl -h```
     - Usage:
         `spotdl save [query] --save-file {filename}.spotdl`
 
-- `web`: Starts a web interface instead of using the command line. However, it has limited features and only supports downloading single songs.
+- `web`: Starts a web interface instead of using the command line. However, it has limited features and only supports downloading individual songs.
 
-- `url`: Get direct download link for each song from the query.
+- `url`: Get user-friendly URL for each song from the query.
     - Usage:
         `spotdl url [query]`
 
@@ -128,7 +128,7 @@ For a list of all **options** use ```spotdl -h```
     - Usage:
         `spotdl sync [query] --save-file {filename}.spotdl`
 
-        This create a new **sync** file, to update the directory in the future, use:
+        This creates a new **sync** file. To update the directory in the future, use:
 
         `spotdl sync {filename}.spotdl`
 

docs/CONTRIBUTING.md

@@ -47,7 +47,7 @@ following:
 
 - Open an [Issue](https://github.com/spotDL/spotify-downloader/issues/new).
 - Provide as much context as you can about what you're running into.
-- Provide project and platform versions (nodejs, npm, etc), depending on what seems relevant.
+- Provide project and platform versions (Node.js, npm, etc.), depending on what seems relevant.
 
 We will then take care of the issue as soon as possible.
 
@@ -74,6 +74,31 @@ Depending on how large the project is, you may want to outsource the questioning
 > that you have the necessary rights to the content and that the content you contribute may be
 > provided under the project license.
 
+---
+
+### AUTOMATED CONTRIBUTIONS (AI / LLM) POLICY
+
+#### AI Use
+- It is in everyone's best interest to **not** submit issues, pull requests or feature requests that are AI-generated.
+- All such requests will be closed and submitters will be blocked from the repository.
+
+#### You must...
+- Be able to understand and respond to questions relating to the issue or the fix you provide.
+- You *can* use an AI tool for proofreading, translating or understanding the issue's content.
+- You **cannot** use AI tools to generate the issue text, or the issue itself.
+
+#### Pull Requests
+- You should be able to explain every part of the code you have written/modified in your PR.
+- If you do not understand your PR, **do not** submit it. You cannot use an AI tool to generate code for you.
+
+The rationale behind this policy is that automated contributions are a waste of the maintainers' time. Humans spend their time and brainpower reviewing every submission. Issues or pull requests generated by automation tools create an imbalance of effort between the submitter and the reviewer. Nobody learns anything when a maintainer reviews code written by an LLM.
+
+Additionally, such AI-generated content impedes legitimate issues and feature requests that would add more value to the project.
+
+
+---
+
+
 ### Reporting Bugs
 
 <!-- omit in toc -->
@@ -263,13 +288,13 @@ Any submitted code is expected to have accompanying documentation
 
 - We generate our documentation with [`mkdocs`](https://www.mkdocs.org/)
 
-  generate docs with
+  Generate docs with
 
   ```bash
   mkdocs build --strict
   ```
 
-  view docs live-time while editing with
+  View docs in real-time while editing with
 
   ```bash
   mkdocs serve
@@ -280,7 +305,7 @@ Any submitted code is expected to have accompanying documentation
 - For functions
 
   ```text
-  one-liner about functions purpose
+  one-liner about function's purpose
 
   ### Args (optional)
   - arg_name: description
@@ -310,9 +335,9 @@ Any submitted code is expected to have accompanying documentation
 - For modules/package `__init__`
 
   ```text
-  at max 3 lines about module/package purpose
+  At most 3 lines about module/package purpose
 
-  optional usage example for module/package preferably showcasing most commonly used functionality
+  Optional usage example for module/package, preferably showcasing most commonly used functionality
   ```
 
 #### Notes about docstrings

docs/installation.md

@@ -1,15 +1,15 @@
 # spotDL Installation Guide
 
-spotDL is a free and open source tool that downloads your Spotify playlists & music
+spotDL is a free and open-source tool that downloads your Spotify playlists & music
 
 > **The fastest, easiest, and most accurate command-line music downloader**
 
 ## Install via Python
 
 > This is our recommended installation method.
 
-If you are on Windows, Install Visual C++ Redistributable (link below) and then proceed to
-install Python & FFmpeg
+If you are on Windows, install Visual C++ Redistributable (link below) and then proceed to
+install Python & FFmpeg.
 
 ### Prerequisites to spotDL
 
@@ -31,11 +31,11 @@ When installing [Python](https://python.org/), ensure to select "**Add to PATH**
 > If you are not on Windows (e.g. OSX/UNIX), replace `pip` with `pip3` and `python` with
 > `python3` in all commands.
 
-Firstly, open a terminal. On Windows: Command Prompt, OSX: "Terminal", \*UNIX: Bash or Zsh.
+First, open a terminal. On Windows: Command Prompt, macOS: "Terminal", *UNIX: Bash or Zsh.
 
 Verify you have installed Python correctly via `python -V`. Ensure you have v3.7 or greater.
 
-Next, install spotDL by typing the following
+Next, install spotDL by typing the following:
 
 ```shell
 pip install spotdl
@@ -65,15 +65,15 @@ You can download the latest version from the
 
 ### Running Web UI
 
-Web UI will start by default if no arguments are passed to the command line (after
-double-clicking for example)
+The Web UI will start by default if no arguments are passed to the command line (after
+double-clicking, for example).
 
 ![Web UI](images/WEB_UI.png)
 
 ### Running the CLI
 
-To use the command line interface just open your terminal and run
-`./spotdl-vX.X.X operation [urls]`
+To use the command line interface, just open your terminal and run
+`./spotdl-vX.X.X operation [urls]`.
 
 ## Docker Setup
 
@@ -118,7 +118,7 @@ docker create \
 
 ### Termux
 
-We have a dedicated Termux installation script
+We have a dedicated Termux installation script:
 `curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh`
 
 ### Arch User Repository (AUR) package
@@ -129,7 +129,7 @@ We have a dedicated Termux installation script
 
 spotDL downloads files to the folder where you ran spotDL from.
 
-Open pwsh/powershell/cmd/terminal/similar in the folder you want files to download to, or cd to
+Open pwsh/powershell/cmd/terminal/similar in the folder you want files to download to, or cd to the
 desired folder.
 
 **Windows Shortcut:** Navigate to the folder you want the files to download to.

docs/troubleshooting.md

@@ -7,8 +7,8 @@ As common issues or questions are encountered solutions will be added to this gu
     Python/(site packages) is not added to PATH correctly. You need to install Python from
     <https://www.python.org/downloads/>
 
-    Or you are using python from microsoft store. If so uninstall it and restart cmd. If this
-    doesn't work reinstall python.
+    Or you are using Python from the Microsoft Store. If so, uninstall it and restart cmd. If this
+    doesn't work, reinstall Python.
 
     ### Error message
 
@@ -24,7 +24,7 @@ As common issues or questions are encountered solutions will be added to this gu
 ??? "spotdl: command not found"
 
     If you see this error after installing spotdl, that means that the bin (Binaries) folder is not
-    on `$PATH`
+    in `$PATH`.
 
     ### Solution
 
@@ -40,8 +40,8 @@ As common issues or questions are encountered solutions will be added to this gu
 
 ??? "pkg_resources.DistributionNotFound"
 
-    Sometimes not all packages are installed but are required by yt-dlp for example: `brotli` or
-    `websockets`
+    Sometimes not all packages are installed but are required by yt-dlp, for example: `brotli` or
+    `websockets`.
 
     ### Error Message
 
@@ -61,7 +61,7 @@ As common issues or questions are encountered solutions will be added to this gu
 
     ### Solution
 
-    Update spotdl to the latest version which contains workaround.
+    Update spotdl to the latest version which contains a workaround.
 
     `pip install -U spotdl`
 
@@ -87,7 +87,7 @@ As common issues or questions are encountered solutions will be added to this gu
 
     ### Solution
 
-    Update spotdl
+    Update spotdl:
 
     `pip install spotdl -U`
 
@@ -105,11 +105,11 @@ As common issues or questions are encountered solutions will be added to this gu
 
     ### Solution
 
-    You can ignore this error or just run spotdl directly
+    You can ignore this error or just run spotdl directly.
 
 ??? "Not found '\_raw_ecb.so'"
 
-    This error is specific for M1 Macs only.
+    This error is specific to M1 Macs only.
 
     https://discord.com/channels/771628785447337985/871006150357823498
     https://discord.com/channels/771628785447337985/939475659238043738
@@ -130,3 +130,33 @@ As common issues or questions are encountered solutions will be added to this gu
 
     <https://discord.com/channels/771628785447337985/871006150357823498>
     <https://discord.com/channels/771628785447337985/939475659238043738>
+
+??? "KeyError: 'header' - YouTube Music API error"
+
+    This error occurs when YouTube Music's API response structure changes intermittently. The error has been fixed in ytmusicapi v1.11.1, which is the minimum version required by spotdl v4.4.3.
+
+    ### Error Message
+
+    ```
+    KeyError: "Unable to find 'header' using path ['header', 'musicCardShelfHeaderBasicRenderer', 'title', 'runs', 0, 'text']"
+    ```
+
+    ### Solution
+
+    1. Update ytmusicapi to v1.11.1 or later:
+
+        ```bash
+        pip install -U ytmusicapi
+        ```
+
+    2. If the error persists, reinstall spotdl:
+
+        ```bash
+        pip install -U --force spotdl
+        ```
+
+    3. If you're still experiencing issues, the error may be intermittent due to YouTube's anti-bot mechanisms. Wait a few minutes and try again.
+
+    ### Background
+
+    YouTube Music occasionally returns different response structures from their API. Version 1.11.1 of ytmusicapi includes a fallback mechanism that handles cases where the `header` field is missing from search results. This fix was implemented in PR #800 (https://github.com/sigma67/ytmusicapi/pull/800) to address issue #799.

docs/usage.md

@@ -68,8 +68,8 @@
     ```
 
 ??? info "YouTube link with Spotify metadata"
-    To download YouTube video with metadata from Spotify, run
-    > Noting the quote `"` are required
+    To download a YouTube video with metadata from Spotify, run
+    > Note that the quotes `"` are required
 
     ```bash
     spotdl download "YouTubeURL|SpotifyURL"
@@ -82,23 +82,23 @@
     ```
 
 ??? info "Liked songs"
-    To download liked Spotify songs run
+    To download liked Spotify songs, run
     > `--user-auth` is required
 
     ```bash
     spotdl download saved --user-auth
     ```
 
 ??? info "All user playlists"
-    To download all user playlists run
+    To download all user playlists, run
     > `--user-auth` is required
 
     ```bash
     spotdl download all-user-playlists --user-auth
     ```
 
 ??? info "All user saved albums"
-    To download all user saved albums run
+    To download all user saved albums, run
     > `--user-auth` is required
 
     ```bash
@@ -154,11 +154,11 @@ To download music in higher quality follow the steps below:
 
 ## Syncing
 
-Sync function for the console. Keep local files up to date with playlists/albums/etc.
-This will download new songs and remove the ones that are no longer present in the playlists/albums/etc
+Sync function for the console. Keeps local files up to date with playlists/albums/etc.
+This will download new songs and remove the ones that are no longer present in the playlists/albums/etc.
 
 ??? info "Initialize Synchronization"
-    To create the sync file run
+    To create the sync file, run
 
     ```bash
     spotdl sync [query] --save-file [fileName]
@@ -173,7 +173,7 @@ This will download new songs and remove the ones that are no longer present in t
     > Note: The sync file has to end with .spotdl
 
 ??? info "Syncing"
-    To sync the songs run
+    To sync the songs, run
 
     ```bash
     spotdl sync [fileName]
@@ -208,7 +208,7 @@ spotdl save 'The Weeknd - Blinding Lights' --save-file 'the-weeknd.spotdl'
 ```
 
 ??? info "Preloading"
-    Preload the download url to speed up the download process.
+    Preload the download URL to speed up the download process.
 
     ```bash
     spotdl save [query] --save-file [fileName] --preload
@@ -238,9 +238,9 @@ add option `--web-use-output-dir`, which will make output directory follow `--ou
 ### Config file location
 
 The config file is located at `C:\Users\user\.spotdl\config.json`
-or `~/.spotdl/config.json` under linux
+or `~/.config/spotdl/config.json` under Linux
 
-> Note: If you want to use XDG_DATA_HOME directory, run `mkdir $XDG_DATA_HOME/spotdl`, next time you run spotdl it will be automatically used.
+> Note: Prior to v4.4.3 the default Linux location was `~/.spotdl/config.json` which will be used if the new directory doesn't exist.
 
 ### Generate a config file
 
@@ -254,9 +254,9 @@ spotdl --generate-config
 
 ### Loading config
 
-Config file gets loaded automatically if it already exists, or if you've passed `--config` flag
+The config file gets loaded automatically if it already exists, or if you've passed the `--config` flag.
 
-If you don't want config to load automatically change `load_config` option in config file to false
+If you don't want the config to load automatically, change the `load_config` option in the config file to false
 
 ```json
 {
@@ -413,8 +413,8 @@ Main options:
                         {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 search for. (album, single)
+  --album-type {single,album,compilation}
+                        Type of the album to search for. (album, single, compilation)
   --only-verified-results
                         Use only verified results. (Not all providers support this)
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spotdl"
-version = "4.4.2"
+version = "4.4.3"
 requires-python = ">=3.10,<3.14"
 
 description = "Download your Spotify playlists and songs along with album art and metadata"
@@ -32,9 +32,9 @@ classifiers = [
 ]
 dependencies = [
     "spotipy>=2.24.0,<3",
-    "ytmusicapi>=1.11.0,<2",
+    "ytmusicapi>=1.11.1,<2",
     "pytube>=15.0.0,<16",
-    "yt-dlp>=2025.08.27,<2026",
+    "yt-dlp>=2025.09.26,<2027",
     "mutagen>=1.47.0,<2",
     "rich>=13.9.4,<14",
     "beautifulsoup4>=4.12.3,<5",

spotdl/_version.py

@@ -2,4 +2,4 @@
 Version module for spotdl.
 """
 
-__version__ = "4.4.2"
+__version__ = "4.4.3"