ytm 0.2.0__py3-none-any.whl

ytm/__init__.py

@@ -0,0 +1 @@
+"""YouTube Music CLI and daemon."""

ytm/api.py

@@ -0,0 +1,28 @@
+"""Compatibility shim: the catalogue layer now lives in :mod:`ytm.music`.
+
+Kept only until the daemon and Textual TUI that import it are removed.
+"""
+
+from ytm.music import *  # noqa: F401,F403
+from ytm.music import (  # noqa: F401
+    Playlist,
+    Track,
+    UPLOAD_VIDEO_TYPE,
+    _album_name,
+    _duration,
+    _join_artists,
+    _wrap_ytmusic_error,
+    add_playlist_items,
+    create_playlist,
+    delete_playlist,
+    edit_playlist,
+    get_lyrics,
+    get_playlist,
+    is_upload,
+    library_playlists,
+    remove_playlist_items,
+    search,
+    to_playlist,
+    to_track,
+    to_tracks,
+)

ytm/auth.py

@@ -0,0 +1,372 @@
+"""Authentication module."""
+import getpass
+import json
+import os
+import time
+from pathlib import Path
+
+import ytmusicapi
+from yt_dlp.cookies import extract_cookies_from_browser
+from ytmusicapi.auth.oauth.credentials import OAuthCredentials
+from ytmusicapi.auth.oauth.exceptions import BadOAuthClient, UnauthorizedOAuthClient
+from ytmusicapi.auth.oauth.token import OAuthToken
+from ytmusicapi.exceptions import YTMusicError
+
+AUTH_PATH = Path.home() / ".config" / "ytm" / "auth.json"
+
+# Order in which --from-browser auto-detection tries local browser profiles.
+_AUTODETECT_BROWSERS = ("chrome", "chromium", "edge", "brave", "vivaldi", "opera", "firefox")
+
+_USER_AGENT = (
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/124.0.0.0 Safari/537.36"
+)
+
+_EXPIRED_HINT = (
+    "YouTube Music authentication is no longer valid (browser headers expire "
+    "when the session is revoked or the cookie ages out). Run 'ytm auth' to "
+    "paste fresh request headers."
+)
+_MISSING_HINT = "No YouTube Music credentials found at {path}. Run 'ytm auth' to set them up."
+
+_OAUTH_EXPIRED_HINT = (
+    "YouTube Music OAuth authentication is no longer valid (the refresh token "
+    "was revoked or rejected). Run 'ytm auth --oauth' to re-authenticate."
+)
+
+_OAUTH_CLIENT_MISSING_HINT = (
+    "OAuth client credentials are missing (expected alongside {path}). "
+    "Run 'ytm auth --oauth' to set them up again."
+)
+
+
+class _QuietLogger:
+    """A yt-dlp logger that never prints anything (cookies must never be logged)."""
+
+    def debug(self, message):
+        pass
+
+    def info(self, message):
+        pass
+
+    def warning(self, message, only_once=False):
+        pass
+
+    def error(self, message):
+        pass
+
+
+class AuthError(Exception):
+    """Base class for authentication problems."""
+
+
+class AuthMissing(AuthError):
+    """No credentials have been stored yet."""
+
+
+class AuthExpired(AuthError):
+    """Stored credentials are present but no longer accepted by YouTube Music."""
+
+
+def setup(path=AUTH_PATH):
+    """Run the interactive browser-header setup and store credentials at path.
+
+    ytmusicapi 1.12.1's OAuth path needs a user-provisioned Google Cloud
+    client id and secret, so browser headers are the only credentials a human
+    can supply interactively. They are also the cookies stream resolution needs.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    print("Copy the request headers of an authenticated POST request from")
+    print("https://music.youtube.com (devtools > Network > filter '/browse' >")
+    print("right click the browse request > Copy > Copy request headers).")
+    try:
+        headers = ytmusicapi.setup()
+    except YTMusicError as exc:
+        raise AuthError(str(exc)) from exc
+    # os.open with mode 0600 so the file is never briefly world-readable.
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with open(fd, "w", encoding="utf-8") as file:
+        file.write(headers)
+    os.chmod(path, 0o600)
+    return path
+
+
+def _oauth_client_path(path):
+    """Where the OAuth app's client_id/client_secret are stored, alongside path.
+
+    Kept separate from the token file because ytmusicapi rewrites the token
+    file on every refresh with only token fields (see RefreshingToken.store_token),
+    which would silently drop client_id/client_secret if they lived in the same file.
+    """
+    return path.parent / "oauth_client.json"
+
+
+def _write_json_0600(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with open(fd, "w", encoding="utf-8") as file:
+        json.dump(data, file)
+    os.chmod(path, 0o600)
+
+
+def _resolve_oauth_client(client_id, client_secret):
+    """Resolve client_id/client_secret: explicit args > env vars > interactive prompt."""
+    client_id = client_id or os.environ.get("YTM_OAUTH_CLIENT_ID")
+    client_secret = client_secret or os.environ.get("YTM_OAUTH_CLIENT_SECRET")
+    if not client_id:
+        client_id = input("Google Cloud OAuth client ID: ").strip()
+    if not client_secret:
+        client_secret = getpass.getpass("Google Cloud OAuth client secret: ").strip()
+    if not client_id or not client_secret:
+        raise AuthError(
+            "An OAuth client_id and client_secret are required. Create a 'TVs and "
+            "Limited Input devices' OAuth client in Google Cloud Console and pass "
+            "them via --client-id/--client-secret, YTM_OAUTH_CLIENT_ID/"
+            "YTM_OAUTH_CLIENT_SECRET, or the interactive prompt."
+        )
+    return client_id, client_secret
+
+
+def _load_oauth_client(path):
+    """Return the stored (client_id, client_secret) for the OAuth token at path."""
+    client_path = _oauth_client_path(path)
+    try:
+        with open(client_path, encoding="utf-8") as file:
+            data = json.load(file)
+        return data["client_id"], data["client_secret"]
+    except (OSError, ValueError, KeyError) as exc:
+        raise AuthMissing(_OAUTH_CLIENT_MISSING_HINT.format(path=path)) from exc
+
+
+def oauth_setup(
+    client_id=None,
+    client_secret=None,
+    path=AUTH_PATH,
+    credentials_factory=None,
+    sleep=time.sleep,
+):
+    """Run the OAuth device-code flow and store the resulting refreshable token at path.
+
+    Prints a verification URL and short user code for the user to enter on another
+    device, then polls token_from_code at the interval YouTube's response specifies
+    until authorised (or the device code expires). The client_id/client_secret are
+    persisted separately (see _oauth_client_path) since they are needed again for
+    every future token refresh.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    client_id, client_secret = _resolve_oauth_client(client_id, client_secret)
+    _write_json_0600(_oauth_client_path(path), {"client_id": client_id, "client_secret": client_secret})
+
+    make_credentials = credentials_factory or OAuthCredentials
+    credentials = make_credentials(client_id, client_secret)
+    try:
+        code = credentials.get_code()
+    except Exception as exc:
+        raise AuthError(f"Could not start the OAuth device flow: {exc}") from exc
+
+    print(f"Go to {code['verification_url']} and enter the code: {code['user_code']}")
+    print("Waiting for you to authorise this device...")
+
+    interval = code.get("interval", 5)
+    deadline = time.time() + code.get("expires_in", 1800)
+    raw = None
+    while True:
+        sleep(interval)
+        raw = credentials.token_from_code(code["device_code"])
+        if "access_token" in raw:
+            break
+        error = raw.get("error")
+        if error == "slow_down":
+            interval += 5
+        elif error != "authorization_pending":
+            raise AuthError(f"OAuth device authorisation failed: {raw}")
+        if time.time() > deadline:
+            raise AuthError(
+                "OAuth device code expired before authorisation completed; "
+                "run 'ytm auth --oauth' again."
+            )
+
+    token = {
+        "scope": raw["scope"],
+        "token_type": raw["token_type"],
+        "access_token": raw["access_token"],
+        "refresh_token": raw["refresh_token"],
+        "expires_in": raw["expires_in"],
+        "expires_at": int(time.time()) + raw["expires_in"],
+    }
+    _write_json_0600(path, token)
+    return path
+
+
+def _cookie_header_from_jar(jar):
+    """Build a Cookie header value from a http.cookiejar-style jar of youtube.com cookies.
+
+    Returns None if the jar has no usable logged-in YouTube session (no __Secure-3PAPISID).
+    """
+    pairs = [(cookie.name, cookie.value) for cookie in jar if "youtube.com" in cookie.domain]
+    if not any(name == "__Secure-3PAPISID" for name, _ in pairs):
+        return None
+    return "; ".join(f"{name}={value}" for name, value in pairs)
+
+
+def _extract_browser_cookie_header(browser_name):
+    """Return a Cookie header value extracted from browser_name's profile, or None."""
+    try:
+        jar = extract_cookies_from_browser(browser_name, logger=_QuietLogger())
+    except Exception:
+        return None
+    return _cookie_header_from_jar(jar)
+
+
+def from_browser(browser=None, path=AUTH_PATH, client_factory=None):
+    """Extract YouTube cookies from a local browser profile and store credentials at path.
+
+    If browser is None, tries each of _AUTODETECT_BROWSERS in turn and uses the first
+    that yields a logged-in YouTube cookie set. Validates the extracted credentials with
+    a live call before leaving the auth file in place; on failure the file is removed
+    and AuthError is raised so a dead auth file is never left behind silently.
+    """
+    candidates = [browser] if browser else list(_AUTODETECT_BROWSERS)
+    cookie_header = None
+    for name in candidates:
+        cookie_header = _extract_browser_cookie_header(name)
+        if cookie_header:
+            break
+    if cookie_header is None:
+        raise AuthError(
+            "No logged-in YouTube session found in "
+            + ", ".join(candidates)
+            + ". Log in at https://music.youtube.com in one of these browsers first, "
+            "then run 'ytm auth --from-browser' again."
+        )
+
+    headers = {
+        "cookie": cookie_header,
+        "x-goog-authuser": "0",
+        "user-agent": _USER_AGENT,
+        # Placeholder so ytmusicapi recognises this as browser auth; it is
+        # regenerated from the cookie's SAPISID on every request.
+        "authorization": "SAPISIDHASH 0_0",
+        "origin": "https://music.youtube.com",
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with open(fd, "w", encoding="utf-8") as file:
+        json.dump(headers, file)
+    os.chmod(path, 0o600)
+
+    make_client = client_factory or client
+    try:
+        make_client(path).search("test", limit=1)
+    except Exception as exc:
+        path.unlink(missing_ok=True)
+        raise AuthError(
+            "Extracted browser cookies were written but did not authenticate "
+            "successfully; no auth file was left behind. Make sure you are logged "
+            "in at https://music.youtube.com and try again. "
+            f"Underlying error: {exc}"
+        ) from exc
+    return path
+
+
+def load_headers(path=AUTH_PATH):
+    """Return the stored request headers.
+
+    Raises AuthMissing if no usable credentials have been stored.
+    """
+    try:
+        with open(path, encoding="utf-8") as file:
+            return json.load(file)
+    except (OSError, ValueError) as exc:
+        raise AuthMissing(_MISSING_HINT.format(path=path)) from exc
+
+
+def load_cookies(path=AUTH_PATH):
+    """Return the stored Cookie header value, for reuse by stream resolution.
+
+    OAuth auth files have no cookies (there is no browser session to extract
+    one from), so this returns None for them rather than raising -- stream
+    resolution falls back to cookie-less requests, see ytm/resolve.py.
+    """
+    headers = load_headers(path)
+    if OAuthToken.is_oauth(headers):
+        return None
+    for key, value in headers.items():
+        if key.lower() == "cookie":
+            return value
+    raise AuthMissing(_MISSING_HINT.format(path=path))
+
+
+COOKIES_PATH = AUTH_PATH.parent / "cookies.txt"
+
+
+def cookies_file(path=AUTH_PATH, cookies_path=COOKIES_PATH):
+    """A Netscape-format cookie file for yt-dlp, derived from the stored auth.
+
+    yt-dlp (and therefore mpv's ytdl_hook) reads cookies from a file, while
+    ytmusicapi keeps them as one Cookie header in auth.json. This writes the
+    header out in the file format, refreshing it whenever auth.json is newer,
+    so re-authenticating is the only step the user ever takes. Returns None
+    when there are no cookies to write (OAuth auth, or not authenticated).
+    """
+    try:
+        header = load_cookies(path)
+    except AuthError:
+        return None
+    if header is None:
+        return None
+    cookies_path = Path(cookies_path)
+    try:
+        fresh = cookies_path.stat().st_mtime >= Path(path).stat().st_mtime
+    except OSError:
+        fresh = False
+    if fresh:
+        return str(cookies_path)
+    lines = ["# Netscape HTTP Cookie File"]
+    for pair in header.split(";"):
+        name, _, value = pair.strip().partition("=")
+        if name:
+            lines.append(f".youtube.com\tTRUE\t/\tTRUE\t2147483647\t{name}\t{value}")
+    _write_text_0600(cookies_path, "\n".join(lines) + "\n")
+    return str(cookies_path)
+
+
+def _write_text_0600(path, text):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with open(fd, "w", encoding="utf-8") as file:
+        file.write(text)
+    os.chmod(path, 0o600)
+
+
+def client(path=AUTH_PATH, credentials_factory=None):
+    """Return an authenticated ytmusicapi client, for either auth kind stored at path."""
+    headers = load_headers(path)
+    if OAuthToken.is_oauth(headers):
+        return _oauth_client(path, credentials_factory)
+    try:
+        return ytmusicapi.YTMusic(headers)
+    except YTMusicError as exc:
+        raise AuthExpired(_EXPIRED_HINT) from exc
+
+
+def _oauth_client(path, credentials_factory=None):
+    """Build a YTMusic client from a stored OAuth token, eagerly refreshing if due."""
+    client_id, client_secret = _load_oauth_client(path)
+    make_credentials = credentials_factory or OAuthCredentials
+    credentials = make_credentials(client_id, client_secret)
+    try:
+        ytm = ytmusicapi.YTMusic(str(path), oauth_credentials=credentials)
+        # Touching access_token triggers RefreshingToken's auto-refresh (and
+        # persists it back to path) if the stored token is due to expire, so a
+        # revoked/invalid refresh token surfaces here rather than mid-request.
+        _ = ytm._token.access_token
+    except (YTMusicError, UnauthorizedOAuthClient, BadOAuthClient) as exc:
+        raise AuthExpired(_OAUTH_EXPIRED_HINT) from exc
+    return ytm
+
+
+def is_expiry(exc):
+    """Whether a ytmusicapi error indicates credentials are no longer accepted."""
+    return any(code in str(exc) for code in ("HTTP 401", "HTTP 403"))

ytm/cache.py

@@ -0,0 +1,184 @@
+"""Offline cache of downloaded track audio.
+
+Downloads a ``videoId``'s audio via yt-dlp (reusing the cookie/options
+approach from :mod:`ytm.resolve`) into a cache directory under
+``~/.cache/ytm/tracks``, so a track can be replayed later without hitting
+the network or resolving a (short-lived) stream URL at all.
+
+Two correctness properties matter more than anything else here:
+
+* A partial/interrupted download must never be mistaken for a complete
+  cache entry. Downloads land in a private temp directory and are only
+  moved into the cache directory -- via an atomic rename -- once yt-dlp has
+  finished successfully. If anything raises along the way, the temp
+  directory is discarded and the cache directory never sees a partial file.
+* The cache has a size cap enforced by evicting the least-recently-*used*
+  entries (recency of playback, tracked via each file's mtime, which is
+  touched on every read), not least-recently-downloaded.
+
+Unlike stream URLs, the files this module writes are the point -- they are
+supposed to persist. What must never be persisted is a resolved stream URL
+itself (see ytm.resolve); this module never touches those.
+"""
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+import yt_dlp
+
+from ytm import config as config_mod
+
+#: default location for cached track audio
+DEFAULT_CACHE_DIR = Path.home() / ".cache" / "ytm" / "tracks"
+
+#: default total size cap for the cache, in bytes
+DEFAULT_CAP_BYTES = 2 * 1024**3
+
+_WATCH_URL = "https://www.youtube.com/watch?v={video_id}"
+
+
+class CacheError(Exception):
+    """A download completed without producing a usable file."""
+
+
+def _resolve_cache_dir(cache_dir=None):
+    """The cache directory to use, created if necessary."""
+    cache_dir = Path(cache_dir) if cache_dir is not None else DEFAULT_CACHE_DIR
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    return cache_dir
+
+
+# -- lookup ------------------------------------------------------------------
+
+
+def get_cached_path(video_id, cache_dir=None, touch=True):
+    """The local path for `video_id` if fully cached, else None.
+
+    Marks the entry as just-used (for LRU purposes) unless `touch` is False.
+    """
+    cache_dir = _resolve_cache_dir(cache_dir)
+    matches = sorted(cache_dir.glob(f"{video_id}.*"))
+    if not matches:
+        return None
+    path = matches[0]
+    if touch:
+        os.utime(path, None)
+    return path
+
+
+def is_cached(video_id, cache_dir=None):
+    """Whether `video_id` has a complete cache entry."""
+    return get_cached_path(video_id, cache_dir=cache_dir, touch=False) is not None
+
+
+def list_cached(cache_dir=None):
+    """All complete cache entries as dicts with video_id, path, size, mtime."""
+    cache_dir = _resolve_cache_dir(cache_dir)
+    entries = []
+    for path in sorted(cache_dir.glob("*")):
+        if not path.is_file():
+            continue
+        stat = path.stat()
+        entries.append(
+            {
+                "video_id": path.stem,
+                "path": path,
+                "size": stat.st_size,
+                "mtime": stat.st_mtime,
+            }
+        )
+    return entries
+
+
+# -- mutation -----------------------------------------------------------------
+
+
+def remove(video_id, cache_dir=None):
+    """Delete the cache entry for `video_id`, if any. Returns whether removed."""
+    cache_dir = _resolve_cache_dir(cache_dir)
+    removed = False
+    for path in cache_dir.glob(f"{video_id}.*"):
+        path.unlink()
+        removed = True
+    return removed
+
+
+def download(video_id, cache_dir=None, cap_bytes=DEFAULT_CAP_BYTES, ydl_class=yt_dlp.YoutubeDL):
+    """Download `video_id`'s audio into the cache and return its local path.
+
+    Downloads to a private temporary directory first; the file is only
+    moved into the cache directory (via an atomic rename) after a
+    successful download, so an interrupted download never leaves behind
+    something that looks like a complete cache entry. Applies the LRU size
+    cap (if any) after the download lands.
+    """
+    cache_dir = _resolve_cache_dir(cache_dir)
+    tmp_root = cache_dir / ".tmp"
+    tmp_root.mkdir(parents=True, exist_ok=True)
+    work_dir = Path(tempfile.mkdtemp(dir=tmp_root))
+    try:
+        outtmpl = str(work_dir / f"{video_id}.%(ext)s")
+        url = _WATCH_URL.format(video_id=video_id)
+        with ydl_class(_ydl_opts(outtmpl)) as ydl:
+            ydl.extract_info(url, download=True)
+
+        downloaded = [p for p in work_dir.glob(f"{video_id}.*") if p.is_file()]
+        if not downloaded:
+            raise CacheError(f"download of {video_id!r} produced no file")
+        src = downloaded[0]
+        dest = cache_dir / src.name
+        remove(video_id, cache_dir=cache_dir)  # drop a stale entry with a different ext
+        os.replace(src, dest)
+    finally:
+        shutil.rmtree(work_dir, ignore_errors=True)
+
+    if cap_bytes is not None:
+        enforce_cap(cap_bytes, cache_dir=cache_dir)
+    return dest
+
+
+def enforce_cap(cap_bytes, cache_dir=None):
+    """Evict least-recently-used entries until the cache is under `cap_bytes`.
+
+    Recency is each file's mtime, which callers touch on every use via
+    `get_cached_path`. Returns the list of evicted video_ids.
+    """
+    cache_dir = _resolve_cache_dir(cache_dir)
+    entries = sorted(list_cached(cache_dir=cache_dir), key=lambda e: e["mtime"])
+    total = sum(e["size"] for e in entries)
+    evicted = []
+    for entry in entries:
+        if total <= cap_bytes:
+            break
+        try:
+            entry["path"].unlink()
+        except OSError:
+            continue
+        total -= entry["size"]
+        evicted.append(entry["video_id"])
+    return evicted
+
+
+# -- playback integration -----------------------------------------------------
+
+
+def _ydl_opts(outtmpl):
+    """yt-dlp options for an anonymous audio download into `outtmpl`.
+
+    Anonymous on purpose: with account cookies YouTube serves URLs that need
+    an account-bound PO token, and the download then fails with 403 (the
+    same reason ``behaviour.authenticated_streams`` defaults to off).
+    """
+    opts = {
+        "format": "bestaudio",
+        "quiet": True,
+        "no_warnings": True,
+        "noplaylist": True,
+        "outtmpl": outtmpl,
+    }
+    pot = config_mod.load()["pot"]
+    if pot["enabled"]:
+        opts["extractor_args"] = {"youtubepot-bgutilhttp": {"base_url": [pot["base_url"]]}}
+    return opts