Fix spacing in CLI warning message

Introduced ConfigFile.loader decorator to handle config file loading in CLI entrypoint. Removed manual config file loading logic from main function for improved modularity and readability.

README.md

@@ -26,27 +26,23 @@ A command-line app for downloading Apple Music songs, music videos and post vide
 - **Apple Music Cookies** - Export your browser cookies in Netscape format while logged in with an active subscription at the Apple Music website:
   - **Firefox**: [Export Cookies](https://addons.mozilla.org/addon/export-cookies-txt)
   - **Chromium**: [Get cookies.txt LOCALLY](https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
-- **FFmpeg** - Must be in your system PATH
-  - **Windows**: [AnimMouse's FFmpeg Builds](https://github.com/AnimMouse/ffmpeg-stable-autobuild/releases)
-  - **Linux**: [John Van Sickle's FFmpeg Builds](https://johnvansickle.com/ffmpeg/)
 
 ### Optional
 
 Add these tools to your system PATH for additional features:
 
-- **[mp4decrypt](https://www.bento4.com/downloads/)** - Required for `mp4box` remux mode, music videos, and experimental codecs
-- **[MP4Box](https://gpac.io/downloads/gpac-nightly-builds/)** - Required for `mp4box` remux mode
+- **[FFmpeg](https://ffmpeg.org/download.html)** - Required for `ffmpeg` music video remux mode
+- **[mp4decrypt](https://www.bento4.com/downloads/)** - Required for `mp4box` music video remux mode
+- **[MP4Box](https://gpac.io/downloads/gpac-nightly-builds/)** - Required for `mp4box` music video remux mode
 - **[N_m3u8DL-RE](https://github.com/nilaoda/N_m3u8DL-RE/releases/latest)** - Required for `nm3u8dlre` download mode, which is faster than the default downloader
-- **[Wrapper & amdecrypt](#️-wrapper--amdecrypt)** - For downloading songs in ALAC and other experimental codecs without API limitations
+- **[Wrapper](#️-wrapper)** - For downloading songs in ALAC and other experimental codecs without API limitations
 
 ## 📦 Installation
 
-**Install Gamdl via pipx:**
-
-[pipx](https://pipx.pypa.io/stable/installation/) is recommended for installing Gamdl to avoid dependency conflicts, but you can also use pip.
+**Install Gamdl via pip:**
 
 ```bash
-pipx install gamdl
+pip install gamdl
 ```
 
 **Setup cookies:**
@@ -111,79 +107,82 @@ The file is created automatically on first run. Command-line arguments override
 
 ### Configuration Options
 
-| Option                          | Description                     | Default                                        |
-| ------------------------------- | ------------------------------- | ---------------------------------------------- |
-| **General Options**             |                                 |                                                |
-| `--read-urls-as-txt`, `-r`      | Read URLs from text files       | `false`                                        |
-| `--config-path`                 | Config file path                | `<home>/.gamdl/config.ini`                     |
-| `--log-level`                   | Logging level                   | `INFO`                                         |
-| `--log-file`                    | Log file path                   | -                                              |
-| `--no-exceptions`               | Don't print exceptions          | `false`                                        |
-| `--no-config-file`, `-n`        | Don't use a config file         | `false`                                        |
-| **Apple Music Options**         |                                 |                                                |
-| `--cookies-path`, `-c`          | Cookies file path               | `./cookies.txt`                                |
-| `--wrapper-account-url`         | Wrapper account URL             | `http://127.0.0.1:30020`                       |
-| `--language`, `-l`              | Metadata language               | `en-US`                                        |
-| **Output Options**              |                                 |                                                |
-| `--output-path`, `-o`           | Output directory path           | `./Apple Music`                                |
-| `--temp-path`                   | Temporary directory path        | `.`                                            |
-| `--wvd-path`                    | .wvd file path                  | -                                              |
-| `--overwrite`                   | Overwrite existing files        | `false`                                        |
-| `--save-cover`, `-s`            | Save cover as separate file     | `false`                                        |
-| `--save-playlist`               | Save M3U8 playlist file         | `false`                                        |
-| **Download Options**            |                                 |                                                |
-| `--nm3u8dlre-path`              | N_m3u8DL-RE executable path     | `N_m3u8DL-RE`                                  |
-| `--mp4decrypt-path`             | mp4decrypt executable path      | `mp4decrypt`                                   |
-| `--ffmpeg-path`                 | FFmpeg executable path          | `ffmpeg`                                       |
-| `--mp4box-path`                 | MP4Box executable path          | `MP4Box`                                       |
-| `--amdecrypt-path`              | amdecrypt executable path       | `amdecrypt`                                    |
-| `--use-wrapper`                 | Use wrapper and amdecrypt       | `false`                                        |
-| `--wrapper-decrypt-ip`          | Wrapper decryption server IP    | `127.0.0.1:10020`                              |
-| `--download-mode`               | Download mode                   | `ytdlp`                                        |
-| `--remux-mode`                  | Remux mode                      | `ffmpeg`                                       |
-| `--cover-format`                | Cover format                    | `jpg`                                          |
-| **Template Options**            |                                 |                                                |
-| `--album-folder-template`       | Album folder template           | `{album_artist}/{album}`                       |
-| `--compilation-folder-template` | Compilation folder template     | `Compilations/{album}`                         |
-| `--no-album-folder-template`    | No album folder template        | `{artist}/Unknown Album`                       |
-| `--single-disc-file-template`   | Single disc file template       | `{track:02d} {title}`                          |
-| `--multi-disc-file-template`    | Multi disc file template        | `{disc}-{track:02d} {title}`                   |
-| `--no-album-file-template`      | No album file template          | `{title}`                                      |
-| `--playlist-file-template`      | Playlist file template          | `Playlists/{playlist_artist}/{playlist_title}` |
-| `--date-tag-template`           | Date tag template               | `%Y-%m-%dT%H:%M:%SZ`                           |
-| `--exclude-tags`                | Comma-separated tags to exclude | -                                              |
-| `--cover-size`                  | Cover size in pixels            | `1200`                                         |
-| `--truncate`                    | Max filename length             | -                                              |
-| **Song Options**                |                                 |                                                |
-| `--song-codec`                  | Song codec                      | `aac-legacy`                                   |
-| `--synced-lyrics-format`        | Synced lyrics format            | `lrc`                                          |
-| `--no-synced-lyrics`            | Don't download synced lyrics    | `false`                                        |
-| `--synced-lyrics-only`          | Download only synced lyrics     | `false`                                        |
-| **Music Video Options**         |                                 |                                                |
-| `--music-video-codec-priority`  | Comma-separated codec priority  | `h264,h265`                                    |
-| `--music-video-remux-format`    | Music video remux format        | `m4v`                                          |
-| `--music-video-resolution`      | Max music video resolution      | `1080p`                                        |
-| **Post Video Options**          |                                 |                                                |
-| `--uploaded-video-quality`      | Post video quality              | `best`                                         |
+| Option                          | Description                                                       | Default                                        |
+| ------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------- |
+| **General Options**             |                                                                   |                                                |
+| `--read-urls-as-txt`, `-r`      | Read URLs from text files                                         | `false`                                        |
+| `--config-path`                 | Config file path                                                  | `<home>/.gamdl/config.ini`                     |
+| `--log-level`                   | Logging level                                                     | `INFO`                                         |
+| `--log-file`                    | Log file path                                                     | -                                              |
+| `--no-exceptions`               | Don't print exceptions                                            | `false`                                        |
+| `--no-config-file`, `-n`        | Don't use a config file                                           | `false`                                        |
+| **Apple Music Options**         |                                                                   |                                                |
+| `--cookies-path`, `-c`          | Cookies file path                                                 | `./cookies.txt`                                |
+| `--wrapper-account-url`         | Wrapper account URL                                               | `http://127.0.0.1:30020`                       |
+| `--language`, `-l`              | Metadata language                                                 | `en-US`                                        |
+| **Output Options**              |                                                                   |                                                |
+| `--output-path`, `-o`           | Output directory path                                             | `./Apple Music`                                |
+| `--temp-path`                   | Temporary directory path                                          | `.`                                            |
+| `--wvd-path`                    | .wvd file path                                                    | -                                              |
+| `--overwrite`                   | Overwrite existing files                                          | `false`                                        |
+| `--save-cover`, `-s`            | Save cover as separate file                                       | `false`                                        |
+| `--save-playlist`               | Save M3U8 playlist file                                           | `false`                                        |
+| **Download Options**            |                                                                   |                                                |
+| `--nm3u8dlre-path`              | N_m3u8DL-RE executable path                                       | `N_m3u8DL-RE`                                  |
+| `--mp4decrypt-path`             | mp4decrypt executable path                                        | `mp4decrypt`                                   |
+| `--ffmpeg-path`                 | FFmpeg executable path                                            | `ffmpeg`                                       |
+| `--mp4box-path`                 | MP4Box executable path                                            | `MP4Box`                                       |
+| `--use-wrapper`                 | Use wrapper                                                       | `false`                                        |
+| `--wrapper-decrypt-ip`          | Wrapper decryption server IP                                      | `127.0.0.1:10020`                              |
+| `--download-mode`               | Download mode                                                     | `ytdlp`                                        |
+| `--cover-format`                | Cover format                                                      | `jpg`                                          |
+| **Template Options**            |                                                                   |                                                |
+| `--album-folder-template`       | Album folder template                                             | `{album_artist}/{album}`                       |
+| `--compilation-folder-template` | Compilation folder template                                       | `Compilations/{album}`                         |
+| `--no-album-folder-template`    | No album folder template                                          | `{artist}/Unknown Album`                       |
+| `--single-disc-file-template`   | Single disc file template                                         | `{track:02d} {title}`                          |
+| `--multi-disc-file-template`    | Multi disc file template                                          | `{disc}-{track:02d} {title}`                   |
+| `--no-album-file-template`      | No album file template                                            | `{title}`                                      |
+| `--playlist-file-template`      | Playlist file template                                            | `Playlists/{playlist_artist}/{playlist_title}` |
+| `--date-tag-template`           | Date tag template                                                 | `%Y-%m-%dT%H:%M:%SZ`                           |
+| `--exclude-tags`                | Comma-separated tags to exclude                                   | -                                              |
+| `--cover-size`                  | Cover size in pixels                                              | `1200`                                         |
+| `--truncate`                    | Max filename length                                               | -                                              |
+| **Song Options**                |                                                                   |                                                |
+| `--song-codec`                  | Song codec                                                        | `aac-legacy`                                   |
+| `--synced-lyrics-format`        | Synced lyrics format                                              | `lrc`                                          |
+| `--no-synced-lyrics`            | Don't download synced lyrics                                      | `false`                                        |
+| `--synced-lyrics-only`          | Download only synced lyrics                                       | `false`                                        |
+| `--use-album-date`              | Use album release date for songs                                  | `false`                                        |
+| `--fetch-extra-tags`            | Fetch extra tags from preview (normalization and smooth playback) | `false`                                        |
+| **Music Video Options**         |                                                                   |                                                |
+| `--music-video-codec-priority`  | Comma-separated codec priority                                    | `h264,h265`                                    |
+| `--music-video-remux-mode`      | Remux mode                                                        | `ffmpeg`                                       |
+| `--music-video-remux-format`    | Music video remux format                                          | `m4v`                                          |
+| `--music-video-resolution`      | Max music video resolution                                        | `1080p`                                        |
+| **Post Video Options**          |                                                                   |                                                |
+| `--uploaded-video-quality`      | Post video quality                                                | `best`                                         |
+
 
 ### Template Variables
 
-Use these variables in folder/file templates or `--exclude-tags`:
+**Tags for templates and exclude-tags:**
 
-| Variable                                                                     | Description                                   |
-| ---------------------------------------------------------------------------- | --------------------------------------------- |
-| `{album}`, `{album_artist}`, `{album_id}`, `{album_sort}`                    | Album info                                    |
-| `{artist}`, `{artist_id}`, `{artist_sort}`                                   | Artist info                                   |
-| `{title}`, `{title_id}`, `{title_sort}`                                      | Title info                                    |
-| `{composer}`, `{composer_id}`, `{composer_sort}`                             | Composer info                                 |
-| `{track}`, `{track_total}`, `{disc}`, `{disc_total}`                         | Track numbers                                 |
-| `{genre}`, `{genre_id}`                                                      | Genre info                                    |
-| `{date}`                                                                     | Release date (supports strftime: `{date:%Y}`) |
-| `{playlist_artist}`, `{playlist_id}`, `{playlist_title}`, `{playlist_track}` | Playlist info                                 |
-| `{compilation}`, `{gapless}`, `{rating}`                                     | Media properties                              |
-| `{comment}`, `{copyright}`, `{lyrics}`, `{cover}`                            | Additional metadata                           |
-| `{media_type}`, `{storefront}`, `{xid}`                                      | Technical info                                |
-| `all`                                                                        | Special: Skip all tagging                     |
+- `album`, `album_artist`, `album_id`
+- `artist`, `artist_id`
+- `composer`, `composer_id`
+- `date` (supports strftime format: `{date:%Y}`)
+- `disc`, `disc_total`
+- `media_type`
+- `playlist_artist`, `playlist_id`, `playlist_title`, `playlist_track`
+- `title`, `title_id`
+- `track`, `track_total`
+
+**Tags for exclude-tags only:**
+
+- `album_sort`, `artist_sort`, `composer_sort`, `title_sort`
+- `comment`, `compilation`, `copyright`, `cover`, `gapless`, `genre`, `genre_id`, `lyrics`, `rating`, `storefront`, `xid`
+- `all` (special: skip all tagging)
 
 ### Logging Level
 
@@ -254,15 +253,9 @@ Use ISO 639-1 language codes (e.g., `en-US`, `es-ES`, `ja-JP`, `pt-BR`). Don't a
 - `best` - Up to 1080p with AAC 256kbps
 - `ask` - Interactive quality selection
 
-## ⚙️ Wrapper & amdecrypt
+## ⚙️ Wrapper
 
-Use the [wrapper](https://github.com/WorldObservationLog/wrapper) and [amdecrypt](https://github.com/glomatico/amdecrypt) to download songs in ALAC and other experimental codecs without API limitations. Cookies are not required when using the wrapper.
-
-### Prerequisites
-
-- **[wrapper](https://github.com/WorldObservationLog/wrapper)** - Refer to the repository for installation
-- **[amdecrypt](https://github.com/glomatico/amdecrypt)** - Refer to the repository for installation
-- **[mp4decrypt](https://www.bento4.com/downloads/)** - Required by amdecrypt to decrypt protected files
+Use the [wrapper](https://github.com/WorldObservationLog/wrapper) to download songs in ALAC and other experimental codecs without API limitations. Cookies are not required when using the wrapper.
 
 ### Setup Instructions
 
@@ -292,29 +285,27 @@ from gamdl.interface import (
     AppleMusicUploadedVideoInterface,
 )
 
-
 async def main():
-    # Initialize APIs
-    apple_music_api = AppleMusicApi.from_netscape_cookies(cookies_path="cookies.txt")
-    await apple_music_api.setup()
-
+    # Create AppleMusicApi instance (from cookies or wrapper)
+    apple_music_api = await AppleMusicApi.create_from_netscape_cookies(
+        cookies_path="cookies.txt",
+    )
     itunes_api = ItunesApi(
         apple_music_api.storefront,
         apple_music_api.language,
     )
-    itunes_api.setup()
 
-    # Initialize interfaces
+    # Check subscription
+    assert apple_music_api.active_subscription
+
+    # Set up interfaces
     interface = AppleMusicInterface(apple_music_api, itunes_api)
     song_interface = AppleMusicSongInterface(interface)
     music_video_interface = AppleMusicMusicVideoInterface(interface)
     uploaded_video_interface = AppleMusicUploadedVideoInterface(interface)
 
-    # Initialize base downloader
+    # Set up base downloader and specialized downloaders
     base_downloader = AppleMusicBaseDownloader()
-    base_downloader.setup()
-
-    # Initialize specialized downloaders
     song_downloader = AppleMusicSongDownloader(
         base_downloader=base_downloader,
         interface=song_interface,
@@ -328,7 +319,7 @@ async def main():
         interface=uploaded_video_interface,
     )
 
-    # Create main downloader
+    # Main downloader
     downloader = AppleMusicDownloader(
         interface=interface,
         base_downloader=base_downloader,
@@ -338,10 +329,8 @@ async def main():
     )
 
     # Download a song
-    url_info = downloader.get_url_info(
-        "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
-    )
-
+    url = "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
+    url_info = downloader.get_url_info(url)
     if url_info:
         download_queue = await downloader.get_download_queue(url_info)
         if download_queue:
@@ -360,4 +349,3 @@ MIT License - see [LICENSE](LICENSE) file for details
 ## 🤝 Contributing
 
 Currently, I'm not interested in reviewing pull requests that change or add features. Only critical bug fixes will be considered. However, feel free to open issues for bugs or feature requests.
-

gamdl/__init__.py

@@ -1 +1 @@
-__version__ = "2.8"
+__version__ = "2.9"

gamdl/__main__.py

@@ -1,3 +1,3 @@
-from gamdl.cli.cli import main
+from .cli.cli import main
 
 main()

gamdl/api/apple_music_api.py

@@ -6,7 +6,7 @@ from urllib.parse import parse_qs, urlparse
 
 import httpx
 
-from ..utils import raise_for_status, safe_json
+from ..utils import get_response, raise_for_status, safe_json
 from .constants import (
     AMP_API_URL,
     APPLE_MUSIC_COOKIE_DOMAIN,
@@ -14,6 +14,7 @@ from .constants import (
     LICENSE_API_URL,
     WEBPLAYBACK_API_URL,
 )
+from .exceptions import ApiError
 
 logger = logging.getLogger(__name__)
 
@@ -22,20 +23,21 @@ class AppleMusicApi:
     def __init__(
         self,
         storefront: str = "us",
-        media_user_token: str | None = None,
-        token: str | None = None,
         language: str = "en-US",
+        media_user_token: str | None = None,
+        developer_token: str | None = None,
     ) -> None:
         self.storefront = storefront
-        self.media_user_token = media_user_token
-        self.token = token
         self.language = language
+        self.media_user_token = media_user_token
+        self.token = developer_token
 
     @classmethod
-    def from_netscape_cookies(
+    async def create_from_netscape_cookies(
         cls,
         cookies_path: str = "./cookies.txt",
-        language: str = "en-US",
+        *args,
+        **kwargs,
     ) -> "AppleMusicApi":
         cookies = MozillaCookieJar(cookies_path)
         cookies.load(ignore_discard=True, ignore_expires=True)
@@ -56,35 +58,55 @@ class AppleMusicApi:
                 "and are logged in with an active subscription."
             )
 
-        return cls(
+        return await cls.create(
             storefront=None,
             media_user_token=media_user_token,
-            language=language,
+            developer_token=None,
+            *args,
+            **kwargs,
         )
 
     @classmethod
-    def from_wrapper(
+    async def create_from_wrapper(
         cls,
         wrapper_account_url: str = "http://127.0.0.1:30020/",
-        language: str = "en-US",
+        *args,
+        **kwargs,
     ) -> "AppleMusicApi":
-        wrapper_account_response = httpx.get(wrapper_account_url)
-        raise_for_status(wrapper_account_response)
+        wrapper_account_response = await get_response(wrapper_account_url)
         wrapper_account_info = safe_json(wrapper_account_response)
 
-        return cls(
+        return await cls.create(
             storefront=None,
             media_user_token=wrapper_account_info["music_token"],
-            token=wrapper_account_info["dev_token"],
-            language=language,
+            developer_token=wrapper_account_info["dev_token"],
+            *args,
+            **kwargs,
         )
 
-    async def setup(self) -> None:
-        await self._setup_client()
-        await self._setup_token()
-        await self._setup_account_info()
+    @classmethod
+    async def create(
+        cls,
+        storefront: str | None = "us",
+        language: str = "en-US",
+        media_user_token: str | None = None,
+        developer_token: str | None = None,
+    ) -> "AppleMusicApi":
+        api = cls(
+            storefront=storefront,
+            language=language,
+            media_user_token=media_user_token,
+            developer_token=developer_token,
+        )
+        await api.initialize()
+        return api
 
-    async def _setup_client(self) -> None:
+    async def initialize(self) -> None:
+        await self._initialize_client()
+        await self._initialize_token()
+        await self._initialize_account_info()
+
+    async def _initialize_client(self) -> None:
         self.client = httpx.AsyncClient(
             headers={
                 "accept": "*/*",
@@ -104,13 +126,11 @@ class AppleMusicApi:
                 "l": self.language,
             },
             follow_redirects=True,
-            transport=httpx.AsyncHTTPTransport(retries=10),
             timeout=60.0,
         )
 
     async def _get_token(self) -> str:
         response = await self.client.get(APPLE_MUSIC_HOMEPAGE_URL)
-        raise_for_status(response)
         home_page = response.text
 
         index_js_uri_match = re.search(
@@ -122,7 +142,6 @@ class AppleMusicApi:
         index_js_uri = index_js_uri_match.group(1)
 
         response = await self.client.get(f"{APPLE_MUSIC_HOMEPAGE_URL}/{index_js_uri}")
-        raise_for_status(response)
         index_js_page = response.text
 
         token_match = re.search('(?=eyJh)(.*?)(?=")', index_js_page)
@@ -133,11 +152,11 @@ class AppleMusicApi:
         logger.debug(f"Token: {token}")
         return token
 
-    async def _setup_token(self) -> None:
+    async def _initialize_token(self) -> None:
         self.token = self.token or await self._get_token()
         self.client.headers.update({"authorization": f"Bearer {self.token}"})
 
-    async def _setup_account_info(self) -> None:
+    async def _initialize_account_info(self) -> None:
         if not self.media_user_token:
             return
 
@@ -150,43 +169,69 @@ class AppleMusicApi:
         self.account_info = await self.get_account_info()
         self.storefront = self.account_info["meta"]["subscription"]["storefront"]
 
-    async def get_account_info(self, meta: str | None = "subscription") -> dict:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/me/account",
-            params={
-                **({"meta": meta} if meta else {}),
+    @property
+    def active_subscription(self) -> bool:
+        return (
+            getattr(self, "account_info", {})
+            .get("meta", {})
+            .get("subscription", {})
+            .get("active", False)
+        )
+
+    @property
+    def account_restrictions(self) -> dict | None:
+        data = getattr(self, "account_info", {}).get("data", [])
+        if not data:
+            return None
+        return data[0].get("attributes", {}).get("restrictions")
+
+    async def get_account_info(self, meta: str = "subscription") -> dict:
+        account_info = await self._amp_request(
+            f"/v1/me/account",
+            {
+                "meta": meta,
             },
         )
-        raise_for_status(response)
-
-        account_info = safe_json(response)
-        if not "data" in account_info or (meta and "meta" not in account_info):
-            raise Exception("Error getting account info:", response.text)
         logger.debug(f"Account info: {account_info}")
 
         return account_info
 
+    async def _amp_request(
+        self,
+        endpoint: str,
+        params: dict | None = None,
+    ) -> dict:
+        response = await self.client.get(
+            AMP_API_URL + endpoint,
+            params=params or {},
+        )
+        response_json = safe_json(response)
+
+        if (
+            response.status_code != 200
+            or response_json is None
+            or "errors" in response_json
+        ):
+            raise ApiError(
+                message=response.text,
+                status_code=response.status_code,
+            )
+
+        return response_json
+
     async def get_song(
         self,
         song_id: str,
         extend: str = "extendedAssetUrls",
         include: str = "lyrics,albums",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/songs/{song_id}",
-            params={
+        song = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/songs/{song_id}",
+            {
                 "extend": extend,
                 "include": include,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        song = safe_json(response)
-        if not "data" in song:
-            raise Exception("Error getting song:", response.text)
         logger.debug(f"Song: {song}")
 
         return song
@@ -196,20 +241,12 @@ class AppleMusicApi:
         music_video_id: str,
         include: str = "albums",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/music-videos/{music_video_id}",
-            params={
+        music_video = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/music-videos/{music_video_id}",
+            {
                 "include": include,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        music_video = safe_json(response)
-        if not "data" in music_video:
-            raise Exception("Error getting music video:", response.text)
         logger.debug(f"Music video: {music_video}")
 
         return music_video
@@ -218,17 +255,9 @@ class AppleMusicApi:
         self,
         post_id: str,
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/uploaded-videos/{post_id}"
+        uploaded_video = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/uploaded-videos/{post_id}",
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        uploaded_video = safe_json(response)
-        if not "data" in uploaded_video:
-            raise Exception("Error getting uploaded video:", response.text)
         logger.debug(f"Uploaded video: {uploaded_video}")
 
         return uploaded_video
@@ -238,20 +267,12 @@ class AppleMusicApi:
         album_id: str,
         extend: str = "extendedAssetUrls",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/albums/{album_id}",
-            params={
+        album = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/albums/{album_id}",
+            {
                 "extend": extend,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        album = safe_json(response)
-        if not "data" in album:
-            raise Exception("Error getting album:", response.text)
         logger.debug(f"Album: {album}")
 
         return album
@@ -262,21 +283,13 @@ class AppleMusicApi:
         limit_tracks: int = 300,
         extend: str = "extendedAssetUrls",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/playlists/{playlist_id}",
-            params={
+        playlist = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/playlists/{playlist_id}",
+            {
                 "limit[tracks]": limit_tracks,
                 "extend": extend,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        playlist = safe_json(response)
-        if not "data" in playlist:
-            raise Exception("Error getting playlist:", response.text)
         logger.debug(f"Playlist: {playlist}")
 
         return playlist
@@ -285,23 +298,20 @@ class AppleMusicApi:
         self,
         artist_id: str,
         include: str = "albums,music-videos",
+        views: str = "full-albums,compilation-albums,live-albums,singles,top-songs",
         limit: int = 100,
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/artists/{artist_id}",
-            params={
+        artist = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/artists/{artist_id}",
+            {
                 "include": include,
-                **{f"limit[{_include}]": limit for _include in include.split(",")},
+                "views": views,
+                **{
+                    f"limit[{_include}]": limit
+                    for _include in [*include.split(","), *views.split(",")]
+                },
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        artist = safe_json(response)
-        if not "data" in artist:
-            raise Exception("Error getting artist:", response.text)
         logger.debug(f"Artist: {artist}")
 
         return artist
@@ -311,20 +321,12 @@ class AppleMusicApi:
         album_id: str,
         extend: str = "extendedAssetUrls",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/me/library/albums/{album_id}",
-            params={
+        album = await self._amp_request(
+            f"/v1/me/library/albums/{album_id}",
+            {
                 "extend": extend,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        album = safe_json(response)
-        if not "data" in album:
-            raise Exception("Error getting library album:", response.text)
         logger.debug(f"Library album: {album}")
 
         return album
@@ -336,22 +338,15 @@ class AppleMusicApi:
         limit: int = 100,
         extend: str = "extendedAssetUrls",
     ) -> dict | None:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/me/library/playlists/{playlist_id}",
-            params={
+        playlist = await self._amp_request(
+            f"/v1/me/library/playlists/{playlist_id}",
+            {
                 "include": include,
                 **{f"limit[{_include}]": limit for _include in include.split(",")},
                 "extend": extend,
             },
         )
-        raise_for_status(response, {200, 404})
-
-        if response.status_code == 404:
-            return None
-
-        playlist = safe_json(response)
-        if not "data" in playlist:
-            raise Exception("Error getting library playlist:", response.text)
+        logger.debug(f"Library playlist: {playlist}")
 
         return playlist
 
@@ -362,20 +357,15 @@ class AppleMusicApi:
         limit: int = 50,
         offset: int = 0,
     ) -> dict:
-        response = await self.client.get(
-            f"{AMP_API_URL}/v1/catalog/{self.storefront}/search",
-            params={
+        search_results = await self._amp_request(
+            f"/v1/catalog/{self.storefront}/search",
+            {
                 "term": term,
                 "types": types,
                 "limit": limit,
                 "offset": offset,
             },
         )
-        raise_for_status(response)
-
-        search_results = safe_json(response)
-        if not "results" in search_results:
-            raise Exception("Error searching:", response.text)
         logger.debug(f"Search results: {search_results}")
 
         return search_results
@@ -406,19 +396,13 @@ class AppleMusicApi:
         limit: int,
         extend: str,
     ) -> dict:
-        response = await self.client.get(
-            AMP_API_URL + next_uri,
-            params={
-                "limit": limit,
-                "extend": extend,
-                **parse_qs(urlparse(next_uri).query),
-            },
-        )
-        raise_for_status(response)
-
-        extended_api_data = safe_json(response)
-        if not "data" in extended_api_data:
-            raise Exception("Error getting extended API data:", response.text)
+        next_uri_params = parse_qs(urlparse(next_uri).query)
+        params = {
+            "limit": limit,
+            "offset": next_uri_params["offset"][0],
+            "extend": extend,
+        }
+        extended_api_data = await self._amp_request(next_uri, params)
         logger.debug(f"Extended API data: {extended_api_data}")
 
         return extended_api_data
@@ -434,12 +418,17 @@ class AppleMusicApi:
                 "language": self.language,
             },
         )
-        raise_for_status(response)
-
         webplayback = safe_json(response)
-        if not "songList" in webplayback:
-            raise Exception("Error getting webplayback:", response.text)
-        logger.debug(f"Webplayback: {webplayback}")
+
+        if (
+            response.status_code != 200
+            or webplayback is None
+            or "dialog" in webplayback
+        ):
+            raise ApiError(
+                message=response.text,
+                status_code=response.status_code,
+            )
 
         return webplayback
 
@@ -461,11 +450,18 @@ class AppleMusicApi:
                 "user-initiated": True,
             },
         )
-        raise_for_status(response)
-
         license_exchange = safe_json(response)
-        if not "license" in license_exchange:
-            raise Exception("Error getting license exchange:", response.text)
+
+        if (
+            response.status_code != 200
+            or license_exchange is None
+            or license_exchange.get("status") != 0
+        ):
+            raise ApiError(
+                message=response.text,
+                status_code=response.status_code,
+            )
+
         logger.debug(f"License exchange: {license_exchange}")
 
         return license_exchange

gamdl/api/exceptions.py

@@ -0,0 +1,7 @@
+from ..utils import GamdlError
+
+
+class ApiError(GamdlError):
+    def __init__(self, message: str, status_code: int):
+        super().__init__(f"API Error {status_code}: {message}")
+        self.status_code = status_code

gamdl/api/itunes_api.py

@@ -2,8 +2,9 @@ import logging
 
 import httpx
 
-from ..utils import raise_for_status, safe_json
+from ..utils import safe_json
 from .constants import ITUNES_LOOKUP_API_URL, ITUNES_PAGE_API_URL, STOREFRONT_IDS
+from .exceptions import ApiError
 
 logger = logging.getLogger(__name__)
 
@@ -16,18 +17,19 @@ class ItunesApi:
     ) -> None:
         self.storefront = storefront
         self.language = language
+        self.initialize()
 
-    def setup(self) -> None:
-        self._setup_storefront_id()
-        self._setup_session()
+    def initialize(self) -> None:
+        self._initialize_storefront_id()
+        self._initialize_client()
 
-    def _setup_storefront_id(self) -> None:
+    def _initialize_storefront_id(self) -> None:
         try:
             self.storefront_id = STOREFRONT_IDS[self.storefront.upper()]
         except KeyError:
             raise Exception(f"No storefront id for {self.storefront}")
 
-    def _setup_session(self) -> None:
+    def _initialize_client(self) -> None:
         self.client = httpx.AsyncClient(
             params={
                 "country": self.storefront,
@@ -36,6 +38,7 @@ class ItunesApi:
             headers={
                 "X-Apple-Store-Front": f"{self.storefront_id} t:music31",
             },
+            timeout=60.0,
         )
 
     async def get_lookup_result(
@@ -50,11 +53,14 @@ class ItunesApi:
                 "entity": entity,
             },
         )
-        raise_for_status(response)
-
         lookup_result = safe_json(response)
-        if "results" not in lookup_result:
-            raise Exception("Error getting lookup result:", response.text)
+
+        if response.status_code != 200 or lookup_result is None:
+            raise ApiError(
+                message=response.text,
+                status_code=response.status_code,
+            )
+
         logger.debug(f"Lookup result: {lookup_result}")
 
         return lookup_result
@@ -67,11 +73,14 @@ class ItunesApi:
         response = await self.client.get(
             f"{ITUNES_PAGE_API_URL}/{media_type}/{media_id}"
         )
-        raise_for_status(response)
-
         itunes_page = safe_json(response)
-        if "storePlatformData" not in itunes_page:
-            raise Exception("Error getting iTunes page:", response.text)
+
+        if response.status_code != 200 or itunes_page is None:
+            raise ApiError(
+                message=response.text,
+                status_code=response.status_code,
+            )
+
         logger.debug(f"iTunes page: {itunes_page}")
 
         return itunes_page

gamdl/cli/cli.py

@@ -1,10 +1,12 @@
 import asyncio
-import inspect
 import logging
 from functools import wraps
 from pathlib import Path
 
 import click
+import colorama
+from dataclass_click import dataclass_click
+from httpx import ConnectError
 
 from .. import __version__
 from ..api import AppleMusicApi, ItunesApi
@@ -14,11 +16,9 @@ from ..downloader import (
     AppleMusicMusicVideoDownloader,
     AppleMusicSongDownloader,
     AppleMusicUploadedVideoDownloader,
-    CoverFormat,
     DownloadItem,
     DownloadMode,
     GamdlError,
-    RemuxFormatMusicVideo,
     RemuxMode,
 )
 from ..interface import (
@@ -26,53 +26,15 @@ from ..interface import (
     AppleMusicMusicVideoInterface,
     AppleMusicSongInterface,
     AppleMusicUploadedVideoInterface,
-    MusicVideoCodec,
-    MusicVideoResolution,
     SongCodec,
-    SyncedLyricsFormat,
-    UploadedVideoQuality,
 )
+from .cli_config import CliConfig
 from .config_file import ConfigFile
 from .constants import X_NOT_IN_PATH
-from .utils import Csv, CustomLoggerFormatter, prompt_path
+from .utils import CustomLoggerFormatter, prompt_path
 
 logger = logging.getLogger(__name__)
 
-api_from_cookies_sig = inspect.signature(AppleMusicApi.from_netscape_cookies)
-api_from_wrapper_sig = inspect.signature(AppleMusicApi.from_wrapper)
-base_downloader_sig = inspect.signature(AppleMusicBaseDownloader.__init__)
-music_video_downloader_sig = inspect.signature(AppleMusicMusicVideoDownloader.__init__)
-song_downloader_sig = inspect.signature(AppleMusicSongDownloader.__init__)
-uploaded_video_downloader_sig = inspect.signature(
-    AppleMusicUploadedVideoDownloader.__init__
-)
-
-
-def load_config_file(
-    ctx: click.Context,
-    param: click.Parameter,
-    no_config_file: bool,
-) -> click.Context:
-    if no_config_file:
-        return ctx
-
-    config_file = ConfigFile(ctx.params["config_path"])
-    config_file.cleanup_unknown_params(ctx.command.params)
-    config_file.add_params_default_to_config(
-        ctx.command.params,
-    )
-    parsed_params = config_file.parse_params_from_config(
-        [
-            param
-            for param in ctx.command.params
-            if ctx.get_parameter_source(param.name)
-            != click.core.ParameterSource.COMMANDLINE
-        ]
-    )
-    ctx.params.update(parsed_params)
-
-    return ctx
-
 
 def make_sync(func):
     @wraps(func)
@@ -85,377 +47,58 @@ def make_sync(func):
 @click.command()
 @click.help_option("-h", "--help")
 @click.version_option(__version__, "-v", "--version")
-# CLI specific options
-@click.argument(
-    "urls",
-    nargs=-1,
-    type=str,
-    required=True,
-)
-@click.option(
-    "--read-urls-as-txt",
-    "-r",
-    is_flag=True,
-    help="Read URLs from text files",
-)
-@click.option(
-    "--config-path",
-    type=click.Path(file_okay=True, dir_okay=False, writable=True, resolve_path=True),
-    default=str(Path.home() / ".gamdl" / "config.ini"),
-    help="Config file path",
-)
-@click.option(
-    "--log-level",
-    type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"]),
-    default="INFO",
-    help="Logging level",
-)
-@click.option(
-    "--log-file",
-    type=click.Path(file_okay=True, dir_okay=False, writable=True, resolve_path=True),
-    default=None,
-    help="Log file path",
-)
-@click.option(
-    "--no-exceptions",
-    is_flag=True,
-    help="Don't print exceptions",
-)
-# API specific options
-@click.option(
-    "--cookies-path",
-    "-c",
-    type=click.Path(file_okay=True, dir_okay=False, readable=True, resolve_path=True),
-    default=api_from_cookies_sig.parameters["cookies_path"].default,
-    help="Cookies file path",
-)
-@click.option(
-    "--wrapper-account-url",
-    type=str,
-    default=api_from_wrapper_sig.parameters["wrapper_account_url"].default,
-    help="Wrapper account URL",
-)
-@click.option(
-    "--language",
-    "-l",
-    type=str,
-    default=api_from_cookies_sig.parameters["language"].default,
-    help="Metadata language",
-)
-# Base Downloader specific options
-@click.option(
-    "--output-path",
-    "-o",
-    type=click.Path(file_okay=False, dir_okay=True, writable=True, resolve_path=True),
-    default=base_downloader_sig.parameters["output_path"].default,
-    help="Output directory path",
-)
-@click.option(
-    "--temp-path",
-    type=click.Path(file_okay=False, dir_okay=True, writable=True, resolve_path=True),
-    default=base_downloader_sig.parameters["temp_path"].default,
-    help="Temporary directory path",
-)
-@click.option(
-    "--wvd-path",
-    type=click.Path(file_okay=False, dir_okay=True, writable=True, resolve_path=True),
-    default=base_downloader_sig.parameters["wvd_path"].default,
-    help=".wvd file path",
-)
-@click.option(
-    "--overwrite",
-    is_flag=True,
-    help="Overwrite existing files",
-    default=base_downloader_sig.parameters["overwrite"].default,
-)
-@click.option(
-    "--save-cover",
-    "-s",
-    is_flag=True,
-    help="Save cover as separate file",
-    default=base_downloader_sig.parameters["save_cover"].default,
-)
-@click.option(
-    "--save-playlist",
-    is_flag=True,
-    help="Save M3U8 playlist file",
-    default=base_downloader_sig.parameters["save_playlist"].default,
-)
-@click.option(
-    "--nm3u8dlre-path",
-    type=str,
-    default=base_downloader_sig.parameters["nm3u8dlre_path"].default,
-    help="N_m3u8DL-RE executable path",
-)
-@click.option(
-    "--mp4decrypt-path",
-    type=str,
-    default=base_downloader_sig.parameters["mp4decrypt_path"].default,
-    help="mp4decrypt executable path",
-)
-@click.option(
-    "--ffmpeg-path",
-    type=str,
-    default=base_downloader_sig.parameters["ffmpeg_path"].default,
-    help="FFmpeg executable path",
-)
-@click.option(
-    "--mp4box-path",
-    type=str,
-    default=base_downloader_sig.parameters["mp4box_path"].default,
-    help="MP4Box executable path",
-)
-@click.option(
-    "--amdecrypt-path",
-    type=str,
-    default=base_downloader_sig.parameters["amdecrypt_path"].default,
-    help="amdecrypt executable path",
-)
-@click.option(
-    "--use-wrapper",
-    is_flag=True,
-    help="Use wrapper and amdecrypt for decrypting songs",
-    default=False,
-)
-@click.option(
-    "--wrapper-decrypt-ip",
-    type=str,
-    default=base_downloader_sig.parameters["wrapper_decrypt_ip"].default,
-    help="IP address and port for wrapper decryption",
-)
-@click.option(
-    "--download-mode",
-    type=DownloadMode,
-    default=base_downloader_sig.parameters["download_mode"].default,
-    help="Download mode",
-)
-@click.option(
-    "--remux-mode",
-    type=RemuxMode,
-    default=base_downloader_sig.parameters["remux_mode"].default,
-    help="Remux mode",
-)
-@click.option(
-    "--cover-format",
-    type=CoverFormat,
-    default=base_downloader_sig.parameters["cover_format"].default,
-    help="Cover format",
-)
-@click.option(
-    "--album-folder-template",
-    type=str,
-    default=base_downloader_sig.parameters["album_folder_template"].default,
-    help="Album folder template",
-)
-@click.option(
-    "--compilation-folder-template",
-    type=str,
-    default=base_downloader_sig.parameters["compilation_folder_template"].default,
-    help="Compilation folder template",
-)
-@click.option(
-    "--no-album-folder-template",
-    type=str,
-    default=base_downloader_sig.parameters["no_album_folder_template"].default,
-    help="No album folder template",
-)
-@click.option(
-    "--single-disc-file-template",
-    type=str,
-    default=base_downloader_sig.parameters["single_disc_file_template"].default,
-    help="Single disc file template",
-)
-@click.option(
-    "--multi-disc-file-template",
-    type=str,
-    default=base_downloader_sig.parameters["multi_disc_file_template"].default,
-    help="Multi disc file template",
-)
-@click.option(
-    "--no-album-file-template",
-    type=str,
-    default=base_downloader_sig.parameters["no_album_file_template"].default,
-    help="No album file template",
-)
-@click.option(
-    "--playlist-file-template",
-    type=str,
-    default=base_downloader_sig.parameters["playlist_file_template"].default,
-    help="Playlist file template",
-)
-@click.option(
-    "--date-tag-template",
-    type=str,
-    default=base_downloader_sig.parameters["date_tag_template"].default,
-    help="Date tag template",
-)
-@click.option(
-    "--exclude-tags",
-    type=Csv(str),
-    default=base_downloader_sig.parameters["exclude_tags"].default,
-    help="Comma-separated tags to exclude",
-)
-@click.option(
-    "--cover-size",
-    type=int,
-    default=base_downloader_sig.parameters["cover_size"].default,
-    help="Cover size in pixels",
-)
-@click.option(
-    "--truncate",
-    type=int,
-    default=base_downloader_sig.parameters["truncate"].default,
-    help="Max filename length",
-)
-# DownloaderSong specific options
-@click.option(
-    "--song-codec",
-    type=SongCodec,
-    default=song_downloader_sig.parameters["codec"].default,
-    help="Song codec",
-)
-@click.option(
-    "--synced-lyrics-format",
-    type=SyncedLyricsFormat,
-    default=song_downloader_sig.parameters["synced_lyrics_format"].default,
-    help="Synced lyrics format",
-)
-@click.option(
-    "--no-synced-lyrics",
-    is_flag=True,
-    help="Don't download synced lyrics",
-    default=song_downloader_sig.parameters["no_synced_lyrics"].default,
-)
-@click.option(
-    "--synced-lyrics-only",
-    is_flag=True,
-    help="Download only synced lyrics",
-    default=song_downloader_sig.parameters["synced_lyrics_only"].default,
-)
-# DownloaderMusicVideo specific options
-@click.option(
-    "--music-video-codec-priority",
-    type=Csv(MusicVideoCodec),
-    default=music_video_downloader_sig.parameters["codec_priority"].default,
-    help="Comma-separated codec priority",
-)
-@click.option(
-    "--music-video-remux-format",
-    type=RemuxFormatMusicVideo,
-    default=music_video_downloader_sig.parameters["remux_format"].default,
-    help="Music video remux format",
-)
-@click.option(
-    "--music-video-resolution",
-    type=MusicVideoResolution,
-    default=music_video_downloader_sig.parameters["resolution"].default,
-    help="Max music video resolution",
-)
-# DownloaderUploadedVideo specific options
-@click.option(
-    "--uploaded-video-quality",
-    type=UploadedVideoQuality,
-    default=uploaded_video_downloader_sig.parameters["quality"].default,
-    help="Post video quality",
-)
-# This option should always be last
-@click.option(
-    "--no-config-file",
-    "-n",
-    is_flag=True,
-    callback=load_config_file,
-    help="Don't use a config file",
-)
+@dataclass_click(CliConfig)
+@ConfigFile.loader
 @make_sync
-async def main(
-    urls: list[str],
-    read_urls_as_txt: bool,
-    config_path: str,
-    log_level: str,
-    log_file: str,
-    no_exceptions: bool,
-    cookies_path: str,
-    wrapper_account_url: str,
-    language: str,
-    output_path: str,
-    temp_path: str,
-    wvd_path: str,
-    overwrite: bool,
-    save_cover: bool,
-    save_playlist: bool,
-    nm3u8dlre_path: str,
-    mp4decrypt_path: str,
-    ffmpeg_path: str,
-    mp4box_path: str,
-    amdecrypt_path: str,
-    use_wrapper: bool,
-    wrapper_decrypt_ip: str,
-    download_mode: DownloadMode,
-    remux_mode: RemuxMode,
-    cover_format: CoverFormat,
-    album_folder_template: str,
-    compilation_folder_template: str,
-    no_album_folder_template: str,
-    single_disc_file_template: str,
-    multi_disc_file_template: str,
-    no_album_file_template: str,
-    playlist_file_template: str,
-    date_tag_template: str,
-    exclude_tags: list[str],
-    cover_size: int,
-    truncate: int,
-    song_codec: SongCodec,
-    synced_lyrics_format: SyncedLyricsFormat,
-    no_synced_lyrics: bool,
-    synced_lyrics_only: bool,
-    music_video_codec_priority: list[MusicVideoCodec],
-    music_video_remux_format: RemuxFormatMusicVideo,
-    music_video_resolution: MusicVideoResolution,
-    uploaded_video_quality: UploadedVideoQuality,
-    *args,
-    **kwargs,
-):
+async def main(config: CliConfig):
+    colorama.just_fix_windows_console()
+
     root_logger = logging.getLogger(__name__.split(".")[0])
-    root_logger.setLevel(log_level)
+    root_logger.setLevel(config.log_level)
     root_logger.propagate = False
 
     stream_handler = logging.StreamHandler()
     stream_handler.setFormatter(CustomLoggerFormatter())
     root_logger.addHandler(stream_handler)
 
-    if log_file:
-        file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    if config.log_file:
+        file_handler = logging.FileHandler(config.log_file, encoding="utf-8")
         file_handler.setFormatter(CustomLoggerFormatter(use_colors=False))
         root_logger.addHandler(file_handler)
 
     logger.info(f"Starting Gamdl {__version__}")
 
-    if use_wrapper:
-        apple_music_api = AppleMusicApi.from_wrapper(
-            wrapper_account_url=wrapper_account_url,
-            language=language,
-        )
+    if config.use_wrapper:
+        try:
+            apple_music_api = await AppleMusicApi.create_from_wrapper(
+                wrapper_account_url=config.wrapper_account_url,
+                language=config.language,
+            )
+        except ConnectError:
+            logger.critical(
+                "Could not connect to the wrapper account API. "
+                "Make sure the wrapper is running and the URL is correct."
+            )
+            return
     else:
-        cookies_path = prompt_path(cookies_path)
-        apple_music_api = AppleMusicApi.from_netscape_cookies(
+        cookies_path = prompt_path(config.cookies_path)
+        apple_music_api = await AppleMusicApi.create_from_netscape_cookies(
             cookies_path=cookies_path,
-            language=language,
+            language=config.language,
         )
-    await apple_music_api.setup()
 
     itunes_api = ItunesApi(
         apple_music_api.storefront,
         apple_music_api.language,
     )
-    itunes_api.setup()
 
-    if not apple_music_api.account_info["meta"]["subscription"]["active"]:
+    if not apple_music_api.active_subscription:
         logger.critical(
             "No active Apple Music subscription found, you won't be able to download"
             " anything"
         )
         return
-    if apple_music_api.account_info["data"][0]["attributes"].get("restrictions"):
+    if apple_music_api.account_restrictions:
         logger.warning(
             "Your account has content restrictions enabled, some content may not be"
             " downloadable"
@@ -470,54 +113,54 @@ async def main(
     uploaded_video_interface = AppleMusicUploadedVideoInterface(interface)
 
     base_downloader = AppleMusicBaseDownloader(
-        output_path=output_path,
-        temp_path=temp_path,
-        wvd_path=wvd_path,
-        overwrite=overwrite,
-        save_cover=save_cover,
-        save_playlist=save_playlist,
-        nm3u8dlre_path=nm3u8dlre_path,
-        mp4decrypt_path=mp4decrypt_path,
-        ffmpeg_path=ffmpeg_path,
-        mp4box_path=mp4box_path,
-        amdecrypt_path=amdecrypt_path,
-        use_wrapper=use_wrapper,
-        wrapper_decrypt_ip=wrapper_decrypt_ip,
-        download_mode=download_mode,
-        remux_mode=remux_mode,
-        cover_format=cover_format,
-        album_folder_template=album_folder_template,
-        compilation_folder_template=compilation_folder_template,
-        no_album_folder_template=no_album_folder_template,
-        single_disc_file_template=single_disc_file_template,
-        multi_disc_file_template=multi_disc_file_template,
-        no_album_file_template=no_album_file_template,
-        playlist_file_template=playlist_file_template,
-        date_tag_template=date_tag_template,
-        exclude_tags=exclude_tags,
-        cover_size=cover_size,
-        truncate=truncate,
+        output_path=config.output_path,
+        temp_path=config.temp_path,
+        wvd_path=config.wvd_path,
+        overwrite=config.overwrite,
+        save_cover=config.save_cover,
+        save_playlist=config.save_playlist,
+        nm3u8dlre_path=config.nm3u8dlre_path,
+        mp4decrypt_path=config.mp4decrypt_path,
+        ffmpeg_path=config.ffmpeg_path,
+        mp4box_path=config.mp4box_path,
+        use_wrapper=config.use_wrapper,
+        wrapper_decrypt_ip=config.wrapper_decrypt_ip,
+        download_mode=config.download_mode,
+        cover_format=config.cover_format,
+        album_folder_template=config.album_folder_template,
+        compilation_folder_template=config.compilation_folder_template,
+        no_album_folder_template=config.no_album_folder_template,
+        single_disc_file_template=config.single_disc_file_template,
+        multi_disc_file_template=config.multi_disc_file_template,
+        no_album_file_template=config.no_album_file_template,
+        playlist_file_template=config.playlist_file_template,
+        date_tag_template=config.date_tag_template,
+        exclude_tags=config.exclude_tags,
+        cover_size=config.cover_size,
+        truncate=config.truncate,
     )
-    base_downloader.setup()
     song_downloader = AppleMusicSongDownloader(
         base_downloader=base_downloader,
         interface=song_interface,
-        codec=song_codec,
-        synced_lyrics_format=synced_lyrics_format,
-        no_synced_lyrics=no_synced_lyrics,
-        synced_lyrics_only=synced_lyrics_only,
+        codec=config.song_codec,
+        synced_lyrics_format=config.synced_lyrics_format,
+        no_synced_lyrics=config.no_synced_lyrics,
+        synced_lyrics_only=config.synced_lyrics_only,
+        use_album_date=config.use_album_date,
+        fetch_extra_tags=config.fetch_extra_tags,
     )
     music_video_downloader = AppleMusicMusicVideoDownloader(
         base_downloader=base_downloader,
         interface=music_video_interface,
-        codec_priority=music_video_codec_priority,
-        remux_format=music_video_remux_format,
-        resolution=music_video_resolution,
+        codec_priority=config.music_video_codec_priority,
+        remux_mode=config.music_video_remux_mode,
+        remux_format=config.music_video_remux_format,
+        resolution=config.music_video_resolution,
     )
     uploaded_video_downloader = AppleMusicUploadedVideoDownloader(
         base_downloader=base_downloader,
         interface=uploaded_video_interface,
-        quality=uploaded_video_quality,
+        quality=config.uploaded_video_quality,
     )
     downloader = AppleMusicDownloader(
         interface=interface,
@@ -527,56 +170,56 @@ async def main(
         uploaded_video_downloader=uploaded_video_downloader,
     )
 
-    if not synced_lyrics_only:
-        if not base_downloader.full_ffmpeg_path and (
-            remux_mode == RemuxMode.FFMPEG or download_mode == DownloadMode.NM3U8DLRE
-        ):
-            logger.critical(X_NOT_IN_PATH.format("ffmpeg", ffmpeg_path))
-            return
-
-        if not base_downloader.full_mp4box_path and remux_mode == RemuxMode.MP4BOX:
-            logger.critical(X_NOT_IN_PATH.format("MP4Box", mp4box_path))
-            return
-
+    if not config.synced_lyrics_only:
         if (
-            not base_downloader.full_mp4decrypt_path
-            and song_codec
-            not in (
-                SongCodec.AAC_LEGACY,
-                SongCodec.AAC_HE_LEGACY,
-            )
-            or (
-                remux_mode == RemuxMode.MP4BOX
-                and not base_downloader.full_mp4decrypt_path
-            )
-        ):
-            logger.critical(X_NOT_IN_PATH.format("mp4decrypt", mp4decrypt_path))
-            return
-
-        if (
-            download_mode == DownloadMode.NM3U8DLRE
+            config.download_mode == DownloadMode.NM3U8DLRE
             and not base_downloader.full_nm3u8dlre_path
         ):
-            logger.critical(X_NOT_IN_PATH.format("N_m3u8DL-RE", nm3u8dlre_path))
+            logger.critical(X_NOT_IN_PATH.format("N_m3u8DL-RE", config.nm3u8dlre_path))
             return
 
-        if not base_downloader.full_mp4decrypt_path:
-            logger.warning(
-                X_NOT_IN_PATH.format("mp4decrypt", mp4decrypt_path)
-                + ", music videos will not be downloaded"
-            )
-            downloader.skip_music_videos = True
+        missing_music_video_paths = []
 
-        if not song_codec.is_legacy() and not use_wrapper:
+        if not base_downloader.full_ffmpeg_path and (
+            config.music_video_remux_mode == RemuxMode.FFMPEG
+            or config.download_mode == DownloadMode.NM3U8DLRE
+        ):
+            missing_music_video_paths.append(
+                X_NOT_IN_PATH.format("ffmpeg", config.ffmpeg_path)
+            )
+
+        if (
+            not base_downloader.full_mp4box_path
+            and config.music_video_remux_mode == RemuxMode.MP4BOX
+        ):
+            missing_music_video_paths.append(
+                X_NOT_IN_PATH.format("MP4Box", config.mp4box_path)
+            )
+
+        if not base_downloader.full_mp4decrypt_path and (
+            config.song_codec not in (SongCodec.AAC_LEGACY, SongCodec.AAC_HE_LEGACY)
+            or config.music_video_remux_mode == RemuxMode.MP4BOX
+        ):
+            missing_music_video_paths.append(
+                X_NOT_IN_PATH.format("mp4decrypt", config.mp4decrypt_path)
+            )
+
+        if missing_music_video_paths:
             logger.warning(
-                "You have chosen an experimental song codec"
-                " without enabling wrapper."
+                "Music videos will not be downloaded due to missing dependencies:\n"
+                + "\n".join(missing_music_video_paths)
+            )
+
+        if not config.song_codec.is_legacy() and not config.use_wrapper:
+            logger.warning(
+                "You have chosen an experimental song codec "
+                "without enabling wrapper. "
                 "They're not guaranteed to work due to API limitations."
             )
 
-    if read_urls_as_txt:
+    if config.read_urls_as_txt:
         urls_from_file = []
-        for url in urls:
+        for url in config.urls:
             if Path(url).is_file() and Path(url).exists():
                 urls_from_file.extend(
                     [
@@ -586,6 +229,8 @@ async def main(
                     ]
                 )
         urls = urls_from_file
+    else:
+        urls = config.urls
 
     error_count = 0
     for url_index, url in enumerate(urls, 1):
@@ -613,7 +258,7 @@ async def main(
             error_count += 1
             logger.error(
                 url_progress + f' Error processing "{url}"',
-                exc_info=not no_exceptions,
+                exc_info=not config.no_exceptions,
             )
 
         if not download_queue:
@@ -650,7 +295,7 @@ async def main(
                 error_count += 1
                 logger.error(
                     download_queue_progress + f' Error downloading "{media_title}"',
-                    exc_info=not no_exceptions,
+                    exc_info=not config.no_exceptions,
                 )
 
     logger.info(f"Finished with {error_count} error(s)")

gamdl/cli/cli_config.py

@@ -0,0 +1,470 @@
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import click
+from dataclass_click import argument, option
+
+from ..api import AppleMusicApi
+from ..downloader import (
+    AppleMusicBaseDownloader,
+    AppleMusicMusicVideoDownloader,
+    AppleMusicSongDownloader,
+    AppleMusicUploadedVideoDownloader,
+    DownloadMode,
+    RemuxFormatMusicVideo,
+    RemuxMode,
+)
+from ..interface import (
+    CoverFormat,
+    MusicVideoCodec,
+    MusicVideoResolution,
+    SongCodec,
+    SyncedLyricsFormat,
+    UploadedVideoQuality,
+)
+from .utils import Csv
+
+api_from_cookies_sig = inspect.signature(AppleMusicApi.create_from_netscape_cookies)
+api_from_wrapper_sig = inspect.signature(AppleMusicApi.create_from_wrapper)
+api_sig = inspect.signature(AppleMusicApi.__init__)
+base_downloader_sig = inspect.signature(AppleMusicBaseDownloader.__init__)
+music_video_downloader_sig = inspect.signature(AppleMusicMusicVideoDownloader.__init__)
+song_downloader_sig = inspect.signature(AppleMusicSongDownloader.__init__)
+uploaded_video_downloader_sig = inspect.signature(
+    AppleMusicUploadedVideoDownloader.__init__
+)
+
+
+@dataclass
+class CliConfig:
+    # CLI specific options
+    urls: Annotated[
+        list[str],
+        argument(
+            nargs=-1,
+            type=str,
+            required=True,
+        ),
+    ]
+    read_urls_as_txt: Annotated[
+        bool,
+        option(
+            "--read-urls-as-txt",
+            "-r",
+            help="Read URLs from text files",
+            is_flag=True,
+        ),
+    ]
+    config_path: Annotated[
+        str,
+        option(
+            "--config-path",
+            help="Config file path",
+            default=str(Path.home() / ".gamdl" / "config.ini"),
+            type=click.Path(
+                file_okay=True,
+                dir_okay=False,
+                writable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    log_level: Annotated[
+        str,
+        option(
+            "--log-level",
+            help="Logging level",
+            default="INFO",
+            type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"]),
+        ),
+    ]
+    log_file: Annotated[
+        str,
+        option(
+            "--log-file",
+            help="Log file path",
+            default=None,
+            type=click.Path(
+                file_okay=True,
+                dir_okay=False,
+                writable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    no_exceptions: Annotated[
+        bool,
+        option(
+            "--no-exceptions",
+            help="Don't print exceptions",
+            is_flag=True,
+        ),
+    ]
+    # API specific options
+    cookies_path: Annotated[
+        str,
+        option(
+            "--cookies-path",
+            "-c",
+            help="Cookies file path",
+            default=api_from_cookies_sig.parameters["cookies_path"].default,
+            type=click.Path(
+                file_okay=True,
+                dir_okay=False,
+                readable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    wrapper_account_url: Annotated[
+        str,
+        option(
+            "--wrapper-account-url",
+            help="Wrapper account URL",
+            default=api_from_wrapper_sig.parameters["wrapper_account_url"].default,
+        ),
+    ]
+    language: Annotated[
+        str,
+        option(
+            "--language",
+            "-l",
+            help="Metadata language",
+            default=api_sig.parameters["language"].default,
+        ),
+    ]
+    # Base Downloader specific options
+    output_path: Annotated[
+        str,
+        option(
+            "--output-path",
+            "-o",
+            help="Output directory path",
+            default=base_downloader_sig.parameters["output_path"].default,
+            type=click.Path(
+                file_okay=False,
+                dir_okay=True,
+                writable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    temp_path: Annotated[
+        str,
+        option(
+            "--temp-path",
+            help="Temporary directory path",
+            default=base_downloader_sig.parameters["temp_path"].default,
+            type=click.Path(
+                file_okay=False,
+                dir_okay=True,
+                writable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    wvd_path: Annotated[
+        str,
+        option(
+            "--wvd-path",
+            help=".wvd file path",
+            default=base_downloader_sig.parameters["wvd_path"].default,
+            type=click.Path(
+                file_okay=False,
+                dir_okay=True,
+                writable=True,
+                resolve_path=True,
+            ),
+        ),
+    ]
+    overwrite: Annotated[
+        bool,
+        option(
+            "--overwrite",
+            help="Overwrite existing files",
+            is_flag=True,
+        ),
+    ]
+    save_cover: Annotated[
+        bool,
+        option(
+            "--save-cover",
+            "-s",
+            help="Save cover as separate file",
+            is_flag=True,
+        ),
+    ]
+    save_playlist: Annotated[
+        bool,
+        option(
+            "--save-playlist",
+            help="Save M3U8 playlist file",
+            is_flag=True,
+        ),
+    ]
+    nm3u8dlre_path: Annotated[
+        str,
+        option(
+            "--nm3u8dlre-path",
+            help="N_m3u8DL-RE executable path",
+            default=base_downloader_sig.parameters["nm3u8dlre_path"].default,
+        ),
+    ]
+    mp4decrypt_path: Annotated[
+        str,
+        option(
+            "--mp4decrypt-path",
+            help="mp4decrypt executable path",
+            default=base_downloader_sig.parameters["mp4decrypt_path"].default,
+        ),
+    ]
+    ffmpeg_path: Annotated[
+        str,
+        option(
+            "--ffmpeg-path",
+            help="FFmpeg executable path",
+            default=base_downloader_sig.parameters["ffmpeg_path"].default,
+        ),
+    ]
+    mp4box_path: Annotated[
+        str,
+        option(
+            "--mp4box-path",
+            help="MP4Box executable path",
+            default=base_downloader_sig.parameters["mp4box_path"].default,
+        ),
+    ]
+    use_wrapper: Annotated[
+        bool,
+        option(
+            "--use-wrapper",
+            help="Use wrapper for decrypting songs",
+            is_flag=True,
+        ),
+    ]
+    wrapper_decrypt_ip: Annotated[
+        str,
+        option(
+            "--wrapper-decrypt-ip",
+            help="IP address and port for wrapper decryption",
+            default=base_downloader_sig.parameters["wrapper_decrypt_ip"].default,
+        ),
+    ]
+    download_mode: Annotated[
+        DownloadMode,
+        option(
+            "--download-mode",
+            help="Download mode",
+            default=base_downloader_sig.parameters["download_mode"].default,
+            type=DownloadMode,
+        ),
+    ]
+    cover_format: Annotated[
+        CoverFormat,
+        option(
+            "--cover-format",
+            help="Cover format",
+            default=base_downloader_sig.parameters["cover_format"].default,
+            type=CoverFormat,
+        ),
+    ]
+    album_folder_template: Annotated[
+        str,
+        option(
+            "--album-folder-template",
+            help="Album folder template",
+            default=base_downloader_sig.parameters["album_folder_template"].default,
+        ),
+    ]
+    compilation_folder_template: Annotated[
+        str,
+        option(
+            "--compilation-folder-template",
+            help="Compilation folder template",
+            default=base_downloader_sig.parameters[
+                "compilation_folder_template"
+            ].default,
+        ),
+    ]
+    no_album_folder_template: Annotated[
+        str,
+        option(
+            "--no-album-folder-template",
+            help="No album folder template",
+            default=base_downloader_sig.parameters["no_album_folder_template"].default,
+        ),
+    ]
+    single_disc_file_template: Annotated[
+        str,
+        option(
+            "--single-disc-file-template",
+            help="Single disc file template",
+            default=base_downloader_sig.parameters["single_disc_file_template"].default,
+        ),
+    ]
+    multi_disc_file_template: Annotated[
+        str,
+        option(
+            "--multi-disc-file-template",
+            help="Multi disc file template",
+            default=base_downloader_sig.parameters["multi_disc_file_template"].default,
+        ),
+    ]
+    no_album_file_template: Annotated[
+        str,
+        option(
+            "--no-album-file-template",
+            help="No album file template",
+            default=base_downloader_sig.parameters["no_album_file_template"].default,
+        ),
+    ]
+    playlist_file_template: Annotated[
+        str,
+        option(
+            "--playlist-file-template",
+            help="Playlist file template",
+            default=base_downloader_sig.parameters["playlist_file_template"].default,
+        ),
+    ]
+    date_tag_template: Annotated[
+        str,
+        option(
+            "--date-tag-template",
+            help="Date tag template",
+            default=base_downloader_sig.parameters["date_tag_template"].default,
+        ),
+    ]
+    exclude_tags: Annotated[
+        list[str],
+        option(
+            "--exclude-tags",
+            help="Comma-separated tags to exclude",
+            default=base_downloader_sig.parameters["exclude_tags"].default,
+            type=Csv(str),
+        ),
+    ]
+    cover_size: Annotated[
+        int,
+        option(
+            "--cover-size",
+            help="Cover size in pixels",
+            default=base_downloader_sig.parameters["cover_size"].default,
+        ),
+    ]
+    truncate: Annotated[
+        int,
+        option(
+            "--truncate",
+            help="Max filename length",
+            default=base_downloader_sig.parameters["truncate"].default,
+        ),
+    ]
+    # DownloaderSong specific options
+    song_codec: Annotated[
+        SongCodec,
+        option(
+            "--song-codec",
+            help="Song codec",
+            default=song_downloader_sig.parameters["codec"].default,
+            type=SongCodec,
+        ),
+    ]
+    synced_lyrics_format: Annotated[
+        SyncedLyricsFormat,
+        option(
+            "--synced-lyrics-format",
+            help="Synced lyrics format",
+            default=song_downloader_sig.parameters["synced_lyrics_format"].default,
+            type=SyncedLyricsFormat,
+        ),
+    ]
+    no_synced_lyrics: Annotated[
+        bool,
+        option(
+            "--no-synced-lyrics",
+            help="Don't download synced lyrics",
+            is_flag=True,
+        ),
+    ]
+    synced_lyrics_only: Annotated[
+        bool,
+        option(
+            "--synced-lyrics-only",
+            help="Download only synced lyrics",
+            is_flag=True,
+        ),
+    ]
+    use_album_date: Annotated[
+        bool,
+        option(
+            "--use-album-date",
+            help="Use album release date for songs",
+            is_flag=True,
+        ),
+    ]
+    fetch_extra_tags: Annotated[
+        bool,
+        option(
+            "--fetch-extra-tags",
+            help="Fetch extra tags from preview (normalization and smooth playback)",
+            is_flag=True,
+        ),
+    ]
+    # DownloaderMusicVideo specific options
+    music_video_codec_priority: Annotated[
+        list[MusicVideoCodec],
+        option(
+            "--music-video-codec-priority",
+            help="Comma-separated codec priority",
+            default=music_video_downloader_sig.parameters["codec_priority"].default,
+            type=Csv(MusicVideoCodec),
+        ),
+    ]
+    music_video_remux_mode: Annotated[
+        RemuxMode,
+        option(
+            "--music-video-remux-mode",
+            help="Remux mode",
+            default=music_video_downloader_sig.parameters["remux_mode"].default,
+            type=RemuxMode,
+        ),
+    ]
+    music_video_remux_format: Annotated[
+        RemuxFormatMusicVideo,
+        option(
+            "--music-video-remux-format",
+            help="Music video remux format",
+            default=music_video_downloader_sig.parameters["remux_format"].default,
+            type=RemuxFormatMusicVideo,
+        ),
+    ]
+    music_video_resolution: Annotated[
+        MusicVideoResolution,
+        option(
+            "--music-video-resolution",
+            help="Max music video resolution",
+            default=music_video_downloader_sig.parameters["resolution"].default,
+            type=MusicVideoResolution,
+        ),
+    ]
+    # DownloaderUploadedVideo specific options
+    uploaded_video_quality: Annotated[
+        UploadedVideoQuality,
+        option(
+            "--uploaded-video-quality",
+            help="Post video quality",
+            default=uploaded_video_downloader_sig.parameters["quality"].default,
+            type=UploadedVideoQuality,
+        ),
+    ]
+    no_config_file: Annotated[
+        bool,
+        option(
+            "--no-config-file",
+            "-n",
+            help="Don't use a config file",
+            is_flag=True,
+        ),
+    ]

gamdl/cli/config_file.py

@@ -1,10 +1,12 @@
 import configparser
 import typing
+from functools import wraps
 from pathlib import Path
 
 import click
-from click.types import BoolParamType, FuncParamType
+import click.types as click_types
 
+from .cli_config import CliConfig
 from .constants import EXCLUDED_CONFIG_FILE_PARAMS
 from .utils import Csv
 
@@ -18,6 +20,7 @@ class ConfigFile:
         self.config_path = config_path
         self.section_name = section_name
 
+        self.click_context = click.get_current_context()
         self._read_config_file()
 
     def _read_config_file(self) -> None:
@@ -40,15 +43,30 @@ class ConfigFile:
             return "null"
 
         if isinstance(param.type, Csv):
-            return ",".join(item.value for item in param.default)
+            return ",".join(
+                item.value if hasattr(item, "value") else str(item)
+                for item in param.default
+            )
 
-        if isinstance(param.type, BoolParamType):
-            return str(param.default).lower()
-
-        if isinstance(param.type, FuncParamType):
+        if isinstance(param.type, click_types.FuncParamType):
             return param.default.value
 
-        return str(param.default)
+        if isinstance(param.type, click_types.BoolParamType):
+            return "true" if param.default else "false"
+
+        if isinstance(
+            param.type,
+            click_types.Choice
+            | click_types.Path
+            | click_types.StringParamType
+            | click_types.IntParamType,
+        ):
+            return str(param.default)
+
+        raise NotImplementedError(
+            f"Serialization for parameter '{param.name}' of type "
+            f"'{type(param.type)}' is not implemented."
+        )
 
     def _add_param_default_to_config(
         self,
@@ -67,19 +85,24 @@ class ConfigFile:
         param: click.Parameter,
     ) -> typing.Any:
         value = self.config[self.section_name].get(param.name)
+        if value is None:
+            return param.default
 
         if value == "null":
             return None
 
-        return param.type_cast_value(None, value)
+        if not isinstance(param.type, click_types.ParamType):
+            raise NotImplementedError(
+                f"Parsing for parameter '{param.name}' of type "
+                f"'{type(param.type)}' is not implemented."
+            )
 
-    def add_params_default_to_config(
-        self,
-        params: list[click.Parameter],
-    ) -> None:
+        return param.type.convert(value, None, None)
+
+    def add_params_default_to_config(self) -> None:
         has_changes = False
 
-        for param in params:
+        for param in self.click_context.command.params:
             if param.name in EXCLUDED_CONFIG_FILE_PARAMS:
                 continue
 
@@ -88,11 +111,8 @@ class ConfigFile:
         if has_changes:
             self._write_config_file()
 
-    def cleanup_unknown_params(
-        self,
-        params: list[click.Parameter],
-    ) -> None:
-        param_names = {param.name for param in params}
+    def cleanup_unknown_params(self) -> None:
+        param_names = {info.name for info in self.click_context.command.params}
         has_changes = False
 
         for key in list(self.config[self.section_name].keys()):
@@ -103,13 +123,45 @@ class ConfigFile:
         if has_changes:
             self._write_config_file()
 
-    def parse_params_from_config(
-        self,
-        params: list[click.Parameter],
-    ) -> dict[str, typing.Any]:
-        parsed_params = {}
+    def update_params_from_config(self) -> None:
+        for param in self.click_context.command.params:
+            if (
+                self.click_context.get_parameter_source(param.name)
+                == click.core.ParameterSource.COMMANDLINE
+            ):
+                continue
 
-        for param in params:
-            parsed_params[param.name] = self._parse_param_from_config(param)
+            if self.config.has_option(self.section_name, param.name):
+                self.click_context.params[param.name] = self._parse_param_from_config(
+                    param
+                )
 
-        return parsed_params
+    def get_cli_config(self) -> CliConfig:
+        config_dict = {}
+        for param in self.click_context.command.params:
+            if param.name in {"help", "version"}:
+                continue
+
+            config_dict[param.name] = self.click_context.params.get(
+                param.name, param.default
+            )
+        return CliConfig(**config_dict)
+
+    def load(self) -> CliConfig:
+        self.cleanup_unknown_params()
+        self.add_params_default_to_config()
+        self.update_params_from_config()
+        return self.get_cli_config()
+
+    @staticmethod
+    def loader(func):
+        @wraps(func)
+        def wrapper(cli_config: CliConfig):
+            ctx = click.get_current_context()
+            config_path = ctx.params.get("config_path")
+            no_config_file = ctx.params.get("no_config_file")
+            if config_path and not no_config_file:
+                cli_config = ConfigFile(config_path).load()
+            return func(cli_config)
+
+        return wrapper

gamdl/downloader/constants.py

@@ -1,10 +1,5 @@
 import re
 
-DEFAULT_SONG_DECRYPTION_KEY = "32b8ade1769e26b1ffb8986352793fc6"
-IMAGE_FILE_EXTENSION_MAP = {
-    "jpeg": ".jpg",
-    "tiff": ".tif",
-}
 TEMP_PATH_TEMPLATE = "gamdl_temp_{}"
 ILLEGAL_CHARS_RE = r'[\\/:*?"<>|;]'
 ILLEGAL_CHAR_REPLACEMENT = "_"

gamdl/downloader/downloader.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from InquirerPy import inquirer
 from InquirerPy.base.control import Choice
 
+from ..api.exceptions import ApiError
 from ..interface import AppleMusicInterface
 from ..utils import safe_gather
 from .constants import (
@@ -24,9 +25,10 @@ from .enums import DownloadMode, RemuxMode
 from .exceptions import (
     ExecutableNotFound,
     FormatNotAvailable,
+    MediaFileExists,
     NotStreamable,
     SyncedLyricsOnly,
-    MediaFileExists,
+    UnsupportedMediaType,
 )
 from .types import DownloadItem, UrlInfo
 
@@ -79,23 +81,42 @@ class AppleMusicDownloader:
         media_metadata: dict,
         playlist_metadata: dict = None,
     ) -> DownloadItem:
-        download_item = None
-
-        if media_metadata["type"] in SONG_MEDIA_TYPE:
-            download_item = await self.song_downloader.get_download_item(
+        try:
+            if not self.base_downloader.is_media_streamable(
                 media_metadata,
-                playlist_metadata,
-            )
+            ):
+                raise NotStreamable(media_metadata["id"])
 
-        if media_metadata["type"] in MUSIC_VIDEO_MEDIA_TYPE:
-            download_item = await self.music_video_downloader.get_download_item(
-                media_metadata,
-                playlist_metadata,
-            )
+            if media_metadata["type"] in SONG_MEDIA_TYPE:
+                if not self.song_downloader:
+                    raise UnsupportedMediaType(media_metadata["type"])
 
-        if media_metadata["type"] in UPLOADED_VIDEO_MEDIA_TYPE:
-            download_item = await self.uploaded_video_downloader.get_download_item(
-                media_metadata,
+                download_item = await self.song_downloader.get_download_item(
+                    media_metadata,
+                    playlist_metadata,
+                )
+
+            if media_metadata["type"] in MUSIC_VIDEO_MEDIA_TYPE:
+                if not self.music_video_downloader:
+                    raise UnsupportedMediaType(media_metadata["type"])
+
+                download_item = await self.music_video_downloader.get_download_item(
+                    media_metadata,
+                    playlist_metadata,
+                )
+
+            if media_metadata["type"] in UPLOADED_VIDEO_MEDIA_TYPE:
+                if not self.uploaded_video_downloader:
+                    raise UnsupportedMediaType(media_metadata["type"])
+
+                download_item = await self.uploaded_video_downloader.get_download_item(
+                    media_metadata,
+                )
+        except Exception as e:
+            download_item = DownloadItem(
+                media_metadata=media_metadata,
+                playlist_metadata=playlist_metadata,
+                error=e,
             )
 
         return download_item
@@ -111,15 +132,13 @@ class AppleMusicDownloader:
             tracks_metadata.extend(extended_data["data"])
 
         tasks = [
-            asyncio.create_task(
-                self.get_single_download_item(
-                    media_metadata,
-                    (
-                        collection_metadata
-                        if collection_metadata["type"] in PLAYLIST_MEDIA_TYPE
-                        else None
-                    ),
-                )
+            self.get_single_download_item(
+                media_metadata,
+                (
+                    collection_metadata
+                    if collection_metadata["type"] in PLAYLIST_MEDIA_TYPE
+                    else None
+                ),
             )
             for media_metadata in tracks_metadata
         ]
@@ -131,42 +150,67 @@ class AppleMusicDownloader:
         self,
         artist_metadata: dict,
     ) -> list[DownloadItem]:
-        for relationship in artist_metadata["relationships"].keys():
-            artist_metadata["relationships"][relationship]["data"].extend(
-                [
-                    extended_data
-                    async for extended_data in self.interface.apple_music_api.extend_api_data(
-                        artist_metadata["relationships"][relationship],
-                    )
-                ]
-            )
-
         media_type = await inquirer.select(
             message=f'Select which type to download for artist "{artist_metadata["attributes"]["name"]}":',
             choices=[
                 Choice(
-                    name="Albums",
-                    value="albums",
+                    name="Main Albums",
+                    value=["views", "full-albums"],
+                ),
+                Choice(
+                    name="Compilations Albums",
+                    value=["views", "compilation-albums"],
+                ),
+                Choice(
+                    name="Live Albums",
+                    value=["views", "live-albums"],
+                ),
+                Choice(
+                    name="Singles & EPs",
+                    value=["views", "singles"],
+                ),
+                Choice(
+                    name="All Albums",
+                    value=["relationships", "albums"],
+                ),
+                Choice(
+                    name="Top Songs",
+                    value=["views", "top-songs"],
                 ),
                 Choice(
                     name="Music Videos",
-                    value="music-videos",
+                    value=["relationships", "music-videos"],
                 ),
             ],
-            validate=lambda result: artist_metadata["relationships"]
-            .get(result, {})
+            validate=lambda result: artist_metadata.get(result[0], {})
+            .get(result[1], {})
             .get("data"),
             invalid_message="The artist doesn't have any items of this type",
         ).execute_async()
 
-        if media_type == "albums":
-            return await self.get_artist_albums_download_items(
-                artist_metadata["relationships"]["albums"]["data"]
-            )
-        if media_type == "music-videos":
-            return await self.get_artist_music_videos_download_items(
-                artist_metadata["relationships"]["music-videos"]["data"]
-            )
+        media_type, media_type_key = media_type
+        artist_metadata[media_type][media_type_key]["data"].extend(
+            [
+                extended_data
+                async for extended_data in self.interface.apple_music_api.extend_api_data(
+                    artist_metadata[media_type][media_type_key],
+                )
+            ]
+        )
+        selected_tracks = artist_metadata[media_type][media_type_key]["data"]
+
+        if media_type_key in {
+            "full-albums",
+            "compilation-albums",
+            "live-albums",
+            "singles",
+            "albums",
+        }:
+            return await self.get_artist_albums_download_items(selected_tracks)
+        elif media_type_key == "top-songs":
+            return await self.get_artist_songs_download_items(selected_tracks)
+        elif media_type_key == "music-videos":
+            return await self.get_artist_music_videos_download_items(selected_tracks)
 
     async def get_artist_albums_download_items(
         self,
@@ -196,17 +240,13 @@ class AppleMusicDownloader:
         download_items = []
 
         album_tasks = [
-            asyncio.create_task(
-                self.interface.apple_music_api.get_album(album_metadata["id"])
-            )
+            self.interface.apple_music_api.get_album(album_metadata["id"])
             for album_metadata in selected
         ]
         album_responses = await safe_gather(*album_tasks)
 
         track_tasks = [
-            asyncio.create_task(
-                self.get_collection_download_items(album_response["data"][0])
-            )
+            self.get_collection_download_items(album_response["data"][0])
             for album_response in album_responses
         ]
         track_results = await safe_gather(*track_tasks)
@@ -243,10 +283,8 @@ class AppleMusicDownloader:
         ).execute_async()
 
         music_video_tasks = [
-            asyncio.create_task(
-                self.get_single_download_item(
-                    music_video_metadata,
-                )
+            self.get_single_download_item(
+                music_video_metadata,
             )
             for music_video_metadata in selected
         ]
@@ -254,6 +292,40 @@ class AppleMusicDownloader:
 
         return download_items
 
+    async def get_artist_songs_download_items(
+        self,
+        songs_metadata: list[dict],
+    ) -> list[DownloadItem]:
+        choices = [
+            Choice(
+                name=" | ".join(
+                    [
+                        self.millis_to_min_sec(song["attributes"]["durationInMillis"]),
+                        f'{song["attributes"].get("contentRating", "None").title():<8}',
+                        song["attributes"]["name"],
+                    ],
+                ),
+                value=song,
+            )
+            for song in songs_metadata
+            if song.get("attributes")
+        ]
+        selected = await inquirer.select(
+            message="Select which songs to download: (Duration | Rating | Title)",
+            choices=choices,
+            multiselect=True,
+        ).execute_async()
+
+        song_tasks = [
+            self.get_single_download_item(
+                song_metadata,
+            )
+            for song_metadata in selected
+        ]
+        download_items = await safe_gather(*song_tasks)
+
+        return download_items
+
     def millis_to_min_sec(self, millis) -> str:
         minutes, seconds = divmod(millis // 1000, 60)
         return f"{minutes:02}:{seconds:02}"
@@ -286,9 +358,14 @@ class AppleMusicDownloader:
         download_items = []
 
         if url_type in ARTIST_MEDIA_TYPE:
-            artist_response = await self.interface.apple_music_api.get_artist(
-                id,
-            )
+            try:
+                artist_response = await self.interface.apple_music_api.get_artist(
+                    id,
+                )
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if artist_response is None:
                 return None
@@ -298,7 +375,12 @@ class AppleMusicDownloader:
             )
 
         if url_type in SONG_MEDIA_TYPE:
-            song_respose = await self.interface.apple_music_api.get_song(id)
+            try:
+                song_respose = await self.interface.apple_music_api.get_song(id)
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if song_respose is None:
                 return None
@@ -308,12 +390,17 @@ class AppleMusicDownloader:
             )
 
         if url_type in ALBUM_MEDIA_TYPE:
-            if is_library:
-                album_response = await self.interface.apple_music_api.get_library_album(
-                    id
-                )
-            else:
-                album_response = await self.interface.apple_music_api.get_album(id)
+            try:
+                if is_library:
+                    album_response = (
+                        await self.interface.apple_music_api.get_library_album(id)
+                    )
+                else:
+                    album_response = await self.interface.apple_music_api.get_album(id)
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if album_response is None:
                 return None
@@ -323,14 +410,19 @@ class AppleMusicDownloader:
             )
 
         if url_type in PLAYLIST_MEDIA_TYPE:
-            if is_library:
-                playlist_response = (
-                    await self.interface.apple_music_api.get_library_playlist(id)
-                )
-            else:
-                playlist_response = await self.interface.apple_music_api.get_playlist(
-                    id
-                )
+            try:
+                if is_library:
+                    playlist_response = (
+                        await self.interface.apple_music_api.get_library_playlist(id)
+                    )
+                else:
+                    playlist_response = (
+                        await self.interface.apple_music_api.get_playlist(id)
+                    )
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if playlist_response is None:
                 return None
@@ -340,9 +432,14 @@ class AppleMusicDownloader:
             )
 
         if url_type in MUSIC_VIDEO_MEDIA_TYPE:
-            music_video_response = await self.interface.apple_music_api.get_music_video(
-                id
-            )
+            try:
+                music_video_response = (
+                    await self.interface.apple_music_api.get_music_video(id)
+                )
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if music_video_response is None:
                 return None
@@ -352,7 +449,14 @@ class AppleMusicDownloader:
             )
 
         if url_type in UPLOADED_VIDEO_MEDIA_TYPE:
-            uploaded_video = await self.interface.apple_music_api.get_uploaded_video(id)
+            try:
+                uploaded_video = (
+                    await self.interface.apple_music_api.get_uploaded_video(id)
+                )
+            except ApiError as e:
+                if e.status_code == 404:
+                    return None
+                raise e
 
             if uploaded_video is None:
                 return None
@@ -368,15 +472,15 @@ class AppleMusicDownloader:
         download_item: DownloadItem,
     ) -> DownloadItem:
         try:
-            if download_item.error:
-                raise download_item.error
-
             if download_item.flat_filter_result:
                 download_item = await self.get_single_download_item_no_filter(
                     download_item.media_metadata,
                     download_item.playlist_metadata,
                 )
 
+            if download_item.error:
+                raise download_item.error
+
             await self._initial_processing(download_item)
             await self._download(download_item)
             await self._final_processing(download_item)
@@ -399,60 +503,51 @@ class AppleMusicDownloader:
         if self.song_downloader.synced_lyrics_only:
             return
 
-        if not self.base_downloader.is_media_streamable(
-            download_item.media_metadata,
-        ):
-            raise NotStreamable(download_item.media_metadata["id"])
-
         if (
             Path(download_item.final_path).exists()
             and not self.base_downloader.overwrite
         ):
             raise MediaFileExists(download_item.final_path)
 
-        if download_item.media_metadata["type"] in {
-            *SONG_MEDIA_TYPE,
-            *MUSIC_VIDEO_MEDIA_TYPE,
-        }:
+        if (
+            self.base_downloader.download_mode == DownloadMode.NM3U8DLRE
+            and not self.base_downloader.full_nm3u8dlre_path
+        ):
+            raise ExecutableNotFound("N_m3u8DL-RE")
+
+        if download_item.media_metadata["type"] in MUSIC_VIDEO_MEDIA_TYPE:
             if (
-                self.base_downloader.remux_mode == RemuxMode.FFMPEG
+                self.music_video_downloader.remux_mode == RemuxMode.FFMPEG
                 and not self.base_downloader.full_ffmpeg_path
             ):
                 raise ExecutableNotFound("ffmpeg")
 
             if (
-                self.base_downloader.remux_mode == RemuxMode.MP4BOX
+                self.music_video_downloader.remux_mode == RemuxMode.MP4BOX
                 and not self.base_downloader.full_mp4box_path
             ):
                 raise ExecutableNotFound("MP4Box")
 
             if (
-                self.song_downloader.use_wrapper
-                or (
-                    download_item.media_metadata["type"] in MUSIC_VIDEO_MEDIA_TYPE
-                    or self.base_downloader.remux_mode == RemuxMode.MP4BOX
-                )
+                download_item.media_metadata["type"] in MUSIC_VIDEO_MEDIA_TYPE
+                or self.music_video_downloader.remux_mode == RemuxMode.MP4BOX
             ) and not self.base_downloader.full_mp4decrypt_path:
                 raise ExecutableNotFound("mp4decrypt")
 
-            if (
-                self.song_downloader.use_wrapper
-                and not self.base_downloader.full_amdecrypt_path
-            ):
-                raise ExecutableNotFound("amdecrypt")
-
-            if (
-                self.base_downloader.download_mode == DownloadMode.NM3U8DLRE
-                and not self.base_downloader.full_nm3u8dlre_path
-            ):
-                raise ExecutableNotFound("N_m3u8DL-RE")
-
-            if (
-                not download_item.decryption_key
-                or not download_item.decryption_key.audio_track
-                or not download_item.decryption_key.audio_track.key
-            ) and not self.base_downloader.use_wrapper:
-                raise FormatNotAvailable(download_item.media_metadata["id"])
+        if (
+            not download_item.stream_info
+            or not download_item.stream_info.audio_track
+            or not download_item.stream_info.audio_track.stream_url
+            or (
+                (
+                    not download_item.decryption_key
+                    or not download_item.decryption_key.audio_track
+                    or not download_item.decryption_key.audio_track.key
+                )
+                and not self.base_downloader.use_wrapper
+            )
+        ):
+            raise FormatNotAvailable(download_item.media_metadata["id"])
 
         if download_item.media_metadata["type"] in SONG_MEDIA_TYPE:
             await self.song_downloader.download(download_item)
@@ -471,10 +566,7 @@ class AppleMusicDownloader:
             return
 
         if download_item.cover_path and self.base_downloader.save_cover:
-            cover_url = self.base_downloader.get_cover_url(
-                download_item.cover_url_template,
-            )
-            cover_bytes = await self.base_downloader.get_cover_bytes(cover_url)
+            cover_bytes = await self.interface.get_cover_bytes(download_item.cover_url)
             if cover_bytes and (
                 self.base_downloader.overwrite
                 or not Path(download_item.cover_path).exists()

gamdl/downloader/downloader_base.py

@@ -2,25 +2,17 @@ import asyncio
 import re
 import shutil
 import uuid
-from io import BytesIO
 from pathlib import Path
 
-import httpx
-from async_lru import alru_cache
 from mutagen.mp4 import MP4, MP4Cover
-from PIL import Image
 from pywidevine import Cdm, Device
 from yt_dlp import YoutubeDL
 
+from ..interface.enums import CoverFormat
 from ..interface.types import MediaTags, PlaylistTags
-from ..utils import async_subprocess, raise_for_status
-from .constants import (
-    ILLEGAL_CHAR_REPLACEMENT,
-    ILLEGAL_CHARS_RE,
-    IMAGE_FILE_EXTENSION_MAP,
-    TEMP_PATH_TEMPLATE,
-)
-from .enums import CoverFormat, DownloadMode, RemuxMode
+from ..utils import CustomStringFormatter, async_subprocess
+from .constants import ILLEGAL_CHAR_REPLACEMENT, ILLEGAL_CHARS_RE, TEMP_PATH_TEMPLATE
+from .enums import DownloadMode
 from .hardcoded_wvd import HARDCODED_WVD
 
 
@@ -37,11 +29,9 @@ class AppleMusicBaseDownloader:
         mp4decrypt_path: str = "mp4decrypt",
         ffmpeg_path: str = "ffmpeg",
         mp4box_path: str = "MP4Box",
-        amdecrypt_path: str = "amdecrypt",
         use_wrapper: bool = False,
         wrapper_decrypt_ip: str = "127.0.0.1:10020",
         download_mode: DownloadMode = DownloadMode.YTDLP,
-        remux_mode: RemuxMode = RemuxMode.FFMPEG,
         cover_format: CoverFormat = CoverFormat.JPG,
         album_folder_template: str = "{album_artist}/{album}",
         compilation_folder_template: str = "Compilations/{album}",
@@ -66,11 +56,9 @@ class AppleMusicBaseDownloader:
         self.mp4decrypt_path = mp4decrypt_path
         self.ffmpeg_path = ffmpeg_path
         self.mp4box_path = mp4box_path
-        self.amdecrypt_path = amdecrypt_path
         self.use_wrapper = use_wrapper
         self.wrapper_decrypt_ip = wrapper_decrypt_ip
         self.download_mode = download_mode
-        self.remux_mode = remux_mode
         self.cover_format = cover_format
         self.album_folder_template = album_folder_template
         self.compilation_folder_template = compilation_folder_template
@@ -84,19 +72,19 @@ class AppleMusicBaseDownloader:
         self.cover_size = cover_size
         self.truncate = truncate
         self.silent = silent
+        self.initialize()
 
-    def setup(self):
-        self._setup_binary_paths()
-        self._setup_cdm()
+    def initialize(self):
+        self._initialize_binary_paths()
+        self._initialize_cdm()
 
-    def _setup_binary_paths(self):
+    def _initialize_binary_paths(self):
         self.full_nm3u8dlre_path = shutil.which(self.nm3u8dlre_path)
         self.full_mp4decrypt_path = shutil.which(self.mp4decrypt_path)
         self.full_ffmpeg_path = shutil.which(self.ffmpeg_path)
         self.full_mp4box_path = shutil.which(self.mp4box_path)
-        self.full_amdecrypt_path = shutil.which(self.amdecrypt_path)
 
-    def _setup_cdm(self):
+    def _initialize_cdm(self):
         if self.wvd_path:
             self.cdm = Cdm.from_device(Device.load(self.wvd_path))
         else:
@@ -112,22 +100,6 @@ class AppleMusicBaseDownloader:
     ) -> bool:
         return bool(media_metadata["attributes"].get("playParams"))
 
-    async def get_cover_file_extension(self, cover_url_template: str) -> str | None:
-        if self.cover_format != CoverFormat.RAW:
-            return f".{self.cover_format.value}"
-
-        cover_url = self.get_cover_url(cover_url_template)
-        cover_bytes = await self.get_cover_bytes(cover_url)
-        if cover_bytes is None:
-            return None
-
-        image_obj = Image.open(BytesIO(self.get_cover_bytes(cover_url)))
-        image_format = image_obj.format.lower()
-        return IMAGE_FILE_EXTENSION_MAP.get(
-            image_format,
-            f".{image_format.lower()}",
-        )
-
     def get_playlist_tags(
         self,
         playlist_metadata: dict,
@@ -160,112 +132,98 @@ class AppleMusicBaseDownloader:
             / (f"{media_id}_{file_tag}" + file_extension)
         )
 
-    @alru_cache()
-    async def get_cover_bytes(self, cover_url: str) -> bytes | None:
-        async with httpx.AsyncClient() as client:
-            response = await client.get(cover_url)
-            raise_for_status(response, {200, 404})
-
-            if response.status_code == 200:
-                return response.content
-            return None
-
-    def get_sanitized_string(self, dirty_string: str, is_folder: bool) -> str:
-        dirty_string = re.sub(
+    def sanitize_string(
+        self,
+        dirty_string: str,
+        file_ext: str = None,
+    ) -> str:
+        sanitized_string = re.sub(
             ILLEGAL_CHARS_RE,
             ILLEGAL_CHAR_REPLACEMENT,
             dirty_string,
         )
-        if is_folder:
-            dirty_string = dirty_string[: self.truncate]
-            if dirty_string.endswith("."):
-                dirty_string = dirty_string[:-1] + ILLEGAL_CHAR_REPLACEMENT
+
+        if file_ext is None:
+            sanitized_string = sanitized_string[: self.truncate]
+            if sanitized_string.endswith("."):
+                sanitized_string = sanitized_string[:-1] + ILLEGAL_CHAR_REPLACEMENT
         else:
             if self.truncate is not None:
-                dirty_string = dirty_string[: self.truncate - 4]
-        return dirty_string.strip()
+                sanitized_string = sanitized_string[: self.truncate - len(file_ext)]
+            sanitized_string += file_ext
+
+        return sanitized_string.strip()
 
     def get_final_path(
         self,
         tags: MediaTags,
         file_extension: str,
-        playlist_tags: PlaylistTags,
+        playlist_tags: PlaylistTags | None,
     ) -> str:
-        if tags.album is not None:
-            template_folder = (
+        if tags.album:
+            template_folder_parts = (
                 self.compilation_folder_template.split("/")
                 if tags.compilation
                 else self.album_folder_template.split("/")
             )
-            template_file = (
+        else:
+            template_folder_parts = self.no_album_folder_template.split("/")
+
+        if tags.album:
+            template_file_parts = (
                 self.multi_disc_file_template.split("/")
-                if tags.disc_total > 1
+                if isinstance(tags.disc_total, int) and tags.disc_total > 1
                 else self.single_disc_file_template.split("/")
             )
         else:
-            template_folder = self.no_album_folder_template.split("/")
-            template_file = self.no_album_file_template.split("/")
+            template_file_parts = self.no_album_file_template.split("/")
 
-        template_final = template_folder + template_file
+        template_parts = template_folder_parts + template_file_parts
+        formatted_parts = []
 
-        tags_dict = tags.__dict__.copy()
-        if playlist_tags:
-            tags_dict.update(playlist_tags.__dict__)
-
-        return str(
-            Path(
-                self.output_path,
-                *[
-                    self.get_sanitized_string(i.format(**tags_dict), True)
-                    for i in template_final[0:-1]
-                ],
-                (
-                    self.get_sanitized_string(
-                        template_final[-1].format(**tags_dict), False
-                    )
-                    + file_extension
+        for i, part in enumerate(template_parts):
+            is_folder = i < len(template_parts) - 1
+            formatted_part = CustomStringFormatter().format(
+                part,
+                album=(tags.album, "Unknown Album"),
+                album_artist=(tags.album_artist, "Unknown Artist"),
+                album_id=(tags.album_id, "Unknown Album ID"),
+                artist=(tags.artist, "Unknown Artist"),
+                artist_id=(tags.artist_id, "Unknown Artist ID"),
+                composer=(tags.composer, "Unknown Composer"),
+                composer_id=(tags.composer_id, "Unknown Composer ID"),
+                date=(tags.date, "Unknown Date"),
+                disc=(tags.disc, ""),
+                disc_total=(tags.disc_total, ""),
+                media_type=(tags.media_type, "Unknown Media Type"),
+                playlist_artist=(
+                    (playlist_tags.playlist_artist if playlist_tags else None),
+                    "Unknown Playlist Artist",
                 ),
+                playlist_id=(
+                    (playlist_tags.playlist_id if playlist_tags else None),
+                    "Unknown Playlist ID",
+                ),
+                playlist_title=(
+                    (playlist_tags.playlist_title if playlist_tags else None),
+                    "Unknown Playlist Title",
+                ),
+                playlist_track=(
+                    (playlist_tags.playlist_track if playlist_tags else None),
+                    "",
+                ),
+                title=(tags.title, "Unknown Title"),
+                title_id=(tags.title_id, "Unknown Title ID"),
+                track=(tags.track, ""),
+                track_total=(tags.track_total, ""),
             )
-        )
+            sanitized_formatted_part = self.sanitize_string(
+                formatted_part,
+                file_extension if not is_folder else None,
+            )
+            formatted_parts.append(sanitized_formatted_part)
 
-    def get_cover_url_template(self, metadata: dict) -> str:
-        if self.cover_format == CoverFormat.RAW:
-            return self._get_raw_cover_url(metadata["attributes"]["artwork"]["url"])
-        return metadata["attributes"]["artwork"]["url"]
-
-    def _get_raw_cover_url(self, cover_url_template: str) -> str:
-        return re.sub(
-            r"image/thumb/",
-            "",
-            re.sub(
-                r"is1-ssl",
-                "a1",
-                cover_url_template,
-            ),
-        )
-
-    def get_cover_url(self, cover_url_template: str) -> str:
-        return self.format_cover_url(
-            cover_url_template,
-            self.cover_size,
-            self.cover_format.value,
-        )
-
-    def format_cover_url(
-        self,
-        cover_url_template: str,
-        cover_size: int,
-        cover_format: str,
-    ) -> str:
-        return re.sub(
-            r"\{w\}x\{h\}([a-z]{2})\.jpg",
-            (
-                f"{cover_size}x{cover_size}bb.{cover_format}"
-                if self.cover_format != CoverFormat.RAW
-                else ""
-            ),
-            cover_url_template,
-        )
+        return str(Path(self.output_path, *formatted_parts))
 
     async def download_stream(self, stream_url: str, download_path: str):
         if self.download_mode == DownloadMode.YTDLP:
@@ -322,7 +280,8 @@ class AppleMusicBaseDownloader:
         self,
         media_path: Path,
         tags: MediaTags,
-        cover_url_template: str,
+        cover_bytes: bytes | None,
+        extra_tags: dict | None = None,
     ):
         exclude_tags = self.exclude_tags or []
 
@@ -335,9 +294,6 @@ class AppleMusicBaseDownloader:
         )
         mp4_tags = filtered_tags.as_mp4_tags(self.date_tag_template)
 
-        cover_url = self.get_cover_url(cover_url_template)
-        cover_bytes = await self.get_cover_bytes(cover_url)
-
         skip_tagging = "all" in exclude_tags
 
         await asyncio.to_thread(
@@ -346,6 +302,7 @@ class AppleMusicBaseDownloader:
             mp4_tags,
             cover_bytes,
             skip_tagging,
+            extra_tags,
         )
 
     def apply_mp4_tags(
@@ -354,6 +311,7 @@ class AppleMusicBaseDownloader:
         tags: dict,
         cover_bytes: bytes | None,
         skip_tagging: bool,
+        extra_tags: dict | None,
     ):
         mp4 = MP4(media_path)
         mp4.clear()
@@ -371,16 +329,16 @@ class AppleMusicBaseDownloader:
                     )
                 ]
             mp4.update(tags)
+            if extra_tags:
+                mp4.update(extra_tags)
 
         mp4.save()
 
     async def _apply_cover(
         self,
         mp4: MP4,
-        cover_url_template: str,
+        cover_bytes: bytes | None,
     ) -> None:
-        cover_url = self.get_cover_url(cover_url_template)
-        cover_bytes = await self.get_cover_bytes(cover_url)
         if cover_bytes is None:
             return
 
@@ -411,24 +369,26 @@ class AppleMusicBaseDownloader:
         self,
         tags: PlaylistTags,
     ) -> str:
-        template_file = self.playlist_file_template.split("/")
-        tags_dict = tags.__dict__.copy()
+        template_file_parts = self.playlist_file_template.split("/")
+        formatted_parts = []
 
-        return str(
-            Path(
-                self.output_path,
-                *[
-                    self.get_sanitized_string(i.format(**tags_dict), True)
-                    for i in template_file[0:-1]
-                ],
-                *[
-                    self.get_sanitized_string(
-                        template_file[-1].format(**tags_dict), False
-                    )
-                    + ".m3u8"
-                ],
+        for i, part in enumerate(template_file_parts):
+            is_folder = i < len(template_file_parts) - 1
+            formatted_part = CustomStringFormatter().format(
+                part,
+                playlist_artist=(tags.playlist_artist, "Unknown Playlist Artist"),
+                playlist_id=(tags.playlist_id, "Unknown Playlist ID"),
+                playlist_title=(tags.playlist_title, "Unknown Playlist Title"),
+                playlist_track=(tags.playlist_track, ""),
             )
-        )
+            file_ext = None if is_folder else ".m3u8"
+            sanitized_formatted_part = self.sanitize_string(
+                formatted_part,
+                file_ext,
+            )
+            formatted_parts.append(sanitized_formatted_part)
+
+        return str(Path(self.output_path, *formatted_parts))
 
     def update_playlist_file(
         self,

gamdl/downloader/downloader_music_video.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from ..interface.enums import MusicVideoCodec, MusicVideoResolution
+from ..interface.enums import CoverFormat, MusicVideoCodec, MusicVideoResolution
 from ..interface.interface_music_video import AppleMusicMusicVideoInterface
 from ..interface.types import DecryptionKeyAv
 from ..utils import async_subprocess
@@ -18,12 +18,14 @@ class AppleMusicMusicVideoDownloader(AppleMusicBaseDownloader):
             MusicVideoCodec.H264,
             MusicVideoCodec.H265,
         ],
+        remux_mode: RemuxMode = RemuxMode.FFMPEG,
         remux_format: RemuxFormatMusicVideo = RemuxFormatMusicVideo.M4V,
         resolution: MusicVideoResolution = MusicVideoResolution.R1080P,
     ):
         self.__dict__.update(base_downloader.__dict__)
         self.interface = interface
         self.codec_priority = codec_priority
+        self.remux_mode = remux_mode
         self.remux_format = remux_format
         self.resolution = resolution
 
@@ -142,23 +144,6 @@ class AppleMusicMusicVideoDownloader(AppleMusicBaseDownloader):
         self,
         music_video_metadata: dict,
         playlist_metadata: dict = None,
-    ) -> DownloadItem:
-        try:
-            return await self._get_download_item(
-                music_video_metadata,
-                playlist_metadata,
-            )
-        except Exception as e:
-            return DownloadItem(
-                media_metadata=music_video_metadata,
-                playlist_metadata=playlist_metadata,
-                error=e,
-            )
-
-    async def _get_download_item(
-        self,
-        music_video_metadata: dict,
-        playlist_metadata: dict = None,
     ) -> DownloadItem:
         download_item = DownloadItem()
 
@@ -218,11 +203,19 @@ class AppleMusicMusicVideoDownloader(AppleMusicBaseDownloader):
             playlist_metadata,
         )
 
-        download_item.cover_url_template = self.get_cover_url_template(
+        download_item.cover_url_template = self.interface.get_cover_url_template(
             music_video_metadata,
+            self.cover_format,
         )
-        cover_file_extension = await self.get_cover_file_extension(
+        download_item.cover_url = self.interface.get_cover_url(
             download_item.cover_url_template,
+            self.cover_size,
+            self.cover_format,
+        )
+
+        cover_file_extension = await self.interface.get_cover_file_extension(
+            download_item.cover_url,
+            self.cover_format,
         )
         if cover_file_extension:
             download_item.cover_path = self.get_cover_path(
@@ -280,8 +273,13 @@ class AppleMusicMusicVideoDownloader(AppleMusicBaseDownloader):
             download_item.decryption_key,
         )
 
+        cover_bytes = (
+            await self.interface.get_cover_bytes(download_item.cover_url)
+            if self.cover_format != CoverFormat.RAW
+            else None
+        )
         await self.apply_tags(
             download_item.staged_path,
             download_item.media_tags,
-            download_item.cover_url_template,
+            cover_bytes,
         )

gamdl/downloader/downloader_song.py

@@ -1,12 +1,10 @@
 from pathlib import Path
 
-from ..interface.enums import SongCodec, SyncedLyricsFormat
+from ..interface.enums import CoverFormat, SongCodec, SyncedLyricsFormat
 from ..interface.interface_song import AppleMusicSongInterface
 from ..interface.types import DecryptionKeyAv
-from ..utils import async_subprocess
-from .constants import DEFAULT_SONG_DECRYPTION_KEY
+from .amdecrypt import decrypt_file, decrypt_file_hex
 from .downloader_base import AppleMusicBaseDownloader
-from .enums import RemuxMode
 from .types import DownloadItem
 
 
@@ -19,6 +17,8 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
         synced_lyrics_format: SyncedLyricsFormat = SyncedLyricsFormat.LRC,
         no_synced_lyrics: bool = False,
         synced_lyrics_only: bool = False,
+        use_album_date: bool = False,
+        fetch_extra_tags: bool = False,
     ):
         self.__dict__.update(base_downloader.__dict__)
         self.interface = interface
@@ -26,28 +26,13 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
         self.synced_lyrics_format = synced_lyrics_format
         self.no_synced_lyrics = no_synced_lyrics
         self.synced_lyrics_only = synced_lyrics_only
+        self.use_album_date = use_album_date
+        self.fetch_extra_tags = fetch_extra_tags
 
     async def get_download_item(
         self,
         song_metadata: dict,
         playlist_metadata: dict = None,
-    ) -> DownloadItem:
-        try:
-            return await self._get_download_item(
-                song_metadata,
-                playlist_metadata,
-            )
-        except Exception as e:
-            return DownloadItem(
-                media_metadata=song_metadata,
-                playlist_metadata=playlist_metadata,
-                error=e,
-            )
-
-    async def _get_download_item(
-        self,
-        song_metadata: dict,
-        playlist_metadata: dict = None,
     ) -> DownloadItem:
         download_item = DownloadItem()
 
@@ -62,10 +47,15 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
         )
 
         webplayback = await self.interface.apple_music_api.get_webplayback(song_id)
-        download_item.media_tags = self.interface.get_tags(
+        download_item.media_tags = await self.interface.get_tags(
             webplayback,
             download_item.lyrics.unsynced if download_item.lyrics else None,
+            self.use_album_date,
         )
+        if self.fetch_extra_tags:
+            download_item.extra_tags = await self.interface.get_extra_tags(
+                song_metadata,
+            )
 
         if playlist_metadata:
             download_item.playlist_tags = self.get_playlist_tags(
@@ -116,7 +106,15 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
             else:
                 download_item.decryption_key = None
 
-        download_item.cover_url_template = self.get_cover_url_template(song_metadata)
+        download_item.cover_url_template = self.interface.get_cover_url_template(
+            song_metadata,
+            self.cover_format,
+        )
+        download_item.cover_url = self.interface.get_cover_url(
+            download_item.cover_url_template,
+            self.cover_size,
+            self.cover_format,
+        )
 
         download_item.random_uuid = self.get_random_uuid()
         if download_item.stream_info and download_item.stream_info.file_format:
@@ -129,8 +127,9 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
         else:
             download_item.staged_path = None
 
-        cover_file_extension = await self.get_cover_file_extension(
-            download_item.cover_url_template,
+        cover_file_extension = await self.interface.get_cover_file_extension(
+            download_item.cover_url,
+            self.cover_format,
         )
         if cover_file_extension:
             download_item.cover_path = self.get_cover_path(
@@ -140,93 +139,6 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
 
         return download_item
 
-    def fix_key_id(self, input_path: str):
-        count = 0
-        with open(input_path, "rb+") as file:
-            while data := file.read(4096):
-                pos = file.tell()
-                i = 0
-                while tenc := max(0, data.find(b"tenc", i)):
-                    kid = tenc + 12
-                    file.seek(max(0, pos - 4096) + kid, 0)
-                    file.write(bytes.fromhex(f"{count:032}"))
-                    count += 1
-                    i = kid + 1
-                file.seek(pos, 0)
-
-    async def remux_mp4box(self, input_path: str, output_path: str):
-        await async_subprocess(
-            self.full_mp4box_path,
-            "-quiet",
-            "-add",
-            input_path,
-            "-itags",
-            "artist=placeholder",
-            "-keep-utc",
-            "-new",
-            output_path,
-            silent=self.silent,
-        )
-
-    async def remux_ffmpeg(
-        self,
-        input_path: str,
-        output_path: str,
-        decryption_key: str = None,
-    ):
-        if decryption_key:
-            key = [
-                "-decryption_key",
-                decryption_key,
-            ]
-        else:
-            key = []
-
-        await async_subprocess(
-            self.full_ffmpeg_path,
-            "-loglevel",
-            "error",
-            "-y",
-            *key,
-            "-i",
-            input_path,
-            "-c",
-            "copy",
-            "-movflags",
-            "+faststart",
-            output_path,
-            silent=self.silent,
-        )
-
-    async def decrypt_mp4decrypt(
-        self,
-        input_path: str,
-        output_path: str,
-        decryption_key: str,
-        legacy: bool,
-    ):
-        if legacy:
-            keys = [
-                "--key",
-                f"1:{decryption_key}",
-            ]
-        else:
-            self.fix_key_id(input_path)
-            keys = [
-                "--key",
-                "0" * 31 + "1" + f":{decryption_key}",
-                "--key",
-                "0" * 32 + f":{DEFAULT_SONG_DECRYPTION_KEY}",
-            ]
-
-        await async_subprocess(
-            self.full_mp4decrypt_path,
-            *keys,
-            input_path,
-            output_path,
-            silent=self.silent,
-        )
-
     async def decrypt_amdecrypt(
         self,
         input_path: str,
@@ -234,56 +146,51 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
         media_id: str,
         fairplay_key: str,
     ) -> None:
-        await async_subprocess(
-            self.amdecrypt_path,
+        await decrypt_file(
             self.wrapper_decrypt_ip,
-            self.full_mp4decrypt_path,
             media_id,
             fairplay_key,
             input_path,
             output_path,
         )
 
+    async def decrypt_amdecrypt_hex(
+        self,
+        input_path: str,
+        output_path: str,
+        decryption_key: str,
+        legacy: bool = False,
+    ) -> None:
+        await decrypt_file_hex(
+            input_path,
+            output_path,
+            decryption_key,
+            legacy=legacy,
+        )
+
     async def stage(
         self,
         encrypted_path: str,
-        decrypted_path: str,
         staged_path: str,
         decryption_key: DecryptionKeyAv,
         codec: SongCodec,
         media_id: str,
         fairplay_key: str,
     ):
-        if codec.is_legacy() and self.remux_mode == RemuxMode.FFMPEG:
-            await self.remux_ffmpeg(
-                encrypted_path,
-                staged_path,
-                decryption_key.audio_track.key,
-            )
-        elif codec.is_legacy() or not self.use_wrapper:
-            await self.decrypt_mp4decrypt(
-                encrypted_path,
-                decrypted_path,
-                decryption_key.audio_track.key,
-                codec.is_legacy(),
-            )
-            if self.remux_mode == RemuxMode.FFMPEG:
-                await self.remux_ffmpeg(
-                    decrypted_path,
-                    staged_path,
-                )
-            else:
-                await self.remux_mp4box(
-                    decrypted_path,
-                    staged_path,
-                )
-        else:
+        if self.use_wrapper:
             await self.decrypt_amdecrypt(
                 encrypted_path,
                 staged_path,
                 media_id,
                 fairplay_key,
             )
+        else:
+            await self.decrypt_amdecrypt_hex(
+                encrypted_path,
+                staged_path,
+                decryption_key.audio_track.key,
+                legacy=codec.is_legacy(),
+            )
 
     def get_lyrics_synced_path(self, final_path: str) -> str:
         return str(Path(final_path).with_suffix("." + self.synced_lyrics_format.value))
@@ -321,15 +228,8 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
             encrypted_path,
         )
 
-        decrypted_path = self.get_temp_path(
-            download_item.media_metadata["id"],
-            download_item.random_uuid,
-            "decrypted",
-            ".m4a",
-        )
         await self.stage(
             encrypted_path,
-            decrypted_path,
             download_item.staged_path,
             download_item.decryption_key,
             self.codec,
@@ -337,8 +237,14 @@ class AppleMusicSongDownloader(AppleMusicBaseDownloader):
             download_item.stream_info.audio_track.fairplay_key,
         )
 
+        cover_bytes = (
+            await self.interface.get_cover_bytes(download_item.cover_url)
+            if self.cover_format != CoverFormat.RAW
+            else None
+        )
         await self.apply_tags(
             download_item.staged_path,
             download_item.media_tags,
-            download_item.cover_url_template,
+            cover_bytes,
+            download_item.extra_tags,
         )

gamdl/downloader/downloader_uploaded_video.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from ..interface.enums import UploadedVideoQuality
+from ..interface.enums import CoverFormat, UploadedVideoQuality
 from ..interface.interface_uploaded_video import AppleMusicUploadedVideoInterface
 from .downloader_base import AppleMusicBaseDownloader
 from .types import DownloadItem
@@ -64,11 +64,19 @@ class AppleMusicUploadedVideoDownloader(AppleMusicBaseDownloader):
             None,
         )
 
-        download_item.cover_url_template = self.get_cover_url_template(
+        download_item.cover_url_template = self.interface.get_cover_url_template(
             uploaded_video_metadata,
+            self.cover_format,
         )
-        cover_file_extension = await self.get_cover_file_extension(
+        download_item.cover_url = self.interface.get_cover_url(
             download_item.cover_url_template,
+            self.cover_size,
+            self.cover_format,
+        )
+
+        cover_file_extension = await self.interface.get_cover_file_extension(
+            download_item.cover_url,
+            self.cover_format,
         )
         if cover_file_extension:
             download_item.cover_path = self.get_cover_path(
@@ -86,8 +94,14 @@ class AppleMusicUploadedVideoDownloader(AppleMusicBaseDownloader):
             download_item.stream_info.video_track.stream_url,
             download_item.staged_path,
         )
+
+        cover_bytes = (
+            await self.interface.get_cover_bytes(download_item.cover_url)
+            if self.cover_format != CoverFormat.RAW
+            else None
+        )
         await self.apply_tags(
             download_item.staged_path,
             download_item.media_tags,
-            download_item.cover_url_template,
+            cover_bytes,
         )

gamdl/downloader/enums.py

@@ -11,12 +11,6 @@ class RemuxMode(Enum):
     MP4BOX = "mp4box"
 
 
-class CoverFormat(Enum):
-    JPG = "jpg"
-    PNG = "png"
-    RAW = "raw"
-
-
 class RemuxFormatMusicVideo(Enum):
     M4V = "m4v"
     MP4 = "mp4"

gamdl/downloader/exceptions.py

@@ -1,5 +1,4 @@
-class GamdlError(Exception):
-    pass
+from ..utils import GamdlError
 
 
 class MediaFileExists(GamdlError):
@@ -25,3 +24,8 @@ class ExecutableNotFound(GamdlError):
 class SyncedLyricsOnly(GamdlError):
     def __init__(self):
         super().__init__("Only downloading synced lyrics is supported")
+
+
+class UnsupportedMediaType(GamdlError):
+    def __init__(self, media_type: str):
+        super().__init__(f"Unsupported media type: {media_type}")

gamdl/downloader/types.py

@@ -17,10 +17,12 @@ class DownloadItem:
     random_uuid: str = None
     lyrics: Lyrics = None
     media_tags: MediaTags = None
+    extra_tags: dict = None
     playlist_tags: PlaylistTags = None
     stream_info: StreamInfoAv = None
     decryption_key: DecryptionKeyAv = None
     cover_url_template: str = None
+    cover_url: str = None
     staged_path: str = None
     final_path: str = None
     playlist_file_path: str = None

gamdl/interface/constants.py

@@ -55,3 +55,8 @@ UPLOADED_VIDEO_QUALITY_RANK = [
     "sd480pVideo",
     "provisionalUploadVideo",
 ]
+
+IMAGE_FILE_EXTENSION_MAP = {
+    "jpeg": ".jpg",
+    "tiff": ".tif",
+}

gamdl/interface/enums.py

@@ -87,3 +87,9 @@ class MusicVideoResolution(Enum):
 class UploadedVideoQuality(Enum):
     BEST = "best"
     ASK = "ask"
+
+
+class CoverFormat(Enum):
+    JPG = "jpg"
+    PNG = "png"
+    RAW = "raw"

gamdl/interface/interface.py

@@ -2,11 +2,18 @@ import asyncio
 import base64
 import datetime
 import logging
+import re
+from io import BytesIO
 
+from async_lru import alru_cache
+from PIL import Image
 from pywidevine import PSSH, Cdm
 
 from ..api.apple_music_api import AppleMusicApi
 from ..api.itunes_api import ItunesApi
+from ..utils import get_response
+from .constants import IMAGE_FILE_EXTENSION_MAP
+from .enums import CoverFormat
 from .types import DecryptionKey
 
 logger = logging.getLogger(__name__)
@@ -66,3 +73,89 @@ class AppleMusicInterface:
         logger.debug(f"Decryption key: {decryption_key}")
 
         return decryption_key
+
+    def get_cover_url_template(self, metadata: dict, cover_format: CoverFormat) -> str:
+        if cover_format == CoverFormat.RAW:
+            cover_url_template = self._get_raw_cover_url(
+                metadata["attributes"]["artwork"]["url"]
+            )
+        else:
+            cover_url_template = metadata["attributes"]["artwork"]["url"]
+
+        logger.debug(f"Cover URL template: {cover_url_template}")
+        return cover_url_template
+
+    def _get_raw_cover_url(self, cover_url_template: str) -> str:
+        return re.sub(
+            r"image/thumb/",
+            "",
+            re.sub(
+                r"is1-ssl",
+                "a1",
+                cover_url_template,
+            ),
+        )
+
+    def get_cover_url(
+        self,
+        cover_url_template: str,
+        cover_size: int,
+        cover_format: CoverFormat,
+    ) -> str:
+        cover_url = re.sub(
+            r"/\{w\}x\{h\}([a-z]{2})\.jpg",
+            (
+                f"/{cover_size}x{cover_size}bb.{cover_format.value}"
+                if cover_format != CoverFormat.RAW
+                else ""
+            ),
+            cover_url_template,
+        )
+
+        logger.debug(f"Cover URL: {cover_url}")
+        return cover_url
+
+    @alru_cache()
+    async def get_cover_file_extension(
+        self,
+        cover_url: str,
+        cover_format: CoverFormat,
+    ) -> str | None:
+        if cover_format != CoverFormat.RAW:
+            return f".{cover_format.value}"
+
+        cover_bytes = await self.get_cover_bytes(cover_url)
+        if cover_bytes is None:
+            return None
+
+        image_obj = Image.open(BytesIO(await self.get_cover_bytes(cover_url)))
+        image_format = image_obj.format.lower()
+        return IMAGE_FILE_EXTENSION_MAP.get(
+            image_format,
+            f".{image_format.lower()}",
+        )
+
+    @alru_cache()
+    async def get_cover_bytes(self, cover_url: str) -> bytes | None:
+        response = await get_response(cover_url, {200, 404})
+        if response.status_code == 200:
+            return response.content
+        return None
+
+    @alru_cache()
+    async def get_media_date(
+        self,
+        media_id: str,
+    ) -> datetime.datetime | None:
+        lookup_result = await self.itunes_api.get_lookup_result(media_id)
+        if not lookup_result["results"]:
+            return None
+
+        release_date = lookup_result["results"][0].get("releaseDate")
+        if not release_date:
+            return None
+
+        parsed_date = self.parse_date(release_date)
+        logger.debug(f"Parsed media date: {parsed_date}")
+
+        return parsed_date

gamdl/interface/interface_music_video.py

@@ -7,7 +7,7 @@ from InquirerPy import inquirer
 from InquirerPy.base.control import Choice
 from pywidevine import Cdm
 
-from ..utils import get_response_text
+from ..utils import get_response
 from .constants import MP4_FORMAT_CODECS
 from .enums import MediaRating, MediaType, MusicVideoCodec, MusicVideoResolution
 from .interface import AppleMusicInterface
@@ -139,7 +139,9 @@ class AppleMusicMusicVideoInterface(AppleMusicInterface):
                 webplayback_response["songList"][0],
             )
 
-        playlist_master_m3u8_obj = m3u8.loads(await get_response_text(m3u8_master_url))
+        playlist_master_m3u8_obj = m3u8.loads(
+            (await get_response(m3u8_master_url)).text
+        )
         playlist_master_m3u8_obj.base_uri = m3u8_master_url.rpartition("/")[0]
         stream_info_video = await self.get_stream_info_video(
             playlist_master_m3u8_obj,
@@ -318,7 +320,9 @@ class AppleMusicMusicVideoInterface(AppleMusicInterface):
         stream_info.codec = playlist.stream_info.codecs
         stream_info.width, stream_info.height = playlist.stream_info.resolution
 
-        playlist_m3u8_obj = m3u8.loads(await get_response_text(stream_info.stream_url))
+        playlist_m3u8_obj = m3u8.loads(
+            (await get_response(stream_info.stream_url)).text
+        )
         stream_info.widevine_pssh = self.get_widevine_pssh(playlist_m3u8_obj)
         stream_info.fairplay_key = self.get_fairplay_key(playlist_m3u8_obj)
         stream_info.playready_pssh = self.get_playready_pssh(playlist_m3u8_obj)
@@ -343,7 +347,9 @@ class AppleMusicMusicVideoInterface(AppleMusicInterface):
         stream_info.stream_url = playlist["uri"]
         stream_info.codec = playlist["group_id"]
 
-        playlist_m3u8_obj = m3u8.loads(await get_response_text(stream_info.stream_url))
+        playlist_m3u8_obj = m3u8.loads(
+            (await get_response(stream_info.stream_url)).text
+        )
         stream_info.widevine_pssh = self.get_widevine_pssh(playlist_m3u8_obj)
         stream_info.fairplay_key = self.get_fairplay_key(playlist_m3u8_obj)
         stream_info.playready_pssh = self.get_playready_pssh(playlist_m3u8_obj)

gamdl/interface/interface_song.py

@@ -1,6 +1,7 @@
 import asyncio
 import base64
 import datetime
+import io
 import json
 import logging
 import re
@@ -10,10 +11,11 @@ from xml.etree import ElementTree
 import m3u8
 from InquirerPy import inquirer
 from InquirerPy.base.control import Choice
+from mutagen.mp4 import MP4
 from pywidevine import PSSH, Cdm
 from pywidevine.license_protocol_pb2 import WidevinePsshData
 
-from ..utils import get_response_text
+from ..utils import get_response
 from .constants import DRM_DEFAULT_KEY_MAPPING, MP4_FORMAT_CODECS, SONG_CODEC_REGEX_MAP
 from .enums import MediaRating, MediaType, SongCodec, SyncedLyricsFormat
 from .interface import AppleMusicInterface
@@ -168,10 +170,11 @@ class AppleMusicSongInterface(AppleMusicInterface):
 
         return f"[{timestamp.strftime('%M:%S.%f')[:-4]}]{text}"
 
-    def get_tags(
+    async def get_tags(
         self,
         webplayback: dict,
         lyrics: str | None = None,
+        use_album_date: bool = False,
     ) -> MediaTags:
         webplayback_metadata = webplayback["songList"][0]["assets"][0]["metadata"]
 
@@ -194,9 +197,13 @@ class AppleMusicSongInterface(AppleMusicInterface):
             composer_sort=webplayback_metadata.get("sort-composer"),
             copyright=webplayback_metadata.get("copyright"),
             date=(
-                self.parse_date(webplayback_metadata["releaseDate"])
-                if webplayback_metadata.get("releaseDate")
-                else None
+                await self.get_media_date(webplayback_metadata["playlistId"])
+                if use_album_date
+                else (
+                    self.parse_date(webplayback_metadata["releaseDate"])
+                    if webplayback_metadata.get("releaseDate")
+                    else None
+                )
             ),
             disc=webplayback_metadata["discNumber"],
             disc_total=webplayback_metadata["discCount"],
@@ -223,13 +230,20 @@ class AppleMusicSongInterface(AppleMusicInterface):
         song_metadata: dict,
         codec: SongCodec,
     ) -> StreamInfoAv | None:
+        if "extendedAssetUrls" not in song_metadata["attributes"]:
+            song_metadata = (
+                await self.apple_music_api.get_song(
+                    self.get_media_id_of_library_media(song_metadata),
+                )
+            )["data"][0]
+
         m3u8_master_url = song_metadata["attributes"]["extendedAssetUrls"].get(
             "enhancedHls"
         )
         if not m3u8_master_url:
             return None
 
-        m3u8_master_obj = m3u8.loads(await get_response_text(m3u8_master_url))
+        m3u8_master_obj = m3u8.loads((await get_response(m3u8_master_url)).text)
         m3u8_master_data = m3u8_master_obj.data
 
         if codec == SongCodec.ASK:
@@ -273,7 +287,7 @@ class AppleMusicSongInterface(AppleMusicInterface):
                 "com.apple.streamingkeydelivery",
             )
         else:
-            m3u8_obj = m3u8.loads(await get_response_text(stream_info.stream_url))
+            m3u8_obj = m3u8.loads((await get_response(stream_info.stream_url)).text)
 
             stream_info.widevine_pssh = self._get_drm_uri_from_m3u8_keys(
                 m3u8_obj,
@@ -384,7 +398,7 @@ class AppleMusicSongInterface(AppleMusicInterface):
             i for i in webplayback["songList"][0]["assets"] if i["flavor"] == flavor
         )["URL"]
 
-        m3u8_obj = m3u8.loads(await get_response_text(stream_info.stream_url))
+        m3u8_obj = m3u8.loads((await get_response(stream_info.stream_url)).text)
         stream_info.widevine_pssh = m3u8_obj.keys[0].uri
 
         stream_info_av = StreamInfoAv(
@@ -457,3 +471,19 @@ class AppleMusicSongInterface(AppleMusicInterface):
                 cdm,
             )
         )
+
+    async def get_extra_tags(
+        self,
+        song_metadata: dict,
+    ) -> dict:
+        previews = song_metadata["attributes"].get("previews", [])
+        if not previews:
+            return {}
+
+        preview_url = previews[0]["url"]
+        preview_response = await get_response(preview_url)
+        preview_bytes = preview_response.content
+        preview_tags = dict(MP4(io.BytesIO(preview_bytes)).tags)
+
+        logger.debug(f"Extra tags: {preview_tags.keys()}")
+        return preview_tags

gamdl/utils.py

@@ -1,7 +1,8 @@
-import json
-import typing
-import subprocess
 import asyncio
+import json
+import string
+import subprocess
+import typing
 
 import httpx
 
@@ -13,18 +14,21 @@ def raise_for_status(httpx_response: httpx.Response, valid_responses: set[int] =
         )
 
 
-def safe_json(httpx_response: httpx.Response) -> dict:
+def safe_json(httpx_response: httpx.Response) -> dict | None:
     try:
         return httpx_response.json()
     except (json.JSONDecodeError, UnicodeDecodeError):
-        return {}
+        return None
 
 
-async def get_response_text(url: str) -> str:
-    async with httpx.AsyncClient() as client:
+async def get_response(
+    url: str,
+    valid_responses: set[int] = {200},
+) -> httpx.Response:
+    async with httpx.AsyncClient(timeout=60.0) as client:
         response = await client.get(url)
-        raise_for_status(response)
-        return response.text
+        raise_for_status(response, valid_responses)
+        return response
 
 
 async def async_subprocess(*args: str, silent: bool = False) -> None:
@@ -48,24 +52,50 @@ async def async_subprocess(*args: str, silent: bool = False) -> None:
 
 async def safe_gather(
     *tasks: typing.Awaitable[typing.Any],
-    limit: int = 3,
-    retries: int = 10,
+    limit: int = 10,
 ) -> list[typing.Any]:
     semaphore = asyncio.Semaphore(limit)
 
     async def bounded_task(task: typing.Awaitable[typing.Any]) -> typing.Any:
         async with semaphore:
-            last_exception = None
-            for attempt in range(retries + 1):
-                try:
-                    return await task
-                except Exception as e:
-                    last_exception = e
-                    if attempt < retries:
-                        await asyncio.sleep(2**attempt)
-            return last_exception
+            return await task
 
     return await asyncio.gather(
         *(bounded_task(task) for task in tasks),
         return_exceptions=True,
     )
+
+
+async def sequential_gather(
+    *tasks: typing.Awaitable[typing.Any],
+    interval: float = 0.5,
+) -> list[typing.Any]:
+    results = []
+    for i, task in enumerate(tasks):
+        try:
+            result = await task
+            results.append(result)
+        except Exception as e:
+            results.append(e)
+        if interval > 0 and i < len(tasks) - 1:
+            await asyncio.sleep(interval)
+    return results
+
+
+class CustomStringFormatter(string.Formatter):
+    def format_field(self, value: typing.Any, format_spec: str) -> str:
+        if isinstance(value, tuple) and len(value) == 2:
+            actual_value, fallback_value = value
+            if actual_value is None:
+                return fallback_value
+
+            try:
+                return super().format_field(actual_value, format_spec)
+            except Exception:
+                return fallback_value
+
+        return super().format_field(value, format_spec)
+
+
+class GamdlError(Exception):
+    pass

pyproject.toml

@@ -1,13 +1,15 @@
 [project]
 name = "gamdl"
-version = "2.8"
+version = "2.9"
 description = "A command-line app for downloading Apple Music songs, music videos and post videos."
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
 requires-python = ">=3.10"
 dependencies = [
     "async-lru>=2.0.5",
     "click>=8.3.0",
+    "colorama>=0.4.6",
+    "dataclass-click>=1.0.4",
     "httpx>=0.28.1",
     "inquirerpy>=0.3.4",
     "m3u8>=6.0.0",

uv.lock

@@ -188,6 +188,18 @@ version = "2.8.8"
 source = { registry = "https://pypi.org/simple" }
 sdist = { url = "https://files.pythonhosted.org/packages/b6/2c/66bab4fef920ef8caa3e180ea601475b2cbbe196255b18f1c58215940607/construct-2.8.8.tar.gz", hash = "sha256:1b84b8147f6fd15bcf64b737c3e8ac5100811ad80c830cb4b2545140511c4157", size = 717694, upload-time = "2016-10-20T22:29:12.563Z" }
 
+[[package]]
+name = "dataclass-click"
+version = "1.0.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/89/82/5b6035efd90621771fa039960eab3e1ec7ff2a8625033272856843e8bd27/dataclass_click-1.0.4.tar.gz", hash = "sha256:10e7de638dd9e68ae9abd5086f61d8ddee42b1873a70f5fd9fd2167856afac11", size = 7580, upload-time = "2025-10-10T21:11:31.956Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/86/dc/38a94a2eb5f756724a6dc87a7aea38f7b747fe7b2e9daabc34a65e6cd9ac/dataclass_click-1.0.4-py3-none-any.whl", hash = "sha256:a225d30c04e4abbdba411cc3d5ec0a2ea829e1dca6500afe5f87cc243e5ead72", size = 8553, upload-time = "2025-10-10T21:11:30.514Z" },
+]
+
 [[package]]
 name = "exceptiongroup"
 version = "1.3.0"
@@ -202,11 +214,13 @@ wheels = [
 
 [[package]]
 name = "gamdl"
-version = "2.7"
+version = "2.9"
 source = { virtual = "." }
 dependencies = [
     { name = "async-lru" },
     { name = "click" },
+    { name = "colorama" },
+    { name = "dataclass-click" },
     { name = "httpx" },
     { name = "inquirerpy" },
     { name = "m3u8" },
@@ -220,6 +234,8 @@ dependencies = [
 requires-dist = [
     { name = "async-lru", specifier = ">=2.0.5" },
     { name = "click", specifier = ">=8.3.0" },
+    { name = "colorama", specifier = ">=0.4.6" },
+    { name = "dataclass-click", specifier = ">=1.0.4" },
     { name = "httpx", specifier = ">=0.28.1" },
     { name = "inquirerpy", specifier = ">=0.3.4" },
     { name = "m3u8", specifier = ">=6.0.0" },