doblarr 0.1.0__py3-none-any.whl

doblarr/__init__.py

@@ -0,0 +1,10 @@
+"""Doblarr — AI dubbing for your media library.
+
+Turns a foreign-language video into an added, translated audio track by
+orchestrating: source separation, transcription/diarization, LLM translation,
+voice-cloned TTS (via the voicebox service), time-fitting, mixing, and muxing.
+
+Doblarr owns the movie-specific pipeline; voicebox owns voice cloning + TTS.
+"""
+
+__version__ = "0.1.0"

doblarr/__main__.py

@@ -0,0 +1,8 @@
+"""Enable `python -m doblarr ...`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

doblarr/artifacts.py

@@ -0,0 +1,54 @@
+"""Configuration-aware checkpoints and source-isolated working directories."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+from .telemetry import write_json
+
+
+def digest(value) -> str:
+    return hashlib.sha256(json.dumps(value, sort_keys=True, default=str).encode()).hexdigest()
+
+
+def read_json(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+        return value if isinstance(value, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def stamp(path: Path | None) -> dict | None:
+    if path is None:
+        return None
+    try:
+        stat = path.stat()
+        return {"path": str(path.resolve()), "size": stat.st_size, "mtime_ns": stat.st_mtime_ns}
+    except OSError:
+        return None
+
+
+def media_work(root: Path, job) -> Path:
+    identity = digest([str(job.input_file.resolve()), job.source_lang])[:16]
+    return root / "media" / identity
+
+
+def receipt_path(output: Path) -> Path:
+    return output.with_name(output.name + ".manifest.json")
+
+
+def matches(outputs: list[Path], request: dict, force=False) -> bool:
+    if force or not outputs:
+        return False
+    saved = read_json(receipt_path(outputs[0]))
+    states = [stamp(p) for p in outputs]
+    return (all(s and s["size"] > 0 for s in states)
+            and saved.get("request") == request and saved.get("outputs") == states)
+
+
+def record(outputs: list[Path], request: dict) -> None:
+    write_json(receipt_path(outputs[0]), {"request": request,
+                                         "outputs": [stamp(p) for p in outputs]})

doblarr/auth.py

@@ -0,0 +1,39 @@
+"""API-key authentication for the Doblarr HTTP API.
+
+When `web.api_key` is set, every `/api/*` route (except `/api/health`) requires
+the key via the `X-Api-Key` header (or `?api_key=` for convenience). When it is
+empty — the self-hosted default — the API stays open and a warning is logged at
+startup. The static UI mount is not covered by this dependency.
+"""
+
+from __future__ import annotations
+
+import hmac
+import logging
+from collections.abc import Awaitable, Callable
+
+from fastapi import HTTPException, Request
+
+from .config import Config
+
+log = logging.getLogger("doblarr.auth")
+
+OPEN_PATHS = {"/api/health", "/api/health/ready"}
+
+
+def build_api_key_dependency(config: Config) -> Callable[[Request], Awaitable[None]]:
+    """Return a FastAPI dependency enforcing `web.api_key` on API routes."""
+    if not (config.get("web", {}) or {}).get("api_key"):
+        log.warning("web.api_key is not set — the HTTP API is UNAUTHENTICATED; "
+                    "set web.api_key in config.yaml to require X-Api-Key")
+
+    async def verify_api_key(request: Request) -> None:
+        api_key = (config.get("web", {}) or {}).get("api_key") or ""
+        if not api_key or request.url.path in OPEN_PATHS:
+            return
+        supplied = (request.headers.get("x-api-key")
+                    or request.query_params.get("api_key") or "")
+        if not hmac.compare_digest(supplied, api_key):
+            raise HTTPException(status_code=401, detail="missing or invalid API key")
+
+    return verify_api_key

doblarr/cache.py

@@ -0,0 +1,48 @@
+"""Tiny in-memory TTL cache — dict + timestamps, FIFO eviction at max size.
+
+Used for library scan results; intentionally dependency-free and process-local
+(nothing persisted to disk).
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+
+class TTLCache:
+    def __init__(self, ttl: float = 300.0, max_size: int = 64):
+        self.ttl = ttl
+        self.max_size = max_size
+        self._items: dict = {}  # key -> (set-time, value), insertion ordered
+        self._lock = threading.Lock()
+
+    def get(self, key, ttl: float | None = None):
+        """Return the cached value, or None if missing/expired.
+
+        `ttl` overrides the instance default for this lookup, so a caller can
+        keep the TTL configurable at read time.
+        """
+        ttl = self.ttl if ttl is None else ttl
+        with self._lock:
+            item = self._items.get(key)
+            if item is None:
+                return None
+            ts, value = item
+            if time.monotonic() - ts >= ttl:
+                del self._items[key]
+                return None
+            return value
+
+    def set(self, key, value) -> None:
+        with self._lock:
+            self._items[key] = (time.monotonic(), value)
+            while len(self._items) > self.max_size:
+                self._items.pop(next(iter(self._items)))  # evict oldest
+
+    def clear(self) -> None:
+        with self._lock:
+            self._items.clear()
+
+    def __len__(self) -> int:
+        return len(self._items)

doblarr/cli.py

@@ -0,0 +1,104 @@
+"""Doblarr command-line interface.
+
+    doblarr check                         # ping the voicebox service
+    doblarr dub MOVIE --to es --from ko [--subs FILE] [--dry-run]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .clients.voicebox import VoiceboxClient, VoiceboxError
+from .config import Config
+from .logging_setup import setup_logging
+from .models import DubJob
+from .pipeline import run_job
+
+
+def _cmd_check(args: argparse.Namespace, config: Config) -> int:
+    vb = VoiceboxClient(config["voicebox"]["base_url"])
+    try:
+        health = vb.health()
+    except VoiceboxError as exc:
+        print(f"voicebox NOT reachable: {exc}")
+        return 1
+    print(f"voicebox OK at {vb.base_url}: {health}")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace, config: Config) -> int:
+    import uvicorn
+
+    from .server import create_app
+
+    host = args.host or config.get("web", {}).get("host", "127.0.0.1")
+    port = args.port or config.get("web", {}).get("port", 6363)
+    print(f"Doblarr serving on http://{host}:{port}  (UI + /api/library)")
+    # log_config=None: logging_setup already configured uvicorn's loggers.
+    uvicorn.run(create_app(config), host=host, port=int(port), log_config=None)
+    return 0
+
+
+def _cmd_dub(args: argparse.Namespace, config: Config) -> int:
+    src = Path(args.input)
+    if not src.exists():
+        print(f"input not found: {src}")
+        return 1
+    job = DubJob(
+        input_file=src,
+        source_lang=args.source,
+        target_lang=args.to,
+        subtitle_file=Path(args.subs) if args.subs else None,
+        kind=args.kind,
+    )
+    # --dry-run forces a plan; otherwise dub.dry_run from config decides.
+    dry_run = args.dry_run if args.dry_run is not None else config["dub"].get("dry_run", True)
+    run_job(job, config, dry_run=dry_run)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="doblarr", description="AI dubbing for your library")
+    p.add_argument("--version", action="version", version=f"doblarr {__version__}")
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("-c", "--config", default=None, help="path to config.yaml")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("check", help="check the voicebox service is reachable")
+
+    s = sub.add_parser("serve", help="run the web UI + API server")
+    s.add_argument("--host", default=None)
+    s.add_argument("--port", default=None, type=int)
+
+    d = sub.add_parser("dub", help="dub a video into a target language")
+    d.add_argument("input", help="path to the video file")
+    d.add_argument("--to", required=True, help="target language code, e.g. es")
+    d.add_argument("--from", dest="source", default="auto",
+                   help="source language code, e.g. ko (default: auto)")
+    d.add_argument("--subs", default=None, help="subtitle file for text + timing")
+    d.add_argument("--kind", choices=["full", "tease", "audition"], default="full",
+                   help="full video, opening teaser, or representative audio audition")
+    d.add_argument("--dry-run", action="store_true", default=None,
+                   help="print the plan without running heavy stages "
+                        "(overrides dub.dry_run in config)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    config = Config.load(args.config)
+    setup_logging(config, verbose=args.verbose, uvicorn=args.command == "serve")
+    if args.command == "check":
+        return _cmd_check(args, config)
+    if args.command == "serve":
+        return _cmd_serve(args, config)
+    if args.command == "dub":
+        return _cmd_dub(args, config)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

doblarr/clients/__init__.py

@@ -0,0 +1 @@
+"""External service clients (voicebox, translation providers)."""

doblarr/clients/base.py

@@ -0,0 +1,104 @@
+"""Shared HTTP base for the *arr-style service clients.
+
+Wraps a `requests.Session` with a base URL, default timeout, and tenacity-based
+retry: exponential backoff on transient failures (connection errors, timeouts,
+429 — honoring `Retry-After` — and 5xx), with errors mapped uniformly into the
+`doblarr.errors` hierarchy. Per-request `timeout=` overrides are supported for
+long-running calls (e.g. voicebox generation).
+"""
+
+from __future__ import annotations
+
+import logging
+from contextlib import suppress
+from typing import Any
+
+import requests
+from tenacity import Retrying, before_sleep_log, retry_if_exception, stop_after_attempt
+
+from ..errors import ArrClientError
+
+log = logging.getLogger("doblarr.clients.base")
+
+
+class ArrClient:
+    """Session-backed HTTP client with retries and uniform errors."""
+
+    service = "service"              # display name used in error messages
+    auth_label = "API key"           # what a 401 rejects ("API key" / "token")
+    error_cls: type[ArrClientError] = ArrClientError
+    max_retries = 2                  # retries after the first attempt
+    backoff = 0.5                    # seconds; doubles each retry
+
+    def __init__(self, base_url: str, timeout: int = 30,
+                 headers: dict | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        if headers:
+            self.session.headers.update(headers)
+
+    # -- internals --------------------------------------------------------
+    def _error(self, message: str, status: int | None = None) -> ArrClientError:
+        return self.error_cls(message, status=status)
+
+    @staticmethod
+    def _is_transient(exc: BaseException) -> bool:
+        return isinstance(exc, ArrClientError) and (
+            exc.status is None or exc.status == 429 or exc.status >= 500)
+
+    def _wait(self, retry_state) -> float:
+        """Exponential backoff, raised to `Retry-After` when the server asks."""
+        exc = retry_state.outcome.exception()
+        delay = self.backoff * (2 ** (retry_state.attempt_number - 1))
+        retry_after = getattr(exc, "retry_after", None)
+        if retry_after:
+            with suppress(TypeError, ValueError):
+                delay = max(delay, float(retry_after))
+        return delay
+
+    def _attempt(self, method: str, path: str, *,
+                 timeout: int | None = None, **kwargs) -> requests.Response:
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self.session.request(method, url,
+                                        timeout=timeout or self.timeout, **kwargs)
+        except requests.RequestException as exc:
+            raise self._error(
+                f"{self.service} unreachable at {self.base_url}: {exc}") from exc
+        if resp.status_code == 401:
+            raise self._error(
+                f"{self.service} rejected the {self.auth_label} (401)", status=401)
+        if not resp.ok:
+            err = self._error(
+                f"{self.service} {resp.status_code} on {method} {path}: "
+                f"{resp.text[:200]}", status=resp.status_code)
+            err.retry_after = resp.headers.get("Retry-After")
+            raise err
+        return resp
+
+    def _request(self, method: str, path: str, *,
+                 timeout: int | None = None, **kwargs) -> requests.Response:
+        retryer = Retrying(
+            stop=stop_after_attempt(self.max_retries + 1),
+            wait=self._wait,
+            retry=retry_if_exception(self._is_transient),
+            before_sleep=before_sleep_log(log, logging.DEBUG),
+            reraise=True,
+        )
+        return retryer(self._attempt, method, path, timeout=timeout, **kwargs)
+
+    # -- verb helpers -----------------------------------------------------
+    def _get(self, path: str, params: dict | None = None,
+             timeout: int | None = None) -> Any:
+        return self._request("GET", path, params=params, timeout=timeout).json()
+
+    def _post(self, path: str, timeout: int | None = None, **kwargs) -> Any:
+        return self._request("POST", path, timeout=timeout, **kwargs).json()
+
+    def _put(self, path: str, params: dict | None = None,
+             timeout: int | None = None, **kwargs) -> None:
+        self._request("PUT", path, params=params, timeout=timeout, **kwargs)
+
+    def _delete(self, path: str, timeout: int | None = None, **kwargs) -> None:
+        self._request("DELETE", path, timeout=timeout, **kwargs)

doblarr/clients/plex.py

@@ -0,0 +1,91 @@
+"""Minimal Plex client — enough to find items and manage labels.
+
+Labels are added/removed non-destructively: `label[0].tag.tag=X` adds X while
+keeping every existing label (Kometa's included), and `label[].tag.tag-=X` removes
+just X. `label.locked=1` keeps the label through metadata refreshes.
+
+The token travels in the `X-Plex-Token` header, not the query string, so it
+stays out of URLs (and any logs that record them).
+"""
+
+from __future__ import annotations
+
+from ..errors import ArrClientError
+from .base import ArrClient
+
+TYPE_NUM = {"movie": 1, "show": 2}
+
+
+class PlexError(ArrClientError, RuntimeError):
+    pass
+
+
+class PlexClient(ArrClient):
+    service = "Plex"
+    auth_label = "token"
+    error_cls = PlexError
+
+    def __init__(self, base_url: str, token: str, timeout: int = 30):
+        super().__init__(base_url, timeout=timeout,
+                         headers={"X-Plex-Token": token,
+                                  "Accept": "application/json"})
+        self.token = token
+
+    def sections(self) -> list[dict]:
+        data = self._get("/library/sections")
+        return [{"key": s["key"], "type": s["type"], "title": s["title"]}
+                for s in data["MediaContainer"].get("Directory", [])]
+
+    @staticmethod
+    def _meta_labels(m: dict) -> list[str]:
+        return [lbl["tag"] for lbl in m.get("Label", [])]
+
+    def find(self, section_key: str, type_num: int, title: str,
+             year: int | None) -> dict | None:
+        """Best match by exact (case-insensitive) title, preferring the right year."""
+        data = self._get(f"/library/sections/{section_key}/all",
+                         {"type": type_num, "title": title})
+        cands = data["MediaContainer"].get("Metadata", [])
+        exact = [m for m in cands if m.get("title", "").strip().lower() == title.strip().lower()]
+        pool = exact or cands
+        pick = None
+        if year is not None:
+            pick = next((m for m in pool if m.get("year") == year), None)
+        pick = pick or (pool[0] if pool else None)
+        if not pick:
+            return None
+        return {"ratingKey": pick["ratingKey"], "title": pick.get("title"),
+                "year": pick.get("year"), "labels": self._meta_labels(pick)}
+
+    def items_with_label(self, section_key: str, type_num: int, label: str) -> list[dict]:
+        data = self._get(f"/library/sections/{section_key}/all",
+                         {"type": type_num, "label": label})
+        return [{"ratingKey": m["ratingKey"], "title": m.get("title"),
+                 "year": m.get("year")} for m in data["MediaContainer"].get("Metadata", [])]
+
+    def add_label(self, section_key: str, type_num: int, rating_key: str, label: str) -> None:
+        self._put(f"/library/sections/{section_key}/all", {
+            "type": type_num, "id": rating_key,
+            "label[0].tag.tag": label, "label.locked": 1,
+        })
+
+    def remove_label(self, section_key: str, type_num: int, rating_key: str, label: str) -> None:
+        self._put(f"/library/sections/{section_key}/all", {
+            "type": type_num, "id": rating_key,
+            "label[].tag.tag-": label, "label.locked": 1,
+        })
+
+    def refresh_item(self, rating_key: str) -> None:
+        """Refresh one item's metadata (picks up newly muxed audio tracks).
+
+        Documented as PUT; older Plex versions only accept POST, so fall back.
+        The response body is empty, hence `_request` instead of `_put`/`_post`.
+        """
+        path = f"/library/metadata/{rating_key}/refresh"
+        try:
+            self._request("PUT", path)
+        except PlexError as exc:
+            if exc.status in (404, 405):
+                self._request("POST", path)
+            else:
+                raise

doblarr/clients/radarr.py

@@ -0,0 +1,26 @@
+"""Minimal Radarr API client (read-only for now)."""
+
+from __future__ import annotations
+
+from ..errors import ArrClientError
+from .base import ArrClient
+
+
+class RadarrError(ArrClientError, RuntimeError):
+    pass
+
+
+class RadarrClient(ArrClient):
+    service = "Radarr"
+    error_cls = RadarrError
+
+    def __init__(self, base_url: str, api_key: str, timeout: int = 30):
+        super().__init__(base_url, timeout=timeout,
+                         headers={"X-Api-Key": api_key})
+        self.api_key = api_key
+
+    def system_status(self) -> dict:
+        return self._get("/api/v3/system/status")
+
+    def list_movies(self) -> list[dict]:
+        return self._get("/api/v3/movie")

doblarr/clients/sonarr.py

@@ -0,0 +1,32 @@
+"""Minimal Sonarr API client (read-only for now)."""
+
+from __future__ import annotations
+
+from ..errors import ArrClientError
+from .base import ArrClient
+
+
+class SonarrError(ArrClientError, RuntimeError):
+    pass
+
+
+class SonarrClient(ArrClient):
+    service = "Sonarr"
+    error_cls = SonarrError
+
+    def __init__(self, base_url: str, api_key: str, timeout: int = 30):
+        super().__init__(base_url, timeout=timeout,
+                         headers={"X-Api-Key": api_key})
+        self.api_key = api_key
+
+    def system_status(self) -> dict:
+        return self._get("/api/v3/system/status")
+
+    def list_series(self) -> list[dict]:
+        return self._get("/api/v3/series")
+
+    def episode_files(self, series_id: int) -> list[dict]:
+        return self._get(f"/api/v3/episodefile?seriesId={series_id}")
+
+    def episodes(self, series_id: int) -> list[dict]:
+        return self._get(f"/api/v3/episode?seriesId={series_id}")