ytlounge 0.1.0__tar.gz

ytlounge-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# pixi
+.pixi/
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/

ytlounge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 desvaters
+
+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 THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ytlounge-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: ytlounge
+Version: 0.1.0
+Summary: Client for the YouTube Lounge API: pair with a TV screen, play videos, manage its queue
+Project-URL: Homepage, https://github.com/desvaters/ytlounge
+Project-URL: Issues, https://github.com/desvaters/ytlounge/issues
+Author-email: desvaters <pypi@desvate.rs>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cast,lounge,queue,remote,tv,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# ytlounge
+
+Client for the YouTube Lounge API: the protocol behind the "Play on TV"
+button. Pair with a screen once, then play videos on it and manage its
+queue from Python. Synchronous, one dependency (httpx), no device code.
+
+```python
+from ytlounge import Lounge
+
+with Lounge(name="my-remote") as lounge:
+    screen = lounge.pair("123 456 789")     # code from Settings › Link with TV code
+    lounge.play(screen, ["dQw4w9WgXcQ"])    # play now
+    lounge.add(screen, ["jNQXAC9IVRw"])     # append to the queue
+```
+
+`Screen` is a small frozen dataclass; keep `screen_id` and you can always
+get a fresh token with `lounge.refresh(screen)`. Tokens live about two
+weeks, `Screen.is_expired()` tells you when.
+
+## Install
+
+```bash
+pip install ytlounge
+```
+
+Python 3.11 or newer.
+
+## What it does and does not do
+
+- Pair with a TV code, refresh a token from a screen id, open a session,
+  play a list of videos (with a start index and start time), append videos
+  to the queue.
+- `ytlounge.video.parse_video` turns an id or any of the usual YouTube
+  URL forms into a `Video` with an optional start time.
+- It does **not** find TVs, launch apps or store anything. That is the job
+  of a tool built on top, such as [yttv](https://github.com/desvaters/yttv),
+  which adds Cast, Apple TV and DIAL backends, a cache and a command line.
+
+The Lounge API is not documented by Google and can change at any time.
+Everything below was verified on the wire in September 2026 and is kept as
+assertions in the tests; when something breaks, that is where to look.
+
+## The protocol, as verified
+
+| Field | Lives | Comes from |
+|---|---|---|
+| `screen_id` | for good, survives a cold start of the TV | one pairing with a TV code |
+| `lounge_token` | about 13 days | `get_lounge_token_batch` from the screen id |
+| `SID`, `gsessionid` | one session | a bind at the start of every play/add |
+
+- **Pair:** `POST /api/lounge/pairing/get_screen` with `pairing_code=`.
+  The `expiration` here is a string, on the token endpoint a number.
+- **Refresh:** `POST /api/lounge/pairing/get_lounge_token_batch` with
+  `screen_ids=`. A refresh does not revoke earlier tokens.
+- **Session:** `POST /api/lounge/bc/bind?CVER=1&RID=1&VER=8&app=youtube-desktop&device=REMOTE_CONTROL&id=remote&loungeIdToken=…&name=…`
+  with an empty body. The endpoint insists on a `Content-Length` header
+  even then (httpx always sends one). The reply is framed: a decimal
+  length on its own line, then that many characters of a JSON array of
+  numbered messages; `["c", SID, …]` and `["S", gsessionid]` are in the
+  first frame, followed by the screen's status and current queue.
+- **Play:** `POST bind?CVER=1&RID=2&SID=…&VER=8&gsessionid=…&loungeIdToken=…`,
+  form body `count=1&req0__sc=setPlaylist&req0_currentIndex=0&req0_currentTime=0&req0_videoId=…&req0_videoIds=a,b,c`.
+- **Add:** same query, `req0__sc=addVideo&req0_videoId=…`, one request per
+  video with a random 2–5 s pause before each. The pause is not cosmetic:
+  without it consecutive adds race on the screen and the queue comes out
+  incomplete or reordered.
+
+## Development
+
+```bash
+pixi run test                                   # fixture tests
+YTLOUNGE_SCREEN_ID=… pixi run test-device       # against the real API, no TV changes
+pixi run check                                  # build and validate the artifacts
+```
+
+## Origins
+
+The Lounge protocol was reverse-engineered independently by several
+people. This client contains none of their code, but learned the protocol
+from Marco Lucidi's [ytcast](https://github.com/MarcoLucidi01/ytcast),
+whose requests were the reference for verifying this implementation on
+the wire, and through it from the sources ytcast credits:
+
+- https://0x41.cf/automation/2021/03/02/google-assistant-youtube-smart-tvs.html
+- https://github.com/thedroidgeek/youtube-cast-automation-api
+- https://github.com/mutantmonkey/youtube-remote
+- https://bugs.xdavidhu.me/google/2021/04/05/i-built-a-tv-that-plays-all-of-your-private-youtube-videos
+- https://github.com/aykevl/plaincast
+- https://github.com/ur1katz/casttube
+
+The YouTube URL forms in the tests come from
+[this gist](https://gist.github.com/rodrigoborgesdeoliveira/987683cfbfcc8d800192da1e73adc486).

ytlounge-0.1.0/README.md

@@ -0,0 +1,92 @@
+# ytlounge
+
+Client for the YouTube Lounge API: the protocol behind the "Play on TV"
+button. Pair with a screen once, then play videos on it and manage its
+queue from Python. Synchronous, one dependency (httpx), no device code.
+
+```python
+from ytlounge import Lounge
+
+with Lounge(name="my-remote") as lounge:
+    screen = lounge.pair("123 456 789")     # code from Settings › Link with TV code
+    lounge.play(screen, ["dQw4w9WgXcQ"])    # play now
+    lounge.add(screen, ["jNQXAC9IVRw"])     # append to the queue
+```
+
+`Screen` is a small frozen dataclass; keep `screen_id` and you can always
+get a fresh token with `lounge.refresh(screen)`. Tokens live about two
+weeks, `Screen.is_expired()` tells you when.
+
+## Install
+
+```bash
+pip install ytlounge
+```
+
+Python 3.11 or newer.
+
+## What it does and does not do
+
+- Pair with a TV code, refresh a token from a screen id, open a session,
+  play a list of videos (with a start index and start time), append videos
+  to the queue.
+- `ytlounge.video.parse_video` turns an id or any of the usual YouTube
+  URL forms into a `Video` with an optional start time.
+- It does **not** find TVs, launch apps or store anything. That is the job
+  of a tool built on top, such as [yttv](https://github.com/desvaters/yttv),
+  which adds Cast, Apple TV and DIAL backends, a cache and a command line.
+
+The Lounge API is not documented by Google and can change at any time.
+Everything below was verified on the wire in September 2026 and is kept as
+assertions in the tests; when something breaks, that is where to look.
+
+## The protocol, as verified
+
+| Field | Lives | Comes from |
+|---|---|---|
+| `screen_id` | for good, survives a cold start of the TV | one pairing with a TV code |
+| `lounge_token` | about 13 days | `get_lounge_token_batch` from the screen id |
+| `SID`, `gsessionid` | one session | a bind at the start of every play/add |
+
+- **Pair:** `POST /api/lounge/pairing/get_screen` with `pairing_code=`.
+  The `expiration` here is a string, on the token endpoint a number.
+- **Refresh:** `POST /api/lounge/pairing/get_lounge_token_batch` with
+  `screen_ids=`. A refresh does not revoke earlier tokens.
+- **Session:** `POST /api/lounge/bc/bind?CVER=1&RID=1&VER=8&app=youtube-desktop&device=REMOTE_CONTROL&id=remote&loungeIdToken=…&name=…`
+  with an empty body. The endpoint insists on a `Content-Length` header
+  even then (httpx always sends one). The reply is framed: a decimal
+  length on its own line, then that many characters of a JSON array of
+  numbered messages; `["c", SID, …]` and `["S", gsessionid]` are in the
+  first frame, followed by the screen's status and current queue.
+- **Play:** `POST bind?CVER=1&RID=2&SID=…&VER=8&gsessionid=…&loungeIdToken=…`,
+  form body `count=1&req0__sc=setPlaylist&req0_currentIndex=0&req0_currentTime=0&req0_videoId=…&req0_videoIds=a,b,c`.
+- **Add:** same query, `req0__sc=addVideo&req0_videoId=…`, one request per
+  video with a random 2–5 s pause before each. The pause is not cosmetic:
+  without it consecutive adds race on the screen and the queue comes out
+  incomplete or reordered.
+
+## Development
+
+```bash
+pixi run test                                   # fixture tests
+YTLOUNGE_SCREEN_ID=… pixi run test-device       # against the real API, no TV changes
+pixi run check                                  # build and validate the artifacts
+```
+
+## Origins
+
+The Lounge protocol was reverse-engineered independently by several
+people. This client contains none of their code, but learned the protocol
+from Marco Lucidi's [ytcast](https://github.com/MarcoLucidi01/ytcast),
+whose requests were the reference for verifying this implementation on
+the wire, and through it from the sources ytcast credits:
+
+- https://0x41.cf/automation/2021/03/02/google-assistant-youtube-smart-tvs.html
+- https://github.com/thedroidgeek/youtube-cast-automation-api
+- https://github.com/mutantmonkey/youtube-remote
+- https://bugs.xdavidhu.me/google/2021/04/05/i-built-a-tv-that-plays-all-of-your-private-youtube-videos
+- https://github.com/aykevl/plaincast
+- https://github.com/ur1katz/casttube
+
+The YouTube URL forms in the tests come from
+[this gist](https://gist.github.com/rodrigoborgesdeoliveira/987683cfbfcc8d800192da1e73adc486).

ytlounge-0.1.0/pixi.toml

@@ -0,0 +1,28 @@
+[workspace]
+name = "ytlounge"
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+[dependencies]
+# Unpinned on purpose: the client must work on the newest Python; nothing
+# here caps the version. Today that resolves to 3.14.
+python = ">=3.11"
+# The only runtime dependency. Without it: ModuleNotFoundError on import.
+httpx = ">=0.27"
+# Test runner. Without it `pixi run test` fails with "pytest: command not found".
+pytest = ">=8"
+# Builds wheel and sdist for `pixi run build`. Without it: "No module named build".
+python-build = ">=1.2"
+# Validates the built metadata the way PyPI will, and does the upload.
+twine = ">=6"
+
+[pypi-dependencies]
+# The project itself, editable, so changes under src/ are visible at once.
+ytlounge = { path = ".", editable = true }
+
+[tasks]
+# Fixture tests only. The device test needs YTLOUNGE_SCREEN_ID and network.
+test = "pytest -m 'not device'"
+test-device = "pytest -m device"
+build = "python -m build"
+check = { cmd = "twine check dist/*", depends-on = ["build"] }

ytlounge-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ytlounge"
+version = "0.1.0"
+description = "Client for the YouTube Lounge API: pair with a TV screen, play videos, manage its queue"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "desvaters", email = "pypi@desvate.rs" }]
+keywords = ["youtube", "lounge", "tv", "remote", "cast", "queue"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Software Development :: Libraries",
+]
+# The only runtime dependency. httpx always sends Content-Length, which the
+# Lounge bind endpoint requires even for an empty body.
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/desvaters/ytlounge"
+Issues = "https://github.com/desvaters/ytlounge/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ytlounge"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/.pixi", "/pixi.lock", "/.claude", "/NOTES.md", "/HANDOFF.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "device: talks to the real Lounge API and needs a paired screen (opt-in)",
+]

ytlounge-0.1.0/src/ytlounge/__init__.py

@@ -0,0 +1,31 @@
+"""ytlounge: a client for the YouTube Lounge API.
+
+The Lounge API is the unofficial protocol that a phone or browser uses to
+drive the YouTube app on a TV: pair with a screen, play a video, append to the
+queue. Every way of reaching a TV (Cast, Apple TV, DIAL) ends up here.
+
+Scope of this package: a ``screen_id`` goes in, play and queue come out.
+It knows nothing about device discovery, app launching, caches or file
+paths; tools such as yttv build those on top.
+"""
+
+from .client import Lounge, Session
+from .models import (
+    CommandError,
+    LoungeError,
+    PairingError,
+    Screen,
+    SessionError,
+    TokenError,
+)
+
+__all__ = [
+    "CommandError",
+    "Lounge",
+    "LoungeError",
+    "PairingError",
+    "Screen",
+    "Session",
+    "SessionError",
+    "TokenError",
+]

ytlounge-0.1.0/src/ytlounge/chunked.py

@@ -0,0 +1,74 @@
+"""Parser for the framed responses of ``/api/lounge/bc/bind``.
+
+The body is a sequence of frames. Each frame is a decimal length on its own
+line followed by that many characters of JSON: an array of numbered messages
+``[index, [name, payload...]]``. The session handshake answers with the
+session id as ``["c", sid, ...]`` and the gsession id as ``["S", gsessionid]``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+Message = list[Any]
+
+
+def parse_frames(body: str) -> list[Message]:
+    """Return every message from every frame in ``body``, in order.
+
+    Raises ``ValueError`` on a malformed frame.
+    """
+    messages: list[Message] = []
+    pos = 0
+    while pos < len(body):
+        newline = body.find("\n", pos)
+        if newline == -1:
+            raise ValueError(f"missing length line at offset {pos}")
+        length_text = body[pos:newline].strip()
+        if not length_text:
+            pos = newline + 1
+            continue
+        try:
+            length = int(length_text)
+        except ValueError as exc:
+            raise ValueError(f"bad frame length {length_text!r}") from exc
+        start = newline + 1
+        payload = body[start : start + length]
+        try:
+            frame = json.loads(payload)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"bad frame JSON at offset {start}: {exc}") from exc
+        if not isinstance(frame, list):
+            raise ValueError("frame is not a JSON array")
+        messages.extend(frame)
+        pos = start + length
+    return messages
+
+
+def find_event(messages: list[Message], name: str) -> Message | None:
+    """Return the first ``[name, payload...]`` event with the given name."""
+    for message in messages:
+        if (
+            isinstance(message, list)
+            and len(message) >= 2
+            and isinstance(message[1], list)
+            and message[1]
+            and message[1][0] == name
+        ):
+            return message[1]
+    return None
+
+
+def session_ids(messages: list[Message]) -> tuple[str, str]:
+    """Extract ``(sid, gsessionid)`` from a bind handshake.
+
+    Raises ``ValueError`` when either is missing.
+    """
+    c_event = find_event(messages, "c")
+    s_event = find_event(messages, "S")
+    if c_event is None or len(c_event) < 2 or not c_event[1]:
+        raise ValueError("no session id ('c' event) in bind response")
+    if s_event is None or len(s_event) < 2 or not s_event[1]:
+        raise ValueError("no gsessionid ('S' event) in bind response")
+    return str(c_event[1]), str(s_event[1])