bugcap 0.2.2__py3-none-any.whl

bugcap/recorder.py

@@ -0,0 +1,390 @@
+"""Screen recording: ffmpeg (all OSes) or wf-recorder (Wayland), producing a video, an animated
+GIF, or a few keyframes. Argument construction is pure (testable per OS without running
+anything); `run_recording` owns the process, the stop/cap watchdogs and safe finalization."""
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from .backends import Backend
+from .paths import media_dir
+
+FORMATS = ("video", "frames", "animated")
+
+RECORD_BACKENDS = [
+    Backend(
+        name="ffmpeg",
+        binaries=["ffmpeg"],
+        description="Cross-platform screen recording (X11, Windows, macOS)",
+        platforms=("linux", "macos", "windows"),
+        annotates=False,
+        installs={
+            "linux": [
+                ("apt-get", ["apt-get", "install", "-y", "ffmpeg"]),
+                ("dnf", ["dnf", "install", "-y", "ffmpeg"]),
+                ("pacman", ["pacman", "-S", "--noconfirm", "ffmpeg"]),
+                ("zypper", ["zypper", "install", "-y", "ffmpeg"]),
+                ("brew", ["brew", "install", "ffmpeg"]),
+            ],
+            "macos": [("brew", ["brew", "install", "ffmpeg"])],
+            "windows": [
+                ("winget", ["winget", "install", "--id", "Gyan.FFmpeg", "-e"]),
+                ("scoop", ["scoop", "install", "ffmpeg"]),
+                ("choco", ["choco", "install", "-y", "ffmpeg"]),
+            ],
+        },
+        manual={
+            "linux": "Install ffmpeg from your distro (e.g. sudo apt install ffmpeg).",
+            "macos": "brew install ffmpeg",
+            "windows": "winget install Gyan.FFmpeg, or https://ffmpeg.org/download.html",
+        },
+    ),
+    Backend(
+        name="wf-recorder",
+        binaries=["wf-recorder"],
+        description="Wayland screen recording (ffmpeg's x11grab cannot capture Wayland)",
+        platforms=("linux",),
+        annotates=False,
+        installs={
+            "linux": [
+                ("apt-get", ["apt-get", "install", "-y", "wf-recorder"]),
+                ("dnf", ["dnf", "install", "-y", "wf-recorder"]),
+                ("pacman", ["pacman", "-S", "--noconfirm", "wf-recorder"]),
+                ("zypper", ["zypper", "install", "-y", "wf-recorder"]),
+            ]
+        },
+        manual={"linux": "Install wf-recorder from your distro, or https://github.com/ammen99/wf-recorder"},
+    ),
+]
+
+MACOS_PERMISSION_HELP = (
+    "macOS blocked screen recording. Open System Settings > Privacy & Security > Screen Recording, "
+    "allow your terminal app, then run the command again."
+)
+WAYLAND_HELP = (
+    "Recording a Wayland session needs wf-recorder (ffmpeg's x11grab cannot capture Wayland). "
+    "Install it, e.g. sudo apt install wf-recorder."
+)
+
+
+class RecorderError(RuntimeError):
+    def __init__(self, message: str, guidance: Optional[str] = None):
+        super().__init__(message)
+        self.guidance = guidance
+
+
+def platform_key(platform: Optional[str] = None) -> str:
+    platform = platform or sys.platform
+    if platform in ("windows", "win32"):
+        return "windows"
+    if platform in ("macos", "darwin"):
+        return "macos"
+    return "linux"
+
+
+def by_name(name: str) -> Backend:
+    for backend in RECORD_BACKENDS:
+        if backend.name == name:
+            return backend
+    raise KeyError(name)
+
+
+def detect_recorder(platform: Optional[str] = None, env: Optional[dict] = None, which=shutil.which) -> Optional[Backend]:
+    """wf-recorder on Wayland when installed, otherwise ffmpeg, otherwise None."""
+    platform = platform_key(platform)
+    env = os.environ if env is None else env
+    if platform == "linux" and env.get("WAYLAND_DISPLAY") and which("wf-recorder"):
+        return by_name("wf-recorder")
+    if which("ffmpeg"):
+        return by_name("ffmpeg")
+    return None
+
+
+# --- argument construction (pure) ----------------------------------------------
+
+def _scale_filter(width: int = 960) -> str:
+    return f"scale='min({width},iw)':-2:flags=lanczos"
+
+
+def build_capture_argv(
+    backend: str,
+    platform: str,
+    fmt: str,
+    fps: int,
+    max_seconds: int,
+    out_path: str,
+    display: Optional[str] = None,
+    codec: str = "h264",
+    av_index: int = 0,
+) -> list[str]:
+    """The command that records the screen to `out_path` (always a real video; animated and
+    frames are derived from it afterwards)."""
+    platform = platform_key(platform)
+    if fmt not in FORMATS:
+        raise ValueError(f"unknown format {fmt!r}")
+    vp9 = codec == "vp9" and fmt == "video"
+    if backend == "wf-recorder":
+        argv = ["wf-recorder", "-r", str(fps)]
+        argv += ["-c", "libvpx-vp9"] if vp9 else ["-c", "libx264", "-x", "yuv420p"]
+        return argv + ["-f", out_path]
+
+    argv = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "warning"]
+    if platform == "linux":
+        argv += ["-f", "x11grab", "-framerate", str(fps), "-i", display or ":0.0"]
+    elif platform == "windows":
+        argv += ["-f", "gdigrab", "-framerate", str(fps), "-i", "desktop"]
+    else:
+        argv += ["-f", "avfoundation", "-framerate", str(fps), "-capture_cursor", "1", "-i", f"{av_index}:none"]
+    argv += ["-t", str(max_seconds)]
+    argv += ["-vf", "pad=ceil(iw/2)*2:ceil(ih/2)*2"]
+    if vp9:
+        argv += ["-c:v", "libvpx-vp9", "-crf", "35", "-b:v", "0"]
+    else:
+        argv += ["-c:v", "libx264", "-crf", "30", "-pix_fmt", "yuv420p", "-preset", "veryfast"]
+    return argv + [out_path]
+
+
+def build_postprocess_argv(fmt: str, in_path: str, out_path: str, fps: float, max_frames: int = 8) -> list[str]:
+    """Derive an animated GIF (palette two-pass in one filter graph) or keyframes (`out_path`
+    is a printf pattern such as `frame-%03d.png`) from a recorded video."""
+    if fmt == "animated":
+        graph = f"fps={fps:g},{_scale_filter()},split[s0][s1];[s0]palettegen=stats_mode=diff[p];[s1][p]paletteuse"
+        return ["ffmpeg", "-y", "-hide_banner", "-loglevel", "warning", "-i", in_path,
+                "-vf", graph, "-loop", "0", out_path]
+    if fmt == "frames":
+        return ["ffmpeg", "-y", "-hide_banner", "-loglevel", "warning", "-i", in_path,
+                "-vf", f"fps={fps:.4f},{_scale_filter(1280)}", "-frames:v", str(max_frames), out_path]
+    raise ValueError(f"no post-processing for format {fmt!r}")
+
+
+_AV_SCREEN = re.compile(r"\[(\d+)\]\s+Capture screen \d+")
+
+
+def parse_avfoundation_screen_index(output: str) -> int:
+    match = _AV_SCREEN.search(output)
+    if not match:
+        raise RecorderError("no screen capture device found by ffmpeg/avfoundation", MACOS_PERMISSION_HELP)
+    return int(match.group(1))
+
+
+def diagnose_failure(stderr: str, platform: str) -> Optional[str]:
+    text = stderr or ""
+    platform = platform_key(platform)
+    if platform == "macos" and re.search(r"Input/output error|not permitted|permission|denied", text, re.I):
+        return MACOS_PERMISSION_HELP
+    if platform == "linux" and re.search(r"Cannot open display|x11grab|Could not open", text, re.I):
+        return WAYLAND_HELP
+    return None
+
+
+# --- running -------------------------------------------------------------------
+
+@dataclass
+class RecordResult:
+    path: Optional[Path]
+    size_bytes: int
+    reason: str
+    duration: float
+    kind: str
+    mime: str
+    frames: list = field(default_factory=list)  # [(path, size)]
+
+
+def _size(path) -> int:
+    try:
+        return os.path.getsize(path)
+    except OSError:
+        return 0
+
+
+def _stop_process(proc, backend: str, platform: str) -> None:
+    if proc.poll() is not None:
+        return
+    try:
+        if backend == "ffmpeg":
+            try:
+                proc.stdin.write(b"q")
+                proc.stdin.flush()
+                proc.stdin.close()
+            except (OSError, ValueError, AttributeError):
+                proc.terminate()
+        elif platform_key(platform) == "windows":  # pragma: no cover
+            proc.terminate()
+        else:
+            proc.send_signal(signal.SIGINT)
+        proc.wait(timeout=15)
+    except subprocess.TimeoutExpired:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+
+
+def run_recording(
+    backend: str,
+    fmt: str,
+    fps: int,
+    max_seconds: int,
+    max_mb: float,
+    out_dir: Optional[Path] = None,
+    wait_for_stop: Callable[[], bool] = lambda: False,
+    *,
+    platform: Optional[str] = None,
+    env: Optional[dict] = None,
+    codec: str = "h264",
+    popen=subprocess.Popen,
+    runner=subprocess.run,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+    size_of: Callable[[object], int] = _size,
+    poll_interval: float = 0.2,
+) -> RecordResult:
+    """Record until `wait_for_stop()` is true, Ctrl+C, or a cap is hit; always wait for the
+    recorder to exit so the file is complete; then derive animated/frames if requested."""
+    platform = platform_key(platform)
+    env = os.environ if env is None else env
+    try:
+        out_dir = Path(out_dir) if out_dir else media_dir()
+        out_dir.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise RecorderError(f"cannot use the output folder: {exc.strerror or exc}") from exc
+    if not os.access(out_dir, os.W_OK):
+        raise RecorderError(f"the output folder is not writable: {out_dir}")
+    stem = uuid.uuid4().hex
+    ext = ".webm" if (codec == "vp9" and fmt == "video") else ".mp4"
+    raw = out_dir / f"{stem}{ext}"
+
+    av_index = 0
+    if backend == "ffmpeg" and platform == "macos":
+        probe = runner(["ffmpeg", "-f", "avfoundation", "-list_devices", "true", "-i", ""],
+                       capture_output=True, text=True)
+        av_index = parse_avfoundation_screen_index((probe.stderr or "") + (probe.stdout or ""))
+
+    argv = build_capture_argv(backend, platform, fmt, fps, max_seconds, str(raw),
+                              display=env.get("DISPLAY"), codec=codec, av_index=av_index)
+    log = tempfile.TemporaryFile()
+    try:
+        proc = popen(argv, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=log)
+    except OSError as exc:
+        log.close()
+        raise RecorderError(f"could not start {backend}: {exc}", guidance_for(backend, platform)) from exc
+
+    started = clock()
+    reason = "stopped by user"
+    max_bytes = int(max_mb * 1024 * 1024)
+    try:
+        while True:
+            if proc.poll() is not None:
+                reason = "recorder exited"
+                break
+            if wait_for_stop():
+                reason = "stopped by user"
+                break
+            if clock() - started >= max_seconds:
+                reason = "duration cap"
+                break
+            if size_of(raw) >= max_bytes:
+                reason = "size cap"
+                break
+            sleep(poll_interval)
+    except KeyboardInterrupt:
+        reason = "interrupted"
+    def _finish() -> RecordResult:
+        duration = clock() - started
+        _stop_process(proc, backend, platform)
+
+        log.seek(0)
+        stderr_text = log.read().decode("utf-8", "replace")
+        log.close()
+        if size_of(raw) == 0:
+            raw_exists = Path(raw).exists()
+            if raw_exists:
+                Path(raw).unlink(missing_ok=True)
+            raise RecorderError(
+                "the recording is empty" + (f": {stderr_text.strip().splitlines()[-1]}" if stderr_text.strip() else ""),
+                diagnose_failure(stderr_text, platform),
+            )
+
+        if fmt == "video":
+            mime = "video/webm" if raw.suffix == ".webm" else "video/mp4"
+            return RecordResult(raw, size_of(raw), reason, duration, "video", mime)
+
+        if fmt == "animated":
+            out = out_dir / f"{stem}.gif"
+            try:
+                _run_checked(runner, build_postprocess_argv("animated", str(raw), str(out), min(fps, 8)))
+            except RecorderError:
+                raw.unlink(missing_ok=True)
+                out.unlink(missing_ok=True)
+                raise
+            raw.unlink(missing_ok=True)
+            return RecordResult(out, size_of(out), reason, duration, "animated", "image/gif")
+
+        frames_dir = out_dir / f"{stem}-frames"
+        frames_dir.mkdir(parents=True, exist_ok=True)
+        pattern = str(frames_dir / "frame-%03d.png")
+        per_second = 8 / max(duration, 1.0)
+        try:
+            _run_checked(runner, build_postprocess_argv("frames", str(raw), pattern, min(float(fps), per_second), 8))
+            frames = [(str(p), size_of(p)) for p in sorted(frames_dir.glob("frame-*.png"))]
+            if not frames:
+                raise RecorderError("no frames could be extracted from the recording")
+        except RecorderError:
+            shutil.rmtree(frames_dir, ignore_errors=True)
+            raise
+        finally:
+            raw.unlink(missing_ok=True)
+        return RecordResult(None, sum(s for _, s in frames), reason, duration, "frames", "image/png", frames)
+
+    try:
+        return _finish()
+    except KeyboardInterrupt:
+        # Ctrl+C while finalizing: never attach (or leave behind) a partial file.
+        if proc.poll() is None:
+            proc.kill()
+        for leftover in (raw, out_dir / f"{stem}.gif"):
+            Path(leftover).unlink(missing_ok=True)
+        shutil.rmtree(out_dir / f"{stem}-frames", ignore_errors=True)
+        raise RecorderError("interrupted while finishing the recording; nothing was attached") from None
+
+
+def discard(result: "RecordResult") -> None:
+    """Delete the files of a recording that will not be attached."""
+    if result.path:
+        Path(result.path).unlink(missing_ok=True)
+    for frame_path, _ in result.frames:
+        Path(frame_path).unlink(missing_ok=True)
+    if result.frames:
+        try:
+            Path(result.frames[0][0]).parent.rmdir()
+        except OSError:
+            pass
+
+
+def _run_checked(runner, argv: list[str]) -> None:
+    try:
+        result = runner(argv, capture_output=True, text=True)
+    except OSError as exc:
+        raise RecorderError(
+            "ffmpeg is needed to make animated/frames output", guidance_for("ffmpeg")
+        ) from exc
+    if getattr(result, "returncode", 0) != 0:
+        raise RecorderError(f"ffmpeg post-processing failed: {(getattr(result, 'stderr', '') or '').strip()[-300:]}")
+
+
+def guidance_for(backend: str, platform: Optional[str] = None) -> str:
+    b = by_name(backend)
+    key = platform_key(platform)
+    return b.manual.get(key, "See the project's website for install steps.")

bugcap/refs.py

@@ -0,0 +1,213 @@
+"""`@` references in notes: `@3` (media index), `@login-error` (media label), `@@` (literal @).
+
+References are ignored inside fenced code blocks, inline code spans and email-like text.
+Everything here is pure text processing; the rules for what a reference may point at
+live in `validate_references`."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from .errors import ServiceError
+
+REMOVED_TEXT = "[image removed]"
+LABEL_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_\-]*$")
+_REF_RE = re.compile(r"@@|(?<![\w.%+\-])@([A-Za-z0-9_\-]+)(?![\w\-])")
+_FENCE_RE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+
+
+@dataclass
+class Ref:
+    token: str  # text as written, e.g. "@1", "@login-error", "@@"
+    start: int
+    end: int
+    kind: Literal["index", "label", "escape", "unknown"]
+
+    @property
+    def name(self) -> str:
+        return self.token[1:]
+
+
+def _blank(text: str) -> str:
+    return "".join(ch if ch == "\n" else " " for ch in text)
+
+
+def mask(notes: str) -> str:
+    """Replace fenced blocks and inline code spans with spaces (same length, same newlines)."""
+    out: list[str] = []
+    fence: Optional[tuple[str, int]] = None  # (char, length) of the open fence
+    prose: list[str] = []  # consecutive non-fence lines, so code spans may cross lines
+
+    def flush():
+        if prose:
+            out.append(_mask_spans("".join(prose)))
+            prose.clear()
+
+    for line in notes.splitlines(keepends=True):
+        stripped = line.rstrip("\r\n")
+        if fence is None:
+            match = _FENCE_RE.match(stripped)
+            if match:
+                flush()
+                run = match.group(1)
+                fence = (run[0], len(run))
+                out.append(_blank(line))
+            else:
+                prose.append(line)
+        else:
+            out.append(_blank(line))
+            match = _FENCE_RE.match(stripped)
+            if (
+                match
+                and match.group(1)[0] == fence[0]
+                and len(match.group(1)) >= fence[1]
+                and not stripped.strip().strip(fence[0])
+            ):
+                fence = None
+    flush()
+    return "".join(out)
+
+
+def _mask_spans(text: str) -> str:
+    chars = list(text)
+    i, n = 0, len(text)
+    while i < n:
+        if text[i] != "`":
+            i += 1
+            continue
+        j = i
+        while j < n and text[j] == "`":
+            j += 1
+        run = j - i
+        k = j
+        closed = -1
+        while k < n:
+            if text[k] == "`":
+                m = k
+                while m < n and text[m] == "`":
+                    m += 1
+                if m - k == run:
+                    closed = m
+                    break
+                k = m
+            else:
+                k += 1
+        if closed == -1:
+            i = j  # unmatched backticks are literal
+        else:
+            for p in range(i, closed):
+                if chars[p] != "\n":
+                    chars[p] = " "
+            i = closed
+    return "".join(chars)
+
+
+def _classify(name: str) -> str:
+    if name.isdigit() and not name.startswith("0"):
+        return "index"
+    if LABEL_RE.match(name):
+        return "label"
+    return "unknown"
+
+
+def parse_references(notes: str) -> list[Ref]:
+    masked = mask(notes or "")
+    refs: list[Ref] = []
+    for match in _REF_RE.finditer(masked):
+        if match.group(0) == "@@":
+            refs.append(Ref("@@", match.start(), match.end(), "escape"))
+        else:
+            refs.append(Ref(match.group(0), match.start(), match.end(), _classify(match.group(1))))  # type: ignore[arg-type]
+    return refs
+
+
+def resolve(ref: Ref, media: list):
+    """The media item a reference points at (label match is case-sensitive), or None."""
+    if ref.kind == "index":
+        for item in media:
+            if item.idx == int(ref.name):
+                return item
+    elif ref.kind == "label":
+        for item in media:
+            if item.label == ref.name:
+                return item
+    return None
+
+
+def valid_tokens(media: list) -> list[str]:
+    indexes = [f"@{m.idx}" for m in sorted(media, key=lambda m: m.idx)]
+    labels = [f"@{m.label}" for m in sorted(media, key=lambda m: m.idx) if m.label]
+    return indexes + labels
+
+
+def validate_references(notes: str, media: list) -> None:
+    for ref in parse_references(notes):
+        if ref.kind == "escape":
+            continue
+        if resolve(ref, media) is None:
+            valid = valid_tokens(media)
+            raise ServiceError(
+                "invalid_reference",
+                f"unknown reference {ref.token} in notes",
+                {"token": ref.token, "valid": valid},
+            )
+
+
+def _rewrite(notes: str, mapping: dict[str, str]) -> tuple[str, int]:
+    out = notes
+    count = 0
+    for ref in reversed(parse_references(notes)):
+        if ref.kind in ("index", "label") and ref.name in mapping:
+            replacement = mapping[ref.name]
+            if replacement != ref.token:
+                out = out[: ref.start] + replacement + out[ref.end :]
+                count += 1
+    return out, count
+
+
+def rewrite_references(notes: str, mapping: dict[str, str]) -> str:
+    """Replace references by name (`{"2": "@1", "old": "@new", "3": "[image removed]"}`).
+    Code, emails and `@@` are never touched; other text is preserved exactly."""
+    return _rewrite(notes, mapping)[0]
+
+
+def rewrite_references_counted(notes: str, mapping: dict[str, str]) -> tuple[str, int]:
+    return _rewrite(notes, mapping)
+
+
+def references_to(notes: str, item, media_all: list) -> list[Ref]:
+    """References in `notes` that resolve to `item`."""
+    return [
+        r
+        for r in parse_references(notes)
+        if (found := resolve(r, media_all)) is not None and found.id == item.id
+    ]
+
+
+def display_notes(notes: str, media: list) -> str:
+    """Notes for terminal display: `@1` becomes `@1 (images/…)` and `@@` prints as `@`."""
+    out = notes or ""
+    for ref in reversed(parse_references(out)):
+        if ref.kind == "escape":
+            out = out[: ref.start] + "@" + out[ref.end :]
+        elif ref.kind in ("index", "label"):
+            item = resolve(ref, media)
+            if item is not None:
+                where = item.path or f"{len(item.frames)} frames"
+                out = out[: ref.start] + f"{ref.token} ({where})" + out[ref.end :]
+    return out
+
+
+def substitute(notes: str, media: list, replacements: dict) -> str:
+    """Notes for an outside destination: each resolvable reference becomes
+    `replacements[media.id]` (left as written when absent) and `@@` becomes `@`."""
+    out = notes or ""
+    for ref in reversed(parse_references(out)):
+        if ref.kind == "escape":
+            out = out[: ref.start] + "@" + out[ref.end :]
+        elif ref.kind in ("index", "label"):
+            item = resolve(ref, media)
+            if item is not None and item.id in replacements:
+                out = out[: ref.start] + replacements[item.id] + out[ref.end :]
+    return out