🔖 Bump version to 3.4.2

* prepare dolby atmos config

* add audio mode filter logic

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -14,6 +14,7 @@ body:
     attributes:
       label: What command was used?
       placeholder: tiddl
+      render: shell
       
   - type: textarea
     id: what-happened
@@ -31,6 +32,7 @@ body:
       options:
         - 3.13
         - 3.14
+        - 3.15
       default: 0
     validations:
       required: true

README.md

@@ -24,6 +24,12 @@ We recommend using [uv](https://docs.astral.sh/uv/)
 uv tool install tiddl
 ```
 
+To install exact version e.g. 3.4.1
+
+```bash
+uv tool install tiddl==3.4.1
+```
+
 ## pip
 
 You can also use [pip](https://packaging.python.org/en/latest/tutorials/installing-packages/)
@@ -81,18 +87,6 @@ $ tiddl download url <url>
 
 Run `tiddl download` to see available download options.
 
-### Error Handling
-
-By default, tiddl stops when encountering unavailable items in collections such as playlists, albums, artists, or mixes (e.g., removed or region-locked tracks).
-
-Use `--skip-errors` to automatically skip these items and continue downloading:
-
-```bash
-tiddl download url <url> --skip-errors
-```
-
-Skipped items are logged with track/album name and IDs for reference.
-
 ### Quality
 
 | Quality | File extension |        Details        |

docs/config.example.toml

@@ -91,6 +91,13 @@ write_lrc_file = false
 # downloads will continue under "FooBar".
 match_existing_path_case = false
 
+# Dolby Atmos filter
+# none - download only STEREO tracks
+# only - download only DOLBY_ATMOS tracks
+# allow - download both
+# (both versions won't be downloaded at a time, it depends on what Tidal returns)
+atmos_filter = "none"
+
 
 [metadata]
 # embed metadata in files
@@ -137,7 +144,7 @@ allowed = [
 # album = "albums/{album.artist} - {album.title}"
 
 # you can access: {playlist}
-# playlist = "playlists/{title}"
+# playlist = "playlists/{playlist.title}"
 
 
 [m3u]

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tiddl"
-version = "3.4.0a6"
+version = "3.4.2"
 description = "Download Tidal tracks with CLI downloader."
 readme = "README.md"
 requires-python = ">=3.13"

tests/cli/commands/auth/test_auth.py

@@ -124,28 +124,73 @@ def test_logout_with_token(monkeypatch: pytest.MonkeyPatch):
         mock_api_instance.logout_token.assert_called_once_with("token")
         mock_save.assert_called_once_with(AuthData())
 
-        assert "Logged out!" in result.stdout
+        assert "Logged out successfully!\n" in result.stdout
         assert result.exit_code == 0
 
 
 def test_logout_no_token(monkeypatch: pytest.MonkeyPatch):
-    """Should only clear auth data."""
+    """Should do nothing."""
 
     monkeypatch.setattr(
         "tiddl.cli.commands.auth.load_auth_data", lambda: AuthData(token=None)
     )
 
+    with (patch("tiddl.cli.commands.auth.AuthAPI") as MockAuthAPI,):
+        result = runner.invoke(auth_command, ["logout"])
+
+        MockAuthAPI.assert_not_called()
+
+        assert "No active session found." in result.stdout
+        assert result.exit_code == 0
+
+
+def test_logout_force(monkeypatch: pytest.MonkeyPatch):
+    """Should remove local token even when the API request raises an error."""
+
+    # 1. Mock existing session
+    monkeypatch.setattr(
+        "tiddl.cli.commands.auth.load_auth_data", lambda: AuthData(token="fake-token")
+    )
+
     with (
         patch("tiddl.cli.commands.auth.AuthAPI") as MockAuthAPI,
         patch("tiddl.cli.commands.auth.save_auth_data") as mock_save,
     ):
+        # 2. Configure the mock to RAISE an exception
+        mock_api_instance = MockAuthAPI.return_value
+        mock_api_instance.logout_token.side_effect = Exception("Server Down")
+
+        # 3. Invoke with --force
+        result = runner.invoke(auth_command, ["logout", "--force"])
+
+        # 4. Assertions
+        # API was still called
+        mock_api_instance.logout_token.assert_called_once_with("fake-token")
+
+        # Local data was still wiped (this is the core of --force)
+        mock_save.assert_called_once_with(AuthData())
+
+        # Check for your specific "force" success message
+        assert "Token removed!" in result.stdout
+        assert result.exit_code == 0
+
+
+def test_logout_fails_without_force(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setattr(
+        "tiddl.cli.commands.auth.load_auth_data", lambda: AuthData(token="token")
+    )
+
+    with (
+        patch("tiddl.cli.commands.auth.AuthAPI") as MockAuthAPI,
+        patch("tiddl.cli.commands.auth.save_auth_data") as mock_save,
+    ):
+
+        MockAuthAPI.return_value.logout_token.side_effect = Exception("Error")
+
         result = runner.invoke(auth_command, ["logout"])
 
-        mock_save.assert_called_once_with(AuthData())
-        MockAuthAPI.assert_not_called()
-
-        assert "Logged out!" in result.stdout
-        assert result.exit_code == 0
+        assert "Local session retained" in result.stdout
+        mock_save.assert_not_called()  # Ensure data wasn't wiped
 
 
 def test_refresh_not_logged_in(monkeypatch: pytest.MonkeyPatch):

tiddl/cli/app.py

@@ -13,7 +13,7 @@ log = logging.getLogger("tiddl")
 app = typer.Typer(name="tiddl", no_args_is_help=True, rich_markup_mode="rich")
 register_commands(app)
 
-VERSION = "v3.4.0a6"
+VERSION = "v3.4.2"
 
 
 @app.callback()

tiddl/cli/commands/auth.py

@@ -38,7 +38,7 @@ def login(
 
     if not NO_BROWSER:
         typer.launch(uri)
-    
+
     console.print(f"Go to '{uri}' and complete authentication!")
 
     auth_end_at = time() + device_auth.expiresIn
@@ -97,17 +97,23 @@ def logout(
         return
 
     try:
-        AuthAPI().logout_token(auth_data.token)
+        api = AuthAPI()
+        api.logout_token(auth_data.token)
         success = True
     except Exception as error:
         console.print(f"[bold red]Logout request failed: {error}")
         success = False
 
-    if success or force:
-        save_auth_data(AuthData())
-        console.print("[bold green]Logged out successfully!")
-    else:
+    if not (success or force):
         console.print("[bold yellow]Local session retained. Use --force to override.")
+        return
+
+    save_auth_data(AuthData())
+
+    if success:
+        console.print("[bold green]Logged out successfully!")
+    elif force:
+        console.print("[bold green]Token removed!")
 
 
 @auth_command.command(help="Refreshes your token in app.")

tiddl/cli/commands/download/__init__.py

@@ -20,6 +20,7 @@ from tiddl.cli.config import (
     ARTIST_SINGLES_FILTER_LITERAL,
     VALID_M3U_RESOURCE_LITERAL,
     VIDEOS_FILTER_LITERAL,
+    ATMOS_FILTER_LITERAL,
 )
 from tiddl.cli.utils.resource import TidalResource
 from tiddl.cli.ctx import Context
@@ -126,6 +127,14 @@ def download_callback(
             help="Raise an error on resource download failure. Use for debugging",
         ),
     ] = False,
+    DOLBY_ATMOS_FILTER: Annotated[
+        ATMOS_FILTER_LITERAL,
+        typer.Option(
+            "--dolby-atmos",
+            "-da",
+            help="Dolby Atmos filter, 'none' to exclude, 'allow' to include, 'only' to download only Dolby Atmos, if available.",
+        ),
+    ] = CONFIG.download.atmos_filter,
 ):
     """
     Download Tidal resources.
@@ -145,7 +154,9 @@ def download_callback(
             with open(lrc_file_path, "w", encoding="utf-8") as f:
                 f.write(lyrics)
         except Exception as e:
-            log.error(f"Failed to write LRC file for track {track.title} (ID: {track.id}): {e}")
+            log.error(
+                f"Failed to write LRC file for track {track.title} (ID: {track.id}): {e}"
+            )
 
     def save_m3u(
         resource_type: VALID_M3U_RESOURCE_LITERAL,
@@ -206,6 +217,7 @@ def download_callback(
             download_path=DOWNLOAD_PATH,
             scan_path=SCAN_PATH,
             match_existing_path_case=CONFIG.download.match_existing_path_case,
+            dolby_atmos_filter=DOLBY_ATMOS_FILTER,
         )
 
         class Metadata:
@@ -346,7 +358,9 @@ def download_callback(
                                     track_metadata=Metadata(
                                         cover=cover,
                                         date=str(album.releaseDate),
-                                        artist=album.artist.name if album.artist else "",
+                                        artist=(
+                                            album.artist.name if album.artist else ""
+                                        ),
                                         credits=album_item.credits,
                                         album_review=album_review,
                                     ),
@@ -355,9 +369,11 @@ def download_callback(
                         except ApiError as e:
                             item = album_item.item
                             track_info = f"Track: {getattr(item, 'title', 'Unknown')} (ID: {item.id})"
-                            if hasattr(item, 'album') and item.album:
+                            if hasattr(item, "album") and item.album:
                                 track_info += f", Album ID: {item.album.id}"
-                            ctx.obj.console.print(f"[red]API Error:[/] {e} ({track_info})")
+                            ctx.obj.console.print(
+                                f"[red]API Error:[/] {e} ({track_info})"
+                            )
                             if RAISE_ERRORS:
                                 raise
                         except Exception as e:
@@ -441,7 +457,11 @@ def download_callback(
                     video = ctx.obj.api.get_video(resource.id)
                     template = TEMPLATE or CONFIG.templates.video
 
-                    if "{album" in template and video.album and video.album.id is not None:
+                    if (
+                        "{album" in template
+                        and video.album
+                        and video.album.id is not None
+                    ):
                         album = ctx.obj.api.get_album(video.album.id)
                     else:
                         album = None
@@ -489,13 +509,17 @@ def download_callback(
                             except ApiError as e:
                                 item = mix_item.item
                                 track_info = f"Track: {getattr(item, 'title', 'Unknown')} (ID: {item.id})"
-                                ctx.obj.console.print(f"[red]API Error:[/] {e} ({track_info})")
+                                ctx.obj.console.print(
+                                    f"[red]API Error:[/] {e} ({track_info})"
+                                )
                                 if RAISE_ERRORS:
                                     raise
                             except Exception as e:
                                 item = mix_item.item
                                 track_info = f"Track: {getattr(item, 'title', 'Unknown')} (ID: {item.id})"
-                                ctx.obj.console.print(f"[red]Error:[/] {e} ({track_info})")
+                                ctx.obj.console.print(
+                                    f"[red]Error:[/] {e} ({track_info})"
+                                )
                                 if RAISE_ERRORS:
                                     raise
 
@@ -526,11 +550,15 @@ def download_callback(
                         try:
                             await download_album(album)
                         except ApiError as e:
-                            ctx.obj.console.print(f"[red]API Error:[/] {e} (Album: {album.title}, ID: {album.id})")
+                            ctx.obj.console.print(
+                                f"[red]API Error:[/] {e} (Album: {album.title}, ID: {album.id})"
+                            )
                             if RAISE_ERRORS:
                                 raise
                         except Exception as e:
-                            ctx.obj.console.print(f"[red]Error:[/] {e} (Album: {album.title}, ID: {album.id})")
+                            ctx.obj.console.print(
+                                f"[red]Error:[/] {e} (Album: {album.title}, ID: {album.id})"
+                            )
                             if RAISE_ERRORS:
                                 raise
 
@@ -580,11 +608,15 @@ def download_callback(
                                         )
                                     )
                                 except ApiError as e:
-                                    ctx.obj.console.print(f"[red]API Error:[/] {e} (Video: {video.title}, ID: {video.id})")
+                                    ctx.obj.console.print(
+                                        f"[red]API Error:[/] {e} (Video: {video.title}, ID: {video.id})"
+                                    )
                                     if RAISE_ERRORS:
                                         raise
                                 except Exception as e:
-                                    ctx.obj.console.print(f"[red]Error:[/] {e} (Video: {video.title}, ID: {video.id})")
+                                    ctx.obj.console.print(
+                                        f"[red]Error:[/] {e} (Video: {video.title}, ID: {video.id})"
+                                    )
                                     if RAISE_ERRORS:
                                         raise
 
@@ -637,7 +669,9 @@ def download_callback(
                                             album=album,
                                             playlist=playlist,
                                             playlist_index=playlist_index,
-                                            quality=get_item_quality(playlist_item.item),
+                                            quality=get_item_quality(
+                                                playlist_item.item
+                                            ),
                                         ),
                                         track_metadata=Metadata(),
                                     )
@@ -645,15 +679,19 @@ def download_callback(
                             except ApiError as e:
                                 item = playlist_item.item
                                 track_info = f"Track: {getattr(item, 'title', 'Unknown')} (ID: {item.id})"
-                                if hasattr(item, 'album') and item.album:
+                                if hasattr(item, "album") and item.album:
                                     track_info += f", Album ID: {item.album.id}"
-                                ctx.obj.console.print(f"[red]API Error:[/] {e} ({track_info})")
+                                ctx.obj.console.print(
+                                    f"[red]API Error:[/] {e} ({track_info})"
+                                )
                                 if RAISE_ERRORS:
                                     raise
                             except Exception as e:
                                 item = playlist_item.item
                                 track_info = f"Track: {getattr(item, 'title', 'Unknown')} (ID: {item.id})"
-                                ctx.obj.console.print(f"[red]Error:[/] {e} ({track_info})")
+                                ctx.obj.console.print(
+                                    f"[red]Error:[/] {e} ({track_info})"
+                                )
                                 if RAISE_ERRORS:
                                     raise
 
@@ -679,7 +717,7 @@ def download_callback(
                         and playlist.squareImage
                     ):
                         Cover(
-                            playlist.squareImage, size=max(CONFIG.cover.size, 1080)
+                            playlist.squareImage, size=min(CONFIG.cover.size, 1080)
                         ).save_to_directory(
                             path=DOWNLOAD_PATH
                             / format_template(

tiddl/cli/commands/download/downloader.py

@@ -7,7 +7,7 @@ from tempfile import NamedTemporaryFile
 import aiofiles
 import aiohttp
 
-from tiddl.cli.config import VIDEOS_FILTER_LITERAL
+from tiddl.cli.config import VIDEOS_FILTER_LITERAL, ATMOS_FILTER_LITERAL
 from tiddl.cli.utils.download import get_existing_track_filename
 from tiddl.cli.utils.path import resolve_existing_path_case
 from tiddl.core.api import ApiError, TidalAPI
@@ -52,6 +52,7 @@ class Downloader:
     download_path: Path
     scan_path: Path
     match_existing_path_case: bool
+    dolby_atmos_filter: ATMOS_FILTER_LITERAL
 
     def __init__(
         self,
@@ -65,6 +66,7 @@ class Downloader:
         download_path: Path,
         scan_path: Path,
         match_existing_path_case: bool = False,
+        dolby_atmos_filter: ATMOS_FILTER_LITERAL = "none",
     ) -> None:
         self.api = tidal_api
         self.rich_output = rich_output
@@ -76,6 +78,7 @@ class Downloader:
         self.download_path = download_path
         self.scan_path = scan_path
         self.match_existing_path_case = match_existing_path_case
+        self.dolby_atmos_filter = dolby_atmos_filter
 
     def get_path(self, base_path: Path, relative_path: Path) -> Path:
         if self.match_existing_path_case:
@@ -144,7 +147,23 @@ class Downloader:
                     stream = self.api.get_track_stream(
                         track_id=item.id, quality=self.track_quality
                     )
-                    log.debug(f"{stream.trackId=}, {stream.audioQuality}, {stream.audioMode}")
+
+                    log.debug(
+                        f"{stream.trackId=}, {stream.audioQuality=}, {stream.audioMode=}"
+                    )
+
+                    if (
+                        self.dolby_atmos_filter == "none"
+                        and stream.audioMode == "DOLBY_ATMOS"
+                    ) or (
+                        self.dolby_atmos_filter == "only"
+                        and stream.audioMode == "STEREO"
+                    ):
+                        self.rich_output.console.print(
+                            f"[blue]Skipping[/] [gray]{item.title}[/] [blue]due to Dolby Atmos filter[/] {self.dolby_atmos_filter}"
+                        )
+                        return None, False
+
                 except ApiError as e:
                     log.error(f"{item.id=} {e=}")
                     self.rich_output.console.print(
@@ -155,27 +174,33 @@ class Downloader:
                 urls, _ = parse_track_stream(stream)
                 download_path = self.get_path(self.download_path, filename)
 
-                quality = track_qualities_color[stream.audioQuality]
+                quality_string = track_qualities_color[stream.audioQuality]
 
-                if stream.audioQuality in ["HI_RES_LOSSLESS", "LOSSLESS"]:
-                    quality = f"{quality} {stream.bitDepth}-bit, {(stream.sampleRate or 0) / 1000:.1f} kHz"
+                if (
+                    stream.audioQuality in ["HI_RES_LOSSLESS", "LOSSLESS"]
+                    and stream.audioMode == "STEREO"
+                ):
+                    quality_string = f"{quality_string} {stream.bitDepth}-bit, {(stream.sampleRate or 0) / 1000:.1f} kHz"
                     should_extract_flac = True
                 else:
                     download_path = download_path.with_suffix(".m4a")
 
+                    if stream.audioMode == "DOLBY_ATMOS":
+                        quality_string = "[blue]Dolby Atmos[/]"
+
             elif isinstance(item, Video):
                 stream = self.api.get_video_stream(
                     video_id=item.id, quality=self.video_quality
                 )
 
                 urls, ext = parse_video_stream(stream), ".ts"
-                download_path = self.get_path(
-                    self.download_path, filename
-                ).with_suffix(ext)
-                quality = video_qualities_color[stream.videoQuality]
+                download_path = self.get_path(self.download_path, filename).with_suffix(
+                    ext
+                )
+                quality_string = video_qualities_color[stream.videoQuality]
 
             task_id = self.rich_output.download_start(
-                f"[{vibrant_color}]{item.title} {quality}"
+                f"[{vibrant_color}]{item.title} {quality_string}"
             )
 
             download_path.parent.mkdir(exist_ok=True, parents=True)

tiddl/cli/commands/subcommands/search.py

@@ -4,12 +4,11 @@ from typing_extensions import Annotated
 from tiddl.cli.ctx import Context
 from tiddl.cli.utils.resource import TidalResource
 from tiddl.core.api.models.base import Search, SearchArtist
-from tiddl.core.api.models.resources import Track, Album, Playlist
+from tiddl.core.api.models.resources import Track, Album, Playlist, Video
 
 from rich.panel import Panel
 from rich.table import Table
 
-
 search_subcommand = typer.Typer()
 
 
@@ -120,15 +119,16 @@ def search(
 
 
 def _display_name(item) -> str:
-    # if searchArtist, else if track/album, else playlist
     if isinstance(item, SearchArtist):
         return item.name
+    elif isinstance(item, Video):
+        return f"{item.artist or item.artists[0].name or ""} - {item.title}"
     elif isinstance(item, (Track, Album)):
-        # Try to format as "Main Artist - Title"
-        main_artist = item.artists[0] if item.artists else None
-        return f"{main_artist.name} - {item.title}" if main_artist else f"{item.title}"
-    else:  # Playlist
+        return f"{item.artist or item.artists[0].name or ""} - {item.title} [blue][{', '.join(item.audioModes)}][/]"
+    elif isinstance(item, (Playlist)):
         return item.title
+    else:
+        raise ValueError("Unknown item type")
 
 
 def _display_id(item) -> str:

tiddl/cli/config.py

@@ -14,6 +14,7 @@ ARTIST_SINGLES_FILTER_LITERAL = Literal["none", "only", "include"]
 VALID_M3U_RESOURCE_LITERAL = Literal["album", "playlist", "mix"]
 VALID_RESOURCE_COVER_SAVE_LITERAL = Literal["track", "album", "playlist"]
 VIDEOS_FILTER_LITERAL = Literal["none", "only", "allow"]
+ATMOS_FILTER_LITERAL = Literal["none", "only", "allow"]
 
 log = getLogger(__name__)
 
@@ -57,6 +58,7 @@ class Config(BaseModel):
         rewrite_metadata: bool = False
         write_lrc_file: bool = False
         match_existing_path_case: bool = False
+        atmos_filter: ATMOS_FILTER_LITERAL = "none"
 
         def model_post_init(self, __context):
             # set scan path to download path when download path is non default

tiddl/core/api/models/resources.py

@@ -125,7 +125,7 @@ class Album(BaseModel):
     numberOfTracks: int
     numberOfVideos: int
     numberOfVolumes: int
-    releaseDate: datetime | str | None
+    releaseDate: datetime | None = None
     copyright: Optional[str] = None
     type: Literal["ALBUM", "SINGLE", "EP"]
     version: Optional[str] = None

tiddl/core/auth/models.py

@@ -23,7 +23,7 @@ class AuthResponse(BaseModel):
         acceptedEULA: bool
         created: int | str
         updated: int | str
-        facebookUid: int
+        facebookUid: Optional[int] = None
         appleUid: Optional[str]
         googleUid: Optional[str]
         accountLinkCreated: bool

tiddl/core/metadata/cover.py

@@ -50,6 +50,10 @@ class Cover:
         if not self.data:
             self.data = self.fetch_data()
 
+            if not self.data:
+                log.debug(f"cover data is empty ({file})")
+                return
+
         file.parent.mkdir(parents=True, exist_ok=True)
 
         try:

tiddl/core/utils/ffmpeg.py

@@ -8,7 +8,14 @@ class FFmpegError(RuntimeError):
 
 def run(cmd: list[str]) -> subprocess.CompletedProcess:
     """Run a process; raise `FFmpegError` on non-zero exit with stderr."""
-    r = subprocess.run(cmd, capture_output=True, text=True)
+    # Force UTF-8 encoding to prevent UnicodeDecodeError on Windows
+    r = subprocess.run(
+        cmd, 
+        capture_output=True, 
+        text=True, 
+        encoding="utf-8", 
+        errors="replace"  # Added as a safety net
+    )
     if r.returncode != 0:
         raise FFmpegError(
             f"{cmd[0]} failed (rc={r.returncode}): {r.stderr.strip()}"

tiddl/core/utils/format.py

@@ -165,7 +165,7 @@ def generate_template_data(
             artists=", ".join(
                 a.name for a in (album.artists or []) if a.type == "MAIN"
             ),
-            date=album.releaseDate,
+            date=album.releaseDate or datetime.min,
             explicit=Explicit(getattr(album, "explicit", None)),
             master=UserFormat(
                 "HIRES_LOSSLESS" in album.mediaMetadata.tags and quality == "MAX"