textflowkit 0.1.3__py3-none-any.whl

textflowkit/sources/acquire.py

@@ -0,0 +1,437 @@
+"""Media acquisition: local files pass through, URLs go through yt-dlp."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+import wave
+from collections.abc import Callable
+from pathlib import Path
+
+from textflowkit.core.cancel import CancelledError
+from textflowkit.core.paths import UnsafeInputPathError, opened_file_path
+from textflowkit.core.service import (
+    ENV_EGRESS_PROXY,
+    ENV_FFMPEG_TIMEOUT_SECONDS,
+    ENV_MAX_DURATION_SECONDS,
+    ENV_MAX_MEDIA_BYTES,
+    positive_limit,
+    production_enabled,
+)
+from textflowkit.sources.detect import SourceRef, UnsafeUrlError, assert_url_is_fetchable
+from textflowkit.sources.scratch import ScratchPaths
+
+
+class AcquisitionError(RuntimeError):
+    """Raised when media cannot be obtained."""
+
+
+def stage_confined_local_media(
+    source: str | Path, *, work_dir: Path, input_root: str | Path
+) -> Path:
+    """Copy a handle-verified local input into isolated scratch before ffmpeg."""
+    base = Path(input_root).expanduser().resolve()
+    path = Path(source)
+    out = ScratchPaths(Path(work_dir)).staged_local(path.suffix)
+    maximum = positive_limit(ENV_MAX_MEDIA_BYTES, 1024 * 1024 * 1024) if production_enabled() else None
+    with path.open("rb") as opened:
+        actual = opened_file_path(opened.fileno(), path)
+        if actual != base and base not in actual.parents:
+            raise UnsafeInputPathError(
+                f"opened input file '{actual}' is outside the allowed root '{base}'"
+            )
+        written = 0
+        out.parent.mkdir(parents=True, exist_ok=True)
+        with out.open("xb") as destination:
+            while chunk := opened.read(1024 * 1024):
+                written += len(chunk)
+                if maximum is not None and written > maximum:
+                    raise AcquisitionError("media exceeds the configured size limit")
+                destination.write(chunk)
+    return out
+
+
+def require_tool(name: str, *, module: str | None = None) -> str | None:
+    """Locate an external tool.
+
+    Checks PATH first, then the interpreter's own Scripts/bin directory. The
+    second check matters for the common case where a dependency was installed
+    into the active environment (or a venv) but the environment is not
+    activated, so its entry point is not on PATH.
+
+    Returns None when the tool is absent and a viable in-process module exists;
+    callers then use the module instead of shelling out.
+    """
+    found = shutil.which(name)
+    if found:
+        return found
+
+    # Look beside the running interpreter (venv/Scripts, venv/bin, ...).
+    exe = name + (".exe" if os.name == "nt" else "")
+    scripts_dir = Path(sys.executable).parent
+    candidate = scripts_dir / exe
+    if candidate.exists():
+        return str(candidate)
+
+    if module:
+        try:
+            __import__(module)
+        except ImportError:
+            pass
+        else:
+            return None  # module usable in-process
+
+    raise AcquisitionError(
+        f"required tool '{name}' not found. Install it (pip install {module or name}) and retry."
+    )
+
+
+# JavaScript runtimes yt-dlp can use, in its own priority order. yt-dlp enables
+# only "deno" by default, so a machine that has Node (or bun/quickjs) still emits
+# "No supported JavaScript runtime could be found". Detecting what is actually
+# present and enabling it explicitly avoids requiring a specific runtime.
+JS_RUNTIMES = ("deno", "node", "bun", "quickjs")
+
+
+def detect_js_runtime() -> str | None:
+    """Return the highest-priority JavaScript runtime available, or None.
+
+    Mirrors yt-dlp's own priority order. Returning None is safe: yt-dlp falls
+    back to non-JS extraction, which works for many videos but can leave some
+    formats unavailable.
+    """
+    for name in JS_RUNTIMES:
+        if shutil.which(name):
+            return name
+    return None
+
+
+def _js_runtime_args() -> list[str]:
+    """Build yt-dlp JS-runtime flags for whatever runtime is installed."""
+    runtime = detect_js_runtime()
+    if not runtime:
+        return []
+    # yt-dlp enables deno by default; enabling another runtime requires clearing
+    # the defaults first so the detected runtime is the one actually used.
+    if runtime == "deno":
+        return []
+    return ["--no-js-runtimes", "--js-runtimes", runtime]
+
+def _fetch_with_module(
+    url: str,
+    *,
+    work_dir: Path,
+    cookies_from_browser: str | None,
+    check_cancel: Callable[[], None] | None = None,
+) -> Path:
+    """Download using the yt_dlp Python API so URL checks cover its requests."""
+    from yt_dlp import YoutubeDL
+
+    layout = ScratchPaths(work_dir)
+    layout.media_dir.mkdir(parents=True, exist_ok=True)
+    outtmpl = layout.download_template
+    hooks: list[Path] = []
+    maximum = positive_limit(ENV_MAX_MEDIA_BYTES, 1024 * 1024 * 1024) if production_enabled() else None
+
+    def _check_download_size(status: dict) -> None:
+        if maximum is None:
+            return
+        for key in ("downloaded_bytes", "total_bytes", "total_bytes_estimate"):
+            value = status.get(key)
+            if isinstance(value, (int, float)) and value > maximum:
+                raise AcquisitionError("download exceeds the configured size limit")
+        # Aggregate fragments and temporary files as well as the final output;
+        # a per-fragment counter alone would reset below the cap each time.
+        total = sum(p.stat().st_size for p in layout.media_dir.rglob("*") if p.is_file())
+        if total > maximum:
+            raise AcquisitionError("download exceeds the configured size limit")
+
+    def _hook(status: dict) -> None:
+        # yt-dlp calls this frequently during a download. Raising here aborts
+        # the download, which is what makes cancellation responsive for the
+        # slowest common case instead of waiting for the whole fetch to finish.
+        if check_cancel is not None:
+            check_cancel()
+        _check_download_size(status)
+        if status.get("status") == "finished":
+            path = status.get("filename") or status.get("_filename")
+            if path:
+                hooks.append(Path(path))
+
+    runtime = detect_js_runtime()
+    opts: dict = {
+        "js_runtimes": {runtime: {}} if runtime else {},
+        "outtmpl": outtmpl,
+        "noplaylist": True,
+        "quiet": True,
+        "no_warnings": True,
+        "format": "bestaudio/best",
+        "restrictfilenames": True,
+        "progress_hooks": [_hook],
+    }
+    if maximum is not None:
+        opts["max_filesize"] = maximum
+    if cookies_from_browser:
+        opts["cookiesfrombrowser"] = (cookies_from_browser,)
+    if production_enabled():
+        proxy = os.environ.get(ENV_EGRESS_PROXY)
+        if not proxy:
+            raise AcquisitionError(
+                f"production URL acquisition requires an SSRF-filtering {ENV_EGRESS_PROXY}"
+            )
+        opts["proxy"] = proxy
+        # External JS runtimes are separate processes and are not guaranteed to
+        # honor yt-dlp's proxy option. Do not let them create an egress bypass.
+        opts["js_runtimes"] = {}
+
+    try:
+        with YoutubeDL(opts) as ydl:
+            original_open = ydl.urlopen
+
+            def checked_open(request):
+                requested = request if isinstance(request, str) else request.url
+                _validate_fetch_url(requested)
+                response = original_open(request)
+                if maximum is not None:
+                    headers = getattr(response, "headers", None)
+                    length = headers.get("Content-Length") if headers is not None else None
+                    if length is not None:
+                        try:
+                            too_large = int(length) > maximum
+                        except (TypeError, ValueError):
+                            too_large = False
+                        if too_large:
+                            close = getattr(response, "close", None)
+                            if callable(close):
+                                close()
+                            raise AcquisitionError("download Content-Length exceeds the configured size limit")
+                final = getattr(response, "url", None)
+                if final:
+                    _validate_fetch_url(final)
+                return response
+
+            ydl.urlopen = checked_open
+            _validate_fetch_url(url)
+            info = ydl.extract_info(url, download=False)
+            _validate_download_info(info, maximum=maximum)
+            ydl.process_info(info)
+    except CancelledError:
+        raise  # an orderly stop, not a fetch failure
+    except AcquisitionError:
+        raise
+    except Exception as exc:
+        raise AcquisitionError(f"yt-dlp failed: {exc}") from exc
+
+    if hooks and hooks[-1].exists():
+        if maximum is not None and hooks[-1].stat().st_size > maximum:
+            raise AcquisitionError("download exceeds the configured size limit")
+        return hooks[-1]
+
+    requested = info.get("requested_downloads") or []
+    for item in requested:
+        candidate = Path(item.get("filepath", ""))
+        if candidate.exists():
+            if maximum is not None and candidate.stat().st_size > maximum:
+                raise AcquisitionError("download exceeds the configured size limit")
+            return candidate
+
+    vid = info.get("id")
+    if vid:
+        for candidate in sorted(work_dir.glob(f"{vid}.*"), key=lambda p: p.stat().st_mtime, reverse=True):
+            if candidate.is_file():
+                return candidate
+
+    files = [f for f in sorted(work_dir.glob("*"), key=lambda p: p.stat().st_mtime, reverse=True) if f.is_file()]
+    if files:
+        return files[0]
+    raise AcquisitionError("yt-dlp reported success but no output file was found")
+
+
+def _validate_fetch_url(url: str) -> None:
+    if not url.startswith(("http://", "https://")):
+        raise AcquisitionError(f"refusing non-HTTP download destination: {url[:100]}")
+    try:
+        assert_url_is_fetchable(url)
+    except UnsafeUrlError as exc:
+        raise AcquisitionError(f"unsafe download destination: {exc}") from exc
+
+
+def _validate_download_info(info: dict | None, *, maximum: int | None = None) -> None:
+    """Recheck final media/fragment URLs selected after yt-dlp extraction."""
+    if not isinstance(info, dict) or info.get("_type", "video") != "video":
+        raise AcquisitionError("yt-dlp did not resolve a single video")
+    selected = [info]
+    selected.extend(item for item in info.get("requested_formats") or [] if isinstance(item, dict))
+    for item in selected:
+        if maximum is not None:
+            size = item.get("filesize") or item.get("filesize_approx")
+            if isinstance(size, (int, float)) and size > maximum:
+                raise AcquisitionError("reported download size exceeds the configured limit")
+        for key in ("url", "manifest_url", "fragment_base_url"):
+            value = item.get(key)
+            if isinstance(value, str) and value.startswith(("http://", "https://")):
+                _validate_fetch_url(value)
+        for fragment in item.get("fragments") or []:
+            value = fragment.get("url") if isinstance(fragment, dict) else None
+            if isinstance(value, str) and value.startswith(("http://", "https://")):
+                _validate_fetch_url(value)
+
+
+def fetch_media(
+    source: SourceRef,
+    *,
+    work_dir: str | Path,
+    cookies_from_browser: str | None = None,
+    check_cancel: Callable[[], None] | None = None,
+) -> Path:
+    """Return a local path to the media.
+
+    Local files are returned unchanged. URLs use yt-dlp's in-process API so
+    requested and selected media URLs can be checked before download.
+    """
+    if source.kind == "file":
+        return Path(source.location)
+
+    if source.kind != "url":
+        raise AcquisitionError(f"unsupported source kind: {source.kind}")
+
+    work = Path(work_dir)
+    work.mkdir(parents=True, exist_ok=True)
+
+    return _fetch_with_module(
+        source.location,
+        work_dir=work,
+        cookies_from_browser=cookies_from_browser,
+        check_cancel=check_cancel,
+    )
+
+def extract_audio(
+    media_path: str | Path,
+    *,
+    work_dir: str | Path,
+    sample_rate: int = 16000,
+    check_cancel: Callable[[], None] | None = None,
+) -> Path:
+    """Decode through a bounded pipe, never an unbounded ffmpeg output file."""
+    ffmpeg = require_tool("ffmpeg")
+    media = Path(media_path)
+    if not media.exists():
+        raise AcquisitionError(f"media not found: {media}")
+
+    work = Path(work_dir)
+    work.mkdir(parents=True, exist_ok=True)
+    out = ScratchPaths(work).decoded_audio
+    out.parent.mkdir(parents=True, exist_ok=True)
+    if media.resolve() == out.resolve():
+        raise AcquisitionError("decoded audio must not overwrite source media")
+
+    production = production_enabled()
+    timeout = positive_limit(ENV_FFMPEG_TIMEOUT_SECONDS, 600)
+    max_media = positive_limit(ENV_MAX_MEDIA_BYTES, 1024 * 1024 * 1024) if production else None
+    max_duration = positive_limit(ENV_MAX_DURATION_SECONDS, 4 * 3600) if production else None
+    max_pcm = max_media - 44 if max_media is not None else None
+    duration_pcm = max_duration * sample_rate * 2 if max_duration is not None else None
+    cmd = [
+        ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin",
+        "-i", str(media),
+        "-vn", "-ac", "1", "-ar", str(sample_rate),
+        "-c:a", "pcm_s16le",
+    ]
+    if max_duration is not None:
+        # The extra second lets the pipe reader distinguish an overlong input
+        # from one that ends exactly at the allowed duration. It never lands on
+        # disk beyond the byte cap below.
+        cmd.extend(["-t", str(max_duration + 1)])
+    cmd.extend(["-f", "s16le", "pipe:1"])
+    if check_cancel is not None:
+        check_cancel()
+    try:
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    except OSError as exc:
+        raise AcquisitionError(f"ffmpeg could not start: {exc}") from exc
+
+    failures: list[str] = []
+    stderr_tail = bytearray()
+
+    def _read_stdout() -> None:
+        written = 0
+        try:
+            assert proc.stdout is not None
+            with wave.open(str(out), "wb") as wav:
+                wav.setnchannels(1)
+                wav.setsampwidth(2)
+                wav.setframerate(sample_rate)
+                while chunk := proc.stdout.read(64 * 1024):
+                    if duration_pcm is not None and written + len(chunk) > duration_pcm:
+                        failures.append("source duration exceeds the configured limit")
+                        return
+                    if max_pcm is not None and written + len(chunk) > max_pcm:
+                        failures.append("decoded output exceeds the configured size limit")
+                        return
+                    wav.writeframesraw(chunk)
+                    written += len(chunk)
+        except (OSError, wave.Error) as exc:
+            failures.append(f"ffmpeg output failed: {exc}")
+
+    def _read_stderr() -> None:
+        assert proc.stderr is not None
+        while chunk := proc.stderr.read(4096):
+            stderr_tail.extend(chunk)
+            if len(stderr_tail) > 8192:
+                del stderr_tail[:-8192]
+
+    output_thread = threading.Thread(target=_read_stdout, daemon=True)
+    error_thread = threading.Thread(target=_read_stderr, daemon=True)
+    output_thread.start()
+    error_thread.start()
+    deadline = time.monotonic() + timeout
+    try:
+        while proc.poll() is None or output_thread.is_alive():
+            if check_cancel is not None:
+                check_cancel()
+            if failures:
+                raise AcquisitionError(failures[0])
+            if time.monotonic() >= deadline:
+                raise AcquisitionError("ffmpeg timed out during decode")
+            time.sleep(0.05)
+        output_thread.join(timeout=5)
+        error_thread.join(timeout=5)
+        if failures:
+            raise AcquisitionError(failures[0])
+        if proc.returncode != 0 or not out.exists():
+            detail = stderr_tail.decode("utf-8", errors="replace").strip()
+            raise AcquisitionError(f"ffmpeg failed: {detail[-1000:] or 'unknown error'}")
+        if max_media is not None and out.stat().st_size > max_media:
+            raise AcquisitionError("decoded output exceeds the configured size limit")
+    except BaseException:
+        if os.name == "nt":
+            # Windows package-manager shims can launch the actual ffmpeg as a
+            # child. Killing only the shim leaves that child holding staged
+            # media open and decoding after cancellation.
+            try:
+                subprocess.run(
+                    ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                    capture_output=True, timeout=10, check=False,
+                )
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+        if proc.poll() is None:
+            proc.kill()
+        proc.wait(timeout=5)
+        output_thread.join(timeout=5)
+        error_thread.join(timeout=5)
+        if proc.stdout is not None:
+            proc.stdout.close()
+        if proc.stderr is not None:
+            proc.stderr.close()
+        out.unlink(missing_ok=True)
+        raise
+    if proc.stdout is not None:
+        proc.stdout.close()
+    if proc.stderr is not None:
+        proc.stderr.close()
+    return out

textflowkit/sources/detect.py

@@ -0,0 +1,200 @@
+"""Platform detection and URL normalization.
+
+The platform layer has exactly one job: figure out where media lives and how to
+fetch it. Transcription never varies by platform.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlparse
+
+PLATFORMS: dict[str, tuple[str, ...]] = {
+    "youtube": ("youtube.com", "youtu.be", "m.youtube.com", "music.youtube.com"),
+    "tiktok": ("tiktok.com", "vm.tiktok.com", "vt.tiktok.com"),
+    "facebook": ("facebook.com", "fb.watch", "fb.com", "m.facebook.com"),
+    "instagram": ("instagram.com", "instagr.am"),
+    "vimeo": ("vimeo.com", "player.vimeo.com"),
+    "twitch": ("twitch.tv", "clips.twitch.tv"),
+    "bilibili": ("bilibili.com", "b23.tv"),
+    "rumble": ("rumble.com",),
+    "kick": ("kick.com",),
+    "zoom": ("zoom.us", "zoom.com"),
+    "medal": ("medal.tv",),
+    "loom": ("loom.com",),
+    "dropbox": ("dropbox.com", "dropboxusercontent.com"),
+}
+
+DIRECT_MEDIA_SUFFIXES = (".mp4", ".mkv", ".webm", ".mov", ".m4a", ".mp3", ".wav", ".ogg", ".flac")
+
+
+class UnsafeUrlError(ValueError):
+    """Raised when a URL targets a loopback, link-local, or private address.
+
+    This is an SSRF guard, not a content policy: transcription is meant for
+    public media, and letting a caller aim the fetcher at the local network or a
+    cloud metadata endpoint turns a tool call into a network probe.
+    """
+
+
+BLOCKED_HOSTNAMES = frozenset(
+    {
+        "localhost",
+        "localhost.localdomain",
+        "ip6-localhost",
+        "ip6-loopback",
+        "metadata",
+        "metadata.google.internal",
+    }
+)
+
+
+# Explicitly blocked networks - the real SSRF targets. Deliberately narrower than
+# `ipaddress.is_private`, which also covers the RFC 2544 benchmarking range
+# (198.18.0.0/15); some local DNS filters resolve public hostnames there, and
+# treating that as private would reject legitimate sites.
+BLOCKED_NETWORKS = tuple(
+    ipaddress.ip_network(n)
+    for n in (
+        "0.0.0.0/8",          # this-network
+        "10.0.0.0/8",         # RFC 1918
+        "100.64.0.0/10",      # CGNAT
+        "127.0.0.0/8",        # loopback
+        "169.254.0.0/16",     # link-local (incl. 169.254.169.254 metadata)
+        "172.16.0.0/12",      # RFC 1918
+        "192.0.0.0/24",       # IETF protocol assignments
+        "192.168.0.0/16",     # RFC 1918
+        "224.0.0.0/4",        # multicast
+        "240.0.0.0/4",        # reserved
+        "::1/128",            # IPv6 loopback
+        "fc00::/7",           # IPv6 unique local
+        "fe80::/10",          # IPv6 link-local
+        "ff00::/8",           # IPv6 multicast
+    )
+)
+
+
+def _is_blocked_ip(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    """True for addresses that must never be reachable from a user-supplied URL."""
+    if ip.is_loopback or ip.is_link_local or ip.is_multicast or ip.is_unspecified:
+        return True
+    return any(ip in net for net in BLOCKED_NETWORKS if net.version == ip.version)
+
+
+def _host_of(url: str) -> str:
+    """Lowercased host from a URL, handling bracketed IPv6 literals.
+
+    `netloc` for `http://[::1]:8080/x` is `[::1]:8080`; naive splitting on ":"
+    yields "[", which silently bypasses any IP check.
+    """
+    netloc = (urlparse(url).netloc or "").lower()
+    netloc = netloc.split("@")[-1]
+    if netloc.startswith("["):
+        end = netloc.find("]")
+        if end != -1:
+            return netloc[1:end]
+    return netloc.split(":")[0]
+
+def assert_url_is_fetchable(url: str) -> None:
+    """Reject URLs aimed at local/private infrastructure.
+
+    Blocks by literal IP and by hostname. Hostname blocking resolves first, so a
+    name pointing at 127.0.0.1 or 169.254.169.254 is caught, and it also catches
+    the well-known metadata hostnames directly.
+
+    Raises `UnsafeUrlError` with an actionable message.
+    """
+    if not is_url(url):
+        return
+
+    host = _host_of(url)
+    if not host:
+        raise UnsafeUrlError(f"URL has no host: {url}")
+
+    if host in BLOCKED_HOSTNAMES or host.endswith(".localhost"):
+        raise UnsafeUrlError(
+            f"refusing to fetch a local address ('{host}'). textflowkit only "
+            "fetches publicly reachable media URLs."
+        )
+
+    # Literal IP? Check it directly.
+    try:
+        literal = ipaddress.ip_address(host)
+    except ValueError:
+        literal = None
+    if literal is not None:
+        if _is_blocked_ip(literal):
+            raise UnsafeUrlError(
+                f"refusing to fetch a non-public IP address ('{host}'). "
+                "Loopback, link-local, and private ranges are blocked."
+            )
+        return
+
+    # Hostname: resolve and check every address it maps to.
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror:
+        # Unresolvable hosts are left to the downloader to report; they are not
+        # an SSRF path because they cannot be connected to.
+        return
+
+    for info in infos:
+        addr = info[4][0]
+        try:
+            resolved = ipaddress.ip_address(addr.split("%")[0])
+        except ValueError:
+            continue
+        if _is_blocked_ip(resolved):
+            raise UnsafeUrlError(
+                f"refusing to fetch '{host}': it resolves to a non-public address "
+                f"({addr}). Loopback, link-local, and private ranges are blocked."
+            )
+
+@dataclass(slots=True)
+class SourceRef:
+    """A resolved input: either a local file or a remote URL."""
+
+    kind: str          # "file" | "url"
+    location: str      # absolute path or URL
+    platform: str      # e.g. "youtube", "local", "direct"
+
+
+def is_url(value: str) -> bool:
+    parsed = urlparse(value)
+    return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+
+
+def detect_platform(value: str) -> str:
+    """Identify the platform for a URL, or 'local' for a filesystem path."""
+    if not is_url(value):
+        return "local"
+    host = (urlparse(value).netloc or "").lower().split("@")[-1].split(":")[0]
+    host = host.removeprefix("www.")
+    for platform, domains in PLATFORMS.items():
+        for domain in domains:
+            if host == domain or host.endswith("." + domain):
+                return platform
+    if host and host.split("/")[-1].lower().endswith(DIRECT_MEDIA_SUFFIXES):
+        return "direct"
+    path = urlparse(value).path.lower()
+    if path.endswith(DIRECT_MEDIA_SUFFIXES):
+        return "direct"
+    return "direct"
+
+
+def resolve_source(value: str) -> SourceRef:
+    """Turn user input into a SourceRef, validating local paths."""
+    if is_url(value):
+        assert_url_is_fetchable(value)
+        return SourceRef(kind="url", location=value, platform=detect_platform(value))
+    p = Path(value).expanduser()
+    if not p.exists():
+        raise FileNotFoundError(f"no such file: {value}")
+    if not p.is_file():
+        raise ValueError(f"not a file: {value}")
+    return SourceRef(kind="file", location=str(p.resolve()), platform="local")
+
+

textflowkit/sources/scratch.py

@@ -0,0 +1,32 @@
+"""The one layout for temporary source media and decoded audio.
+
+Never derive decoded output from the media basename: a staged WAV and its
+decoded WAV would otherwise be the same path. Every pipeline attempt gets its
+own temporary root, and both normal and diarization-reacquisition paths use
+this layout through the acquisition helpers.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class ScratchPaths:
+    root: Path
+
+    @property
+    def media_dir(self) -> Path:
+        return self.root / "media"
+
+    def staged_local(self, suffix: str) -> Path:
+        return self.media_dir / f"input{suffix.lower()}"
+
+    @property
+    def download_template(self) -> str:
+        return str(self.media_dir / "%(id)s.%(ext)s")
+
+    @property
+    def decoded_audio(self) -> Path:
+        return self.root / "audio" / "decoded.wav"