ytm-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{ytm_cli-0.7.0 → ytm_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ytm-cli
-Version: 0.7.0
+Version: 0.7.2
 Summary: YouTube Music CLI tool with interactive terminal interface
 Author-email: thieuluan <thieuluan.dark@gmail.com>
 License-Expression: MIT
@@ -11,7 +11,8 @@ Keywords: youtube-music,cli,terminal,music-player,mpv
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: End Users/Desktop
-Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Multimedia :: Sound/Audio :: Players
@@ -32,9 +33,16 @@ Dynamic: license-file
 
 Stream music directly from YouTube Music in your terminal with intuitive controls, playlist management, and smart filtering.
 
-![YTM CLI Player](image.png)
+<p align="center">
+  <a href="https://github.com/thieuluan1618/ytm/raw/main/screenshots/player.webm">
+    <img src="screenshots/player.gif" alt="ytm-cli player demo" width="800">
+  </a>
+</p>
 
-![YTM CLI Lyrics](image-lyric.png)
+<p align="center">
+  <em>Player UI with the real-time FFT spectrum visualizer (synthetic demo capture).
+  Click for the higher-quality .webm.</em>
+</p>
 
 ## ✨ Features
 
@@ -45,25 +53,24 @@ Stream music directly from YouTube Music in your terminal with intuitive control
 - **👎 Smart Filtering**: Dislike songs to filter them from future results
 - **📜 Synced Lyrics**: Live-highlighted lyrics with auto-scroll (press `l`)
 - **🎯 Radio Mode**: Automatic playlist generation based on your selection
+- **📊 Real-time Spectrum Visualizer**: 24-band FFT bars driven by an `ffmpeg` sidecar — bass left, treble right (stereo oscilloscope fallback when `ffmpeg` is unavailable)
 - **🤖 AI-Powered**: Natural language music requests and AI-generated playlists
 
 ## 🚀 Quick Start
 
 ### Requirements
 
-- Python 3.8+
+- Python **3.14+** (set in `pyproject.toml`)
 - [mpv media player](https://mpv.io/installation/) (must be installed system-wide)
+- [`ffmpeg`](https://ffmpeg.org/) on `PATH` for the real-time spectrum visualizer (optional — falls back to a stereo oscilloscope if missing)
 
 ### Installation
 
 **One command with [uv](https://docs.astral.sh/uv/) (recommended):**
 
 ```bash
-# Install from PyPI
+# Install from PyPI — gets latest version automatically
 uvx ytm-cli "song name"
-
-# Or from source (no clone needed)
-uvx --from git+https://github.com/thieuluan1618/ytm.git ytm-cli "song name"
 ```
 
 <details>
@@ -78,36 +85,16 @@ uv run ytm-cli "song name"
 </details>
 
 <details>
-<summary>Alternative: one-shot setup scripts</summary>
+<summary>Alternative: one-shot setup script (Linux / macOS)</summary>
 
 ```bash
 git clone https://github.com/thieuluan1618/ytm.git
 cd ytm
-```
-
-These create the virtual environment, install dependencies, and configure the `ytm` command globally.
-
-**Linux/macOS:**
-
-```bash
 ./setup.sh
-source ~/.zshrc  # or ~/.bashrc for bash
+source ~/.zshrc            # or ~/.bashrc for bash
 ```
 
-**Windows PowerShell:**
-
-```powershell
-.\setup.ps1
-. $PROFILE
-```
-
-**Windows Command Prompt:**
-
-```cmd
-setup.bat
-```
-
-After setup, use `ytm` (alias for `ytm-cli`) from anywhere.
+This creates the venv, installs runtime deps from `pyproject.toml`, and adds a `ytm` shell alias.
 
 </details>
 
@@ -117,14 +104,15 @@ After setup, use `ytm` (alias for `ytm-cli`) from anywhere.
 ```bash
 git clone https://github.com/thieuluan1618/ytm.git
 cd ytm
-python -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-pip install -r requirements.txt
-./setup_alias.sh          # or setup_alias.ps1 / setup_alias.bat
+uv sync                   # installs runtime deps from pyproject.toml + uv.lock
+./setup_alias.sh          # optional: registers the `ytm` alias
+# Run with: uv run ytm-cli "song"
 ```
 
 </details>
 
+> **Windows users:** native Windows is not supported (the codebase uses POSIX-only `termios`/`tty`/`fcntl`). Use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the Linux instructions above.
+
 ### Basic Usage
 
 **Interactive search:**
@@ -143,9 +131,10 @@ ytm-cli "your favorite song"
 **Non-interactive mode (automation/scripting):**
 
 ```bash
-ytm-cli search "song name" --select 1           # Auto-select first result
-ytm-cli search "song" -s 1 -v                   # With verbose output
-ytm-cli search "song" -s 1 -v --log-file debug.log  # Save debug logs
+ytm-cli search "song name" --select 1                     # Auto-select first result
+ytm-cli search "song" -s 1 --verbose                      # With verbose output
+ytm-cli search "song" -s 1 --verbose --log-file debug.log # Save debug logs
+ytm-cli -v                                                # Print version
 ```
 
 > **Tip:** Set up the shell alias to use `ytm` as a shortcut for `ytm-cli`. See the setup scripts above.
@@ -252,7 +241,7 @@ Having issues? Check out the [**Troubleshooting Guide**](TROUBLESHOOTING.md) for
 
 ```bash
 # Enable verbose logging to see what's happening
-ytm-cli search "test" -s 1 -v --log-file debug.log
+ytm-cli search "test" -s 1 --verbose --log-file debug.log
 
 # Check versions
 mpv --version

{ytm_cli-0.7.0 → ytm_cli-0.7.2}/README.md

@@ -4,9 +4,16 @@
 
 Stream music directly from YouTube Music in your terminal with intuitive controls, playlist management, and smart filtering.
 
-![YTM CLI Player](image.png)
+<p align="center">
+  <a href="https://github.com/thieuluan1618/ytm/raw/main/screenshots/player.webm">
+    <img src="screenshots/player.gif" alt="ytm-cli player demo" width="800">
+  </a>
+</p>
 
-![YTM CLI Lyrics](image-lyric.png)
+<p align="center">
+  <em>Player UI with the real-time FFT spectrum visualizer (synthetic demo capture).
+  Click for the higher-quality .webm.</em>
+</p>
 
 ## ✨ Features
 
@@ -17,25 +24,24 @@ Stream music directly from YouTube Music in your terminal with intuitive control
 - **👎 Smart Filtering**: Dislike songs to filter them from future results
 - **📜 Synced Lyrics**: Live-highlighted lyrics with auto-scroll (press `l`)
 - **🎯 Radio Mode**: Automatic playlist generation based on your selection
+- **📊 Real-time Spectrum Visualizer**: 24-band FFT bars driven by an `ffmpeg` sidecar — bass left, treble right (stereo oscilloscope fallback when `ffmpeg` is unavailable)
 - **🤖 AI-Powered**: Natural language music requests and AI-generated playlists
 
 ## 🚀 Quick Start
 
 ### Requirements
 
-- Python 3.8+
+- Python **3.14+** (set in `pyproject.toml`)
 - [mpv media player](https://mpv.io/installation/) (must be installed system-wide)
+- [`ffmpeg`](https://ffmpeg.org/) on `PATH` for the real-time spectrum visualizer (optional — falls back to a stereo oscilloscope if missing)
 
 ### Installation
 
 **One command with [uv](https://docs.astral.sh/uv/) (recommended):**
 
 ```bash
-# Install from PyPI
+# Install from PyPI — gets latest version automatically
 uvx ytm-cli "song name"
-
-# Or from source (no clone needed)
-uvx --from git+https://github.com/thieuluan1618/ytm.git ytm-cli "song name"
 ```
 
 <details>
@@ -50,36 +56,16 @@ uv run ytm-cli "song name"
 </details>
 
 <details>
-<summary>Alternative: one-shot setup scripts</summary>
+<summary>Alternative: one-shot setup script (Linux / macOS)</summary>
 
 ```bash
 git clone https://github.com/thieuluan1618/ytm.git
 cd ytm
-```
-
-These create the virtual environment, install dependencies, and configure the `ytm` command globally.
-
-**Linux/macOS:**
-
-```bash
 ./setup.sh
-source ~/.zshrc  # or ~/.bashrc for bash
+source ~/.zshrc            # or ~/.bashrc for bash
 ```
 
-**Windows PowerShell:**
-
-```powershell
-.\setup.ps1
-. $PROFILE
-```
-
-**Windows Command Prompt:**
-
-```cmd
-setup.bat
-```
-
-After setup, use `ytm` (alias for `ytm-cli`) from anywhere.
+This creates the venv, installs runtime deps from `pyproject.toml`, and adds a `ytm` shell alias.
 
 </details>
 
@@ -89,14 +75,15 @@ After setup, use `ytm` (alias for `ytm-cli`) from anywhere.
 ```bash
 git clone https://github.com/thieuluan1618/ytm.git
 cd ytm
-python -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-pip install -r requirements.txt
-./setup_alias.sh          # or setup_alias.ps1 / setup_alias.bat
+uv sync                   # installs runtime deps from pyproject.toml + uv.lock
+./setup_alias.sh          # optional: registers the `ytm` alias
+# Run with: uv run ytm-cli "song"
 ```
 
 </details>
 
+> **Windows users:** native Windows is not supported (the codebase uses POSIX-only `termios`/`tty`/`fcntl`). Use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) and follow the Linux instructions above.
+
 ### Basic Usage
 
 **Interactive search:**
@@ -115,9 +102,10 @@ ytm-cli "your favorite song"
 **Non-interactive mode (automation/scripting):**
 
 ```bash
-ytm-cli search "song name" --select 1           # Auto-select first result
-ytm-cli search "song" -s 1 -v                   # With verbose output
-ytm-cli search "song" -s 1 -v --log-file debug.log  # Save debug logs
+ytm-cli search "song name" --select 1                     # Auto-select first result
+ytm-cli search "song" -s 1 --verbose                      # With verbose output
+ytm-cli search "song" -s 1 --verbose --log-file debug.log # Save debug logs
+ytm-cli -v                                                # Print version
 ```
 
 > **Tip:** Set up the shell alias to use `ytm` as a shortcut for `ytm-cli`. See the setup scripts above.
@@ -224,7 +212,7 @@ Having issues? Check out the [**Troubleshooting Guide**](TROUBLESHOOTING.md) for
 
 ```bash
 # Enable verbose logging to see what's happening
-ytm-cli search "test" -s 1 -v --log-file debug.log
+ytm-cli search "test" -s 1 --verbose --log-file debug.log
 
 # Check versions
 mpv --version

{ytm_cli-0.7.0 → ytm_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ytm-cli"
-version = "0.7.0"
+version = "0.7.2"
 description = "YouTube Music CLI tool with interactive terminal interface"
 readme = "README.md"
 license = "MIT"
@@ -17,7 +17,8 @@ classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: End Users/Desktop",
-    "Operating System :: OS Independent",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.14",
     "Topic :: Multimedia :: Sound/Audio :: Players",
@@ -31,6 +32,16 @@ dependencies = [
     "numpy",
 ]
 
+[dependency-groups]
+dev = [
+    "ruff>=0.14.0",
+    "pytest>=9.0.3",
+    "pytest-cov>=6.0.0",
+    "pytest-mock>=3.15.0",
+    "coverage>=7.0.0",
+    "yt-dlp>=2024.0.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/thieuluan1618/ytm"
 Repository = "https://github.com/thieuluan1618/ytm"

ytm_cli-0.7.2/tests/test_cache.py

@@ -0,0 +1,111 @@
+"""Tests for ytm_cli.cache."""
+
+import json
+import time
+from unittest.mock import patch
+
+import pytest
+
+from ytm_cli import cache as cache_module
+
+
+@pytest.fixture
+def temp_cache_file(tmp_path, monkeypatch):
+    """Redirect CACHE_FILE to an isolated temp path for each test."""
+    path = tmp_path / "ytm_cache.json"
+    monkeypatch.setattr(cache_module, "CACHE_FILE", str(path))
+    return path
+
+
+class TestLoadSaveCache:
+    def test_load_cache_returns_empty_dict_when_missing(self, temp_cache_file):
+        assert cache_module.load_cache() == {}
+
+    def test_load_cache_returns_empty_dict_on_invalid_json(self, temp_cache_file):
+        temp_cache_file.write_text("not json {{{")
+        assert cache_module.load_cache() == {}
+
+    def test_save_cache_then_load_round_trip(self, temp_cache_file):
+        payload = {"k": {"data": "v", "timestamp": 1234.0}}
+        cache_module.save_cache(payload)
+        assert json.loads(temp_cache_file.read_text()) == payload
+        assert cache_module.load_cache() == payload
+
+
+class TestGetSetCached:
+    def test_get_cached_missing_key_returns_none(self, temp_cache_file):
+        assert cache_module.get_cached("nope") is None
+
+    def test_set_then_get_returns_value(self, temp_cache_file):
+        cache_module.set_cached("query1", "result1")
+        assert cache_module.get_cached("query1") == "result1"
+
+    def test_get_cached_expired_entry_removed_and_returns_none(self, temp_cache_file):
+        # Write an entry with timestamp older than the TTL.
+        old_ts = time.time() - cache_module.CACHE_TTL - 100
+        cache_module.save_cache({"old": {"data": "stale", "timestamp": old_ts}})
+
+        assert cache_module.get_cached("old") is None
+        # Expired entry should be evicted from disk on read.
+        assert "old" not in cache_module.load_cache()
+
+    def test_set_cached_overwrites_existing(self, temp_cache_file):
+        cache_module.set_cached("k", "v1")
+        cache_module.set_cached("k", "v2")
+        assert cache_module.get_cached("k") == "v2"
+
+
+class TestClearExpired:
+    def test_clear_expired_removes_only_old_entries(self, temp_cache_file):
+        now = time.time()
+        cache_module.save_cache(
+            {
+                "fresh": {"data": "a", "timestamp": now},
+                "stale": {"data": "b", "timestamp": now - cache_module.CACHE_TTL - 10},
+            }
+        )
+
+        cache_module.clear_expired()
+
+        remaining = cache_module.load_cache()
+        assert "fresh" in remaining
+        assert "stale" not in remaining
+
+    def test_clear_expired_on_empty_cache_is_noop(self, temp_cache_file):
+        cache_module.clear_expired()
+        assert cache_module.load_cache() == {}
+
+
+class TestSearchWithCache:
+    def test_search_with_cache_calls_search_func_on_miss(self, temp_cache_file):
+        search_func = lambda q: [{"title": q}]  # noqa: E731
+
+        result = cache_module.search_with_cache("song", search_func)
+
+        assert result == [{"title": "song"}]
+        # Underlying entry is JSON-serialized.
+        stored = cache_module.get_cached("song")
+        assert json.loads(stored) == [{"title": "song"}]
+
+    def test_search_with_cache_uses_cached_value_on_hit(self, temp_cache_file):
+        calls = {"n": 0}
+
+        def search_func(q):
+            calls["n"] += 1
+            return [{"title": q}]
+
+        cache_module.search_with_cache("song", search_func)
+        cache_module.search_with_cache("song", search_func)
+
+        assert calls["n"] == 1  # second call served from cache
+
+    def test_search_with_cache_handles_non_string_cached_value(self, temp_cache_file):
+        # Pre-populate cache with a non-string (already-deserialized) value.
+        cache_module.set_cached("song", [{"title": "song"}])
+
+        # search_func should NOT be called.
+        with patch.object(cache_module, "save_cache") as mock_save:
+            result = cache_module.search_with_cache("song", lambda q: pytest.fail("must not call"))
+
+        assert result == [{"title": "song"}]
+        mock_save.assert_not_called()

{ytm_cli-0.7.0 → ytm_cli-0.7.2}/tests/test_config.py

@@ -8,7 +8,7 @@ import pytest
 
 # We need to mock the imports before importing the config module
 # since it initializes global objects on import
-with patch("ytm_cli.config.AuthManager"), patch("ytm_cli.config.configparser.ConfigParser"):
+with patch("ytm_cli.config.configparser.ConfigParser"):
     from ytm_cli.config import get_mpv_flags, get_songs_to_display
 
 
@@ -139,10 +139,9 @@ class TestConfigModule:
     """Tests for config module initialization and behavior"""
 
     def test_config_reads_file(self):
-        """Test that config reads from config.ini file"""
+        """Test that config reads from ~/.config/ytm-cli/config.ini"""
         with (
             patch("ytm_cli.config.configparser.ConfigParser") as mock_parser_class,
-            patch("ytm_cli.config.AuthManager"),
         ):
             mock_parser = Mock()
             mock_parser_class.return_value = mock_parser
@@ -154,25 +153,10 @@ class TestConfigModule:
 
             importlib.reload(ytm_cli.config)
 
-            mock_parser.read.assert_called_with("config.ini")
-
-    def test_auth_manager_initialization(self):
-        """Test that AuthManager is properly initialized"""
-        mock_auth_manager = Mock()
-        mock_auth_manager.get_ytmusic_instance.return_value = Mock()
-
-        with patch(
-            "ytm_cli.auth.AuthManager", return_value=mock_auth_manager
-        ) as mock_auth_manager_class:
-            # Re-import to trigger initialization
-            import importlib
-
-            import ytm_cli.config
-
-            importlib.reload(ytm_cli.config)
-
-            mock_auth_manager_class.assert_called_once()
-            mock_auth_manager.get_ytmusic_instance.assert_called_once()
+            # Config now lives under ~/.config/ytm-cli/
+            mock_parser.read.assert_called_once()
+            called_path = mock_parser.read.call_args[0][0]
+            assert called_path.endswith(os.path.join(".config", "ytm-cli", "config.ini"))
 
 
 class TestConfigIntegration:

{ytm_cli-0.7.0 → ytm_cli-0.7.2}/tests/test_dislikes.py

@@ -11,11 +11,13 @@ class TestDislikeManagerInit:
     """Tests for DislikeManager initialization"""
 
     def test_init_default_file(self):
-        """Test initialization with default file"""
+        """Test initialization with default file (~/.config/ytm-cli/dislikes.json)"""
         with patch("os.path.exists", return_value=False):
             manager = DislikeManager()
 
-            assert manager.dislikes_file == "dislikes.json"
+            assert manager.dislikes_file.endswith(
+                os.path.join(".config", "ytm-cli", "dislikes.json")
+            )
             assert manager._disliked_ids == set()
 
     def test_init_custom_file(self):