panoscribe 0.4.0__py3-none-any.whl

panoscribe/__init__.py

@@ -0,0 +1,10 @@
+"""panoscribe — transcribe any video with speech + on-screen text."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("panoscribe")
+except PackageNotFoundError:  # pragma: no cover — editable install without metadata
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

panoscribe/acquire/__init__.py

@@ -0,0 +1 @@
+

panoscribe/acquire/downloader.py

@@ -0,0 +1,46 @@
+"""Video acquisition — local passthrough or yt-dlp download."""
+
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+
+from yt_dlp import YoutubeDL
+from yt_dlp.utils import DownloadError
+
+from panoscribe.errors import PanoScribeError
+
+logger = logging.getLogger(__name__)
+
+_URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+
+def download_video(source: str, temp_dir: Path) -> Path:
+    """Return a local path to the video referenced by ``source``.
+
+    If ``source`` is an existing local file, it is returned unchanged.
+    If it is an http(s) URL, yt-dlp downloads it into ``temp_dir`` and the
+    resulting path is returned. Any yt-dlp failure — as well as an unrecognised
+    source string — is raised as :class:`PanoScribeError` with a single-line
+    message (no traceback chain) so the CLI can surface it cleanly.
+    """
+    if Path(source).is_file():
+        logger.debug("Using local file passthrough: %s", source)
+        return Path(source)
+
+    if _URL_RE.match(source):
+        temp_dir.mkdir(parents=True, exist_ok=True)
+        ydl_opts = {
+            "outtmpl": str(temp_dir / "%(id)s.%(ext)s"),
+            "quiet": True,
+            "no_warnings": True,
+        }
+        try:
+            with YoutubeDL(ydl_opts) as ydl:
+                info = ydl.extract_info(source, download=True)
+                return Path(ydl.prepare_filename(info))
+        except DownloadError as e:
+            raise PanoScribeError(f"Download failed: {e}") from None
+
+    raise PanoScribeError(f"Invalid source: {source!r} is neither a file nor an http(s) URL")

panoscribe/acquire/photo.py

@@ -0,0 +1,168 @@
+"""Photo-post acquisition -- gallery-dl download of image slideshows + audio.
+
+TikTok ``/photo/`` posts are image slideshows with optional audio. yt-dlp cannot
+download them; gallery-dl can. This module wraps gallery-dl for that purpose and
+provides local-directory scanning as an alternative input path.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from panoscribe.errors import PanoScribeError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_IMAGE_EXTS = frozenset({".jpg", ".jpeg", ".png", ".webp"})
+_AUDIO_EXTS = frozenset({".mp3", ".m4a", ".aac", ".wav"})
+
+
+def is_photo_post(source: str) -> bool:
+    """Return True if *source* looks like a TikTok photo-post URL.
+
+    Checks for ``/photo/`` in the URL path. Must be False for ``/video/`` URLs,
+    other platforms, and local file paths.
+    """
+    lower = source.lower()
+    if "tiktok.com" not in lower:
+        return False
+    return "/photo/" in lower
+
+
+@dataclass(frozen=True)
+class PhotoPost:
+    """Represents a downloaded photo post.
+
+    Attributes
+    ----------
+    image_paths:
+        Slide image file paths, sorted in presentation order (gallery-dl
+        zero-pads slide numbers, so lexical sort is correct).
+    audio_path:
+        Optional audio track (.mp3, .m4a, .aac, or .wav). ``None`` when the
+        post has no audio.
+    """
+
+    image_paths: tuple[Path, ...]
+    audio_path: Path | None
+
+
+def _run_gallery_dl(dest: Path, source: str) -> None:
+    """Run gallery-dl as a subprocess, trying module invocation first.
+
+    Tries ``python -m gallery_dl`` first, then falls back to ``gallery-dl``
+    script. Raises :class:`PanoScribeError` with an install hint if both fail.
+    """
+    # Try module invocation first.
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "gallery_dl", "-D", str(dest), source],
+            capture_output=True,
+            timeout=300,
+        )
+        if result.returncode == 0:
+            return
+        # Check module-specific failure immediately (result still bound).
+        stderr = result.stderr.decode(errors="replace") if result.stderr else ""
+        if "No module named" in stderr or "ModuleNotFoundError" in stderr:
+            raise PanoScribeError(
+                "photo posts need the optional extra - "
+                "`uv sync --extra photo` (or `pip install panoscribe[photo]`)"
+            )
+    except FileNotFoundError:
+        pass
+
+    # Fall back to script name.
+    gallery_dl_path = shutil.which("gallery-dl")
+    if gallery_dl_path is not None:
+        try:
+            result = subprocess.run(
+                [gallery_dl_path, "-D", str(dest), source],
+                capture_output=True,
+                timeout=300,
+            )
+            if result.returncode == 0:
+                return
+        except FileNotFoundError:
+            pass
+
+    hint = (
+        "photo posts need the optional extra - "
+        "`uv sync --extra photo` (or `pip install panoscribe[photo]`)"
+    )
+    raise PanoScribeError(f"gallery-dl failed - {hint}")
+
+
+def download_photo_post(source: str, temp_dir: Path) -> PhotoPost:
+    """Download a TikTok photo-post from *source* into *temp_dir*.
+
+    gallery-dl may create extractor subdirectories under the base dir, so the
+    result is scanned recursively.
+
+    Parameters
+    ----------
+    source:
+        TikTok ``/photo/`` URL.
+    temp_dir:
+        Parent directory for downloaded files. A ``slides/`` subdirectory is
+        created inside it.
+
+    Returns
+    -------
+    PhotoPost
+        Sorted image paths (slide order) and optional audio file.
+    """
+    dest = temp_dir / "slides"
+    dest.mkdir(parents=True, exist_ok=True)
+    _run_gallery_dl(dest, source)
+
+    images = sorted(p for p in dest.rglob("*") if p.suffix.lower() in _IMAGE_EXTS)
+    if not images:
+        raise PanoScribeError("no slides downloaded - is this a photo post?")
+
+    audio: Path | None = None
+    for p in dest.rglob("*"):
+        if p.suffix.lower() in _AUDIO_EXTS:
+            audio = p
+            break
+
+    return PhotoPost(image_paths=tuple(images), audio_path=audio)
+
+
+def scan_photo_dir(directory: Path) -> PhotoPost:
+    """Scan a user-provided directory for photo-post content.
+
+    Scans the top level of *directory* only (non-recursive) for images and
+    optional audio, returning a :class:`PhotoPost` in image-sort order.
+
+    Parameters
+    ----------
+    directory:
+        Local directory containing slide images and optionally an audio file.
+
+    Returns
+    -------
+    PhotoPost
+        Sorted image paths and optional audio file.
+    """
+    images = sorted(
+        p for p in directory.iterdir() if p.is_file() and p.suffix.lower() in _IMAGE_EXTS
+    )
+    if not images:
+        raise PanoScribeError(f"no image files found in {directory}")
+
+    audio: Path | None = None
+    for p in directory.iterdir():
+        if p.is_file() and p.suffix.lower() in _AUDIO_EXTS:
+            audio = p
+            break
+
+    return PhotoPost(image_paths=tuple(images), audio_path=audio)

panoscribe/acquire/platform.py

@@ -0,0 +1,30 @@
+"""Platform detection from source URLs."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Platform(StrEnum):
+    """Known source platforms for video acquisition."""
+
+    TIKTOK = "tiktok"
+    YOUTUBE = "youtube"
+    INSTAGRAM = "instagram"
+    UNKNOWN = "unknown"
+    GENERIC = "generic"
+
+
+def detect_platform(source: str) -> Platform:
+    """Infer the source platform from a URL or file path.
+
+    Returns :class:`Platform.UNKNOWN` for local files and unrecognized URLs.
+    """
+    s = source.lower()
+    if "tiktok.com" in s:
+        return Platform.TIKTOK
+    if "youtube.com" in s or "youtu.be" in s:
+        return Platform.YOUTUBE
+    if "instagram.com" in s:
+        return Platform.INSTAGRAM
+    return Platform.UNKNOWN

panoscribe/acquire/playlist.py

@@ -0,0 +1,105 @@
+"""Playlist / channel URL expansion via yt-dlp metadata-only extraction.
+
+Sprint 8.1: feeds the per-line URL list of ``transcribe-many`` through this
+module before reconcile so that a single playlist URL becomes the list of its
+constituent video URLs, in feed order.
+
+The single public entry point :func:`expand_playlist` returns:
+
+- ``list[str]``: one URL per video for a recognised playlist / channel,
+  in yt-dlp's natural feed order.
+- ``None``: input is a single-video URL, a local file path / non-URL string,
+  or any extraction error (DownloadError, ExtractorError, network /
+  SSL-level failure, malformed response). Callers treat ``None`` as
+  "not a playlist — keep the original line".
+"""
+
+from __future__ import annotations
+
+import logging
+
+from yt_dlp import YoutubeDL
+
+logger = logging.getLogger(__name__)
+
+_YDL_OPTS: dict[str, object] = {
+    "quiet": True,
+    "no_warnings": True,
+    "extract_flat": True,
+    "skip_download": True,
+}
+
+
+def _entry_to_url(entry: dict) -> str | None:
+    """Resolve one playlist entry to a URL via the locked fallback chain.
+
+    Order: ``entry["url"]`` → ``entry["webpage_url"]`` → reconstructed
+    ``https://www.youtube.com/watch?v={id}`` if ``entry["id"]`` is present.
+    Returns ``None`` when all three are falsy / missing.
+    """
+    return (
+        entry.get("url")
+        or entry.get("webpage_url")
+        or (f"https://www.youtube.com/watch?v={entry['id']}" if entry.get("id") else None)
+    )
+
+
+def expand_playlist(url: str) -> list[str] | None:
+    """Return expanded video URLs for a playlist/channel URL, else ``None``.
+
+    Behaviour:
+
+    - Local-file / non-URL detection is scheme-based: any ``url`` that does
+      not start with ``http://`` or ``https://`` returns ``None`` without
+      touching yt-dlp (deterministic on Windows backslash paths and on
+      Linux absolute paths that may or may not exist).
+    - For http(s) URLs, runs ``YoutubeDL.extract_info`` with ``extract_flat``
+      so only metadata is fetched (no video download).
+    - If the response's ``_type`` is not exactly ``"playlist"``, returns
+      ``None`` — single-video URLs flow through the per-video pipeline
+      unchanged.
+    - Entries are coerced via ``list(info.get("entries") or [])`` to handle
+      yt-dlp's ``LazyList`` return shape.
+    - Each entry is resolved via :func:`_entry_to_url`. Entries without any
+      resolvable URL are dropped + logged at WARNING.
+    - Empty playlists return ``[]`` (caller will splice nothing in place).
+    - Any exception during extraction → WARNING log + ``None``. Returning
+      ``None`` rather than raising lets the caller treat extraction failures
+      identically to "not a playlist": the original URL passes through to
+      the per-video pipeline, which surfaces the actual extractor error.
+    - One level of expansion only: nested ``_type == "playlist"`` entries are
+      treated as opaque single URLs (no recursion).
+    """
+    if not url.startswith(("http://", "https://")):
+        return None
+
+    try:
+        with YoutubeDL(_YDL_OPTS) as ydl:
+            info = ydl.extract_info(url, download=False, process=False)
+    except Exception as e:
+        # yt-dlp raises a wide hierarchy (DownloadError, ExtractorError, ...)
+        # plus network/SSL-level errors; treat all as "not a playlist".
+        logger.warning("Playlist expansion failed for %s (%s: %s)", url, type(e).__name__, e)
+        return None
+
+    if not isinstance(info, dict):
+        return None
+
+    if info.get("_type") != "playlist":
+        return None
+
+    entries = list(info.get("entries") or [])
+
+    out: list[str] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            logger.warning("Skipping non-dict playlist entry: %r", entry)
+            continue
+        resolved = _entry_to_url(entry)
+        if not resolved:
+            logger.warning("Skipping playlist entry with no resolvable URL: %r", entry)
+            continue
+        out.append(resolved)
+
+    logger.debug("Expanded %s to %d video URL(s)", url, len(out))
+    return out

panoscribe/api/server.py

@@ -0,0 +1,267 @@
+"""FastAPI server providing an HTTP API for panoscribe transcription.
+
+v1 non-goals
+------------
+- No persistence: restarting the server loses all jobs.
+- No cancellation / job deletion.
+- No authentication.
+- No result formats other than JSON (output_format is hard-coded to "json").
+- No file upload --- sources are URLs or local paths.
+- No SSE / webhooks --- clients poll GET /jobs/{id}.
+- Shutdown hang: the executor uses non-daemon threads, so Ctrl+C/uvicorn
+  shutdown blocks until the in-flight job finishes. Acceptable v1 behaviour.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path  # noqa: TC003 — runtime use in file ops
+from typing import TYPE_CHECKING, Any, Protocol
+from uuid import uuid4
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+
+from panoscribe import __version__
+from panoscribe.config import PanoScribeConfig
+from panoscribe.errors import PanoScribeError
+from panoscribe.pipeline import process_single_video
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+
+class JobStatus(StrEnum):
+    """Status of a transcription job."""
+
+    queued = "queued"
+    running = "running"
+    done = "done"
+    failed = "failed"
+
+
+class JobRequest(BaseModel):
+    """Request body for POST /jobs."""
+
+    source: str
+    language: str | None = None
+    translate: bool | None = None
+    ocr: bool | None = None
+    ocr_language: str | None = None
+    platform: str | None = None
+
+
+class Job(BaseModel):
+    """Represents a transcription job."""
+
+    id: str
+    source: str
+    status: JobStatus
+    created_at: datetime
+    error: str | None = None
+    result: dict[str, Any] | None = None
+
+
+class _JobStore:
+    """Thread-safe in-memory job store."""
+
+    def __init__(self) -> None:
+        self._jobs: dict[str, Job] = {}
+        self._lock = threading.Lock()
+
+    def add(self, job: Job) -> None:
+        with self._lock:
+            self._jobs[job.id] = job
+
+    def get(self, job_id: str) -> Job | None:
+        with self._lock:
+            return self._jobs.get(job_id)
+
+    def all(self) -> list[Job]:
+        with self._lock:
+            return list(self._jobs.values())
+
+    def update(
+        self,
+        job_id: str,
+        *,
+        status: JobStatus | None = None,
+        error: str | None = None,
+        result: dict[str, Any] | None = None,
+    ) -> None:
+        """Atomically update a job's fields."""
+        with self._lock:
+            job = self._jobs.get(job_id)
+            if job is None:
+                return
+            if status is not None:
+                job.status = status
+            if error is not None:
+                job.error = error
+            if result is not None:
+                job.result = result
+
+
+class _Executor(Protocol):
+    """Minimal executor protocol for dependency injection.
+
+    Tests pass a synchronous executor so job state is deterministic at
+    POST-return time; production uses ``ThreadPoolExecutor(max_workers=1)``.
+    """
+
+    def submit(
+        self,
+        fn: Callable[..., Any],
+        /,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any: ...
+    def shutdown(self, wait: bool = True) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Worker
+# ---------------------------------------------------------------------------
+
+
+def _run_job(
+    job_id: str,
+    source: str,
+    request: JobRequest,
+    base_config: PanoScribeConfig,
+    base_temp: Path,
+    store: _JobStore,
+) -> None:
+    """Run the transcription pipeline and store the result.
+
+    Single-worker design: the executor's ``max_workers=1`` guarantees that
+    only one job runs at a time, which matches GPU serialisation and avoids
+    temp-dir clobber (each job gets a unique ``temp_dir`` below).
+    """
+    # Per-job temp_dir so concurrent jobs (even with max_workers=1 the
+    # guarantee is architectural, not accidental) do not share workdirs.
+    updates: dict[str, Any] = {"temp_dir": base_temp / job_id}
+    if request.language is not None:
+        updates["whisper_language"] = request.language
+    if request.translate is not None:
+        updates["whisper_task"] = "translate" if request.translate else "transcribe"
+    if request.ocr_language is not None:
+        updates["ocr_language"] = request.ocr_language
+    if request.platform is not None:
+        updates["platform_profile"] = request.platform
+
+    cfg = base_config.model_copy(update=updates)
+    ocr_active = request.ocr if request.ocr is not None else cfg.ocr_enabled
+
+    # Output goes to a dedicated api-results subdirectory under the base
+    # temp dir so it survives per-job temp_dir cleanup (process_single_video
+    # deletes cfg.temp_dir in its finally block).
+    output_dir = base_temp / "api-results"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_path = output_dir / f"{job_id}.json"
+
+    store.update(job_id, status=JobStatus.running)
+
+    try:
+        process_single_video(
+            source,
+            cfg,
+            output_path,
+            ocr_active=ocr_active,
+            output_format="json",
+        )
+    except PanoScribeError as e:
+        store.update(job_id, status=JobStatus.failed, error=str(e))
+        return
+    except Exception:
+        logger.exception("Unexpected error processing job %s", job_id)
+        store.update(job_id, status=JobStatus.failed, error="Internal pipeline error")
+        return
+
+    try:
+        result_data: dict[str, Any] = json.loads(output_path.read_text(encoding="utf-8"))
+    except Exception:
+        logger.exception("Failed to read pipeline output for job %s", job_id)
+        store.update(job_id, status=JobStatus.failed, error="Failed to read pipeline output")
+        return
+
+    store.update(job_id, status=JobStatus.done, result=result_data)
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def create_app(
+    config: PanoScribeConfig | None = None,
+    *,
+    executor: _Executor | None = None,
+) -> FastAPI:
+    """Create a FastAPI application for the panoscribe API.
+
+    Parameters
+    ----------
+    config:
+        Optional config override. Defaults to ``PanoScribeConfig()`` (env-only).
+    executor:
+        Optional executor override. Production default is
+        ``ThreadPoolExecutor(max_workers=1)`` --- single worker because GPU
+        serialisation and the per-job temp-dir contract both demand it.
+        Pass a synchronous executor in tests so job state is final at
+        POST-return time without polling.
+    """
+    if config is None:
+        config = PanoScribeConfig()
+    if executor is None:
+        executor = ThreadPoolExecutor(max_workers=1)
+
+    store = _JobStore()
+    # Resolve once so all per-job temp_dir values are absolute.
+    base_temp = config.temp_dir.resolve()
+
+    app = FastAPI(title="panoscribe API", version=__version__)
+
+    @app.get("/healthz")
+    def _healthz() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    @app.post("/jobs", status_code=202)
+    def _submit_job(request: JobRequest) -> dict[str, str]:
+        job = Job(
+            id=uuid4().hex,
+            source=request.source,
+            status=JobStatus.queued,
+            created_at=datetime.now(UTC),
+        )
+        store.add(job)
+        executor.submit(_run_job, job.id, request.source, request, config, base_temp, store)
+        return {"job_id": job.id}
+
+    @app.get("/jobs")
+    def _list_jobs() -> list[dict[str, str]]:
+        return [
+            {
+                "id": j.id,
+                "source": j.source,
+                "status": j.status.value,
+                "created_at": j.created_at.isoformat(),
+            }
+            for j in store.all()
+        ]
+
+    @app.get("/jobs/{job_id}")
+    def _get_job(job_id: str) -> Job:
+        job = store.get(job_id)
+        if job is None:
+            raise HTTPException(status_code=404, detail="Job not found")
+        return job
+
+    return app

panoscribe/asr/__init__.py

@@ -0,0 +1 @@
+"""ASR (Automatic Speech Recognition) subpackage."""

panoscribe/asr/protocol.py

@@ -0,0 +1,34 @@
+"""ASR engine protocol — structural subtyping for swappable backends.
+
+Uses :class:`typing.Protocol` (not ABC) so a future remote or alternative
+transcription backend satisfies the interface by having the right method,
+without needing to inherit from a base class.  Marked ``@runtime_checkable``
+so ``isinstance(engine, AsrEngine)`` works at runtime.
+
+The method signature mirrors :class:`panoscribe.asr.whisper.WhisperTranscriber`
+exactly — every backend must expose:
+* ``transcribe(audio_path)`` -> ``(segments, detected_language)``
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from panoscribe.output import TranscriptSegment
+
+
+@runtime_checkable
+class AsrEngine(Protocol):
+    """Structural protocol for ASR (speech-to-text) backends.
+
+    Any object whose methods match this protocol — whether via inheritance,
+    duck typing, or explicit implementation — is accepted as an ``AsrEngine``
+    at runtime via ``isinstance(engine, AsrEngine)``.
+    """
+
+    def transcribe(self, audio_path: Path) -> tuple[list[TranscriptSegment], str]:
+        """Run ASR on ``audio_path``; return (segments, detected_language)."""
+        ...