pulse-engine 0.2.43__tar.gz → 0.2.44__tar.gz

{pulse_engine-0.2.43 → pulse_engine-0.2.44}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pulse-engine
-Version: 0.2.43
+Version: 0.2.44
 Summary: Pulse Engine — Hybrid framework for building Pulse products
 Author: Pulse Team
 Requires-Python: >=3.11,<3.13

{pulse_engine-0.2.43 → pulse_engine-0.2.44}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pulse-engine"
-version = "0.2.43"
+version = "0.2.44"
 description = "Pulse Engine — Hybrid framework for building Pulse products"
 authors = ["Pulse Team"]
 readme = "README.md"

{pulse_engine-0.2.43 → pulse_engine-0.2.44}/src/pulse_engine/adapters/youtube_downloader.py

@@ -207,10 +207,114 @@ class YouTubeDownloader:
             path=path, used_proxy=used_proxy, used_cookies=used_cookies, error=error
         )
 
+    async def has_captions(
+        self, video_id: str, *, languages: list[str] | None = None
+    ) -> bool:
+        """Whether YouTube holds captions for *video_id*, without downloading anything.
+
+        For a caller that stages audio only so transcription has something to fall back
+        on, this is the question worth asking first: a video with captions does not need
+        its audio pulled at all, and the pull is the expensive part.
+
+        Cheap by construction — `process=False` skips format resolution, so this is
+        one metadata call. The same direct → proxy → cookies escalation as `download`
+        applies: a bot-gated probe reports "no captions" rather than failing, and a
+        false negative costs a download rather than losing data.
+
+        `languages` narrows the question: only those codes count. A bare prefix match,
+        so "en" accepts "en-GB". Manual and automatic captions both count — the caller
+        decides what is good enough by whether it allows auto captions downstream.
+
+        Returns False when every attempt fails. That is the safe direction: the
+        caller downloads audio it might not have needed, rather than skipping audio
+        it did.
+        """
+        manual, auto = await self._list_captions(
+            video_id, use_proxy=False, use_cookies=False
+        )
+
+        if manual is None and self._proxy_configured:
+            logger.info("youtube_captions_probe_retry_with_proxy", video_id=video_id)
+            manual, auto = await self._list_captions(
+                video_id, use_proxy=True, use_cookies=False
+            )
+
+        if manual is None and self._proxy_configured and self._cookies_secret_id:
+            logger.info("youtube_captions_probe_retry_with_cookies", video_id=video_id)
+            manual, auto = await self._list_captions(
+                video_id, use_proxy=True, use_cookies=True
+            )
+
+        if manual is None:
+            logger.warning("youtube_captions_probe_failed", video_id=video_id)
+            return False
+
+        found = sorted(set(manual) | set(auto or []))
+        if languages:
+            wanted = [code.strip().lower() for code in languages if code.strip()]
+            found = [
+                code
+                for code in found
+                if any(code.lower().startswith(want) for want in wanted)
+            ]
+
+        logger.info("youtube_captions_probe", video_id=video_id, available=len(found))
+        return bool(found)
+
     # ------------------------------------------------------------------
     # Private helpers
     # ------------------------------------------------------------------
 
+    async def _list_captions(
+        self, video_id: str, *, use_proxy: bool, use_cookies: bool
+    ) -> tuple[list[str] | None, list[str] | None]:
+        """(manual, automatic) caption languages, or (None, None) if the probe failed.
+
+        None is distinct from an empty list: one means the probe could not run, the
+        other means it ran and the video has no captions.
+        """
+        import tempfile
+
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            opts = _build_yt_dlp_opts(
+                output_template=str(Path(tmp_dir) / "%(id)s.%(ext)s"),
+                extra={"skip_download": True},
+                use_proxy=use_proxy,
+            )
+            if use_cookies:
+                cookies = await self._resolve_cookies()
+                if cookies:
+                    cookies_path = Path(tmp_dir) / "cookies.txt"
+                    cookies_path.write_text(cookies, encoding="utf-8")
+                    cookies_path.chmod(0o600)
+                    opts["cookiefile"] = str(cookies_path)
+
+            def _probe() -> tuple[list[str] | None, list[str] | None]:
+                import yt_dlp as _yt
+
+                url = f"https://www.youtube.com/watch?v={video_id}"
+                try:
+                    with _yt.YoutubeDL(opts) as ydl:
+                        # process=False keeps this to one metadata call: subtitle keys
+                        # are populated before format processing, and format resolution
+                        # is what fails on restricted format sets from datacentre IPs.
+                        info = (
+                            ydl.extract_info(url, download=False, process=False) or {}
+                        )
+                except Exception as exc:  # noqa: BLE001 — reported, not raised
+                    logger.info(
+                        "youtube_captions_probe_attempt_failed",
+                        video_id=video_id,
+                        error=str(exc)[:200],
+                    )
+                    return None, None
+                return (
+                    list((info.get("subtitles") or {}).keys()),
+                    list((info.get("automatic_captions") or {}).keys()),
+                )
+
+            return await asyncio.to_thread(_probe)
+
     async def _resolve_cookies(self) -> str:
         """Return cookies.txt content, fetching from Secrets Manager if configured.