yttv 0.1.0__tar.gz

yttv-0.1.0/.gitignore

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

yttv-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.

yttv-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: yttv
+Version: 0.1.0
+Summary: Play YouTube videos on a TV: Cast, Apple TV and DIAL devices, all driven through the YouTube Lounge API
+Project-URL: Homepage, https://github.com/desvaters/yttv
+Project-URL: Issues, https://github.com/desvaters/yttv/issues
+Author-email: desvaters <pypi@desvate.rs>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apple-tv,cast,chromecast,dial,lounge,tv,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: ytlounge<0.2,>=0.1
+Provides-Extra: all
+Requires-Dist: pyatv>=0.18; (python_version < '3.14') and extra == 'all'
+Requires-Dist: pychromecast>=14; extra == 'all'
+Provides-Extra: appletv
+Requires-Dist: pyatv>=0.18; (python_version < '3.14') and extra == 'appletv'
+Provides-Extra: cast
+Requires-Dist: pychromecast>=14; extra == 'cast'
+Description-Content-Type: text/markdown
+
+# yttv
+
+Play YouTube videos on a TV from the command line or from Python: Apple TV,
+Cast TVs (Chromecast, Samsung Tizen) and DIAL devices (Fire TV, WebOS).
+
+```bash
+yttv https://youtu.be/dQw4w9WgXcQ        # play on the last used screen
+yttv -a ID1 ID2                          # append to its queue, one call for all
+yttv -d bedroom ID                       # pick a screen by name or address
+yttv -l                                  # list known screens
+```
+
+## Install
+
+```bash
+pip install 'yttv[all]'        # every backend
+pip install 'yttv[cast]'       # Cast TVs only
+pip install 'yttv[appletv]'    # Apple TV only (needs Python < 3.14, see below)
+pip install yttv               # DIAL and screens paired by code; only httpx
+```
+
+Or, in a [pixi](https://pixi.sh) project: `pixi add --pypi 'yttv[all]'`.
+
+## Setting up a screen
+
+Every TV needs one of these once. yttv remembers the result under
+`~/.cache/yttv/devices.json` and picks the last used screen by default.
+
+| TV | Once | Then |
+|---|---|---|
+| Apple TV | `yttv --appletv 192.168.1.5` and type the PIN it shows | `yttv URL` opens the app and plays |
+| Chromecast, Samsung Tizen, other Cast TVs | `yttv --cast 192.168.1.6` | `yttv URL`; the first cast makes a Samsung ask you to accept Cast terms, once |
+| Fire TV, WebOS, other DIAL devices | `yttv -s` finds them | `yttv URL` wakes the TV and starts the app |
+| Anything with a YouTube app | `yttv --pair 123456789` with the code from *Settings › Link with TV code* | `yttv URL`, with the app already open |
+
+Videos are ids or URLs in any of the usual forms (`watch?v=`, `youtu.be`,
+`shorts`, `live`, `embed`, ...). A `t=` parameter becomes the start
+position. Several videos are always sent together in one call: sending
+them one after another scrambles the TV's queue.
+
+## From Python
+
+```python
+import yttv
+
+yttv.devices()                        # known screens, from the cache, no network
+yttv.cast(["dQw4w9WgXcQ"])            # play now on the last used screen
+yttv.cast([url1, url2], queue=True)   # append to its queue
+yttv.cast([url], device="bedroom")    # pick a screen
+yttv.pair("123 456 789")              # link a screen by TV code
+yttv.add_device("cast", "192.168.1.6", cast_uuid="...")
+yttv.discover()                       # DIAL search
+```
+
+Every failure is a subclass of `yttv.YttvError` with a message meant for
+people, so a caller can show it as is. `cast()` takes up to `timeout`
+seconds (default 90) for waking the TV and starting the app; that is how
+long a sleeping Fire TV needs.
+
+Screens paired with [ytcast](https://github.com/MarcoLucidi01/ytcast) are
+taken over from `~/.cache/ytcast/ytcast.json` on the first run.
+
+## How it works
+
+Three ways to reach a TV, one protocol to drive it:
+
+| Device | Finds and starts the app via | Plays via |
+|---|---|---|
+| Apple TV | [pyatv](https://github.com/postlund/pyatv), Companion protocol | Lounge |
+| Cast TVs | [pychromecast](https://github.com/home-assistant-libs/pychromecast), the YouTube receiver's `mdx` channel | Lounge |
+| DIAL devices | SSDP and the DIAL REST interface, built in | Lounge |
+
+The Lounge API is the unofficial protocol behind the "Play on TV" button in
+the phone app: pair with a screen, play a video, append to the queue. Each
+backend's only job is to bring the YouTube app up and obtain the screen's
+id; from there everything goes through
+[ytlounge](https://github.com/desvaters/ytlounge), a separate package by
+the same author that knows nothing about devices, caches or files.
+
+The Lounge API is not documented and can change at any time. If it does,
+expect this to break the same way for every tool built on it.
+
+### Python versions
+
+The core runs on Python 3.11 and newer, 3.14 included. The Apple TV backend
+depends on pyatv, which does not run on 3.14 yet; its extra is skipped
+there and `yttv` says so when an Apple TV is used.
+
+## When the search finds nothing
+
+The DIAL search is a multicast packet; every device answers with a unicast
+reply from its own address. A stateful firewall on your machine (ufw,
+firewalld) does not connect that reply to the packet you sent and drops it
+silently. Discovery then reports "no device found" although the packets are
+on the wire.
+
+```bash
+yttv --doctor
+```
+
+sends the searches, counts the replies and, when nothing comes back, prints
+the rule to check and the ufw line that fixes it. Cast TVs and Apple TV
+never answer DIAL searches; that is expected, use `--cast` and `--appletv`
+for those. `--doctor --host <ip>` probes a device directly and sidesteps
+multicast.
+
+## Origins
+
+The Lounge protocol was reverse-engineered independently by several
+people; nothing here is derived from their code, but their write-ups made
+the protocol knowable. yttv and ytlounge learned it from Marco Lucidi's
+[ytcast](https://github.com/MarcoLucidi01/ytcast) (Go), whose behaviour
+served as the reference for verifying requests on the wire, and, through
+it, from the sources ytcast itself 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 list of YouTube URL forms used in the tests comes from
+[this gist](https://gist.github.com/rodrigoborgesdeoliveira/987683cfbfcc8d800192da1e73adc486).
+
+## Development
+
+```bash
+pixi run test              # unit and fixture tests, Python 3.13 with all backends
+pixi run -e core314 test   # the same on Python 3.14 without any backend extra
+pixi run test-device       # needs a real TV on the network
+pixi run check             # build wheel and sdist, validate the metadata
+```
+
+The pixi environments take `ytlounge` from a checkout in `../ytlounge`, so
+both can be changed together; a released `yttv` gets it from PyPI.

yttv-0.1.0/README.md

@@ -0,0 +1,136 @@
+# yttv
+
+Play YouTube videos on a TV from the command line or from Python: Apple TV,
+Cast TVs (Chromecast, Samsung Tizen) and DIAL devices (Fire TV, WebOS).
+
+```bash
+yttv https://youtu.be/dQw4w9WgXcQ        # play on the last used screen
+yttv -a ID1 ID2                          # append to its queue, one call for all
+yttv -d bedroom ID                       # pick a screen by name or address
+yttv -l                                  # list known screens
+```
+
+## Install
+
+```bash
+pip install 'yttv[all]'        # every backend
+pip install 'yttv[cast]'       # Cast TVs only
+pip install 'yttv[appletv]'    # Apple TV only (needs Python < 3.14, see below)
+pip install yttv               # DIAL and screens paired by code; only httpx
+```
+
+Or, in a [pixi](https://pixi.sh) project: `pixi add --pypi 'yttv[all]'`.
+
+## Setting up a screen
+
+Every TV needs one of these once. yttv remembers the result under
+`~/.cache/yttv/devices.json` and picks the last used screen by default.
+
+| TV | Once | Then |
+|---|---|---|
+| Apple TV | `yttv --appletv 192.168.1.5` and type the PIN it shows | `yttv URL` opens the app and plays |
+| Chromecast, Samsung Tizen, other Cast TVs | `yttv --cast 192.168.1.6` | `yttv URL`; the first cast makes a Samsung ask you to accept Cast terms, once |
+| Fire TV, WebOS, other DIAL devices | `yttv -s` finds them | `yttv URL` wakes the TV and starts the app |
+| Anything with a YouTube app | `yttv --pair 123456789` with the code from *Settings › Link with TV code* | `yttv URL`, with the app already open |
+
+Videos are ids or URLs in any of the usual forms (`watch?v=`, `youtu.be`,
+`shorts`, `live`, `embed`, ...). A `t=` parameter becomes the start
+position. Several videos are always sent together in one call: sending
+them one after another scrambles the TV's queue.
+
+## From Python
+
+```python
+import yttv
+
+yttv.devices()                        # known screens, from the cache, no network
+yttv.cast(["dQw4w9WgXcQ"])            # play now on the last used screen
+yttv.cast([url1, url2], queue=True)   # append to its queue
+yttv.cast([url], device="bedroom")    # pick a screen
+yttv.pair("123 456 789")              # link a screen by TV code
+yttv.add_device("cast", "192.168.1.6", cast_uuid="...")
+yttv.discover()                       # DIAL search
+```
+
+Every failure is a subclass of `yttv.YttvError` with a message meant for
+people, so a caller can show it as is. `cast()` takes up to `timeout`
+seconds (default 90) for waking the TV and starting the app; that is how
+long a sleeping Fire TV needs.
+
+Screens paired with [ytcast](https://github.com/MarcoLucidi01/ytcast) are
+taken over from `~/.cache/ytcast/ytcast.json` on the first run.
+
+## How it works
+
+Three ways to reach a TV, one protocol to drive it:
+
+| Device | Finds and starts the app via | Plays via |
+|---|---|---|
+| Apple TV | [pyatv](https://github.com/postlund/pyatv), Companion protocol | Lounge |
+| Cast TVs | [pychromecast](https://github.com/home-assistant-libs/pychromecast), the YouTube receiver's `mdx` channel | Lounge |
+| DIAL devices | SSDP and the DIAL REST interface, built in | Lounge |
+
+The Lounge API is the unofficial protocol behind the "Play on TV" button in
+the phone app: pair with a screen, play a video, append to the queue. Each
+backend's only job is to bring the YouTube app up and obtain the screen's
+id; from there everything goes through
+[ytlounge](https://github.com/desvaters/ytlounge), a separate package by
+the same author that knows nothing about devices, caches or files.
+
+The Lounge API is not documented and can change at any time. If it does,
+expect this to break the same way for every tool built on it.
+
+### Python versions
+
+The core runs on Python 3.11 and newer, 3.14 included. The Apple TV backend
+depends on pyatv, which does not run on 3.14 yet; its extra is skipped
+there and `yttv` says so when an Apple TV is used.
+
+## When the search finds nothing
+
+The DIAL search is a multicast packet; every device answers with a unicast
+reply from its own address. A stateful firewall on your machine (ufw,
+firewalld) does not connect that reply to the packet you sent and drops it
+silently. Discovery then reports "no device found" although the packets are
+on the wire.
+
+```bash
+yttv --doctor
+```
+
+sends the searches, counts the replies and, when nothing comes back, prints
+the rule to check and the ufw line that fixes it. Cast TVs and Apple TV
+never answer DIAL searches; that is expected, use `--cast` and `--appletv`
+for those. `--doctor --host <ip>` probes a device directly and sidesteps
+multicast.
+
+## Origins
+
+The Lounge protocol was reverse-engineered independently by several
+people; nothing here is derived from their code, but their write-ups made
+the protocol knowable. yttv and ytlounge learned it from Marco Lucidi's
+[ytcast](https://github.com/MarcoLucidi01/ytcast) (Go), whose behaviour
+served as the reference for verifying requests on the wire, and, through
+it, from the sources ytcast itself 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 list of YouTube URL forms used in the tests comes from
+[this gist](https://gist.github.com/rodrigoborgesdeoliveira/987683cfbfcc8d800192da1e73adc486).
+
+## Development
+
+```bash
+pixi run test              # unit and fixture tests, Python 3.13 with all backends
+pixi run -e core314 test   # the same on Python 3.14 without any backend extra
+pixi run test-device       # needs a real TV on the network
+pixi run check             # build wheel and sdist, validate the metadata
+```
+
+The pixi environments take `ytlounge` from a checkout in `../ytlounge`, so
+both can be changed together; a released `yttv` gets it from PyPI.

yttv-0.1.0/pixi.toml

@@ -0,0 +1,64 @@
+[workspace]
+name = "yttv"
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+
+# ---------------------------------------------------------------------------
+# Shared by every environment: the core's runtime dependency, the test
+# runner and the tasks. The Python version and the project install live in
+# the features below, because they differ between environments.
+# ---------------------------------------------------------------------------
+[dependencies]
+# The only runtime dependency of the core. Without it: ModuleNotFoundError
+# on `import ytlounge`.
+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"
+# `pixi run check` validates the built metadata the way PyPI will; also the
+# eventual upload. Without it: "twine: command not found".
+twine = ">=6"
+
+[tasks]
+# Unit and fixture tests only. Device tests are opt-in via `pixi run test-device`
+# because they need a TV on the network and would fail in any other setup.
+test = "pytest -m 'not device'"
+test-device = "pytest -m device"
+test-all = "pytest"
+# Release: build both artifacts into dist/, then let twine validate them.
+build = "python -m build"
+check = { cmd = "twine check dist/*", depends-on = ["build"] }
+
+# ---------------------------------------------------------------------------
+# backends: Python 3.13 with every backend extra. 3.13 and not 3.14 because
+# pyatv (Apple TV backend) breaks on 3.14, see NOTES.md §5. With 3.14 the
+# appletv extra would silently resolve to nothing (its marker excludes it)
+# and every Apple TV test would error with ModuleNotFoundError: pyatv.
+# ---------------------------------------------------------------------------
+[feature.backends.dependencies]
+python = "3.13.*"
+
+[feature.backends.pypi-dependencies]
+# The project itself, editable, with all backend extras. Editable so that
+# changes under src/ are visible without reinstalling; without this line
+# `import yttv` fails inside the environment.
+yttv = { path = ".", editable = true, extras = ["all"] }
+# The protocol core from its own checkout next door, editable, so both can
+# be developed together. Released installs get it from PyPI instead.
+ytlounge = { path = "../ytlounge", editable = true }
+
+# ---------------------------------------------------------------------------
+# py314: the newest Python without any backend extra. Proves that ytlounge
+# and the yttv core do not depend on anything that caps the Python version.
+# ---------------------------------------------------------------------------
+[feature.py314.dependencies]
+python = "3.14.*"
+
+[feature.py314.pypi-dependencies]
+yttv = { path = ".", editable = true }
+ytlounge = { path = "../ytlounge", editable = true }
+
+[environments]
+default = { features = ["backends"] }
+core314 = { features = ["py314"] }

yttv-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "yttv"
+version = "0.1.0"
+description = "Play YouTube videos on a TV: Cast, Apple TV and DIAL devices, all driven through the YouTube Lounge API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "desvaters", email = "pypi@desvate.rs" }]
+keywords = ["youtube", "tv", "cast", "chromecast", "apple-tv", "dial", "lounge"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "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",
+]
+# ytlounge is the protocol core (same author, separate distribution) and
+# brings httpx, the only other runtime dependency, with it.
+dependencies = ["ytlounge>=0.1,<0.2", "httpx>=0.27"]
+
+[project.optional-dependencies]
+# Cast TVs (e.g. Samsung Tizen): discovery via mDNS and app launch through
+# pychromecast. Only the launch and screenId retrieval come from here; play and
+# queue always go through ytlounge.
+cast = ["pychromecast>=14"]
+# Apple TV: app launch through the Companion protocol. pyatv does not run on
+# Python 3.14 (asyncio.get_event_loop() raises), which is why this is an extra
+# and not a hard dependency: it must not cap the Python version of the core.
+appletv = ["pyatv>=0.18; python_version < '3.14'"]
+all = ["yttv[cast,appletv]"]
+
+[project.scripts]
+yttv = "yttv.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/desvaters/yttv"
+Issues = "https://github.com/desvaters/yttv/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yttv"]
+
+# The sdist is what people read; keep the reference implementation and the
+# private working notes out of it (both are git-excluded locally, which
+# hatch does not see).
+[tool.hatch.build.targets.sdist]
+exclude = ["/upstream", "/NOTES.md", "/HANDOFF.md", "/.pixi", "/pixi.lock", "/.claude"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "device: needs a real TV on the network (deselected by default in pixi tasks)",
+]

yttv-0.1.0/src/yttv/__init__.py

@@ -0,0 +1,45 @@
+"""yttv: play YouTube videos on a TV.
+
+Device backends (Cast, Apple TV, DIAL) bring the YouTube app to the front and
+obtain the screen's ``screen_id``; the ``ytlounge`` package does the actual
+playing.
+
+The public API is three functions::
+
+    import yttv
+    yttv.devices()                      # paired screens, from the cache
+    yttv.cast(["dQw4w9WgXcQ"])          # play now on the last used screen
+    yttv.cast([url1, url2], queue=True) # append to the queue
+    yttv.pair("123 456 789")            # link a screen by TV code
+"""
+
+from .api import (
+    CastError,
+    InvalidVideoError,
+    NoDeviceError,
+    PairError,
+    YttvError,
+    add_device,
+    attach,
+    cast,
+    devices,
+    discover,
+    pair,
+)
+from .cache import Cache, Device
+
+__all__ = [
+    "Cache",
+    "CastError",
+    "Device",
+    "InvalidVideoError",
+    "NoDeviceError",
+    "PairError",
+    "YttvError",
+    "add_device",
+    "attach",
+    "cast",
+    "devices",
+    "discover",
+    "pair",
+]