watchby 0.0.1__py3-none-any.whl

watchby/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("watchby")
+except PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

watchby/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+from watchby.cli import main
+
+if __name__ == "__main__":
+    main()

watchby/cli/__init__.py

@@ -0,0 +1,103 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+import os
+import sys
+from typing import Annotated
+
+import typer
+
+from watchby import __version__
+from watchby.cli.doctor import doctor
+from watchby.cli.init import init
+from watchby.cli.process import EPILOG as PROCESS_EPILOG
+from watchby.cli.process import HELP as PROCESS_HELP
+from watchby.cli.process import process
+from watchby.cli.term import prepare_streams
+from watchby.errors import WatchbyError
+from watchby.i18n import _, set_language
+from watchby.runtime import host
+
+UNSUPPORTED_ENV = "WATCHBY_UNSUPPORTED_OS"
+WATCH = "Watch"
+SETUP = "Set up"
+
+EPILOG = """\b
+Start here:
+  watchby doctor                 check this machine
+  watchby init                   write watchby.toml so runs need no flags
+  watchby process screen.mp4     read a screen recording
+
+Every command has its own help: watchby process --help
+Documentation: https://github.com/khvostpola/watchby/tree/main/docs"""
+
+app = typer.Typer(
+    name="watchby",
+    help=(
+        "What a screen recording showed, next to what was said: stable screens, their text, "
+        "and a transcript that points at them. Runs on your machine."
+    ),
+    epilog=EPILOG,
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+app.command("process", rich_help_panel=WATCH, epilog=PROCESS_EPILOG, help=PROCESS_HELP)(process)
+app.command("init", rich_help_panel=SETUP)(init)
+app.command("doctor", rich_help_panel=SETUP)(doctor)
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+def _ui_language(value: str | None) -> str | None:
+    if value is not None:
+        set_language(value)
+    return value
+
+
+@app.callback()
+def root(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version, is_eager=True, help="Show the version and exit."
+        ),
+    ] = False,
+    ui_lang: Annotated[
+        str | None,
+        typer.Option(
+            "--ui-lang",
+            callback=_ui_language,
+            is_eager=True,
+            help="Language of messages, such as es (default: your system language).",
+        ),
+    ] = None,
+) -> None:
+    pass
+
+
+def warn_unsupported_system() -> None:
+    if host.is_supported() or os.environ.get(UNSUPPORTED_ENV):
+        return
+    message = _(
+        "watchby supports Linux and Windows; {system} is untested (set {env}=1 to hide this)"
+    )
+    print(message.format(system=host.platform_label(), env=UNSUPPORTED_ENV), file=sys.stderr)
+
+
+def main() -> None:
+    prepare_streams()
+    set_language()
+    warn_unsupported_system()
+    try:
+        app()
+    except KeyboardInterrupt:
+        sys.exit(130)
+    except WatchbyError as exc:
+        message = _("error: {message}").format(message=exc)
+        print(f"{message}  [{exc.error_id} · exit {exc.exit_code}]", file=sys.stderr)
+        sys.exit(exc.exit_code)

watchby/cli/doctor.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+import json
+import platform
+import sys
+from typing import Annotated
+
+import typer
+
+from watchby import __version__
+from watchby.i18n import _, ngettext, set_language
+from watchby.runtime.diagnose import Check, run_checks
+
+SYMBOLS = {"ok": "ok  ", "warn": "warn", "fail": "FAIL"}
+
+
+def _as_dict(check: Check) -> dict[str, str | None]:
+    return {
+        "name": check.name,
+        "status": check.status,
+        "detail": check.detail,
+        "hint": check.hint,
+    }
+
+
+def _print(checks: list[Check]) -> None:
+    width = max(len(c.name) for c in checks)
+    for check in checks:
+        typer.echo(f"{SYMBOLS[check.status]}  {check.name.ljust(width)}  {check.detail}")
+        if check.hint and check.status != "ok":
+            typer.echo(f"      {' ' * width}  -> {check.hint}")
+
+
+def doctor(
+    as_json: Annotated[bool, typer.Option("--json", help="Machine-readable output")] = False,
+) -> None:
+    """Check that this machine can run watchby and say how to fix what is missing."""
+    if as_json:
+        set_language("en")
+    checks = run_checks()
+    failures = [c for c in checks if c.status == "fail"]
+    if as_json:
+        typer.echo(
+            json.dumps(
+                {
+                    "watchby": __version__,
+                    "python": platform.python_version(),
+                    "platform": sys.platform,
+                    "ffmpeg": next((c.detail for c in checks if c.name == "ffmpeg"), None),
+                    "saidby": next((c.detail for c in checks if c.name == "saidby"), None),
+                    "checks": [_as_dict(c) for c in checks],
+                    "problems": [f"{c.name}: {c.detail}" for c in failures],
+                },
+                indent=2,
+            )
+        )
+    else:
+        typer.echo(_("watchby {version}").format(version=__version__))
+        _print(checks)
+        typer.echo("")
+        if failures:
+            problems = ngettext(
+                "{n} problem to fix before processing",
+                "{n} problems to fix before processing",
+                len(failures),
+            )
+            typer.echo(problems.format(n=len(failures)))
+        else:
+            typer.echo(_("ready"))
+    raise typer.Exit(1 if failures else 0)

watchby/cli/init.py

@@ -0,0 +1,68 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from watchby.config.settings import CONFIG_NAME, global_config_path
+from watchby.config.writer import check_language, default_language, render_config
+from watchby.errors import InputError
+from watchby.i18n import _
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty() and sys.stderr.isatty()
+
+
+def _write_new(path: Path, text: str, note: str) -> None:
+    if path.exists():
+        typer.echo(_("  kept   {name:<16} already there, not touched").format(name=path.name))
+        return
+    try:
+        path.write_text(text, encoding="utf-8", newline="\n")
+    except OSError as exc:
+        raise InputError(_("cannot write {path}: {error}").format(path=path, error=exc)) from exc
+    typer.echo(_("  wrote  {name:<16} {note}").format(name=path.name, note=note))
+
+
+def init(
+    language: Annotated[
+        str | None,
+        typer.Option(help="Language of your recordings, such as es or en (default: asks)."),
+    ] = None,
+    yes: Annotated[
+        bool, typer.Option("--yes", help="Do not ask: take the language option or the default.")
+    ] = False,
+    global_: Annotated[
+        bool,
+        typer.Option(
+            "--global",
+            help="Set up the user config folder for every folder, not this one "
+            "(~/.config/watchby on Linux, %APPDATA%\\watchby on Windows).",
+        ),
+    ] = False,
+) -> None:
+    """Create watchby.toml so the next run needs no flags."""
+    ask = _interactive() and not yes
+    chosen = language or default_language()
+    if ask and language is None:
+        chosen = typer.prompt(_("Language of your recordings"), default=chosen)
+    chosen = check_language(chosen)
+    folder = global_config_path().parent if global_ else Path.cwd()
+    try:
+        folder.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise InputError(_("cannot create {path}: {error}").format(path=folder, error=exc)) from exc
+    config = folder / ("config.toml" if global_ else CONFIG_NAME)
+    typer.echo(_("Setting up {folder}").format(folder=folder))
+    note = _("language {language}").format(language=chosen)
+    if not global_:
+        note += " · " + _("output ./watchby/")
+    _write_new(config, render_config(language=chosen, out=None if global_ else "watchby"), note)
+    where = _("every folder") if global_ else _("this folder")
+    typer.echo(
+        _("Done. In {where}, `watchby process screen.mp4` needs no flags now.").format(where=where)
+    )

watchby/cli/process.py

@@ -0,0 +1,320 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from watchby import __version__
+from watchby.config.settings import Settings
+from watchby.errors import WatchbyError
+from watchby.i18n import _
+
+IO = "Input and output"
+SCREENS = "Screens"
+TRANSCRIPT = "Transcript"
+TEXT = "Text"
+MODELS = "Models"
+PRIVACY = "Privacy"
+BEHAVIOR = "Run behavior"
+
+HELP = (
+    "Turn screen recordings into stable screens, their text, and a transcript that points at "
+    "them. Not available yet: this version only checks the options."
+)
+EPILOG = """\b
+Examples:
+  watchby process screen.mp4 --language es
+  watchby process call.mp4 --source call --out results/
+  watchby process app.mp4 --source screen --ocr none
+  watchby process call.mp4 --transcript saidby/call
+  watchby process call.mp4 --describe --llm-backend anthropic --allow-remote-llm
+
+Each input gets its own folder under the output folder (./watchby unless you pass --out or set
+`out` in watchby.toml). A failed run keeps its work and the next run resumes from the last
+finished stage."""
+
+
+def process(
+    inputs: Annotated[list[Path], typer.Argument(help="Videos (anything ffmpeg reads).")],
+    out: Annotated[
+        Path | None,
+        typer.Option(
+            "--out",
+            help="Folder for the results, one subfolder per input (default: ./watchby).",
+            rich_help_panel=IO,
+        ),
+    ] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            help="A watchby.toml with defaults for the options below.", rich_help_panel=IO
+        ),
+    ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option(
+            help=(
+                "auto (default): look for a shared screen inside a video call and fall back to "
+                "the whole frame. call: only the shared screen. screen: always the whole frame."
+            ),
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    crop: Annotated[
+        str | None,
+        typer.Option(
+            help="A fixed screen rectangle WxH+X+Y in pixels, such as 894x504+94+906; "
+            "skips the detection.",
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    fps: Annotated[
+        float | None,
+        typer.Option(
+            help="Frames per second looked at to find changes (default 1).",
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    min_screen: Annotated[
+        float | None,
+        typer.Option(
+            help="Seconds a screen must stay to count as stable (default 2).",
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    change_threshold: Annotated[
+        float | None,
+        typer.Option(
+            help="Share of a grid cell's pixels that must change to count it (default 0.02).",
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    mask: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--mask",
+            help="A rectangle WxH+X+Y of the screen to ignore when comparing frames "
+            "(% works too); repeat it.",
+            rich_help_panel=SCREENS,
+        ),
+    ] = None,
+    transcript: Annotated[
+        Path | None,
+        typer.Option(
+            help="Use this finished saidby run of the same video instead of running saidby "
+            "(one input only).",
+            rich_help_panel=TRANSCRIPT,
+        ),
+    ] = None,
+    no_transcript: Annotated[
+        bool,
+        typer.Option(
+            "--no-transcript",
+            help="Do not run saidby: screens only. Automatic when the video has no audio.",
+            rich_help_panel=TRANSCRIPT,
+        ),
+    ] = False,
+    language: Annotated[
+        str | None,
+        typer.Option(
+            help="Language code of the speech and the on-screen text (es, en, pt...). "
+            "Passed to saidby.",
+            rich_help_panel=TRANSCRIPT,
+        ),
+    ] = None,
+    saidby_arg: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--saidby-arg",
+            help="One extra argument for saidby; repeat it. Options watchby sets itself are "
+            "refused.",
+            rich_help_panel=TRANSCRIPT,
+        ),
+    ] = None,
+    ocr: Annotated[
+        str | None,
+        typer.Option(
+            help="Text reader: rapidocr (default), tesseract (extra) or none.",
+            rich_help_panel=TEXT,
+        ),
+    ] = None,
+    ocr_lang: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--ocr-lang",
+            help="Language of the on-screen text; repeat it (default: the transcript language "
+            "plus en).",
+            rich_help_panel=TEXT,
+        ),
+    ] = None,
+    describe: Annotated[
+        bool,
+        typer.Option(
+            "--describe",
+            help="Have a model describe each stable screen.",
+            rich_help_panel=MODELS,
+        ),
+    ] = False,
+    summarize: Annotated[
+        bool,
+        typer.Option(
+            "--summarize",
+            help="Have a model sum up each stretch of talk next to what was on screen. "
+            "Implies --describe.",
+            rich_help_panel=MODELS,
+        ),
+    ] = False,
+    llm_backend: Annotated[
+        str | None,
+        typer.Option(
+            help="openai (default): a llama-server or any OpenAI-compatible server. "
+            "anthropic: Claude through the official SDK (extra).",
+            rich_help_panel=MODELS,
+        ),
+    ] = None,
+    llm_url: Annotated[
+        str | None,
+        typer.Option(
+            help="Use an OpenAI-compatible server you already run, not llama-server.",
+            rich_help_panel=MODELS,
+        ),
+    ] = None,
+    llm_model: Annotated[
+        str | None,
+        typer.Option(help="Model to ask (default depends on the backend).", rich_help_panel=MODELS),
+    ] = None,
+    llm_binary: Annotated[
+        str | None,
+        typer.Option(
+            help="Path to llama-server (default: PATH or WATCHBY_LLAMA_SERVER).",
+            rich_help_panel=MODELS,
+        ),
+    ] = None,
+    allow_remote_llm: Annotated[
+        bool,
+        typer.Option(
+            "--allow-remote-llm",
+            help="Allow a model endpoint that is not on this machine.",
+            rich_help_panel=MODELS,
+        ),
+    ] = False,
+    llm_max_screens: Annotated[
+        int | None,
+        typer.Option(
+            min=1,
+            help="Most screens sent to the model in one run (default 150).",
+            rich_help_panel=MODELS,
+        ),
+    ] = None,
+    no_pii: Annotated[
+        bool,
+        typer.Option(
+            "--no-pii",
+            help="Do not flag screens that show email addresses or phone numbers.",
+            rich_help_panel=PRIVACY,
+        ),
+    ] = False,
+    keep_all_screens: Annotated[
+        bool,
+        typer.Option(
+            "--keep-all-screens",
+            help="Also keep captures from stretches with no shared screen.",
+            rich_help_panel=PRIVACY,
+        ),
+    ] = False,
+    strict_offline: Annotated[
+        bool,
+        typer.Option(
+            "--strict-offline",
+            help="Fail with exit code 8 if anything tries to leave this machine.",
+            rich_help_panel=PRIVACY,
+        ),
+    ] = False,
+    device: Annotated[
+        str | None,
+        typer.Option(
+            help="auto (default): GPU if usable, else CPU. Or force cuda or cpu. "
+            "Applies to saidby and to a local model server.",
+            rich_help_panel=BEHAVIOR,
+        ),
+    ] = None,
+    keep_intermediates: Annotated[
+        bool,
+        typer.Option(
+            "--keep-intermediates",
+            help="Keep the .work folder after success (it is kept on failure).",
+            rich_help_panel=BEHAVIOR,
+        ),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Redo a stage whose results are already in the output folder.",
+            rich_help_panel=BEHAVIOR,
+        ),
+    ] = False,
+    fail_fast: Annotated[
+        bool,
+        typer.Option(
+            "--fail-fast", help="Stop at the first input that fails.", rich_help_panel=BEHAVIOR
+        ),
+    ] = False,
+    progress: Annotated[
+        str | None,
+        typer.Option(
+            help="human (default, on stderr), json (one event per line on stdout) or none.",
+            rich_help_panel=BEHAVIOR,
+        ),
+    ] = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Exit with code 1 when a run finishes degraded (screens without a transcript, "
+            "for example).",
+            rich_help_panel=BEHAVIOR,
+        ),
+    ] = False,
+) -> None:
+    Settings.load(
+        config,
+        {
+            "out": out,
+            "source": source,
+            "crop": crop,
+            "fps": fps,
+            "min_screen": min_screen,
+            "change_threshold": change_threshold,
+            "masks": mask or None,
+            "run_saidby": False if no_transcript else None,
+            "language": language,
+            "saidby_args": saidby_arg or None,
+            "ocr": ocr,
+            "ocr_lang": ocr_lang or None,
+            "describe": describe or None,
+            "summarize": summarize or None,
+            "llm_backend": llm_backend,
+            "llm_url": llm_url,
+            "llm_model": llm_model,
+            "llm_binary": llm_binary,
+            "allow_remote_llm": allow_remote_llm or None,
+            "llm_max_screens": llm_max_screens,
+            "pii": False if no_pii else None,
+            "keep_all_screens": keep_all_screens or None,
+            "strict_offline": strict_offline or None,
+            "device": device,
+            "keep_intermediates": keep_intermediates or None,
+            "force": force or None,
+            "fail_fast": fail_fast or None,
+            "progress": progress,
+            "strict": strict or None,
+        },
+    )
+    raise WatchbyError(
+        _("watchby {version} cannot process recordings yet: the pipeline arrives in 0.1.0").format(
+            version=__version__
+        )
+    )

watchby/cli/term.py

@@ -0,0 +1,106 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0
+
+import contextlib
+import io
+import os
+import shutil
+import sys
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import TextIO
+
+from watchby.runtime import host
+
+RESET = "\x1b[0m"
+CODES = {
+    "bold": "1",
+    "dim": "2",
+    "red": "31",
+    "green": "32",
+    "yellow": "33",
+    "blue": "34",
+    "cyan": "36",
+}
+TRUECOLOR_VALUES = {"truecolor", "24bit"}
+VT_PROCESSING = 0x0004
+
+
+@dataclass(frozen=True)
+class Terminal:
+    tty: bool
+    color: bool
+    truecolor: bool
+    columns: int
+
+    def paint(self, text: str, *styles: str) -> str:
+        if not self.color or not styles or not text:
+            return text
+        return f"\x1b[{';'.join(CODES[s] for s in styles)}m{text}{RESET}"
+
+    def fit(self, text: str) -> str:
+        limit = max(self.columns - 1, 10)
+        return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+def detect(
+    stream: TextIO,
+    environ: Mapping[str, str] | None = None,
+    *,
+    vt: Callable[[TextIO], bool] | None = None,
+) -> Terminal:
+    env = os.environ if environ is None else environ
+    if host.is_windows():
+        return _detect_windows(stream, env, vt or enable_vt)
+    tty = stream.isatty() and env.get("TERM", "") not in {"", "dumb"}
+    color = tty and not env.get("NO_COLOR")
+    columns = shutil.get_terminal_size(fallback=(80, 24)).columns if tty else 80
+    return Terminal(
+        tty=tty,
+        color=color,
+        truecolor=color and env.get("COLORTERM", "").lower() in TRUECOLOR_VALUES,
+        columns=columns,
+    )
+
+
+def _detect_windows(
+    stream: TextIO, env: Mapping[str, str], vt: Callable[[TextIO], bool]
+) -> Terminal:
+    """Windows consoles set no TERM; a console is a terminal once it accepts ANSI escapes."""
+    tty = stream.isatty() and env.get("TERM", "") != "dumb"
+    color = tty and not env.get("NO_COLOR") and vt(stream)
+    columns = shutil.get_terminal_size(fallback=(80, 24)).columns if tty else 80
+    return Terminal(tty=tty, color=color, truecolor=color, columns=columns)
+
+
+def enable_vt(stream: TextIO) -> bool:
+    """Switch the console behind `stream` to ANSI escape processing; False when it cannot."""
+    if sys.platform != "win32":
+        return True
+    import ctypes
+    import msvcrt
+
+    try:
+        handle = msvcrt.get_osfhandle(stream.fileno())
+    except (OSError, ValueError, AttributeError):
+        return False
+    kernel32 = ctypes.windll.kernel32
+    kernel32.GetConsoleMode.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_uint32)]
+    kernel32.SetConsoleMode.argtypes = [ctypes.c_void_p, ctypes.c_uint32]
+    mode = ctypes.c_uint32()
+    if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+        return False
+    if mode.value & VT_PROCESSING:
+        return True
+    return bool(kernel32.SetConsoleMode(handle, mode.value | VT_PROCESSING))
+
+
+def prepare_streams() -> None:
+    """On Windows a redirected stream uses the ANSI code page: make it UTF-8 and never fail."""
+    if not host.is_windows():
+        return
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        if not isinstance(stream, io.TextIOWrapper) or stream.isatty():
+            continue
+        with contextlib.suppress(OSError, ValueError):
+            stream.reconfigure(encoding="utf-8", errors="replace")

watchby/config/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-FileCopyrightText: 2026 the watchby authors
+# SPDX-License-Identifier: Apache-2.0