u-transcript-max 0.1.0a2__tar.gz → 0.1.0a4__tar.gz

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: u-transcript-max
-Version: 0.1.0a2
+Version: 0.1.0a4
 Summary: YouTube transcripts, AI translation and downloads for Python, with zero dependencies.
 Project-URL: Homepage, https://github.com/U-C4N/U-transkript
 Project-URL: Issues, https://github.com/U-C4N/U-transkript/issues
@@ -72,7 +72,7 @@ transcript.save("rick.srt")  # also .vtt, .json and .txt
 turkish = utmax.translate(transcript, "tr", model="claude=claude-opus-5-5")  # needs [claude]
 utmax.bilingual(transcript, turkish).save("rick.en+tr.srt")
 
-utmax.download("dQw4w9WgXcQ", "rick.mp4")  # H.264 up to 1080p with English subtitles
+utmax.download("dQw4w9WgXcQ", "rick.mp4")  # the best MP4 (AV1 or H.264) with English subtitles
 videos = utmax.list_videos("@RickAstleyYT", kind="videos", limit=20)
 ```
 
@@ -84,16 +84,18 @@ from utmax.compat import YouTubeTranscriptApi
 
 ## MCP server
 
-`utmax-mcp` gives an AI assistant four tools: `list_tracks`, `get_transcript`, `list_videos`
-and `download`. It needs no API key: ask for a translation and the assistant translates the
-transcript itself. The commands below start it with `uvx` from
-[uv](https://docs.astral.sh/uv/getting-started/installation/), which installs it from PyPI on
-first use.
+`utmax-mcp` gives an AI assistant six tools: `list_tracks`, `get_transcript`, `list_formats`,
+`list_videos`, `download` and `save_subtitles`. It needs no API key. Ask it to download a video
+and the assistant asks which file type, which of the video's resolutions and which subtitles
+(original or translated) you want; ask for a translation and it translates the subtitles
+itself. The commands below start it with `uvx` from
+[uv](https://docs.astral.sh/uv/getting-started/installation/), which installs it from PyPI;
+`@latest` makes it move to each new release the next time the client starts the server.
 
 ### Claude Code
 
 ```bash
-claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]" utmax-mcp
+claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]@latest" utmax-mcp
 ```
 
 `claude mcp get utmax` should say `Connected`; inside Claude Code, `/mcp` lists the server.
@@ -101,7 +103,7 @@ claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]" utmax-mc
 ### Codex
 
 ```bash
-codex mcp add utmax -- uvx --from "u-transcript-max[mcp]" utmax-mcp
+codex mcp add utmax -- uvx --from "u-transcript-max[mcp]@latest" utmax-mcp
 ```
 
 A long download can outlast Codex's default tool timeout, and the first start installs the
@@ -111,7 +113,7 @@ file):
 ```toml
 [mcp_servers.utmax]
 command = "uvx"
-args = ["--from", "u-transcript-max[mcp]", "utmax-mcp"]
+args = ["--from", "u-transcript-max[mcp]@latest", "utmax-mcp"]
 startup_timeout_sec = 60
 tool_timeout_sec = 1800
 ```
@@ -126,7 +128,7 @@ restart Claude Desktop:
   "mcpServers": {
     "utmax": {
       "command": "uvx",
-      "args": ["--from", "u-transcript-max[mcp]", "utmax-mcp"]
+      "args": ["--from", "u-transcript-max[mcp]@latest", "utmax-mcp"]
     }
   }
 }

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/README.md

@@ -33,7 +33,7 @@ transcript.save("rick.srt")  # also .vtt, .json and .txt
 turkish = utmax.translate(transcript, "tr", model="claude=claude-opus-5-5")  # needs [claude]
 utmax.bilingual(transcript, turkish).save("rick.en+tr.srt")
 
-utmax.download("dQw4w9WgXcQ", "rick.mp4")  # H.264 up to 1080p with English subtitles
+utmax.download("dQw4w9WgXcQ", "rick.mp4")  # the best MP4 (AV1 or H.264) with English subtitles
 videos = utmax.list_videos("@RickAstleyYT", kind="videos", limit=20)
 ```
 
@@ -45,16 +45,18 @@ from utmax.compat import YouTubeTranscriptApi
 
 ## MCP server
 
-`utmax-mcp` gives an AI assistant four tools: `list_tracks`, `get_transcript`, `list_videos`
-and `download`. It needs no API key: ask for a translation and the assistant translates the
-transcript itself. The commands below start it with `uvx` from
-[uv](https://docs.astral.sh/uv/getting-started/installation/), which installs it from PyPI on
-first use.
+`utmax-mcp` gives an AI assistant six tools: `list_tracks`, `get_transcript`, `list_formats`,
+`list_videos`, `download` and `save_subtitles`. It needs no API key. Ask it to download a video
+and the assistant asks which file type, which of the video's resolutions and which subtitles
+(original or translated) you want; ask for a translation and it translates the subtitles
+itself. The commands below start it with `uvx` from
+[uv](https://docs.astral.sh/uv/getting-started/installation/), which installs it from PyPI;
+`@latest` makes it move to each new release the next time the client starts the server.
 
 ### Claude Code
 
 ```bash
-claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]" utmax-mcp
+claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]@latest" utmax-mcp
 ```
 
 `claude mcp get utmax` should say `Connected`; inside Claude Code, `/mcp` lists the server.
@@ -62,7 +64,7 @@ claude mcp add --scope user utmax -- uvx --from "u-transcript-max[mcp]" utmax-mc
 ### Codex
 
 ```bash
-codex mcp add utmax -- uvx --from "u-transcript-max[mcp]" utmax-mcp
+codex mcp add utmax -- uvx --from "u-transcript-max[mcp]@latest" utmax-mcp
 ```
 
 A long download can outlast Codex's default tool timeout, and the first start installs the
@@ -72,7 +74,7 @@ file):
 ```toml
 [mcp_servers.utmax]
 command = "uvx"
-args = ["--from", "u-transcript-max[mcp]", "utmax-mcp"]
+args = ["--from", "u-transcript-max[mcp]@latest", "utmax-mcp"]
 startup_timeout_sec = 60
 tool_timeout_sec = 1800
 ```
@@ -87,7 +89,7 @@ restart Claude Desktop:
   "mcpServers": {
     "utmax": {
       "command": "uvx",
-      "args": ["--from", "u-transcript-max[mcp]", "utmax-mcp"]
+      "args": ["--from", "u-transcript-max[mcp]@latest", "utmax-mcp"]
     }
   }
 }

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/src/utmax/__init__.py

@@ -10,7 +10,7 @@ Quick start::
     turkish = utmax.translate(transcript, "tr", model="claude=claude-opus-5")
     utmax.bilingual(transcript, turkish).save("rick.en+tr.srt")
 
-    utmax.download("dQw4w9WgXcQ", "rick.mp4")  # H.264 + AAC + English subtitles
+    utmax.download("dQw4w9WgXcQ", "rick.mp4")  # the best MP4 (AV1 or H.264), English subtitles
 
     videos = utmax.list_videos("@RickAstleyYT", kind="videos", limit=20)
     utmax.fetch_many(videos, out_dir="subs")  # one .srt per video
@@ -77,6 +77,7 @@ from utmax.models import (
     Container,
     DownloadResult,
     Format,
+    FormatList,
     FormatName,
     Language,
     Progress,
@@ -112,6 +113,7 @@ __all__ = [
     "FFmpegNotFound",
     "FailedToCreateConsentCookie",
     "Format",
+    "FormatList",
     "FormatName",
     "FormatNotAvailable",
     "InvalidModelSpec",
@@ -161,6 +163,7 @@ __all__ = [
     "download_many",
     "fetch",
     "fetch_many",
+    "list_formats",
     "list_tracks",
     "list_videos",
     "translate",
@@ -234,6 +237,23 @@ def list_tracks(video: str) -> TrackList:
     return _client().list_tracks(video)
 
 
+def list_formats(video: str) -> FormatList:
+    """The streams of a video utmax can download, in YouTube's order; :func:`download` picks
+    among those its file type holds (see :func:`utmax.core.streams.file_types`).
+
+    Example::
+
+        formats = utmax.list_formats("dQw4w9WgXcQ")
+        print([f.label for f in formats if f.kind == "video"])  # "401 mp4 av1 2160p25", ...
+        utmax.download("dQw4w9WgXcQ", "rick.mp4", resolution=720)  # lines of the short side
+
+    Raises:
+        InvalidVideoId: ``video`` is not a YouTube video URL or ID.
+        VideoUnavailable, VideoUnplayable, AgeRestricted, RequestBlocked: YouTube refused.
+    """
+    return _client().list_formats(video)
+
+
 def video_info(video: str) -> VideoInfo:
     """Title, channel and duration of a video."""
     return _client().video_info(video)
@@ -334,7 +354,8 @@ def download(
     path: str | os.PathLike[str],
     *,
     format: Container | None = None,
-    quality: Quality = "compat",
+    quality: Quality = "best",
+    resolution: int | None = None,
     subtitles: Sequence[str | Transcript] | None = None,
     subtitle_mode: SubtitleMode = "embed",
     default_subtitle: str | None = None,
@@ -350,9 +371,9 @@ def download(
 
     Examples::
 
-        utmax.download("dQw4w9WgXcQ", "rick.mp4")  # H.264 up to 1080p, AAC, English subtitles
+        utmax.download("dQw4w9WgXcQ", "rick.mp4")  # the best AV1 or H.264, AAC, English subtitles
         utmax.download("dQw4w9WgXcQ", "rick.m4a")  # audio only; no ffmpeg needed
-        utmax.download("dQw4w9WgXcQ", "videos/", quality="max")  # AV1 up to 4K, named by title
+        utmax.download("dQw4w9WgXcQ", "videos/")  # the best MP4 (AV1 up to 8K), named by title
         utmax.download("dQw4w9WgXcQ", "rick.mp4", subtitles=[english, turkish])
 
     Args:
@@ -362,8 +383,11 @@ def download(
             ``"{title} [{video_id}].{ext}"``.
         format: the file type when ``path`` is a folder or has no extension; it must match the
             extension otherwise.
-        quality: ``"compat"`` (H.264 up to 1080p, plays everywhere) or ``"max"`` (AV1 or
-            H.264 up to 2160p; ``.mp4`` only).
+        quality: ``"best"`` (the largest picture the file type holds: AV1 or H.264 in
+            ``.mp4``, HDR where it is the only way to a larger picture; H.264 in ``.mov``) or
+            ``"compat"`` (H.264 up to 1080p, plays everywhere).
+        resolution: the largest picture to take, in lines of its short side (``1080`` means at
+            most 1080p); ``None`` takes the largest. :func:`list_formats` shows what exists.
         subtitles: language codes and/or transcripts (translations and bilingual ones too).
             ``None`` embeds the spoken-language track in videos and adds nothing to audio;
             ``[]`` adds none. Codes are chosen like :func:`fetch`, never with YouTube's own
@@ -373,7 +397,8 @@ def download(
         default_subtitle: the language code of the embedded track shown by default (else the
             first one).
         connections: parallel connections, 1 to 16.
-        chunk_size: bytes per range request, at least 256 KiB.
+        chunk_size: bytes per range request, at least 256 KiB (YouTube slows down larger
+            requests of 8 MiB, so the default is 2 MiB).
         resume: continue an interrupted download from its ``.part`` files.
         overwrite: replace existing files instead of raising :class:`OutputExists`.
         ffmpeg: the ffmpeg executable for ``.mp3`` (default: ``$UTMAX_FFMPEG``, then ``PATH``).
@@ -396,6 +421,8 @@ def download(
         FormatNotAvailable: no stream fits the type and quality (live streams, for example).
         StreamForbidden, DownloadIncomplete, NetworkError: the download failed; call again to
             resume.
+        PoTokenRequired: YouTube serves only the start of this video's streams without a
+            proof-of-origin token, which utmax cannot create.
         DownloadCancelled: ``cancel`` was set.
         MuxError, FFmpegFailed: the file could not be assembled.
         VideoUnavailable, VideoUnplayable, AgeRestricted, RequestBlocked: YouTube refused.
@@ -405,6 +432,7 @@ def download(
         path,
         format=format,
         quality=quality,
+        resolution=resolution,
         subtitles=subtitles,
         subtitle_mode=subtitle_mode,
         default_subtitle=default_subtitle,
@@ -597,7 +625,8 @@ def download_many(
     out_dir: str | os.PathLike[str],
     *,
     format: Container = "mp4",
-    quality: Quality = "compat",
+    quality: Quality = "best",
+    resolution: int | None = None,
     subtitles: Sequence[str] | None = None,
     subtitle_mode: SubtitleMode = "embed",
     concurrency: int = 2,
@@ -616,8 +645,8 @@ def download_many(
     Args:
         videos: video IDs, URLs and/or entries of a :func:`list_videos` result.
         out_dir: the folder for the files (created when missing).
-        format, quality, subtitles, subtitle_mode, ffmpeg: as in :func:`download`, for every
-            video; ``subtitles`` takes language codes only.
+        format, quality, resolution, subtitles, subtitle_mode, ffmpeg: as in :func:`download`,
+            for every video; ``subtitles`` takes language codes only.
         concurrency: how many videos are downloaded at the same time, 1 to 16 (each with four
             connections).
         skip_existing: skip a video, without any request, when ``out_dir`` already holds its
@@ -641,6 +670,7 @@ def download_many(
         out_dir,
         format=format,
         quality=quality,
+        resolution=resolution,
         subtitles=subtitles,
         subtitle_mode=subtitle_mode,
         concurrency=concurrency,

u_transcript_max-0.1.0a4/src/utmax/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a4"

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/src/utmax/adapters/downloader.py

@@ -34,7 +34,13 @@ from utmax.core.downloads import (
 )
 from utmax.core.retry import backoff_delay, is_transient_status
 from utmax.core.streams import Stream
-from utmax.errors import DownloadCancelled, DownloadIncomplete, NetworkError, StreamForbidden
+from utmax.errors import (
+    DownloadCancelled,
+    DownloadIncomplete,
+    NetworkError,
+    PoTokenRequired,
+    StreamForbidden,
+)
 from utmax.models import Progress, ProgressPhase
 from utmax.transport import HttpRequest, HttpStream
 
@@ -173,6 +179,8 @@ class Downloader:
         Raises:
             DownloadCancelled: ``cancel`` was set; the parts stay for a resume.
             StreamForbidden: YouTube kept answering 403 after ``max_refreshes`` fresh URLs.
+            PoTokenRequired: ... while still serving the stream's first byte: it wants a
+                proof-of-origin token for this video.
             DownloadIncomplete: a stream kept failing, changed on YouTube's side or answered
                 an unexpected status.
             NetworkError: the connection kept failing.
@@ -350,13 +358,7 @@ class Downloader:
             if self._fresh_streams is None or self._refreshes >= self._max_refreshes:
                 if not required:
                     return
-                itag = target.stream.format.itag
-                raise StreamForbidden(
-                    f"YouTube refused stream {itag} of video {self._video_id} (HTTP 403) "
-                    f"after {self._refreshes} fresh URLs.",
-                    itag=itag,
-                    video_id=self._video_id,
-                )
+                raise self._forbidden(target)
             self._refreshes += 1
             log.info(
                 "getting fresh stream URLs for %s (%d/%d)",
@@ -370,6 +372,40 @@ class Downloader:
                     each.stream = self._match(each, fresh)
                 self._generation += 1
 
+    def _forbidden(self, target: _Target) -> PoTokenRequired | StreamForbidden:
+        """Why YouTube keeps refusing a stream: without a proof-of-origin token it serves only
+        the first megabyte of some videos' streams, so a stream whose first byte still comes
+        needs that token; otherwise its URLs do not work from here."""
+        stream = target.stream
+        itag = stream.format.itag
+        if self._serves_first_byte(stream):
+            return PoTokenRequired(
+                f"YouTube serves only the start of stream {itag} of video {self._video_id} and "
+                "refuses the rest (HTTP 403): it wants a proof-of-origin (PO) token for this "
+                "video, which utmax cannot create.",
+                suggestion=(
+                    "YouTube asks for this token for some videos only, and not always: try "
+                    "again later. The video's subtitles can still be fetched."
+                ),
+                video_id=self._video_id,
+            )
+        return StreamForbidden(
+            f"YouTube refused stream {itag} of video {self._video_id} (HTTP 403) "
+            f"after {self._refreshes} fresh URLs.",
+            itag=itag,
+            video_id=self._video_id,
+        )
+
+    def _serves_first_byte(self, stream: Stream) -> bool:
+        try:
+            body = self._opener(self._request(stream, "bytes=0-0"))
+        except NetworkError:
+            return False
+        try:
+            return body.status == 206
+        finally:
+            body.close()
+
     def _match(self, target: _Target, fresh: Sequence[Stream]) -> Stream:
         """The fresh stream with the same itag, size and version as ``target``'s."""
         old = target.stream.format

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/src/utmax/adapters/innertube.py

@@ -5,15 +5,24 @@ from __future__ import annotations
 
 import json
 import logging
+import threading
 from collections.abc import Callable
 from functools import partial
 from typing import Any, TypeVar
 
 from utmax.adapters.watch_page import fetch_api_key
 from utmax.core.captions import caption_url, check_caption_url
-from utmax.core.clients import ANDROID, DESKTOP_USER_AGENT, ORDER, ClientProfile, Purpose
+from utmax.core.clients import (
+    ANDROID,
+    DESKTOP_USER_AGENT,
+    ORDER,
+    VISIONOS,
+    ClientProfile,
+    Purpose,
+)
 from utmax.core.playability import check_playability
 from utmax.core.player import PlayerData, parse_player_response
+from utmax.core.ytdata import mapping
 from utmax.errors import (
     IpBlocked,
     RequestBlocked,
@@ -34,24 +43,36 @@ _HTTP_LEVEL_FAILURES = (YouTubeRequestFailed, YouTubeDataUnparsable)
 
 
 class InnerTubeClient:
-    """Talks to InnerTube with a chain of client profiles (see ``utmax.core.clients``)."""
+    """Talks to InnerTube with a chain of client profiles (see ``utmax.core.clients``).
+
+    Profiles that need a ``visitorData`` send the one this client asked YouTube for on first
+    use, shared by every thread; a bot check renews it once per player request.
+    """
 
     def __init__(self, transport: Transport, *, block_retries: int = 0) -> None:
         self._transport = transport
         self._block_retries = block_retries
+        self._visitor: str | None = None
+        self._visitor_lock = threading.Lock()
 
-    def player(self, video_id: str, *, purpose: Purpose = "captions") -> PlayerData:
+    def player(
+        self, video_id: str, *, purpose: Purpose = "captions", renew_visitor: bool = False
+    ) -> PlayerData:
         """A playable player response, trying each profile for ``purpose`` in order.
 
         For ``"streams"``, a response without a direct MP4 stream URL counts as a failed profile.
+        ``renew_visitor`` first asks YouTube for a new ``visitorData``: it restricts the streams
+        of some visitors, so a download that keeps meeting 403s refreshes as a new one.
         """
+        if renew_visitor:
+            self._renew_visitor_data(self._visitor)
         profiles = ORDER[purpose]
         failures: list[YouTubeError] = []
         http_failures = 0
         for profile in profiles:
             try:
                 return self._with_block_retries(
-                    partial(self._playable, profile, video_id, None, purpose=purpose)
+                    partial(self._playable_as_visitor, profile, video_id, purpose=purpose)
                 )
             except _HTTP_LEVEL_FAILURES as error:
                 http_failures += 1
@@ -70,22 +91,38 @@ class InnerTubeClient:
         raise failures[0]
 
     def player_json(
-        self, profile: ClientProfile, video_id: str, *, api_key: str | None = None
+        self,
+        profile: ClientProfile,
+        video_id: str,
+        *,
+        api_key: str | None = None,
+        visitor_data: str | None = None,
     ) -> dict[str, Any]:
         """The raw player response of one profile (low level; used by the fixture recorder)."""
         url = f"{API_BASE}/player?prettyPrint=false"
         if api_key is not None:
             url += f"&key={api_key}"
         payload = {
-            "context": profile.context_payload(),
+            "context": profile.context_payload(visitor_data),
             "videoId": video_id,
             "contentCheckOk": True,
             "racyCheckOk": True,
         }
         body = json.dumps(payload).encode("utf-8")
-        response = self._transport.send(HttpRequest("POST", url, profile.request_headers(), body))
+        headers = profile.request_headers(visitor_data)
+        response = self._transport.send(HttpRequest("POST", url, headers, body))
         return _json_object(response, video_id=video_id)
 
+    def visitor_data(self) -> str | None:
+        """The ``visitorData`` YouTube issued to this client, asked for on first use.
+
+        ``None`` when YouTube issued none; the next call asks again.
+        """
+        with self._visitor_lock:
+            if self._visitor is None:
+                self._visitor = self._new_visitor_data()
+            return self._visitor
+
     def browse(
         self,
         profile: ClientProfile,
@@ -126,10 +163,51 @@ class InnerTubeClient:
         response = self._transport.send(HttpRequest("POST", url, profile.request_headers(), body))
         return _json_object(response)
 
+    def _new_visitor_data(self) -> str | None:
+        try:
+            data = self._post(VISIONOS, "visitor_id", {"context": VISIONOS.context_payload()})
+        except (YouTubeRequestFailed, YouTubeDataUnparsable) as error:
+            log.info("YouTube issued no visitorData: %s", error)
+            return None
+        value = mapping(data.get("responseContext")).get("visitorData")
+        return value if isinstance(value, str) and value else None
+
+    def _renew_visitor_data(self, seen: str | None) -> str | None:
+        """A new ``visitorData``, unless another thread already replaced ``seen``."""
+        with self._visitor_lock:
+            if self._visitor == seen:
+                self._visitor = self._new_visitor_data()
+            return self._visitor
+
+    def _playable_as_visitor(
+        self, profile: ClientProfile, video_id: str, *, purpose: Purpose
+    ) -> PlayerData:
+        """``_playable`` for ``profile``; one that needs a ``visitorData`` and meets a bot check
+        tries once more with a new one."""
+        if not profile.needs_visitor:
+            return self._playable(profile, video_id, None, purpose=purpose)
+        visitor = self.visitor_data()
+        try:
+            return self._playable(profile, video_id, None, purpose=purpose, visitor_data=visitor)
+        except RequestBlocked as error:
+            if isinstance(error, IpBlocked):
+                raise
+            log.info(
+                "%s met a bot check for %s; asking for a new visitorData", profile.name, video_id
+            )
+            visitor = self._renew_visitor_data(visitor)
+            return self._playable(profile, video_id, None, purpose=purpose, visitor_data=visitor)
+
     def _playable(
-        self, profile: ClientProfile, video_id: str, api_key: str | None, *, purpose: Purpose
+        self,
+        profile: ClientProfile,
+        video_id: str,
+        api_key: str | None,
+        *,
+        purpose: Purpose,
+        visitor_data: str | None = None,
     ) -> PlayerData:
-        data = self.player_json(profile, video_id, api_key=api_key)
+        data = self.player_json(profile, video_id, api_key=api_key, visitor_data=visitor_data)
         player = parse_player_response(data, video_id=video_id)
         check_playability(player.playability, video_id=video_id)
         if purpose == "streams" and not any(

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/src/utmax/client.py

@@ -20,6 +20,7 @@ from utmax.models import (
     CollectionKind,
     Container,
     DownloadResult,
+    FormatList,
     FormatName,
     Progress,
     Quality,
@@ -121,6 +122,10 @@ class Client:
         """Every subtitle track of ``video``, in YouTube's order."""
         return self._transcripts.list_tracks(video)
 
+    def list_formats(self, video: str) -> FormatList:
+        """The streams of ``video`` a download can choose from; see :func:`utmax.list_formats`."""
+        return self._downloads.list_formats(video)
+
     def video_info(self, video: str) -> VideoInfo:
         """Title, channel and duration of ``video``."""
         return self._transcripts.video_info(video)
@@ -161,7 +166,8 @@ class Client:
         path: str | os.PathLike[str],
         *,
         format: Container | None = None,
-        quality: Quality = "compat",
+        quality: Quality = "best",
+        resolution: int | None = None,
         subtitles: Sequence[str | Transcript] | None = None,
         subtitle_mode: SubtitleMode = "embed",
         default_subtitle: str | None = None,
@@ -177,6 +183,7 @@ class Client:
         options = DownloadOptions(
             format=format,
             quality=quality,
+            resolution=resolution,
             subtitles=subtitles,
             subtitle_mode=subtitle_mode,
             default_subtitle=default_subtitle,
@@ -266,7 +273,8 @@ class Client:
         out_dir: str | os.PathLike[str],
         *,
         format: Container = "mp4",
-        quality: Quality = "compat",
+        quality: Quality = "best",
+        resolution: int | None = None,
         subtitles: Sequence[str] | None = None,
         subtitle_mode: SubtitleMode = "embed",
         concurrency: int = 2,
@@ -281,6 +289,7 @@ class Client:
             out_dir,
             format=format,
             quality=quality,
+            resolution=resolution,
             subtitles=subtitles,
             subtitle_mode=subtitle_mode,
             concurrency=concurrency,

{u_transcript_max-0.1.0a2 → u_transcript_max-0.1.0a4}/src/utmax/core/clients.py

@@ -2,6 +2,11 @@
 
 Verified on 2026-09-27: ANDROID, IOS and ANDROID_VR return captions and direct stream URLs
 without an API key or proof-of-origin token; ANDROID_VR returns no ``translationLanguages``.
+
+Verified on 2026-10-09: the stream URLs of ANDROID and IOS serve only the start of a stream
+without a proof-of-origin token, and ANDROID_VR mostly answers with a bot check. VISIONOS, sent
+with a ``visitorData`` that YouTube issued, serves whole streams of every quality (H.264, AV1
+and VP9 up to 2160p and HDR, AAC and Opus) without JavaScript or a token.
 """
 
 from __future__ import annotations
@@ -18,6 +23,7 @@ __all__ = [
     "IOS",
     "ORDER",
     "PROFILES",
+    "VISIONOS",
     "WEB",
     "ClientProfile",
     "Purpose",
@@ -33,24 +39,31 @@ DESKTOP_USER_AGENT = (
 
 @dataclass(frozen=True, slots=True)
 class ClientProfile:
-    """How utmax introduces itself to InnerTube as one of YouTube's apps."""
+    """How utmax introduces itself to InnerTube as one of YouTube's apps.
+
+    ``needs_visitor``: YouTube answers this app with a bot check unless the request carries a
+    ``visitorData`` that it issued (``POST /youtubei/v1/visitor_id``).
+    """
 
     name: str
     client_id: int
     version: str
     user_agent: str
     extra: tuple[tuple[str, str | int], ...] = ()
+    needs_visitor: bool = False
 
-    def context_payload(self) -> dict[str, Any]:
+    def context_payload(self, visitor_data: str | None = None) -> dict[str, Any]:
         """The ``context`` object of an InnerTube request body."""
         client: dict[str, Any] = {"clientName": self.name, "clientVersion": self.version}
         client.update(self.extra)
         client.update({"hl": "en", "gl": "US"})
+        if visitor_data is not None:
+            client["visitorData"] = visitor_data
         return {"client": client}
 
-    def request_headers(self) -> dict[str, str]:
+    def request_headers(self, visitor_data: str | None = None) -> dict[str, str]:
         """HTTP headers for an InnerTube request made as this app."""
-        return {
+        headers = {
             "Content-Type": "application/json",
             "User-Agent": self.user_agent,
             "X-YouTube-Client-Name": str(self.client_id),
@@ -58,6 +71,9 @@ class ClientProfile:
             "Accept-Language": "en-US,en;q=0.9",
             "Accept-Encoding": "gzip",
         }
+        if visitor_data is not None:
+            headers["X-Goog-Visitor-Id"] = visitor_data
+        return headers
 
 
 ANDROID = ClientProfile(
@@ -95,6 +111,22 @@ ANDROID_VR = ClientProfile(
         ("osVersion", "12L"),
     ),
 )
+VISIONOS = ClientProfile(
+    name="VISIONOS",
+    client_id=101,
+    version="1.02",
+    user_agent=(
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_7_3) AppleWebKit/605.1.15 "
+        "(KHTML, like Gecko) Version/26.0 Safari/605.1.15"
+    ),
+    extra=(
+        ("deviceMake", "Apple"),
+        ("deviceModel", "RealityDevice17,1"),
+        ("osName", "visionOS"),
+        ("osVersion", "26.5.23O471"),
+    ),
+    needs_visitor=True,
+)
 WEB = ClientProfile(
     name="WEB", client_id=1, version="2.20260925.01.00", user_agent=DESKTOP_USER_AGENT
 )
@@ -102,12 +134,12 @@ WEB = ClientProfile(
 ORDER: Mapping[Purpose, tuple[ClientProfile, ...]] = MappingProxyType(
     {
         "captions": (ANDROID, IOS, ANDROID_VR),
-        "streams": (ANDROID_VR, ANDROID, IOS),
+        "streams": (VISIONOS, ANDROID_VR),
         "browse": (ANDROID_VR, WEB),
         "resolve": (ANDROID_VR, WEB),
     }
 )
 
 PROFILES: Mapping[str, ClientProfile] = MappingProxyType(
-    {profile.name: profile for profile in (ANDROID, IOS, ANDROID_VR, WEB)}
+    {profile.name: profile for profile in (ANDROID, IOS, ANDROID_VR, VISIONOS, WEB)}
 )