ytm 0.2.0__tar.gz

ytm-0.2.0/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Mahesh Koduri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR OTHER USE OF THE SOFTWARE.

ytm-0.2.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: ytm
+Version: 0.2.0
+Summary: YouTube Music in the terminal: a Textual TUI and CLI on top of mpv
+Author: Mahesh Koduri
+License: MIT License
+        
+        Copyright (c) 2026 Mahesh Koduri
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR OTHER USE OF THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/MaheshBhushan/yt-music-cli
+Project-URL: Source, https://github.com/MaheshBhushan/yt-music-cli
+Project-URL: Issues, https://github.com/MaheshBhushan/yt-music-cli/issues
+Keywords: youtube-music,music,player,tui,cli,mpv,textual
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Players
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ytmusicapi
+Requires-Dist: yt-dlp
+Requires-Dist: bgutil-ytdlp-pot-provider
+Requires-Dist: textual
+Requires-Dist: textual-image
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<h1 align="center">ytm</h1>
+<p align="center">YouTube Music in the terminal: search, queue, radio and lyrics, with mpv doing the playing.</p>
+
+<p align="center">
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/ytm">
+  <img alt="Tests" src="https://github.com/MaheshBhushan/yt-music-cli/actions/workflows/tests.yml/badge.svg">
+  <img alt="License" src="https://img.shields.io/github/license/MaheshBhushan/yt-music-cli">
+  <img alt="Last commit" src="https://img.shields.io/github/last-commit/MaheshBhushan/yt-music-cli">
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue">
+</p>
+
+![ytm's TUI: search results on top, queue, playlists and lyrics in the middle, the current track with its cover at the bottom](docs/screenshot.png)
+
+## Overview
+
+YouTube Music has no desktop client that is not a browser. `ytm` is a small Python CLI and a Textual TUI over three tools that already do the hard parts: [ytmusicapi](https://github.com/sigma67/ytmusicapi) for the catalogue, [yt-dlp](https://github.com/yt-dlp/yt-dlp) for stream resolution and [mpv](https://mpv.io) for audio.
+
+mpv is the only long-running process. `ytm` starts it once, idle, with a JSON IPC socket, and every command after that is a stateless message to it. Close the terminal and the music keeps playing. A Lua script inside mpv keeps the queue fed with the station for whatever is playing, so it never runs dry.
+
+## Quickstart
+
+```bash
+pipx install ytm              # or: uv tool install ytm   /   pip install ytm
+
+ytm auth                      # cookies from a logged-in browser, see Authentication
+ytm play "daft punk"          # search, play the first hit, radio follows
+ytm                           # the TUI
+```
+
+To hack on it instead:
+
+```bash
+git clone https://github.com/MaheshBhushan/yt-music-cli.git && cd yt-music-cli
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+> [!IMPORTANT]
+> `mpv` must be on your `PATH`; pip cannot install it. `pacman -S mpv`, `apt install mpv`, `brew install mpv`, or the installers at <https://mpv.io>. Node is optional but recommended: yt-dlp uses it to solve YouTube's JavaScript challenges.
+
+## Usage
+
+The TUI is `ytm` with no arguments. Type a query and press Enter to play the first result. Every key is listed in the bar at the bottom, and everything is clickable: results, queue rows, playlists, the progress bar, the shortcuts.
+
+| Key | Action |
+|---|---|
+| `/` or `s` | Focus search |
+| `Enter` | Play the selected result, queue entry or playlist |
+| `q` | Enqueue the selected result |
+| `space` | Play / pause |
+| `n` `p` | Next / previous |
+| `←` `→` | Seek 5 s |
+| `+` `-` | Volume |
+| `a` | Add the selected song to a playlist: `a`, pick the list with `↑` `↓`, `a` or `Enter` |
+| `l` | Focus playlists |
+| `Tab` | Cycle panes |
+| `e` | Exit, music keeps playing |
+| `x` | Exit and stop mpv |
+
+One-shot commands talk to the same mpv. Add `--json` to any of them for machine-readable output.
+
+```bash
+ytm search "song name" -n 10   # results are numbered
+ytm play 3                     # a number from the last search, an 11-char video id, or a query
+ytm add 4                      # enqueue
+ytm radio                      # replace the queue with a station for the current track
+ytm status | queue | lyrics | like
+ytm pause | resume | toggle | next | prev | stop
+ytm seek -10 | seek --to 90 | volume 60 | clear | shuffle
+ytm quit                       # stop mpv entirely
+```
+
+The queue never holds a track twice: playing something already queued jumps to it, and radio skips what is there.
+
+## Authentication
+
+Search works signed out, but library, playlists, likes and lyrics need your account. Credentials live in `~/.config/ytm/auth.json` (mode 0600) and are validated with a live call before being kept.
+
+```bash
+ytm auth                          # cookies from Chrome, Chromium, Edge, Brave, Vivaldi, Opera or Firefox
+ytm auth --from-browser firefox   # pick one
+ytm auth --manual                 # paste request headers copied from DevTools
+ytm auth --oauth                  # device-code flow, for SSH and headless boxes
+```
+
+Browser cookies expire after a few weeks; re-run `ytm auth` when the app says so. OAuth needs your own Google Cloud client (YouTube removed the shared one in 2024): create an OAuth client of type *TVs and Limited Input devices* and pass `--client-id`/`--client-secret`, or set `YTM_OAUTH_CLIENT_ID`/`YTM_OAUTH_CLIENT_SECRET`.
+
+> [!NOTE]
+> Streams resolve **anonymously by default**. With account cookies, YouTube hands out URLs that require an account-bound proof-of-origin token and then answers 403. Anonymous resolution plays the same catalogue. Set `behaviour.authenticated_streams = true` only if you need private or age-gated tracks.
+
+## Configuration
+
+`~/.config/ytm/config.toml`. A missing file means these defaults; a partial file overrides only what it names; a bad value is warned about and ignored.
+
+```toml
+[audio]
+volume = 70
+device = "auto"                 # an mpv --audio-device name
+
+[behaviour]
+autoplay_radio = true           # keep the queue fed with radio
+confirm_remote_delete = true
+authenticated_streams = false   # see the note above
+
+[ui]
+theme = "dark"                  # or "light"
+art = "blocks"                  # blocks | kitty | sixel | auto | ascii | off
+
+[pot]
+enabled = true                  # proof-of-origin tokens via bgutil-ytdlp-pot-provider
+base_url = "http://127.0.0.1:4416"
+
+[keys]
+toggle = "space"
+next = "n"
+prev = "p"
+search = "/"
+quit = "e"
+```
+
+`art = "blocks"` draws the cover with coloured half-cell glyphs and works in every terminal, tmux included. `kitty` and `sixel` use the terminal's pixel protocol; Sixel is known to freeze the pane in Konsole, which is why it is opt-in.
+
+The proof-of-origin token provider is a yt-dlp plugin installed with `ytm`. It asks an HTTP service for tokens when YouTube demands one; run `docker run -d --name bgutil-provider -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider` if you want it, or set `enabled = false`. Playback works without it for most accounts.
+
+## More
+
+- **Offline cache.** `ytm cache add <video_id>` downloads a track into `~/.cache/ytm/tracks/`; `cache rm` and `cache list` manage it. 2 GB cap, least-recently-played evicted first.
+- **Local playlists** live in `~/.local/state/ytm/playlists.json` and show up next to your YouTube Music playlists in the TUI.
+- **Media keys.** `ytm` has no MPRIS of its own; install the [mpv-mpris](https://github.com/hoyon/mpv-mpris) plugin and mpv announces itself to your desktop.
+- **yt-dlp goes stale.** YouTube changes things; yt-dlp follows within days. `pipx upgrade ytm` (or `pip install -U yt-dlp` in the same environment) fixes most sudden resolution failures.
+- **Windows** is supported in design (named-pipe IPC, no D-Bus) but has not been tested.
+- **Logs.** mpv writes to `~/.local/state/ytm/mpv.log`.
+
+## Repository structure
+
+```
+ytm/
+  cli.py            commands and the mpv launch configuration
+  player.py         Player: mpv over JSON IPC
+  music.py          ytmusicapi wrappers, Track
+  state.py          remembered searches and track metadata
+  auth.py           browser cookies, DevTools headers, OAuth
+  cache.py          offline downloads
+  mpv/autoplay.lua  radio autoplay inside mpv
+  tui/              Textual app, panes, backend over Player
+tests/              pytest; no network and no mpv needed
+```
+
+```bash
+pip install -e '.[dev]' && pytest -q
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

ytm-0.2.0/README.md

@@ -0,0 +1,155 @@
+<h1 align="center">ytm</h1>
+<p align="center">YouTube Music in the terminal: search, queue, radio and lyrics, with mpv doing the playing.</p>
+
+<p align="center">
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/ytm">
+  <img alt="Tests" src="https://github.com/MaheshBhushan/yt-music-cli/actions/workflows/tests.yml/badge.svg">
+  <img alt="License" src="https://img.shields.io/github/license/MaheshBhushan/yt-music-cli">
+  <img alt="Last commit" src="https://img.shields.io/github/last-commit/MaheshBhushan/yt-music-cli">
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue">
+</p>
+
+![ytm's TUI: search results on top, queue, playlists and lyrics in the middle, the current track with its cover at the bottom](docs/screenshot.png)
+
+## Overview
+
+YouTube Music has no desktop client that is not a browser. `ytm` is a small Python CLI and a Textual TUI over three tools that already do the hard parts: [ytmusicapi](https://github.com/sigma67/ytmusicapi) for the catalogue, [yt-dlp](https://github.com/yt-dlp/yt-dlp) for stream resolution and [mpv](https://mpv.io) for audio.
+
+mpv is the only long-running process. `ytm` starts it once, idle, with a JSON IPC socket, and every command after that is a stateless message to it. Close the terminal and the music keeps playing. A Lua script inside mpv keeps the queue fed with the station for whatever is playing, so it never runs dry.
+
+## Quickstart
+
+```bash
+pipx install ytm              # or: uv tool install ytm   /   pip install ytm
+
+ytm auth                      # cookies from a logged-in browser, see Authentication
+ytm play "daft punk"          # search, play the first hit, radio follows
+ytm                           # the TUI
+```
+
+To hack on it instead:
+
+```bash
+git clone https://github.com/MaheshBhushan/yt-music-cli.git && cd yt-music-cli
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+> [!IMPORTANT]
+> `mpv` must be on your `PATH`; pip cannot install it. `pacman -S mpv`, `apt install mpv`, `brew install mpv`, or the installers at <https://mpv.io>. Node is optional but recommended: yt-dlp uses it to solve YouTube's JavaScript challenges.
+
+## Usage
+
+The TUI is `ytm` with no arguments. Type a query and press Enter to play the first result. Every key is listed in the bar at the bottom, and everything is clickable: results, queue rows, playlists, the progress bar, the shortcuts.
+
+| Key | Action |
+|---|---|
+| `/` or `s` | Focus search |
+| `Enter` | Play the selected result, queue entry or playlist |
+| `q` | Enqueue the selected result |
+| `space` | Play / pause |
+| `n` `p` | Next / previous |
+| `←` `→` | Seek 5 s |
+| `+` `-` | Volume |
+| `a` | Add the selected song to a playlist: `a`, pick the list with `↑` `↓`, `a` or `Enter` |
+| `l` | Focus playlists |
+| `Tab` | Cycle panes |
+| `e` | Exit, music keeps playing |
+| `x` | Exit and stop mpv |
+
+One-shot commands talk to the same mpv. Add `--json` to any of them for machine-readable output.
+
+```bash
+ytm search "song name" -n 10   # results are numbered
+ytm play 3                     # a number from the last search, an 11-char video id, or a query
+ytm add 4                      # enqueue
+ytm radio                      # replace the queue with a station for the current track
+ytm status | queue | lyrics | like
+ytm pause | resume | toggle | next | prev | stop
+ytm seek -10 | seek --to 90 | volume 60 | clear | shuffle
+ytm quit                       # stop mpv entirely
+```
+
+The queue never holds a track twice: playing something already queued jumps to it, and radio skips what is there.
+
+## Authentication
+
+Search works signed out, but library, playlists, likes and lyrics need your account. Credentials live in `~/.config/ytm/auth.json` (mode 0600) and are validated with a live call before being kept.
+
+```bash
+ytm auth                          # cookies from Chrome, Chromium, Edge, Brave, Vivaldi, Opera or Firefox
+ytm auth --from-browser firefox   # pick one
+ytm auth --manual                 # paste request headers copied from DevTools
+ytm auth --oauth                  # device-code flow, for SSH and headless boxes
+```
+
+Browser cookies expire after a few weeks; re-run `ytm auth` when the app says so. OAuth needs your own Google Cloud client (YouTube removed the shared one in 2024): create an OAuth client of type *TVs and Limited Input devices* and pass `--client-id`/`--client-secret`, or set `YTM_OAUTH_CLIENT_ID`/`YTM_OAUTH_CLIENT_SECRET`.
+
+> [!NOTE]
+> Streams resolve **anonymously by default**. With account cookies, YouTube hands out URLs that require an account-bound proof-of-origin token and then answers 403. Anonymous resolution plays the same catalogue. Set `behaviour.authenticated_streams = true` only if you need private or age-gated tracks.
+
+## Configuration
+
+`~/.config/ytm/config.toml`. A missing file means these defaults; a partial file overrides only what it names; a bad value is warned about and ignored.
+
+```toml
+[audio]
+volume = 70
+device = "auto"                 # an mpv --audio-device name
+
+[behaviour]
+autoplay_radio = true           # keep the queue fed with radio
+confirm_remote_delete = true
+authenticated_streams = false   # see the note above
+
+[ui]
+theme = "dark"                  # or "light"
+art = "blocks"                  # blocks | kitty | sixel | auto | ascii | off
+
+[pot]
+enabled = true                  # proof-of-origin tokens via bgutil-ytdlp-pot-provider
+base_url = "http://127.0.0.1:4416"
+
+[keys]
+toggle = "space"
+next = "n"
+prev = "p"
+search = "/"
+quit = "e"
+```
+
+`art = "blocks"` draws the cover with coloured half-cell glyphs and works in every terminal, tmux included. `kitty` and `sixel` use the terminal's pixel protocol; Sixel is known to freeze the pane in Konsole, which is why it is opt-in.
+
+The proof-of-origin token provider is a yt-dlp plugin installed with `ytm`. It asks an HTTP service for tokens when YouTube demands one; run `docker run -d --name bgutil-provider -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider` if you want it, or set `enabled = false`. Playback works without it for most accounts.
+
+## More
+
+- **Offline cache.** `ytm cache add <video_id>` downloads a track into `~/.cache/ytm/tracks/`; `cache rm` and `cache list` manage it. 2 GB cap, least-recently-played evicted first.
+- **Local playlists** live in `~/.local/state/ytm/playlists.json` and show up next to your YouTube Music playlists in the TUI.
+- **Media keys.** `ytm` has no MPRIS of its own; install the [mpv-mpris](https://github.com/hoyon/mpv-mpris) plugin and mpv announces itself to your desktop.
+- **yt-dlp goes stale.** YouTube changes things; yt-dlp follows within days. `pipx upgrade ytm` (or `pip install -U yt-dlp` in the same environment) fixes most sudden resolution failures.
+- **Windows** is supported in design (named-pipe IPC, no D-Bus) but has not been tested.
+- **Logs.** mpv writes to `~/.local/state/ytm/mpv.log`.
+
+## Repository structure
+
+```
+ytm/
+  cli.py            commands and the mpv launch configuration
+  player.py         Player: mpv over JSON IPC
+  music.py          ytmusicapi wrappers, Track
+  state.py          remembered searches and track metadata
+  auth.py           browser cookies, DevTools headers, OAuth
+  cache.py          offline downloads
+  mpv/autoplay.lua  radio autoplay inside mpv
+  tui/              Textual app, panes, backend over Player
+tests/              pytest; no network and no mpv needed
+```
+
+```bash
+pip install -e '.[dev]' && pytest -q
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

ytm-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ytm"
+version = "0.2.0"
+description = "YouTube Music in the terminal: a Textual TUI and CLI on top of mpv"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Mahesh Koduri" }]
+requires-python = ">=3.11"
+keywords = ["youtube-music", "music", "player", "tui", "cli", "mpv", "textual"]
+classifiers = [
+    "Environment :: Console",
+    "Environment :: Console :: Curses",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Players",
+]
+dependencies = [
+    "ytmusicapi",
+    "yt-dlp",
+    "bgutil-ytdlp-pot-provider",
+    "textual",
+    "textual-image",
+]
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.scripts]
+ytm = "ytm.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MaheshBhushan/yt-music-cli"
+Source = "https://github.com/MaheshBhushan/yt-music-cli"
+Issues = "https://github.com/MaheshBhushan/yt-music-cli/issues"
+
+[tool.setuptools.packages.find]
+include = ["ytm*"]
+
+[tool.setuptools.package-data]
+ytm = ["mpv/*.lua", "tui/*.tcss"]

ytm-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ytm-0.2.0/tests/test_api.py

@@ -0,0 +1,232 @@
+"""Tests for search-result normalisation and typed auth errors."""
+import json
+
+import pytest
+from ytmusicapi.exceptions import YTMusicServerError
+
+from ytm import api, auth
+
+# Hand-written fixture mirroring the shapes ytmusicapi 1.12.1 actually returns
+# for search(filter="songs"), including the degenerate ones.
+SEARCH_RESPONSE = [
+    {
+        "category": "Songs",
+        "resultType": "song",
+        "videoId": "ZrOKjDZOtkA",
+        "title": "Wonderwall",
+        "artists": [{"name": "Oasis", "id": "UCmMUZbaYdNH0bEd1PAlAqsA"}],
+        "album": {"name": "(What's The Story) Morning Glory?", "id": "MPREb_9nqEki4ZDpp"},
+        "duration": "4:19",
+        "duration_seconds": 259,
+    },
+    {
+        # no album key at all
+        "resultType": "song",
+        "videoId": "noalbum123",
+        "title": "Untitled Demo",
+        "artists": [{"name": "Some Artist", "id": "UC1"}],
+        "duration": "2:05",
+        "duration_seconds": 125,
+    },
+    {
+        # empty artists list
+        "resultType": "song",
+        "videoId": "noartist123",
+        "title": "Field Recording",
+        "artists": [],
+        "album": None,
+        "duration": "1:00",
+        "duration_seconds": 60,
+    },
+    {
+        # null duration
+        "resultType": "song",
+        "videoId": "nodur123",
+        "title": "Mystery Length",
+        "artists": [{"name": "Anon"}],
+        "album": {"name": "Anon EP"},
+        "duration": None,
+        "duration_seconds": None,
+    },
+    {
+        # personal upload: out of scope, must be filtered out
+        "resultType": "song",
+        "videoId": "upload123",
+        "title": "My Own Rip",
+        "artists": [{"name": "Me"}],
+        "videoType": "MUSIC_VIDEO_TYPE_PRIVATELY_OWNED_TRACK",
+        "duration": "3:00",
+        "duration_seconds": 180,
+    },
+    {
+        # upload from a library-scope search, identified by resultType/entityId
+        "resultType": "upload",
+        "entityId": "t_po_abc",
+        "videoId": "upload456",
+        "title": "Another Rip",
+        "artists": [{"name": "Me"}],
+        "duration": "3:30",
+        "duration_seconds": 210,
+    },
+]
+
+
+class FakeYTMusic:
+    """Stand-in for ytmusicapi.YTMusic; never touches the network."""
+
+    def __init__(self, results=None, error=None):
+        self._results = results if results is not None else []
+        self._error = error
+        self.calls = []
+
+    def search(self, query, filter=None, limit=20):
+        self.calls.append({"query": query, "filter": filter, "limit": limit})
+        if self._error:
+            raise self._error
+        return self._results
+
+
+def test_normalises_fixture_into_tracks():
+    tracks = api.to_tracks(SEARCH_RESPONSE)
+    assert [t.video_id for t in tracks] == ["ZrOKjDZOtkA", "noalbum123", "noartist123", "nodur123"]
+    first = tracks[0]
+    assert first.title == "Wonderwall"
+    assert first.artist == "Oasis"
+    assert first.album == "(What's The Story) Morning Glory?"
+    assert first.duration == "4:19"
+    assert first.duration_seconds == 259
+
+
+def test_missing_album_normalises_to_empty_string():
+    no_album, null_album = api.to_tracks(SEARCH_RESPONSE)[1:3]
+    assert no_album.album == ""
+    assert null_album.album == ""
+
+
+def test_empty_artists_normalises_to_placeholder():
+    track = api.to_tracks(SEARCH_RESPONSE)[2]
+    assert track.artist == "Unknown Artist"
+
+
+def test_null_duration_normalises_to_zero():
+    track = api.to_tracks(SEARCH_RESPONSE)[3]
+    assert track.duration_seconds == 0
+    assert track.duration == "0:00"
+
+
+def test_uploads_filtered_out_of_search_results():
+    yt = FakeYTMusic(results=SEARCH_RESPONSE)
+    tracks = api.search("wonderwall", yt=yt)
+    assert all(t.video_id not in {"upload123", "upload456"} for t in tracks)
+    assert "My Own Rip" not in [t.title for t in tracks]
+    assert len(tracks) == 4
+
+
+def test_search_uses_songs_filter():
+    yt = FakeYTMusic(results=[])
+    api.search("kaanave kaanave", yt=yt)
+    assert yt.calls[0]["filter"] == "songs"
+
+
+def test_expired_auth_raises_typed_autherror_not_raw_traceback():
+    expired = YTMusicServerError(
+        "Server returned HTTP 401: Unauthorized.\nRequest had invalid authentication credentials."
+    )
+    yt = FakeYTMusic(error=expired)
+    with pytest.raises(auth.AuthExpired) as excinfo:
+        api.search("anything", yt=yt)
+    assert "ytm auth" in str(excinfo.value)
+
+
+def test_non_auth_server_error_is_not_swallowed():
+    yt = FakeYTMusic(error=YTMusicServerError("Server returned HTTP 500: Internal Server Error.\nboom"))
+    with pytest.raises(YTMusicServerError):
+        api.search("anything", yt=yt)
+
+
+class FakeLyricsYTMusic:
+    """Stand-in for the two calls behind api.get_lyrics."""
+
+    def __init__(self, browse_id="browse-1", lyrics_result=None, error=None):
+        self._browse_id = browse_id
+        self._lyrics_result = lyrics_result
+        self._error = error
+        self.watch_calls = []
+        self.lyrics_calls = []
+
+    def get_watch_playlist(self, videoId=None):
+        self.watch_calls.append(videoId)
+        if self._error:
+            raise self._error
+        data = {"tracks": []}
+        if self._browse_id is not None:
+            data["lyrics"] = self._browse_id
+        return data
+
+    def get_lyrics(self, browseId):
+        self.lyrics_calls.append(browseId)
+        return self._lyrics_result
+
+
+def test_get_lyrics_returns_normalised_text_and_source():
+    yt = FakeLyricsYTMusic(
+        browse_id="browse-1",
+        lyrics_result={"lyrics": "some lyrics text", "source": "Musixmatch"},
+    )
+    lyrics, source = api.get_lyrics("PYgcJpC6WAQ", yt=yt)
+    assert lyrics == "some lyrics text"
+    assert source == "Musixmatch"
+    assert yt.watch_calls == ["PYgcJpC6WAQ"]
+    assert yt.lyrics_calls == ["browse-1"]
+
+
+def test_get_lyrics_missing_browse_id_returns_none_without_second_call():
+    yt = FakeLyricsYTMusic(browse_id=None)
+    lyrics, source = api.get_lyrics("no-lyrics-track", yt=yt)
+    assert lyrics is None
+    assert source is None
+    assert yt.lyrics_calls == []
+
+
+def test_get_lyrics_null_result_returns_none():
+    yt = FakeLyricsYTMusic(browse_id="browse-1", lyrics_result=None)
+    lyrics, source = api.get_lyrics("v1", yt=yt)
+    assert lyrics is None
+    assert source is None
+
+
+def test_get_lyrics_expired_auth_raises_typed_autherror():
+    expired = YTMusicServerError(
+        "Server returned HTTP 401: Unauthorized.\nRequest had invalid authentication credentials."
+    )
+    yt = FakeLyricsYTMusic(error=expired)
+    with pytest.raises(auth.AuthExpired):
+        api.get_lyrics("v1", yt=yt)
+
+
+def test_playlist_normalisation_marks_remote_and_local():
+    remote = api.to_playlist({"playlistId": "PL1", "title": "Mix", "count": "12"})
+    assert (remote.playlist_id, remote.title, remote.track_count, remote.local) == ("PL1", "Mix", 12, False)
+    local = api.to_playlist({"playlistId": "local-1", "title": "Offline"}, local=True)
+    assert local.local is True
+    assert local.track_count == 0
+
+
+def test_missing_auth_file_raises_authmissing(tmp_path):
+    with pytest.raises(auth.AuthMissing) as excinfo:
+        auth.load_headers(tmp_path / "auth.json")
+    assert "ytm auth" in str(excinfo.value)
+
+
+def test_cookies_exposed_for_stream_resolution(tmp_path):
+    path = tmp_path / "auth.json"
+    path.write_text(json.dumps({"Cookie": "SID=abc; HSID=def", "authorization": "SAPISIDHASH x"}))
+    assert auth.load_cookies(path) == "SID=abc; HSID=def"
+
+
+def test_setup_writes_file_with_mode_0600(tmp_path, monkeypatch):
+    path = tmp_path / "config" / "auth.json"
+    monkeypatch.setattr(auth.ytmusicapi, "setup", lambda: json.dumps({"cookie": "SID=abc"}))
+    auth.setup(path)
+    assert path.stat().st_mode & 0o777 == 0o600
+    assert json.loads(path.read_text())["cookie"] == "SID=abc"