From 65e72d8ded57130ebd7b3ccab0a9b110da8df4d4 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Mon, 16 Nov 2026 14:29:47 +0100 Subject: [PATCH] Add game_recording 0.1.0 Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V --- .../workflows/game-recording-precommit.yml | 71 ++++++ .github/workflows/game-recording-tests.yml | 35 +++ game_recording/.pre-commit-config.yaml | 131 ++++++++++ game_recording/README.md | 91 +++++++ game_recording/game_recording/__init__.py | 11 + game_recording/game_recording/cli.py | 95 +++++++ game_recording/game_recording/config.py | 102 ++++++++ game_recording/game_recording/encoder.py | 124 ++++++++++ game_recording/game_recording/finalize.py | 91 +++++++ game_recording/game_recording/gsr.py | 133 ++++++++++ game_recording/game_recording/library.py | 93 +++++++ game_recording/game_recording/moments.py | 162 ++++++++++++ game_recording/game_recording/options.py | 34 +++ game_recording/game_recording/policy.py | 75 ++++++ game_recording/game_recording/procs.py | 33 +++ game_recording/game_recording/recorder.py | 223 +++++++++++++++++ game_recording/game_recording/supervise.py | 177 +++++++++++++ .../game_recording/tests/__init__.py | 2 + .../game_recording/tests/test_derived.py | 38 +++ .../game_recording/tests/test_encoder.py | 113 +++++++++ .../game_recording/tests/test_events.py | 96 +++++++ .../game_recording/tests/test_finalize.py | 150 +++++++++++ .../game_recording/tests/test_gsr.py | 87 +++++++ .../game_recording/tests/test_gsr_start.py | 108 ++++++++ .../game_recording/tests/test_helpers.py | 48 ++++ .../game_recording/tests/test_library.py | 145 +++++++++++ .../game_recording/tests/test_moment_map.py | 138 +++++++++++ .../game_recording/tests/test_policy.py | 108 ++++++++ .../game_recording/tests/test_procs.py | 63 +++++ .../game_recording/tests/test_record.py | 139 +++++++++++ .../game_recording/tests/test_recorder.py | 234 ++++++++++++++++++ .../tests/test_recorder_steps.py | 231 +++++++++++++++++ .../game_recording/tests/test_supervise.py | 153 ++++++++++++ .../tests/test_supervise_run.py | 232 +++++++++++++++++ .../game_recording/tests/test_timeline.py | 232 +++++++++++++++++ .../game_recording/tests/test_window.py | 100 ++++++++ game_recording/game_recording/timeline.py | 150 +++++++++++ game_recording/game_recording/window.py | 63 +++++ game_recording/pyproject.toml | 159 ++++++++++++ game_recording/requirements.txt | 10 + 40 files changed, 4480 insertions(+) create mode 100644 .github/workflows/game-recording-precommit.yml create mode 100644 .github/workflows/game-recording-tests.yml create mode 100644 game_recording/.pre-commit-config.yaml create mode 100644 game_recording/README.md create mode 100644 game_recording/game_recording/__init__.py create mode 100644 game_recording/game_recording/cli.py create mode 100644 game_recording/game_recording/config.py create mode 100644 game_recording/game_recording/encoder.py create mode 100644 game_recording/game_recording/finalize.py create mode 100644 game_recording/game_recording/gsr.py create mode 100644 game_recording/game_recording/library.py create mode 100644 game_recording/game_recording/moments.py create mode 100644 game_recording/game_recording/options.py create mode 100644 game_recording/game_recording/policy.py create mode 100644 game_recording/game_recording/procs.py create mode 100644 game_recording/game_recording/recorder.py create mode 100644 game_recording/game_recording/supervise.py create mode 100644 game_recording/game_recording/tests/__init__.py create mode 100644 game_recording/game_recording/tests/test_derived.py create mode 100644 game_recording/game_recording/tests/test_encoder.py create mode 100644 game_recording/game_recording/tests/test_events.py create mode 100644 game_recording/game_recording/tests/test_finalize.py create mode 100644 game_recording/game_recording/tests/test_gsr.py create mode 100644 game_recording/game_recording/tests/test_gsr_start.py create mode 100644 game_recording/game_recording/tests/test_helpers.py create mode 100644 game_recording/game_recording/tests/test_library.py create mode 100644 game_recording/game_recording/tests/test_moment_map.py create mode 100644 game_recording/game_recording/tests/test_policy.py create mode 100644 game_recording/game_recording/tests/test_procs.py create mode 100644 game_recording/game_recording/tests/test_record.py create mode 100644 game_recording/game_recording/tests/test_recorder.py create mode 100644 game_recording/game_recording/tests/test_recorder_steps.py create mode 100644 game_recording/game_recording/tests/test_supervise.py create mode 100644 game_recording/game_recording/tests/test_supervise_run.py create mode 100644 game_recording/game_recording/tests/test_timeline.py create mode 100644 game_recording/game_recording/tests/test_window.py create mode 100644 game_recording/game_recording/timeline.py create mode 100644 game_recording/game_recording/window.py create mode 100644 game_recording/pyproject.toml create mode 100644 game_recording/requirements.txt diff --git a/.github/workflows/game-recording-precommit.yml b/.github/workflows/game-recording-precommit.yml new file mode 100644 index 0000000..341e6ce --- /dev/null +++ b/.github/workflows/game-recording-precommit.yml @@ -0,0 +1,71 @@ +name: game_recording pre-commit + +on: + push: + branches: [main] + # The workflow's own file counts as game_recording: editing only this file used + # to trigger nothing, so a fix to the job itself could never prove itself. + paths: ['game_recording/**', '.github/workflows/game-recording-precommit.yml'] + pull_request: + branches: [main] + paths: ['game_recording/**', '.github/workflows/game-recording-precommit.yml'] + +jobs: + pre-commit: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.x" + # Only pre-commit itself. Every linting hook runs in its own isolated + # env -- ruff, mypy, pylint, bandit and codespell each come from their + # own repo+rev, and the local hooks need nothing beyond bash and + # python3 -- so installing the full requirements.txt spent 9s a run on + # packages no pre-commit-stage hook imports. Verified by running this + # package's config green in a venv holding pre-commit and nothing else. + # The pin is read out of requirements.txt rather than repeated here, so + # it cannot drift from what the dependency-freshness gate governs. + - name: Install pre-commit + run: | + pip install "$(grep '^pre-commit==' game_recording/requirements.txt)" + + # Keyed on THIS package's config. pre-commit/action@v3.0.1 caches on + # hashFiles('.pre-commit-config.yaml') -- the repo ROOT's -- so editing + # this package's config would not invalidate it, and other jobs in the + # repo that cache hooks under that key could overwrite it with a + # different hook set. A key from this config cannot go stale that way. + - uses: actions/cache@v4 + with: + path: ~/.cache/pre-commit + key: >- + pre-commit-game-recording-${{ env.pythonLocation }}-${{ + hashFiles('game_recording/.pre-commit-config.yaml') }} + # Prefix fallback, or this fix would evaporate on the very + # event that motivated it: bumping a hook rev changes the + # exact key, and a total miss means reinstalling every hook + # again. pre-commit's store is keyed internally by hook + # repo+rev, so a superseded entry is ignored disk rather + # than a wrong hook, and cache still re-saves under the new + # exact key after a prefix-only hit. + restore-keys: pre-commit-game-recording-${{ env.pythonLocation }}- + # mypy re-analyses the stdlib and every third-party stub from scratch + # without this, which measured 10s of the hook step in CI against 0.25s + # warm locally -- a 19MB cache dir does the whole difference. Keyed on + # the config, not the sources: mypy's own cache metadata records the + # interpreter, the flag set and a hash per source file, so it re-checks + # what changed and cannot pass stale code. Deliberately NOT keyed on + # github.sha -- that re-saves 19MB every commit and would evict the + # 68MB hook caches under the repo's 10GB LRU budget. A fixed key keeps + # the expensive part, the dependency analysis, which is what costs 10s. + - uses: actions/cache@v4 + with: + path: .mypy_cache + key: >- + mypy-game-recording-${{ env.pythonLocation }}-${{ + hashFiles('game_recording/.pre-commit-config.yaml') }} + restore-keys: mypy-game-recording-${{ env.pythonLocation }}- + - name: Run the hooks + run: >- + pre-commit run --config game_recording/.pre-commit-config.yaml + --all-files --show-diff-on-failure diff --git a/.github/workflows/game-recording-tests.yml b/.github/workflows/game-recording-tests.yml new file mode 100644 index 0000000..b51eb93 --- /dev/null +++ b/.github/workflows/game-recording-tests.yml @@ -0,0 +1,35 @@ +name: game_recording tests + +on: + push: + branches: [main] + # The workflow's own file counts as game_recording: editing only this file used + # to trigger nothing, so a fix to the job itself could never prove itself. + paths: ['game_recording/**', '.github/workflows/game-recording-tests.yml'] + pull_request: + branches: [main] + paths: ['game_recording/**', '.github/workflows/game-recording-tests.yml'] + +jobs: + test: + runs-on: ubuntu-latest + defaults: + run: + working-directory: game_recording + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.x" + + # The finalize and library tests run the real ffmpeg and ffprobe. + - name: Install ffmpeg + run: sudo apt-get update && sudo apt-get install -y ffmpeg + + - name: Install dependencies + run: pip install -r requirements.txt + + - name: Run tests with coverage + run: python -m pytest -v --cov=game_recording diff --git a/game_recording/.pre-commit-config.yaml b/game_recording/.pre-commit-config.yaml new file mode 100644 index 0000000..de260cb --- /dev/null +++ b/game_recording/.pre-commit-config.yaml @@ -0,0 +1,131 @@ +# Pre-commit Configuration for game_recording +# Install: pre-commit install && pre-commit install --hook-type pre-push +# Run: pre-commit run --all-files +# Update: pre-commit autoupdate + +# NOTE: this subproject lives inside the ~/src/utils monorepo, whose git root is +# one level up. pre-commit always runs hooks from the git root, so every path +# below is written relative to THAT, not to this directory, and the top-level +# `files` key keeps these hooks off the sibling subprojects. CI invokes this +# config exactly the same way: +# pre-commit run --config game_recording/.pre-commit-config.yaml --all-files +files: ^game_recording/ + +default_language_version: + python: python3 +default_stages: [pre-commit] +fail_fast: false + +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: trailing-whitespace + args: [--markdown-linebreak-ext=md] + - id: end-of-file-fixer + - id: check-yaml + - id: check-json + - id: check-toml + - id: check-added-large-files + args: [--maxkb=2000] + - id: check-merge-conflict + - id: detect-private-key + - id: debug-statements + - id: name-tests-test + args: [--pytest-test-first] + - id: check-ast + - id: mixed-line-ending + args: [--fix=lf] + - id: requirements-txt-fixer + + - repo: local + hooks: + - id: file-length-cap + name: file length <= 250 lines + entry: bash scripts/check_file_length.sh + language: system + pass_filenames: true + - id: subproject-scope + name: subproject scope regex still matches + entry: scripts/check_subproject_scope.sh game_recording + language: script + # always_run so the top-level `files` filter cannot skip the one hook + # whose job is to notice that filter has stopped matching anything. + always_run: true + pass_filenames: false + - id: no-noqa + name: Block noqa comments + entry: '(?i)#\s*(noqa|type:\s*ignore)' + language: pygrep + types: [python] + - id: no-ruff-noqa + name: Block ruff noqa file-level comments + entry: '(?i)#\s*ruff:\s*noqa' + language: pygrep + types: [python] + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.17.2 + hooks: + - id: ruff + args: [--fix, --unsafe-fixes, --exit-non-zero-on-fix, --show-fixes] + types_or: [python, pyi] + - id: ruff-format + types_or: [python, pyi] + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.13.0 + hooks: + - id: mypy + # Strict mode from the package's own pyproject, which pre-commit would + # not find from the git root. + args: + - --config-file=game_recording/pyproject.toml + - --no-error-summary + # The tests import pytest: without it every fixture type is Any. + additional_dependencies: + - pytest==9.2.0 + + - repo: https://github.com/pylint-dev/pylint + rev: v4.1.4 + hooks: + - id: pylint + args: + - --rcfile=game_recording/pyproject.toml + - --fail-under=10 + # One process: with --jobs>1 pylint pickles its AST via dill, which + # dies on Python 3.15 (code objects lost co_lnotab), 2026-11-16. + - --jobs=1 + additional_dependencies: + - pytest + + - repo: https://github.com/PyCQA/bandit + rev: 1.9.4 + hooks: + - id: bandit + args: + - -c + - game_recording/pyproject.toml + - --severity-level=high + - --confidence-level=medium + - --skip=B113 + additional_dependencies: ["bandit[toml]"] + exclude: ^(game_recording/game_recording/tests/|.*test.*\.py$) + + - repo: local + hooks: + - id: pytest-coverage + name: pytest with coverage enforcement + entry: scripts/run_subproject_tests.sh game_recording --cov=game_recording + language: script + types: [python] + pass_filenames: false + require_serial: true + stages: [pre-push] + + - repo: https://github.com/codespell-project/codespell + rev: v2.3.0 + hooks: + - id: codespell + args: + - --skip=*.json,*.lock,.git,__pycache__,.venv diff --git a/game_recording/README.md b/game_recording/README.md new file mode 100644 index 0000000..a48a90e --- /dev/null +++ b/game_recording/README.md @@ -0,0 +1,91 @@ +# game_recording + +Session recorder for a game, as a package (import name `game_recording`, not +published to PyPI, stdlib only). It needs Python 3.14 or newer +(`requires-python` in `pyproject.toml`). It records a person's own dev play from +outside the game (so the game's frame time stays untouched) and stamps the +game's telemetry moments onto the video as events and MKV chapters. + +- Starts the game as a child process, finds its X11 window by pid (`xdotool`), + records it with `gpu-screen-recorder` (else `ffmpeg` x11grab) plus the audio + monitor, and stops the recorder with SIGINT when the game exits. +- A window that goes away and returns (an i3 workspace switch) starts a new + part file; every part sits on one timeline. +- `finalize` writes `.events.json` next to the video and remuxes + chapters in without re-encoding. `latest`, `list` and `open N` show moments + and open the video in `mpv` three seconds before one. +- Recording trouble never changes the game's exit code or stops the game. +- Bots, tests, headless and muted runs are never recorded. + +Needs `ffmpeg`, `ffprobe`, `xdotool` and, optionally, `gpu-screen-recorder`. + +Consume via: +``` +game_recording @ git+https://github.com/kuhyx/utils@game-recording-v0.1.0#subdirectory=game_recording +``` + +## Configure it for a game + +The package knows no game. One `Config` carries everything game-specific; the +game's own entry script (a few lines) builds it and calls `cli.main`: + +```python +import sys + +from game_recording import Config, MomentMap, cli +from game_recording.config import COMMON_DIRECT + +CONFIG = Config( + binaries_dir="data/my-game_binaries", # under $HOME; feedback/ lives inside + env_prefix="MYGAME", # MYGAME_NO_RECORD, MYGAME_FEEDBACK_DIR, ... + moments=MomentMap( + direct={**COMMON_DIRECT, "buy": ("item", "cost")}, + passthrough_prefixes=("sim_", "milestone"), + ), +) + +if __name__ == "__main__": + sys.exit(cli.main(sys.argv[1:], CONFIG)) +``` + +| Field | Meaning | +| --- | --- | +| `Config.binaries_dir` | The game's binaries folder, relative to `$HOME`. Default feedback dir: `/feedback`; recordings go in its `recordings/`. | +| `Config.env_prefix` | Variables derive from it: `

_NO_RECORD` (`1` = never record), `

_FEEDBACK_DIR` (any value = never record), `

_BINARIES` (binaries folder override), `

_RECORDER_BACKEND` (`auto`, `gsr`, `x11grab`), `

_RECORDER_NICE` (default 10). | +| `Config.binaries_env` | Overrides the `

_BINARIES` variable name. | +| `Config.extra_blocking_flags` | More environment flags that switch recording off at `1`. | +| `Config.bot_args` | Game args that mark a bot or test run (default `--autodrive`, `--result-file=`, `--expect-window=`, `--screenshot-dir=`, `--save-dir=`). | +| `MomentMap.direct` | Event name to the fields kept; one telemetry line is one moment. Default `COMMON_DIRECT`. | +| `MomentMap.passthrough_prefixes` | Events starting with these are moments as they are. | +| `MomentMap.game_end_fields`, `error_kinds`, `hitch_merge_s` | Fields of a `game_end` moment, the `engine_error` kinds that count, and the merge window of a hitch burst. | +| `MomentMap.classifiers` | Extra per-line rules `(row) -> moment or None`, tried first. Build moments with `moments.moment(row, kind, label, **extra)`. | +| `MomentMap.session_rules` | Extra rules `(rows) -> moments` for moments that need several lines (a stall, a repeated failure). | + +## Contract with the game + +- The game is started with `--session-id=` and `--feedback-dir=

` + appended to its user args (after `--`); a recorded run needs `--dev`. +- It writes `/feedback.jsonl`, one JSON object per line with + `session`, `event`, `seq` and `ms` (its own clock). One `recording_sync` + line (`ms` plus `unix` or `unix_us`) pins that clock to unix time. +- Output layout: `/recordings/.mkv` (`.partN.mkv` for + later parts), `.rec.json`, `.events.json`, `.ffmpeg.log`. + +## CLI + +``` +wrap [--session ID] [--force] [--audio default|lavfi|SRC] [--fps N] [--max-seconds S] -- +finalize .rec.json +latest | list [--dir D] [--session ID] +open [N] [--dir D] [--session ID] [--dry-run] +``` + +## Develop + +``` +pip install -r requirements.txt +python -m pytest --cov=game_recording # 100 % branch coverage required +pre-commit run --config game_recording/.pre-commit-config.yaml --all-files # from the utils root +``` + +Version 0.1.0; the tag is `game-recording-v0.1.0`. diff --git a/game_recording/game_recording/__init__.py b/game_recording/game_recording/__init__.py new file mode 100644 index 0000000..d92ba75 --- /dev/null +++ b/game_recording/game_recording/__init__.py @@ -0,0 +1,11 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Session recorder for a game: records a dev run beside it, stamps telemetry moments on the video. + +A game configures it with one `Config` (names, blockers, telemetry vocabulary) +and calls `game_recording.cli.main`. See the package README for the whole surface. +""" + +from game_recording.config import Config, MomentMap + +__version__ = "0.1.0" +__all__ = ["Config", "MomentMap", "__version__"] diff --git a/game_recording/game_recording/cli.py b/game_recording/game_recording/cli.py new file mode 100644 index 0000000..64972c5 --- /dev/null +++ b/game_recording/game_recording/cli.py @@ -0,0 +1,95 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Session recording CLI; a game's own entry script calls `main(argv, config)`. + +wrap [--session ID] [--force] [--audio SRC] [--fps N] [--max-seconds S] -- +finalize rebuild events.json + chapters +latest|list [--dir D] moments of the newest recording / all recordings +open [N] [--session ID] [--dir D] [--dry-run] +""" + +import argparse +import os +from pathlib import Path +import sys +from typing import TYPE_CHECKING + +from game_recording import finalize, library, supervise +from game_recording.options import DEFAULT_FPS, RunOptions + +if TYPE_CHECKING: + from collections.abc import Sequence + + from game_recording.config import Config + from game_recording.library import Doc + + +def default_dir(config: Config) -> Path: + """The recordings folder of the game's default feedback dir.""" + return supervise.feedback_dir([], os.environ, config) / "recordings" + + +def pick(rec_dir: Path, session: str) -> Doc: + """The newest recording (of the session whose id starts with `session`, when given).""" + found = library.sessions(rec_dir) + if session: + found = [p for p in found if p.name.startswith(session)] + if not found: + msg = f"no recordings in {rec_dir}" + raise SystemExit(msg) + return library.load(found[0]) + + +def parser() -> argparse.ArgumentParser: + """The argument parser of every subcommand.""" + top = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + sub = top.add_subparsers(dest="cmd", required=True) + wrap = sub.add_parser("wrap") + wrap.add_argument("--session", default="") + wrap.add_argument("--force", action="store_true", help="record bot/test runs too (tests only)") + wrap.add_argument("--audio", default="default", help="default|lavfi|") + wrap.add_argument("--fps", type=int, default=DEFAULT_FPS) + wrap.add_argument("--max-seconds", type=float, default=0.0) + wrap.add_argument("command", nargs=argparse.REMAINDER) + fin = sub.add_parser("finalize") + fin.add_argument("meta") + for name in ("latest", "list", "open"): + p = sub.add_parser(name) + p.add_argument("--dir", default="") + p.add_argument("--session", default="") + if name == "open": + p.add_argument("n", nargs="?", type=int) + p.add_argument("--dry-run", action="store_true") + return top + + +def _wrap(args: argparse.Namespace, config: Config) -> int: + command = args.command[1:] if args.command[:1] == ["--"] else args.command + options = RunOptions( + force=args.force, session=args.session, audio=args.audio, fps=args.fps, max_seconds=args.max_seconds + ) + return supervise.run(command, config, options) + + +def _show(args: argparse.Namespace, config: Config) -> int: + rec_dir = Path(args.dir) if args.dir else default_dir(config) + if args.cmd == "list": + sys.stdout.write(library.listing(rec_dir) + "\n") + elif args.cmd == "latest": + sys.stdout.write(library.table(pick(rec_dir, args.session)) + "\n") + else: + try: + return library.open_moment(pick(rec_dir, args.session), rec_dir, args.n, dry_run=args.dry_run) + except IndexError as err: + raise SystemExit(str(err)) from err + return 0 + + +def main(argv: Sequence[str], config: Config) -> int: + """Runs one subcommand for the game described by `config`; returns the exit code.""" + args = parser().parse_args(argv) + if args.cmd == "wrap": + return _wrap(args, config) + if args.cmd == "finalize": + finalize.finalize(Path(args.meta), config.moments) + return 0 + return _show(args, config) diff --git a/game_recording/game_recording/config.py b/game_recording/game_recording/config.py new file mode 100644 index 0000000..b3874fa --- /dev/null +++ b/game_recording/game_recording/config.py @@ -0,0 +1,102 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""What a game tells the recorder: its names, its blockers, its telemetry vocabulary. + +The package knows nothing about any one game. A game builds one `Config` and +hands it to `game_recording.cli.main` (see the README for the whole surface). +""" + +from collections.abc import Callable, Mapping +from dataclasses import dataclass, field +from types import MappingProxyType +from typing import Any + +type Row = dict[str, Any] +"""One telemetry line, as the game wrote it.""" +type Moment = dict[str, Any] +"""One timestamped moment built from telemetry.""" +type Classifier = Callable[[Row], Moment | None] +"""Turns one telemetry line into a moment, or None when it is not one.""" +type SessionRule = Callable[[list[Row]], list[Moment]] +"""Finds the moments that need several telemetry lines.""" + +# Entries any dev telemetry has: a moment as they are, with the fields worth keeping. +COMMON_DIRECT: Mapping[str, tuple[str, ...]] = MappingProxyType( + { + "session_start": (), + "hub_open": (), + "pause_open": (), + "pause_close": ("paused_s",), + "quit": ("reason",), + "session_end": ("reason", "elapsed_s"), + } +) + +# Game args that only a bot or a test run carries. +BOT_ARGS = ( + "--autodrive", + "--result-file=", + "--expect-window=", + "--screenshot-dir=", + "--save-dir=", +) + + +@dataclass(frozen=True) +class MomentMap: + """Which telemetry entries are moments worth a timestamp. + + Attributes: + direct: event name -> the fields kept; one entry is one moment. + passthrough_prefixes: events starting with these are moments as they are. + game_end_fields: the fields of a `game_end` moment. + error_kinds: `engine_error` kinds that are a moment (warnings are noise). + hitch_merge_s: `hitch` entries closer than this are one moment. + classifiers: extra per-entry rules, tried before the built-in ones. + session_rules: extra rules over the whole session, added to the hitch burst. + """ + + direct: Mapping[str, tuple[str, ...]] = COMMON_DIRECT + passthrough_prefixes: tuple[str, ...] = () + game_end_fields: tuple[str, ...] = ("outcome", "elapsed_s") + error_kinds: frozenset[str] = frozenset({"error", "script_error", "shader_error"}) + hitch_merge_s: float = 2.0 + classifiers: tuple[Classifier, ...] = () + session_rules: tuple[SessionRule, ...] = () + + +@dataclass(frozen=True) +class Config: + """One game's recorder settings. + + Attributes: + binaries_dir: the game's binaries folder, relative to $HOME; its + `feedback/` folder holds the telemetry and the recordings. + env_prefix: prefix of the game's environment variables, e.g. `GAME` for + `GAME_NO_RECORD`, `GAME_FEEDBACK_DIR`, `GAME_RECORDER_BACKEND`, + `GAME_RECORDER_NICE` and `GAME_BINARIES`. + moments: the telemetry-to-moment map. + bot_args: game args that mark a bot or test run (never recorded). + extra_blocking_flags: more env flags that switch recording off at "1". + binaries_env: overrides the `_BINARIES` variable name. + """ + + binaries_dir: str + env_prefix: str + moments: MomentMap = field(default_factory=MomentMap) + bot_args: tuple[str, ...] = BOT_ARGS + extra_blocking_flags: tuple[str, ...] = () + binaries_env: str = "" + + def env_name(self, suffix: str) -> str: + """The game's environment variable `_`.""" + return f"{self.env_prefix}_{suffix}" + + @property + def blocking_flags(self) -> tuple[str, ...]: + """Env flags that count only as "1" and switch recording off.""" + return (self.env_name("NO_RECORD"), *self.extra_blocking_flags) + + @property + def binaries_var(self) -> str: + """The variable that names the binaries folder.""" + return self.binaries_env or self.env_name("BINARIES") diff --git a/game_recording/game_recording/encoder.py b/game_recording/game_recording/encoder.py new file mode 100644 index 0000000..7c9335c --- /dev/null +++ b/game_recording/game_recording/encoder.py @@ -0,0 +1,124 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The ffmpeg command line of a session recording. + +External recorder, so the game's frame time is untouched: x11grab of the game +window, PulseAudio/PipeWire monitor audio, hardware encode. Godot's MovieWriter +is not an option: it forces fixed-step, non-realtime playback. + +Timestamps: frames are stamped with the wall clock as ffmpeg reads them +(-use_wallclock_as_timestamps) and pulse stamps audio with it by default. +x11grab hands a frame over 1 to 2 frame periods after the screen had that +content (measured at 60 and 120 fps under Xvfb), so the video input is shifted +back by the middle of that range (GRAB_LATENCY_FRAMES): a stamp then lies within +half a frame of the moment its content was on screen. -copyts keeps +those absolute and -output_ts_offset -T0 moves them so the file's timeline +starts at T0, a unix time the launcher chose. That makes the offset between the +game's telemetry (unix-stamped by recording_sync) and the file exact, with no +guess about ffmpeg's start-up latency. +""" + +from dataclasses import dataclass +import subprocess +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Collection + +NVENC = "h264_nvenc" +X264 = "libx264" +NVENC_P7_MAX_PIXELS = 2560 * 1440 +# Measured: x11grab frames are stamped 1..2 frame periods after their content. +GRAB_LATENCY_FRAMES = 1.5 +DEFAULT_MONITOR = "@DEFAULT_MONITOR@" +# A silent source for tests only: stamped with the wall clock like pulse is. +LAVFI_AUDIO = "anullsrc=r=48000:cl=stereo" +LAVFI_STAMP = "asetpts='RTCTIME/(1000000*TB)'" + + +class NoEncoderError(Exception): + """Neither NVENC nor libx264 can encode here.""" + + +@dataclass(frozen=True) +class Spec: + """What one recorder part needs to know.""" + + window_id: int + fps: int + t0_unix: float + out: str + audio: str = "default" # "default" = monitor of the default sink; "lavfi" = test silence; else a pulse source + display: str = ":0" + width: int = 0 # window size; an odd side is cropped to even (h264 yuv420 needs it) + height: int = 0 + + +def pick(usable: Collection[str]) -> str: + """NVENC when it works (the RTX 3090 encodes without touching the game's frame time), else x264.""" + for name in (NVENC, X264): + if name in usable: + return name + msg = "neither h264_nvenc nor libx264 is usable" + raise NoEncoderError(msg) + + +def probe_usable() -> set[str]: + """Encoders that really encode one frame here (listed is not the same as working).""" + ok: set[str] = set() + for name in (NVENC, X264): + cmd = ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=size=256x256:rate=1", "-frames:v", "1"] + cmd += ["-c:v", name, "-f", "null", "-"] + done = subprocess.run(cmd, capture_output=True, check=False, timeout=20) + if not done.returncode: + ok.add(name) + return ok + + +def nvenc_preset(width: int, height: int) -> str: + """The NVENC preset: p7 (best quality) while it keeps real time on the RTX 3090. + + Measured 1.7x at 2560x1440, 2.4x at 1920x1200; above 1440p p7 only reaches 0.78x at 4K, p4 does 1.6x. + """ + return "p7" if width * height <= NVENC_P7_MAX_PIXELS else "p4" + + +def _video_codec(name: str, width: int = 0, height: int = 0) -> list[str]: + if name == NVENC: + preset = nvenc_preset(width, height) + return ["-c:v", NVENC, "-preset", preset, "-tune", "hq", "-rc", "vbr", "-cq", "17", "-b:v", "0", "-g", "60"] + return ["-c:v", X264, "-crf", "16", "-preset", "veryfast", "-pix_fmt", "yuv420p", "-g", "60"] + + +def _even_crop(spec: Spec) -> list[str]: + if spec.width % 2 or spec.height % 2: + return ["-vf", "crop=trunc(iw/2)*2:trunc(ih/2)*2"] + return [] + + +def _audio_input(audio: str) -> tuple[list[str], list[str]]: + """(input args, output filter args) of the audio source.""" + if audio == "lavfi": + return ["-f", "lavfi", "-i", LAVFI_AUDIO], ["-af", LAVFI_STAMP] + source = DEFAULT_MONITOR if audio == "default" else audio + return ["-thread_queue_size", "1024", "-f", "pulse", "-i", source], [] + + +def command(spec: Spec, codec: str) -> list[str]: + """The ffmpeg argv. SIGINT makes it finalize the file. + + -shortest ends it when x11grab dies (window unmapped, resized or gone), which the launcher + takes as the cue for a new part. + """ + audio_in, audio_filter = _audio_input(spec.audio) + return [ + "ffmpeg", "-hide_banner", "-loglevel", "warning", "-nostdin", "-y", + "-thread_queue_size", "1024", "-use_wallclock_as_timestamps", "1", + "-itsoffset", f"{-GRAB_LATENCY_FRAMES / spec.fps:.6f}", "-f", "x11grab", "-window_id", f"0x{spec.window_id:x}", + "-framerate", str(spec.fps), "-draw_mouse", "0", "-i", spec.display, + *audio_in, + "-copyts", "-output_ts_offset", f"{-spec.t0_unix:.6f}", + *_even_crop(spec), + *_video_codec(codec, spec.width, spec.height), + "-c:a", "flac", *audio_filter, + "-shortest", "-f", "matroska", spec.out, + ] # fmt: skip diff --git a/game_recording/game_recording/finalize.py b/game_recording/game_recording/finalize.py new file mode 100644 index 0000000..ea6bdee --- /dev/null +++ b/game_recording/game_recording/finalize.py @@ -0,0 +1,91 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""After the game exits: events.json next to the video, chapters remuxed in (no re-encode).""" + +import json +from pathlib import Path +import subprocess +from typing import TYPE_CHECKING, Any + +from game_recording import gsr, timeline + +if TYPE_CHECKING: + from game_recording.config import MomentMap + + +def _ffprobe(*args: str) -> dict[str, Any]: + cmd = ["ffprobe", "-v", "error", "-of", "json", *args] + done = subprocess.run(cmd, capture_output=True, text=True, check=True, timeout=60) + probed: dict[str, Any] = json.loads(done.stdout) + return probed + + +TAIL_S = 5.0 # only the file's last seconds are scanned for its true end + + +def probe_span(video: Path) -> tuple[float, float]: + """(first timestamp, duration) in seconds on the file's timeline. + + The end is the last packet's end, not the container's Duration (muxers differ on + whether that counts from zero or from the first timestamp). + """ + fmt = _ffprobe("-show_entries", "format=start_time,duration", str(video))["format"] + start = float(fmt.get("start_time", 0)) + scan = ["-show_entries", "packet=pts_time,duration_time", "-of", "json"] + if "duration" in fmt: # a finalized file: jump near the end (cues) instead of reading it all + scan = ["-read_intervals", f"{max(0.0, float(fmt['duration']) - TAIL_S)}%", *scan] + packets = _ffprobe(*scan, str(video))["packets"] + end = max( + (float(p["pts_time"]) + float(p.get("duration_time", 0)) for p in packets if "pts_time" in p), default=start + ) + return start, max(0.0, end - start) + + +def embed_chapters(video: Path, ffmetadata: Path) -> None: + """Remux with chapters, streams copied, timestamps kept (-copyts) so t stays valid.""" + tmp = video.with_suffix(".chapters.mkv") + cmd = ["ffmpeg", "-v", "error", "-y", "-copyts", "-i", str(video), "-f", "ffmetadata", "-i", str(ffmetadata)] + cmd += ["-map", "0", "-map_metadata", "0", "-map_chapters", "1", "-c", "copy", "-f", "matroska", str(tmp)] + subprocess.run(cmd, check=True, timeout=300) + tmp.replace(video) + + +def _part_spans(folder: Path, meta: dict[str, Any]) -> list[dict[str, Any]]: + """Each existing part file with its first timestamp and duration (gsr parts are aligned first).""" + names = [n for n in meta.get("parts") or [meta["video"]] if (folder / n).is_file()] + for name, first in (meta.get("first_frame_unix") or {}).items(): # gsr parts: a no-op once aligned + if name in names: + gsr.align(folder / name, first_unix=float(first), t0=float(meta["t0_unix"])) + spans = [] + for name in names: + start_s, duration_s = probe_span(folder / name) + spans.append({"file": name, "start_s": start_s, "duration_s": duration_s}) + return spans + + +def _embed_all_chapters(folder: Path, doc: dict[str, Any], parts: list[dict[str, Any]]) -> None: + """Remuxes each part that has moments inside it with its chapters.""" + ffmeta = folder / f"{doc['session']}.ffmeta" + for part in parts: + chapters = timeline.chapters_ffmetadata(doc["events"], part["duration_s"], part["start_s"], file=part["file"]) + if "[CHAPTER]" in chapters: + ffmeta.write_text(chapters, encoding="utf-8") + embed_chapters(folder / part["file"], ffmeta) + ffmeta.unlink(missing_ok=True) + + +def finalize(meta_path: Path, moment_map: MomentMap) -> dict[str, Any]: + """Builds .events.json and each part's chapters from .rec.json; returns the document.""" + meta_path = Path(meta_path) + meta = json.loads(meta_path.read_text(encoding="utf-8")) + folder = meta_path.parent + parts = _part_spans(folder, meta) + entries = timeline.load_session(Path(meta["feedback"]), meta["session"]) + doc = timeline.build_events( + entries, session=meta["session"], t0_unix=float(meta["t0_unix"]), parts=parts, moment_map=moment_map + ) + doc["video"]["file"] = parts[0]["file"] + doc["video"]["encoder"] = meta.get("encoder", "") + _embed_all_chapters(folder, doc, parts) + out = folder / f"{meta['session']}.events.json" + out.write_text(json.dumps(doc, indent=1) + "\n", encoding="utf-8") + return doc diff --git a/game_recording/game_recording/gsr.py b/game_recording/game_recording/gsr.py new file mode 100644 index 0000000..066f039 --- /dev/null +++ b/game_recording/game_recording/gsr.py @@ -0,0 +1,133 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""gpu-screen-recorder (gsr): the low-impact recording backend. + +x11grab makes the X server read every frame of the window back from the GPU into +system RAM (about 2 GB/s at 4K60), which slows the game. gsr captures the window +on the GPU (XComposite) and encodes with NVENC without that read-back; ffmpeg's +x11grab (encoder.py) stays as the fallback when gsr is missing or fails at start. + +Timeline: gsr's file starts at 0 with its first frame, and +`-write-first-frame-ts yes` writes `.ts` ("monotonic_microsecrealtime_microsec" +header, then one line of values). The realtime column is the unix time of file +time 0, less CAPTURE_LATENCY_S (measured): the first part's t0 is that time; a later part is +remuxed (streams copied) so it sits on the same timeline. +Audio is Opus: gsr 6.1 has FLAC disabled. +""" + +from pathlib import Path +import shutil +import signal +import subprocess +import time +from typing import IO, TYPE_CHECKING + +from game_recording import encoder, procs + +if TYPE_CHECKING: + from collections.abc import Mapping + + from game_recording.config import Config + +GSR = "gpu-screen-recorder" +BACKEND_SUFFIX = "RECORDER_BACKEND" # the game's _RECORDER_BACKEND: auto (default) | gsr | x11grab +START_WAIT_S = 8.0 # EGL + NVENC init, until the first frame is stamped +TS_FIELDS = 2 # monotonic_microsec, realtime_microsec +ALIGN_TOLERANCE_S = 0.002 # a part this close to the timeline is not remuxed +# gsr writes the first-frame stamp ~87 ms after the screen showed that content +# (a sync bench on a real display, 2026-11-11: ten flips 76-98 ms late at 30 fps), so +# file time 0 is that much earlier; the median of the measurement, like x11grab's +# GRAB_LATENCY_FRAMES. +CAPTURE_LATENCY_S = 0.087 + + +def available() -> bool: + """True when gpu-screen-recorder is installed.""" + return shutil.which(GSR) is not None + + +def pick_backend(env: Mapping[str, str], audio: str, config: Config, *, have_gsr: bool) -> str: + """Gsr when installed; x11grab when forced, when gsr is missing, or for the silent test source.""" + if env.get(config.env_name(BACKEND_SUFFIX)) == "x11grab" or audio == "lavfi" or not have_gsr: + return "x11grab" + return "gsr" + + +def command(spec: encoder.Spec) -> list[str]: + """The gsr argv. SIGINT makes it stop and finalize the file.""" + audio = "default_output" if spec.audio == "default" else f"device:{spec.audio}" + return [ + GSR, "-w", str(spec.window_id), "-f", str(spec.fps), "-fm", "cfr", "-k", "h264", "-q", "very_high", + "-c", "mkv", "-cursor", "no", "-a", audio, "-ac", "opus", "-write-first-frame-ts", "yes", + "-v", "no", "-o", spec.out, + ] # fmt: skip + + +def ts_path(out: str | Path) -> Path: + """The file gsr writes the first-frame stamp to.""" + return Path(f"{out}.ts") + + +def parse_first_frame(text: str) -> float | None: + """Unix seconds of the first frame from the .ts file, None until it is completely written.""" + if not text.endswith("\n"): + return None + fields = text.splitlines()[-1].split("\t") + if len(fields) != TS_FIELDS or not all(f.isdigit() for f in fields): + return None + return int(fields[1]) / 1_000_000 + + +def _read_first_frame(path: Path) -> float | None: + try: + return parse_first_frame(path.read_text(encoding="utf-8")) + except OSError: + return None + + +def start( + spec: encoder.Spec, log: IO[bytes], nice: str, wait_s: float = START_WAIT_S +) -> tuple[subprocess.Popen[bytes], float] | None: + """Starts gsr; (process, unix time of its first frame) once it records, None when it failed.""" + ts = ts_path(spec.out) + ts.unlink(missing_ok=True) + proc = procs.spawn(procs.niced(nice, command(spec)), log=log, detach=True) + deadline = time.monotonic() + wait_s + while proc.poll() is None and time.monotonic() < deadline: + first = _read_first_frame(ts) + if first is not None: + return proc, first - CAPTURE_LATENCY_S + time.sleep(0.05) + if proc.poll() is None: + proc.send_signal(signal.SIGKILL) + proc.wait() + ts.unlink(missing_ok=True) + Path(spec.out).unlink(missing_ok=True) + return None + + +def shift_delta(first_unix: float, t0: float, first_stamp: float) -> float: + """Seconds to add to a part's stamps so its first frame lands at first_unix on the t0 timeline.""" + return (first_unix - t0) - first_stamp + + +def shift_command(src: Path, dst: Path, delta: float) -> list[str]: + """The ffmpeg argv that stream-copies `src` to `dst` with every stamp moved by `delta` seconds.""" + cmd = ["ffmpeg", "-v", "error", "-y", "-copyts", "-i", str(src), "-map", "0"] + return [*cmd, "-c", "copy", "-output_ts_offset", f"{delta:.6f}", "-f", "matroska", str(dst)] + + +def video_start(video: Path) -> float: + """The first video stamp of the file, in seconds.""" + cmd = ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries", "stream=start_time"] + done = subprocess.run([*cmd, "-of", "csv=p=0", str(video)], capture_output=True, text=True, check=True, timeout=60) + return float(done.stdout.strip()) + + +def align(video: Path, first_unix: float, t0: float) -> None: + """Moves a finished gsr part onto the t0 timeline (stream copy; nothing when it is already there).""" + delta = shift_delta(first_unix, t0, video_start(video)) + if abs(delta) <= ALIGN_TOLERANCE_S: + return + tmp = video.with_suffix(".shift.mkv") + subprocess.run(shift_command(video, tmp, delta), check=True, timeout=600) + tmp.replace(video) diff --git a/game_recording/game_recording/library.py b/game_recording/game_recording/library.py new file mode 100644 index 0000000..9db7fa9 --- /dev/null +++ b/game_recording/game_recording/library.py @@ -0,0 +1,93 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Lists recordings and opens one at a moment (the code behind scripts/recordings.sh).""" + +import json +import shlex +import subprocess +import sys +from typing import TYPE_CHECKING, Any + +from game_recording import timeline + +if TYPE_CHECKING: + from pathlib import Path + +type Doc = dict[str, Any] +LEAD_S = 3.0 # open this long before the moment, so the cause is on screen + + +def stamp(seconds: float) -> str: + """mm:ss.mmm of a time on the recording's timeline.""" + sign = "-" if seconds < 0 else "" + millis = round(abs(seconds) * 1000) + return f"{sign}{millis // 60000:02d}:{millis // 1000 % 60:02d}.{millis % 1000:03d}" + + +def sessions(rec_dir: Path) -> list[Path]: + """events.json files, newest first.""" + return sorted(rec_dir.glob("*.events.json"), key=lambda p: p.stat().st_mtime, reverse=True) + + +def load(path: Path) -> Doc: + """One events.json document.""" + doc: Doc = json.loads(path.read_text(encoding="utf-8")) + return doc + + +def shown(doc: Doc) -> list[Doc]: + """The moments inside a recording part, in the numbering `open ` uses (1-based).""" + return [e for e in doc["events"] if timeline.in_recording(e)] + + +def table(doc: Doc) -> str: + """One recording as text: a header line, notes, then its numbered moments.""" + video = doc["video"] + lines = [f"{doc['session']} {doc.get('tag', '')} {stamp(video['duration_s'])} {video.get('file', '')}"] + if len(video.get("parts", [])) > 1: + spans = ", ".join( + f"{p['file']} {stamp(p['start_s'])}-{stamp(p['start_s'] + p['duration_s'])}" for p in video["parts"] + ) + lines.append(f"note: the window went away; {len(video['parts'])} parts: {spans}") + if doc["sync"]["approx"]: + lines.append("note: clocks synced from a whole-second wall time (build without recording_sync), +-1 s") + for n, event in enumerate(shown(doc), 1): + png = f" {event['png']}" if event.get("png") else "" + part = f" [{event['file']}]" if event.get("file") and event["file"] != video.get("file") else "" + lines.append(f"{n:3d} {stamp(event['t'])} {event['label']}{png}{part}") + return "\n".join(lines) + + +def listing(rec_dir: Path) -> str: + """One line per recording, newest first.""" + out = [] + for path in sessions(rec_dir): + doc = load(path) + out.append( + f"{doc['session']} {stamp(doc['video']['duration_s'])} {len(shown(doc))} moments {doc.get('tag', '')}" + ) + return "\n".join(out) + + +def open_command(doc: Doc, rec_dir: Path, n: int | None) -> list[str]: + """Mpv argv at moment n (None = from the start). --rebase-start-time=no keeps mpv on the file's own timeline.""" + parts = doc["video"].get("parts") or [{"file": doc["video"]["file"], "start_s": doc["video"]["start_s"]}] + name, first_frame = doc["video"]["file"], parts[0]["start_s"] + cmd = ["mpv", "--rebase-start-time=no", "--force-window=yes"] + if n is not None: + moments = shown(doc) + if not 1 <= n <= len(moments): + msg = f"no moment {n} (1..{len(moments)})" + raise IndexError(msg) + name = moments[n - 1].get("file", name) + first_frame = next((p["start_s"] for p in parts if p["file"] == name), first_frame) + cmd.append(f"--start={max(first_frame, moments[n - 1]['t'] - LEAD_S):.3f}") + return [*cmd, str(rec_dir / name)] + + +def open_moment(doc: Doc, rec_dir: Path, n: int | None, *, dry_run: bool) -> int: + """Plays the recording in mpv at moment n (or prints the command when `dry_run`).""" + cmd = open_command(doc, rec_dir, n) + if dry_run: + sys.stdout.write(shlex.join(cmd) + "\n") + return 0 + return subprocess.call(cmd) diff --git a/game_recording/game_recording/moments.py b/game_recording/game_recording/moments.py new file mode 100644 index 0000000..bd531ff --- /dev/null +++ b/game_recording/game_recording/moments.py @@ -0,0 +1,162 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Which telemetry entries are moments worth a timestamp, and the derived ones. + +Direct moments map one entry to one moment (the game's dev telemetry writes +them). Derived moments need several entries: a burst of hitches is one moment. +Moments carry `ms` (the entry's game clock); timeline.py turns it into `t`. +What counts is the game's `MomentMap` (config.py); this module only applies it. +""" + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Callable + + from game_recording.config import Moment, MomentMap, Row + +# Fields every entry carries; never part of a passthrough moment's payload. +ENVELOPE = ("session", "time", "frame", "tag", "event", "seq", "ms") +ANNOTATION = "annotation" +NEVER_MS = -(10**12) + + +def event_name(row: Row) -> str: + """The entry's event name, "" when it has none.""" + return str(row.get("event", "")) + + +def moment(row: Row, kind: str, label: str, **extra: object) -> Moment: + """A moment at the entry's game clock; custom rules build theirs with this.""" + out: Moment = { + "kind": kind, + "label": label, + "event": event_name(row), + "seq": row.get("seq"), + "ms": row["ms"], + } + if row.get("game"): + out["game"] = row["game"] + out.update(extra) + return out + + +def _keep(row: Row, keys: tuple[str, ...]) -> Row: + return {k: row[k] for k in keys if k in row} + + +def _words(value: object) -> str: + """A field value as label text: a list reads as a,b,c.""" + if isinstance(value, list): + return ",".join(str(v) for v in value) + return str(value) + + +def _direct(row: Row, moment_map: MomentMap) -> Moment | None: + name = event_name(row) + if name not in moment_map.direct: + return None + extra = _keep(row, moment_map.direct[name]) + detail = " ".join(_words(v) for v in extra.values() if v not in ("", None)) + return moment( + row, + name, + f"{name} {row.get('game', '')} {detail}".replace(" ", " ").strip(), + **extra, + ) + + +def _game_end(row: Row, moment_map: MomentMap) -> Moment | None: + if event_name(row) != "game_end": + return None + extra = _keep(row, moment_map.game_end_fields) + return moment(row, "game_end", f"game_end {row.get('outcome', '')}".strip(), **extra) + + +def _annotation(row: Row, _moment_map: MomentMap) -> Moment | None: + if event_name(row) != ANNOTATION: + return None + return moment( + row, + ANNOTATION, + "F12 annotation", + png=row.get("image", ""), + marks=row.get("marks"), + ) + + +def _engine_error(row: Row, moment_map: MomentMap) -> Moment | None: + if event_name(row) != "engine_error" or row.get("kind") not in moment_map.error_kinds: + return None + text = str(row.get("message", ""))[:60] + extra = _keep(row, ("message", "file", "line")) + return moment(row, "engine_error", f"engine_error {text}", error_kind=row["kind"], **extra) + + +def _passthrough(row: Row, moment_map: MomentMap) -> Moment | None: + name = event_name(row) + if not (moment_map.passthrough_prefixes and name.startswith(moment_map.passthrough_prefixes)): + return None + extra = {k: v for k, v in row.items() if k not in ENVELOPE} + return moment(row, name, name, **extra) + + +_BUILT_IN: tuple[Callable[[Row, MomentMap], Moment | None], ...] = ( + _direct, + _game_end, + _annotation, + _engine_error, + _passthrough, +) + + +def _one(row: Row, moment_map: MomentMap) -> Moment | None: + for classifier in moment_map.classifiers: + found = classifier(row) + if found is not None: + return found + for rule in _BUILT_IN: + found = rule(row, moment_map) + if found is not None: + return found + return None + + +def classify(rows: list[Row], moment_map: MomentMap) -> list[Moment]: + """The direct moments of a session's entries.""" + return [m for m in (_one(r, moment_map) for r in rows) if m is not None] + + +def derive(rows: list[Row], moment_map: MomentMap) -> list[Moment]: + """The moments that need more than one entry.""" + out = _hitches(rows, moment_map.hitch_merge_s) + for session_rule in moment_map.session_rules: + out += session_rule(rows) + return out + + +def _hitches(rows: list[Row], merge_s: float) -> list[Moment]: + """A burst of `hitch` entries closer than `merge_s` is one moment.""" + out: list[Moment] = [] + last_ms = NEVER_MS + for row in rows: + if event_name(row) != "hitch": + continue + dur = row.get("dur_ms", 0) + if out and row["ms"] - last_ms <= merge_s * 1000: + out[-1]["count"] += 1 + out[-1]["max_ms"] = max(out[-1]["max_ms"], dur) + else: + out.append( + moment( + row, + "hitch", + "", + count=1, + max_ms=dur, + cause=row.get("cause", ""), + derived=True, + ) + ) + out[-1]["label"] = f"hitch x{out[-1]['count']} max {out[-1]['max_ms']} ms" + last_ms = row["ms"] + return out diff --git a/game_recording/game_recording/options.py b/game_recording/game_recording/options.py new file mode 100644 index 0000000..4757b56 --- /dev/null +++ b/game_recording/game_recording/options.py @@ -0,0 +1,34 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The settings of one recorded run, as plain values.""" + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from pathlib import Path + +DEFAULT_FPS = 30 + + +@dataclass(frozen=True) +class RunOptions: + """What the command line asks of `supervise.run`.""" + + force: bool = False # record bot and test runs too (tests only) + session: str = "" + audio: str = "default" # default | lavfi | + fps: int = DEFAULT_FPS + max_seconds: float = 0.0 # the test flag: stop the game this long after recording began + + +@dataclass(frozen=True) +class RecorderOptions: + """What the recorder needs to start parts of one session.""" + + session: str + feedback: Path + fps: int + audio: str + nice: str + usable: frozenset[str] + backend: str = "x11grab" # gsr or x11grab diff --git a/game_recording/game_recording/policy.py b/game_recording/game_recording/policy.py new file mode 100644 index 0000000..1dd140c --- /dev/null +++ b/game_recording/game_recording/policy.py @@ -0,0 +1,75 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""When a run is recorded: a person's own dev play, never bots, tests or headless runs.""" + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Mapping, Sequence + + from game_recording.config import Config + +DEV_ARG = "--dev" +NO_DEV_ARG = "--no-dev" +# (engine flag, the value after it that makes the run headless or muted) +ENGINE_BLOCKERS = (("--display-driver", "headless"), ("--audio-driver", "Dummy")) + + +@dataclass(frozen=True) +class Decision: + """Whether to record, and the reason either way.""" + + record: bool + reason: str + + +def arg_value(args: Sequence[str], prefix: str) -> str: + """The value of the first `value` argument, "" when absent.""" + for arg in args: + if arg.startswith(prefix): + return arg[len(prefix) :] + return "" + + +def _engine_blocker(args: Sequence[str]) -> str: + """Why the engine arguments (before `--`) make this a headless or muted run.""" + engine = list(args[: args.index("--")]) if "--" in args else list(args) + if "--headless" in engine: + return "--headless" + for flag, value in ENGINE_BLOCKERS: + if flag in engine and engine[engine.index(flag) + 1 : engine.index(flag) + 2] == [value]: + return f"{flag} {value}" + return "" + + +def _env_blocker(env: Mapping[str, str], config: Config) -> str: + """Why the environment opts out: a flag is on only as "1"; a feedback dir is a path, any value counts.""" + for name in config.blocking_flags: + if env.get(name) == "1": + return f"{name}=1" + path = config.env_name("FEEDBACK_DIR") + return f"{path} is set" if env.get(path) else "" + + +def _args_blocker(args: Sequence[str], config: Config) -> str: + """Why the game's own arguments say this is not dev play.""" + if NO_DEV_ARG in args or DEV_ARG not in args: + return "not a --dev run" + for marker in config.bot_args: + hit = next((a for a in args if a.startswith(marker)), "") + if hit: + return f"bot or test run ({hit})" + blocker = _engine_blocker(args) + return f"headless or muted run ({blocker})" if blocker else "" + + +def decide(args: Sequence[str], env: Mapping[str, str], config: Config, *, force: bool = False) -> Decision: + """Record only a windowed dev run on a real display; `force` is for tests.""" + if not env.get("DISPLAY"): + return Decision(record=False, reason="no DISPLAY") + if force: + return Decision(record=True, reason="forced") + reason = _env_blocker(env, config) or _args_blocker(args, config) + if reason: + return Decision(record=False, reason=reason) + return Decision(record=True, reason="dev play") diff --git a/game_recording/game_recording/procs.py b/game_recording/game_recording/procs.py new file mode 100644 index 0000000..973460f --- /dev/null +++ b/game_recording/game_recording/procs.py @@ -0,0 +1,33 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Helpers for starting the external programs (ffmpeg, gpu-screen-recorder, xdotool, mpv).""" + +import shutil +import subprocess +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Mapping, Sequence + from typing import IO + + +def program(name: str) -> str: + """The full path of an installed program; the bare name when it is not on PATH (the start then fails clearly).""" + return shutil.which(name) or name + + +def niced(nice: str, argv: Sequence[str]) -> list[str]: + """`argv` run under `nice -n `: when the CPU is contended the game wins, not the recorder.""" + return [program("nice"), "-n", nice, *argv] + + +def spawn( + argv: Sequence[str], + *, + env: Mapping[str, str] | None = None, + log: IO[bytes] | None = None, + detach: bool = False, +) -> subprocess.Popen[bytes]: + """Starts a child that outlives this call; `log` takes its output, `detach` gives it its own session.""" + return subprocess.Popen( + list(argv), env=None if env is None else dict(env), stdout=log, stderr=log, start_new_session=detach + ) diff --git a/game_recording/game_recording/recorder.py b/game_recording/game_recording/recorder.py new file mode 100644 index 0000000..da281b7 --- /dev/null +++ b/game_recording/game_recording/recorder.py @@ -0,0 +1,223 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The recorder beside the game: gpu-screen-recorder, or ffmpeg x11grab as the fallback. + +One part file per run of the recorder; every part sits on the same t0 timeline (the +unix time of the first part's time 0), see encoder.py (x11grab) and gsr.py. +""" + +from dataclasses import dataclass, field +import json +import os +import signal +import subprocess +import sys +import time +from typing import TYPE_CHECKING + +from game_recording import encoder, gsr, procs, window + +if TYPE_CHECKING: + from pathlib import Path + + from game_recording.options import RecorderOptions + +WINDOW_WAIT_S = 30.0 +RETURN_WAIT_S = 3600.0 # a window that went away may take a whole break to return +MAX_QUICK_DEATHS = 3 # ffmpeg dying right at start this many times in a row: give up +RECORDER_NICE = 10 +STOP_GRACE_S = 20.0 +SHORT_LIFE_S = 5.0 # a gsr part that ends sooner than this counts against gsr +X11GRAB_SETTLE_S = 1.0 # still running after this long = recording + + +def say(message: str) -> None: + """One status line on stderr.""" + sys.stderr.write(f"record: {message}\n") + sys.stderr.flush() + + +def stop_recorder(proc: subprocess.Popen[bytes], grace_s: float = STOP_GRACE_S) -> bool: + """SIGINT so the recorder writes the trailer; kill only after the grace. True = it finalized by itself.""" + if proc.poll() is not None: + return True + proc.send_signal(signal.SIGINT) + try: + proc.wait(timeout=grace_s) + except subprocess.TimeoutExpired: + proc.kill() + proc.wait() + return False + return True + + +def part_file(session: str, number: int) -> str: + """Part 1 is .mkv; each restart (window came back) adds .partN.mkv.""" + return f"{session}.mkv" if number == 1 else f"{session}.part{number}.mkv" + + +@dataclass +class GsrState: + """What the recorder remembers about gpu-screen-recorder parts.""" + + open_part: tuple[Path, float] | None = None # (file, first-frame unix) of the running part + pending: list[tuple[Path, float]] = field(default_factory=list) # ended parts, aligned after the game + first_frames: dict[str, float] = field(default_factory=dict) # part file -> unix time of its first frame + started: float = 0.0 # monotonic start of the running part + short_lives: int = 0 + + +class Recorder: + """The recorder process, restarted when the game's window goes away and returns. + + The window capture ends when the window is unmapped (an i3 workspace switch), resized or + replaced. Each run is a part file on the same t0 timeline; the time between + parts is simply not in the video (events there are `in_gap`). `backend` is "gsr" or + "x11grab"; a gsr that fails to start switches the rest of the session to x11grab. + """ + + def __init__(self, game: subprocess.Popen[bytes], paths: dict[str, Path], opts: RecorderOptions) -> None: + """Watches `game`; writes into `paths` (dir, video, events, meta, log).""" + self.game, self.paths, self.opts = game, paths, opts + self.backend = opts.backend + self.proc: subprocess.Popen[bytes] | None = None + self.parts: list[str] = [] + self.t0 = 0.0 + self.quick_deaths = 0 + self.off = False + self.win: window.Window | None = None # the window the running part records + self.gsr = GsrState() + + def _write_meta(self, codec: str, win: window.Window) -> None: + meta = { + "session": self.opts.session, "t0_unix": self.t0, "video": self.parts[0], "parts": self.parts, + "feedback": str(self.opts.feedback / "feedback.jsonl"), "encoder": codec, "backend": self.backend, + "first_frame_unix": self.gsr.first_frames, "audio": self.opts.audio, "fps": self.opts.fps, + "window": {"id": win.id, "width": win.width, "height": win.height}, + } # fmt: skip + self.paths["meta"].write_text(json.dumps(meta, indent=1) + "\n", encoding="utf-8") + + def _spec(self, win: window.Window, out: Path) -> encoder.Spec: + return encoder.Spec( + window_id=win.id, fps=self.opts.fps, t0_unix=self.t0, out=str(out), + audio=self.opts.audio, display=os.environ["DISPLAY"], width=win.width, height=win.height, + ) # fmt: skip + + def _start_gsr(self, win: window.Window, name: str, out: Path) -> bool: + with self.paths["log"].open("ab") as log: + started = gsr.start(self._spec(win, out), log, self.opts.nice) + if started is None: + say(f"gpu-screen-recorder failed to start, using x11grab; see {self.paths['log']}") + self.backend = "x11grab" + return False + self.proc, first = started + if not self.parts: + self.t0 = first # the timeline starts at the first frame, exactly (see gsr.py) + self.parts.append(name) + self.gsr.open_part = (out, first) + self.gsr.first_frames[name] = first + self.gsr.started = time.monotonic() + self._write_meta("gsr-h264", win) + say(f"recording {win.width}x{win.height} with gpu-screen-recorder -> {out}") + self.quick_deaths = 0 + return True + + def _start_x11grab(self, win: window.Window, name: str, out: Path) -> None: + codec = encoder.pick(self.opts.usable) + if not self.parts: + self.t0 = time.time() # the files' timeline starts here, exactly (see encoder.py) + spec = self._spec(win, out) + self.parts.append(name) + self._write_meta(codec, win) + with self.paths["log"].open("ab") as log: + cmd = procs.niced(self.opts.nice, encoder.command(spec, codec)) + self.proc = procs.spawn(cmd, log=log, detach=True) + try: + self.proc.wait(timeout=X11GRAB_SETTLE_S) + except subprocess.TimeoutExpired: + say(f"recording {win.width}x{win.height} with {codec} -> {out}") + self.quick_deaths = 0 + return + self.quick_deaths += 1 + self.parts.pop() + self.proc = None + say(f"ffmpeg died at start, see {self.paths['log']}") + self.off = self.quick_deaths >= MAX_QUICK_DEATHS + + def _start_part(self, win: window.Window) -> None: + name = part_file(self.opts.session, len(self.parts) + 1) + out = self.paths["dir"] / name + self.paths["dir"].mkdir(parents=True, exist_ok=True) + self.win = win + if self.backend == "gsr" and self._start_gsr(win, name, out): + return + self._start_x11grab(win, name, out) + + def close_part(self) -> None: + """The running gsr part has ended. Aligning it is a remux (disk I/O), so it waits for the game's end.""" + if self.gsr.open_part is not None: + self.gsr.pending.append(self.gsr.open_part) + self.gsr.open_part = None + + def _align_pending(self) -> None: + """Moves each ended gsr part onto the t0 timeline (stream copy). Trouble is only reported.""" + pending, self.gsr.pending = self.gsr.pending, [] + for video, first in pending: + try: + gsr.align(video, first_unix=first, t0=self.t0) + except (subprocess.SubprocessError, OSError, ValueError) as err: + say(f"could not align {video.name} to the timeline: {err}") + + def _count_short_life(self) -> None: + """A gsr that keeps dying soon after it started is replaced by x11grab for the rest of the session.""" + if self.gsr.open_part is None: + return + young = time.monotonic() - self.gsr.started < SHORT_LIFE_S + self.gsr.short_lives = self.gsr.short_lives + 1 if young else 0 + if self.gsr.short_lives >= MAX_QUICK_DEATHS: + say("gpu-screen-recorder keeps stopping, using x11grab") + self.backend = "x11grab" + + def _still_recording(self) -> bool: + """True while the running part is fine; ends a gsr part whose window changed.""" + if self.proc is None or self.proc.poll() is not None: + return False + if self.gsr.open_part is None or window.largest(self.game.pid) == self.win: + return True + # x11grab dies with its window; gsr neither exits nor resumes after an unmap + # (an i3 workspace switch), so its part is ended here and the next one waits. + stop_recorder(self.proc) + return False + + def step(self) -> bool: + """One look at the recorder; True while a part is being recorded.""" + if self.off: + return False + if self._still_recording(): + return True + first = not self.parts + if self.proc is not None: + say("recorder stopped (the window went away); waiting for it to come back") + self.proc = None + self._count_short_life() + self.close_part() + win = window.wait_stable( + self.game.pid, WINDOW_WAIT_S if first else RETURN_WAIT_S, lambda: self.game.poll() is None + ) + if win is None: + if first: + say("no game window found, not recording") + self.off = True + return False + try: + self._start_part(win) + except (encoder.NoEncoderError, OSError) as err: + say(f"not recording: {err}") + self.off = True + return self.proc is not None + + def stop(self) -> None: + """Ends the running part (SIGINT, kill after the grace) and aligns the gsr parts.""" + if self.proc is not None and not stop_recorder(self.proc): + say("the recorder ignored SIGINT and was killed; the mkv keeps what was written") + self.close_part() + self._align_pending() diff --git a/game_recording/game_recording/supervise.py b/game_recording/game_recording/supervise.py new file mode 100644 index 0000000..af0accc --- /dev/null +++ b/game_recording/game_recording/supervise.py @@ -0,0 +1,177 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Runs the game and, for a person's own dev play, an external recorder beside it. + +The game is a child process; its window is found by pid; the recorder +(gpu-screen-recorder, else ffmpeg x11grab, with the audio monitor) starts once the +window has settled and gets SIGINT when the game exits, so the mkv is finalized. +Then finalize.py writes events.json + chapters. +Recording trouble never changes the game's exit code or stops the game. +""" + +from concurrent.futures import ThreadPoolExecutor +import os +from pathlib import Path +import secrets +import signal +import subprocess +import threading +import time +from typing import TYPE_CHECKING + +from game_recording import encoder, finalize, gsr, policy, procs, timeline +from game_recording.options import RecorderOptions, RunOptions +from game_recording.recorder import Recorder, say + +if TYPE_CHECKING: + from collections.abc import Mapping, Sequence + from types import FrameType + + from game_recording.config import Config + +SESSION_ARG = "--session-id=" +FEEDBACK_ARG = "--feedback-dir=" +POLL_S = 0.5 +# What finalize can fail with: files, JSON (NoSyncError is a ValueError), a missing key, ffmpeg. +# Recording trouble must not fail the play session. +FINALIZE_ERRORS = (OSError, ValueError, KeyError, TypeError, subprocess.SubprocessError) +DEFAULT_NICE = "10" + + +def session_of(command: Sequence[str]) -> str: + """The session id the command already carries, "" when none.""" + return policy.arg_value(command, SESSION_ARG) + + +def with_session(command: Sequence[str], session: str) -> list[str]: + """The command with `--session-id=` among the game's user args (an existing one wins).""" + return _with_user_arg(command, SESSION_ARG, session) + + +def _with_user_arg(command: Sequence[str], prefix: str, value: str) -> list[str]: + out = list(command) + if policy.arg_value(out, prefix): + return out + if "--" not in out: + out.append("--") + return [*out, f"{prefix}{value}"] + + +def feedback_dir(command: Sequence[str], env: Mapping[str, str], config: Config) -> Path: + """Where the game's telemetry goes: --feedback-dir=, else the binaries folder's feedback/.""" + forced = policy.arg_value(command, FEEDBACK_ARG) + if forced: + return Path(forced) + binaries = env.get(config.binaries_var) + if binaries: + return Path(binaries) / "feedback" + return Path(env.get("HOME", str(Path.home()))) / config.binaries_dir / "feedback" + + +def recording_paths(feedback: Path, session: str) -> dict[str, Path]: + """Every file of one recording, by role.""" + rec = feedback / "recordings" + return { + "dir": rec, + "video": rec / f"{session}.mkv", + "events": rec / f"{session}.events.json", + "meta": rec / f"{session}.rec.json", + "log": rec / f"{session}.ffmpeg.log", + } + + +def new_session() -> str: + """A fresh session id: unix time plus four hex digits.""" + return f"{int(time.time())}-run-{secrets.token_hex(2)}" + + +def _forward_signals(game: subprocess.Popen[bytes]) -> None: + """The launcher is a thin parent: kill/hangup go to the game; Ctrl-C already reaches it directly.""" + signal.signal(signal.SIGINT, signal.SIG_IGN) + + def forward(number: int, _frame: FrameType | None) -> None: + game.send_signal(number) + + for sig in (signal.SIGTERM, signal.SIGHUP): + signal.signal(sig, forward) + + +def _stop_game(game: subprocess.Popen[bytes]) -> None: + if game.poll() is None: + game.send_signal(signal.SIGTERM) + + +def _finish(paths: dict[str, Path], config: Config) -> None: + if not paths["meta"].exists(): + return + try: + doc = finalize.finalize(paths["meta"], config.moments) + shown = sum(1 for e in doc["events"] if timeline.in_recording(e)) + parts = doc["video"]["parts"] + gaps = f", {len(parts)} parts" if len(parts) > 1 else "" + say(f"{paths['dir'] / doc['video']['file']} ({doc['video']['duration_s']:.0f} s, {shown} moments{gaps})") + except FINALIZE_ERRORS as err: + say(f"could not build the timeline: {err}") + + +def _nice(env: Mapping[str, str], config: Config) -> str: + """The recorder's nice value; `_RECORDER_NICE=0` for tests under a CPU cap.""" + return env.get(config.env_name("RECORDER_NICE"), DEFAULT_NICE) + + +def _play_unrecorded(command: Sequence[str], env: Mapping[str, str]) -> int: + game = procs.spawn(command, env=env) + _forward_signals(game) + return game.wait() + + +def _watch(game: subprocess.Popen[bytes], recorder: Recorder, options: RunOptions) -> None: + """Steps the recorder until the game exits.""" + timer_started = False + while game.poll() is None: + recording = recorder.step() + if options.max_seconds > 0 and not timer_started and (recording or recorder.off): + timer_started = True # the test flag: stop the game N s after recording began + threading.Timer(options.max_seconds, _stop_game, (game,)).start() + time.sleep(POLL_S) + + +def _play_recorded(command: Sequence[str], env: Mapping[str, str], config: Config, options: RunOptions) -> int: + session = session_of(command) or options.session or new_session() + fb = feedback_dir(command, env, config) + argv = _with_user_arg(with_session(command, session), FEEDBACK_ARG, str(fb)) + paths = recording_paths(fb, session) + with ThreadPoolExecutor(max_workers=1) as pool: + usable = pool.submit(encoder.probe_usable) # NVENC init overlaps the game's start + game = procs.spawn(argv, env=env) + _forward_signals(game) + opts = RecorderOptions( + session=session, + feedback=fb, + fps=options.fps, + audio=options.audio, + nice=_nice(env, config), + usable=frozenset(usable.result()), + backend=gsr.pick_backend(env, options.audio, config, have_gsr=gsr.available()), + ) + recorder = Recorder(game, paths, opts) + _watch(game, recorder, options) + code = game.wait() + recorder.stop() + _finish(paths, config) + return code + + +def run( + command: Sequence[str], + config: Config, + options: RunOptions | None = None, + env: Mapping[str, str] | None = None, +) -> int: + """Runs `command`; records it when policy allows. Returns the game's exit code.""" + options = options or RunOptions() + env = os.environ if env is None else env + decision = policy.decide(command, env, config, force=options.force) + if not decision.record: + say(f"off ({decision.reason})") + return _play_unrecorded(command, env) + return _play_recorded(command, env, config, options) diff --git a/game_recording/game_recording/tests/__init__.py b/game_recording/game_recording/tests/__init__.py new file mode 100644 index 0000000..ff6b7fd --- /dev/null +++ b/game_recording/game_recording/tests/__init__.py @@ -0,0 +1,2 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Tests of game_recording.""" diff --git a/game_recording/game_recording/tests/test_derived.py b/game_recording/game_recording/tests/test_derived.py new file mode 100644 index 0000000..0d194d4 --- /dev/null +++ b/game_recording/game_recording/tests/test_derived.py @@ -0,0 +1,38 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Derived moments: several telemetry entries that are one moment together.""" + +from game_recording import moments +from game_recording.tests.test_helpers import MOMENT_MAP, entry + + +def test_a_burst_of_hitches_is_one_moment() -> None: + rows = [ + entry("hitch", 1000, 1, dur_ms=40, cause="load"), + entry("hitch", 1500, 2, dur_ms=90), + entry("hitch", 3400, 3, dur_ms=55), + ] + found = moments.derive(rows, MOMENT_MAP) + assert len(found) == 1 + assert found[0]["kind"] == "hitch" + assert (found[0]["count"], found[0]["max_ms"]) == (3, 90) + assert found[0]["label"] == "hitch x3 max 90 ms" + assert found[0]["ms"] == 1000, "stamped at the first hitch" + assert found[0]["cause"] == "load" + assert found[0]["derived"] + + +def test_hitches_far_apart_are_separate_moments() -> None: + gap_ms = int(MOMENT_MAP.hitch_merge_s * 1000) + 1 + rows = [entry("hitch", 1000, 1, dur_ms=40), entry("hitch", 1000 + gap_ms, 2, dur_ms=20)] + found = moments.derive(rows, MOMENT_MAP) + assert [m["label"] for m in found] == ["hitch x1 max 40 ms", "hitch x1 max 20 ms"] + + +def test_a_hitch_without_a_duration_counts_as_zero() -> None: + assert moments.derive([entry("hitch", 1000, 1)], MOMENT_MAP)[0]["max_ms"] == 0 + + +def test_other_entries_derive_nothing() -> None: + rows = [entry("game_start", 1000, 1, game="watch"), entry("command", 2000, 2, order="charge")] + assert moments.derive(rows, MOMENT_MAP) == [] + assert moments.derive([], MOMENT_MAP) == [] diff --git a/game_recording/game_recording/tests/test_encoder.py b/game_recording/game_recording/tests/test_encoder.py new file mode 100644 index 0000000..3f82449 --- /dev/null +++ b/game_recording/game_recording/tests/test_encoder.py @@ -0,0 +1,113 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The ffmpeg command line: encoder choice, window capture, exact timestamps.""" + +from dataclasses import replace +from itertools import pairwise +import subprocess + +import pytest + +from game_recording import encoder + +SPEC = encoder.Spec(window_id=0x4200007, fps=60, t0_unix=1_800_000_000.5, out="/o/s.mkv", audio="default") + + +def _pairs(cmd: list[str]) -> list[tuple[str, str]]: + return list(pairwise(cmd)) + + +def test_nvenc_is_preferred_when_it_works() -> None: + assert encoder.pick({"h264_nvenc", "libx264"}) == "h264_nvenc" + + +def test_falls_back_to_x264() -> None: + assert encoder.pick(["libx264"]) == "libx264" + + +def test_nothing_usable_is_an_error() -> None: + with pytest.raises(encoder.NoEncoderError): + encoder.pick({"mpeg4"}) + + +def test_probe_lists_only_the_encoders_that_encode_a_frame(monkeypatch: pytest.MonkeyPatch) -> None: + calls: list[list[str]] = [] + + def run(cmd: list[str], **_: object) -> subprocess.CompletedProcess[bytes]: + calls.append(cmd) + return subprocess.CompletedProcess(cmd, 0 if "libx264" in cmd else 1) + + monkeypatch.setattr(subprocess, "run", run) + assert encoder.probe_usable() == {"libx264"} + assert len(calls) == 2 + + +def test_nvenc_is_quality_first() -> None: + pairs = _pairs(encoder.command(SPEC, "h264_nvenc")) + for pair in (("-preset", "p7"), ("-rc", "vbr"), ("-cq", "17"), ("-b:v", "0")): + assert pair in pairs + + +def test_4k_windows_use_a_faster_nvenc_preset_to_stay_real_time() -> None: + big = replace(SPEC, width=3840, height=2160) + assert ("-preset", "p4") in _pairs(encoder.command(big, "h264_nvenc")) + qhd = replace(SPEC, width=2560, height=1440) + assert ("-preset", "p7") in _pairs(encoder.command(qhd, "h264_nvenc")) + + +def test_x264_fallback_settings() -> None: + pairs = _pairs(encoder.command(SPEC, "libx264")) + assert ("-crf", "16") in pairs + assert ("-preset", "veryfast") in pairs + + +def test_captures_the_window_by_id_at_the_fps() -> None: + cmd = encoder.command(SPEC, "h264_nvenc") + assert ("-window_id", "0x4200007") in _pairs(cmd) + assert ("-framerate", "60") in _pairs(cmd) + assert "x11grab" in cmd + + +def test_output_is_mkv_and_sits_on_the_launcher_clock() -> None: + cmd = encoder.command(SPEC, "h264_nvenc") + assert "-copyts" in cmd + assert ("-output_ts_offset", "-1800000000.500000") in _pairs(cmd) + assert cmd[-1] == "/o/s.mkv" + assert ("-f", "matroska") in _pairs(cmd) + + +def test_video_stamps_are_shifted_back_by_the_grab_latency() -> None: + cmd = encoder.command(SPEC, "h264_nvenc") + assert ("-itsoffset", "-0.025000") in _pairs(cmd) # 1.5 frames at 60 fps + assert cmd.index("-itsoffset") < cmd.index("x11grab"), "an input option of the video input" + + +def test_ffmpeg_ends_when_the_window_capture_dies() -> None: + assert "-shortest" in encoder.command(SPEC, "h264_nvenc") + + +def test_audio_is_recorded_not_muted() -> None: + cmd = encoder.command(SPEC, "h264_nvenc") + assert "pulse" in cmd + assert ("-c:a", "flac") in _pairs(cmd) + assert ("-i", encoder.DEFAULT_MONITOR) in _pairs(cmd) + + +def test_pulse_source_is_the_given_monitor() -> None: + cmd = encoder.command(replace(SPEC, audio="sink.monitor"), "h264_nvenc") + assert ("-i", "sink.monitor") in _pairs(cmd) + + +def test_silent_test_source_rides_the_wall_clock() -> None: + cmd = encoder.command(replace(SPEC, audio="lavfi"), "h264_nvenc") + assert "lavfi" in cmd + assert any("RTCTIME" in part for part in cmd) + + +def test_odd_window_sizes_are_cropped_to_even() -> None: + assert "-vf" in encoder.command(replace(SPEC, width=1281, height=800), "h264_nvenc") + assert "-vf" in encoder.command(replace(SPEC, width=1280, height=801), "h264_nvenc") + assert "-vf" not in encoder.command(replace(SPEC, width=1280, height=800), "h264_nvenc") + + +def test_no_resize_scaler_in_the_path() -> None: + assert "-vf" not in encoder.command(SPEC, "h264_nvenc") diff --git a/game_recording/game_recording/tests/test_events.py b/game_recording/game_recording/tests/test_events.py new file mode 100644 index 0000000..0b994da --- /dev/null +++ b/game_recording/game_recording/tests/test_events.py @@ -0,0 +1,96 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Which telemetry entries become moments, and what each one keeps.""" + +from typing import TYPE_CHECKING + +import pytest + +from game_recording import moments +from game_recording.tests.test_helpers import MOMENT_MAP, entry + +if TYPE_CHECKING: + from game_recording.config import Moment, Row + + +def one(row: Row, kind: str) -> Moment: + found = moments.classify([row], MOMENT_MAP) + assert [m["kind"] for m in found] == [kind], row + return found[0] + + +def test_session_start_and_hub_are_moments() -> None: + one(entry("session_start", 0, 1), "session_start") + assert one(entry("hub_open", 50, 2), "hub_open")["label"] == "hub_open" + + +def test_game_start_keeps_the_whole_loadout() -> None: + row = entry("game_start", 9000, 2, game="command", loadout=["double_men", "stew"], cost=6, men=200, seed=7) + m = one(row, "game_start") + assert m["game"] == "command" + assert m["loadout"] == ["double_men", "stew"] + assert (m["cost"], m["men"], m["seed"]) == (6, 200, 7) + assert m["label"] == "game_start command double_men,stew 6 200 7" + assert (m["ms"], m["seq"], m["event"]) == (9000, 2, "game_start") + + +def test_game_end_names_the_outcome() -> None: + m = one(entry("game_end", 9000, 2, outcome="win", elapsed_s=20.5), "game_end") + assert m["label"] == "game_end win" + assert m["elapsed_s"] == 20.5 + + +def test_a_buy_and_an_order_keep_their_fields() -> None: + buy = one(entry("buy", 100, 2, buff="moose", bought=True, cost=3), "buy") + assert buy["label"] == "buy moose True 3" + order = one(entry("command", 200, 3, order="rally", pos=[120.0, 80.0]), "command") + assert order["order"] == "rally" + assert order["label"] == "command rally 120.0,80.0" + + +def test_pause_lab_reset_quit_and_session_end() -> None: + one(entry("pause_open", 9000, 2), "pause_open") + assert one(entry("pause_close", 9000, 2, paused_s=3.0), "pause_close")["paused_s"] == 3.0 + lab = one(entry("lab_result", 9000, 2, wins=12, runs=30, mean_seconds=19.5), "lab_result") + assert lab["label"] == "lab_result 12 30 19.5" + assert one(entry("reset_progress", 9000, 2, files=1), "reset_progress")["files"] == 1 + assert one(entry("quit", 9000, 2, reason="menu"), "quit")["reason"] == "menu" + end = one(entry("session_end", 9000, 2, reason="exit", elapsed_s=120.0), "session_end") + assert end["label"] == "session_end exit 120.0" + + +def test_an_annotation_carries_its_png_and_mark_count() -> None: + m = one(entry("annotation", 9000, 2, image="/fb/x/annotated.png", marks=3, bundle="/fb/x"), "annotation") + assert m["label"] == "F12 annotation" + assert m["png"] == "/fb/x/annotated.png" + assert m["marks"] == 3 + + +def test_real_engine_errors_are_moments() -> None: + row = entry("engine_error", 9000, 2, kind="script_error", message="boom " * 30, file="a.gd", line=3) + m = one(row, "engine_error") + assert m["error_kind"] == "script_error" + assert m["label"] == "engine_error " + ("boom " * 30)[:60] + assert (m["file"], m["line"]) == ("a.gd", 3) + + +@pytest.mark.parametrize("kind", ["warning", "stderr"]) +def test_engine_noise_is_not_a_moment(kind: str) -> None: + assert moments.classify([entry("engine_error", 1, 1, kind=kind, message="x")], MOMENT_MAP) == [] + + +def test_sim_events_the_game_may_log_later_pass_through() -> None: + m = one(entry("evt_wall_breached", 9000, 2, at=[1, 2], tag="v01"), "evt_wall_breached") + assert m["at"] == [1, 2] + assert "tag" not in m + assert "session" not in m + one(entry("milestone_first_win", 9000, 2), "milestone_first_win") + + +@pytest.mark.parametrize("name", ["recording_sync", "screen", "hitch", "", "perf"]) +def test_everything_else_is_not_a_moment(name: str) -> None: + assert moments.classify([entry(name, 9000, 2)], MOMENT_MAP) == [] + + +def test_event_name_is_the_event_field() -> None: + assert moments.event_name({"event": "buy"}) == "buy" + assert moments.event_name({}) == "" diff --git a/game_recording/game_recording/tests/test_finalize.py b/game_recording/game_recording/tests/test_finalize.py new file mode 100644 index 0000000..163a2fe --- /dev/null +++ b/game_recording/game_recording/tests/test_finalize.py @@ -0,0 +1,150 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""After the game exits: events.json, chapters remuxed in, no re-encode.""" + +import json +import subprocess +from typing import TYPE_CHECKING, Any + +import pytest + +from game_recording import finalize +from game_recording.tests.test_helpers import MOMENT_MAP, SESSION, SYNC_MS, SYNC_UNIX, entry, sync_entry + +if TYPE_CHECKING: + from pathlib import Path + +T0 = SYNC_UNIX + 0.5 +START = 0.052 + + +def make_video(path: Path) -> None: + """A 4 s test pattern + tone whose timeline starts at START (like the real recorder's).""" + cmd = ["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=30"] + cmd += ["-f", "lavfi", "-i", "sine=frequency=440:sample_rate=48000", "-t", "4"] + cmd += ["-output_ts_offset", str(START), "-c:v", "libx264", "-c:a", "flac", str(path)] + subprocess.run(cmd, check=True, timeout=30) + + +def ffprobe(*args: str) -> dict[str, Any]: + cmd = ["ffprobe", "-v", "error", "-of", "json", *args] + out = subprocess.run(cmd, capture_output=True, text=True, check=True) + probed: dict[str, Any] = json.loads(out.stdout) + return probed + + +def write_meta(root: Path, rec: Path, extra: dict[str, object]) -> Path: + """A rec.json for a single video file next to the feedback log.""" + meta = { + "session": SESSION, + "t0_unix": T0, + "video": f"{SESSION}.mkv", + "feedback": str(root / "feedback.jsonl"), + **extra, + } + path = rec / f"{SESSION}.rec.json" + path.write_text(json.dumps(meta), encoding="utf-8") + return path + + +@pytest.fixture(scope="module") +def session(tmp_path_factory: pytest.TempPathFactory) -> tuple[Path, dict[str, Any]]: + root = tmp_path_factory.mktemp("session") + rec = root / "recordings" + rec.mkdir() + make_video(rec / f"{SESSION}.mkv") + rows = [ + sync_entry(), + entry("game_start", SYNC_MS + 100, 2, game="watch"), + entry("command", SYNC_MS + 1500, 3, order="rally", pos=[1, 2]), + entry("buy", SYNC_MS + 2500, 4, buff="stew", bought=True, cost=1), + entry("game_end", SYNC_MS + 3300, 5, game="watch", outcome="lose", elapsed_s=3.2), + ] + (root / "feedback.jsonl").write_text("\n".join(json.dumps(r) for r in rows) + "\n", encoding="utf-8") + meta_path = write_meta(root, rec, {"encoder": "libx264"}) + return rec, finalize.finalize(meta_path, MOMENT_MAP) + + +def test_events_json_is_written_with_timestamps_inside_the_duration(session: tuple[Path, dict[str, Any]]) -> None: + rec, doc = session + written = json.loads((rec / f"{SESSION}.events.json").read_text(encoding="utf-8")) + assert written["events"] == doc["events"] + assert written["video"]["encoder"] == "libx264" + assert written["video"]["file"] == f"{SESSION}.mkv" + end = written["video"]["end_s"] + inside = [e for e in written["events"] if not e.get("before_recording")] + assert inside + for event in inside: + assert START - 1e-3 <= event["t"] <= end + 1e-3 + + +def test_video_start_and_duration_come_from_the_file(session: tuple[Path, dict[str, Any]]) -> None: + doc = session[1] + assert doc["video"]["start_s"] == pytest.approx(START, abs=1e-2) + assert doc["video"]["duration_s"] > 3.5 + + +def test_chapters_are_embedded_without_reencoding_or_moving_the_timeline( + session: tuple[Path, dict[str, Any]], +) -> None: + rec, doc = session + info = ffprobe("-show_chapters", "-show_streams", str(rec / f"{SESSION}.mkv")) + starts = [float(c["start_time"]) for c in info["chapters"]] + expected = [e["t"] for e in doc["events"] if not e.get("before_recording")] + assert len(starts) == len(expected) + for got, want in zip(starts, expected, strict=True): + assert got == pytest.approx(want, abs=1e-2) + video = next(s for s in info["streams"] if s["codec_type"] == "video") + assert video["codec_name"] == "h264" + assert float(video["start_time"]) == pytest.approx(START, abs=1e-2) + assert not (rec / f"{SESSION}.ffmeta").exists() + + +def test_first_run_game_start_before_the_recorder_is_flagged(session: tuple[Path, dict[str, Any]]) -> None: + start = next(e for e in session[1]["events"] if e["kind"] == "game_start") + assert start.get("before_recording") + + +def test_finalize_is_repeatable(session: tuple[Path, dict[str, Any]]) -> None: + rec, doc = session + again = finalize.finalize(rec / f"{SESSION}.rec.json", MOMENT_MAP) + assert [e["t"] for e in again["events"]] == [e["t"] for e in doc["events"]] + + +def test_a_file_without_a_duration_is_scanned_whole(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + video = tmp_path / "open.mkv" + make_video(video) + real = finalize._ffprobe + + def fake(*args: str) -> dict[str, Any]: + return {"format": {"start_time": "0.5"}} if "format=start_time,duration" in args else real(*args) + + monkeypatch.setattr(finalize, "_ffprobe", fake) + start, duration = finalize.probe_span(video) + assert start == 0.5 + assert duration > 3.0 + + +def test_a_file_without_packets_has_no_duration(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + def fake(*args: str) -> dict[str, Any]: + return {"format": {"start_time": "0.5"}} if "format=start_time,duration" in args else {"packets": [{}]} + + monkeypatch.setattr(finalize, "_ffprobe", fake) + assert finalize.probe_span(tmp_path / "x.mkv") == (0.5, 0.0) + + +def test_a_first_frame_for_a_missing_part_is_ignored(tmp_path: Path) -> None: + (tmp_path / "feedback.jsonl").write_text(json.dumps(sync_entry()) + "\n", encoding="utf-8") + make_video(tmp_path / f"{SESSION}.mkv") + meta = write_meta(tmp_path, tmp_path, {"first_frame_unix": {"gone.mkv": T0}}) + assert finalize.finalize(meta, MOMENT_MAP)["video"]["start_s"] == pytest.approx(START, abs=1e-2) + + +def test_an_unaligned_gsr_part_is_moved_once_and_stays_put(tmp_path: Path) -> None: + """A gsr part starts at 0; rec.json says when its first frame was, finalize puts it on the t0 timeline.""" + cmd = ["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=30", "-t", "2"] + subprocess.run([*cmd, "-c:v", "libx264", str(tmp_path / f"{SESSION}.mkv")], check=True, timeout=30) + (tmp_path / "feedback.jsonl").write_text(json.dumps(sync_entry()) + "\n", encoding="utf-8") + meta = write_meta(tmp_path, tmp_path, {"first_frame_unix": {f"{SESSION}.mkv": T0 + 2.0}}) + for _ in range(2): + doc = finalize.finalize(meta, MOMENT_MAP) + assert doc["video"]["start_s"] == pytest.approx(2.0, abs=1e-2) diff --git a/game_recording/game_recording/tests/test_gsr.py b/game_recording/game_recording/tests/test_gsr.py new file mode 100644 index 0000000..8ba3e61 --- /dev/null +++ b/game_recording/game_recording/tests/test_gsr.py @@ -0,0 +1,87 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""gpu-screen-recorder backend: argv, backend choice, first-frame time.""" + +from itertools import pairwise +from pathlib import Path + +import pytest + +from game_recording import encoder, gsr +from game_recording.tests.test_helpers import CONFIG + +SPEC = encoder.Spec(window_id=39845893, fps=30, t0_unix=1_800_000_000.5, out="/o/s.mkv", audio="default") +TS_TEXT = "monotonic_microsec\trealtime_microsec\n8935499369\t1794415951373572\n" +ENV_NAME = "DEMO_RECORDER_BACKEND" + + +def _pairs(spec: encoder.Spec = SPEC) -> list[tuple[str, str]]: + return list(pairwise(gsr.command(spec))) + + +def test_records_the_window_on_the_gpu_at_the_fps() -> None: + cmd = gsr.command(SPEC) + assert cmd[0] == "gpu-screen-recorder" + pairs = _pairs() + for pair in (("-w", "39845893"), ("-f", "30"), ("-k", "h264"), ("-c", "mkv"), ("-o", "/o/s.mkv")): + assert pair in pairs + assert "x11grab" not in cmd + + +def test_the_first_frame_time_is_written_for_the_timeline() -> None: + assert ("-write-first-frame-ts", "yes") in _pairs() + + +def test_constant_frame_rate_without_the_cursor_and_quiet() -> None: + pairs = _pairs() + for pair in (("-fm", "cfr"), ("-cursor", "no"), ("-v", "no"), ("-q", "very_high")): + assert pair in pairs + + +def test_audio_is_the_default_output_as_opus_because_flac_is_disabled_in_gsr() -> None: + pairs = _pairs() + assert ("-a", "default_output") in pairs + assert ("-ac", "opus") in pairs + + +def test_a_named_pulse_source_is_a_device() -> None: + spec = encoder.Spec(window_id=1, fps=30, t0_unix=0.0, out="/o/s.mkv", audio="sink.monitor") + assert ("-a", "device:sink.monitor") in _pairs(spec) + + +def test_ts_file_sits_next_to_the_video_with_an_extra_extension() -> None: + assert gsr.ts_path("/o/s.mkv") == Path("/o/s.mkv.ts") + + +def test_the_realtime_column_is_the_unix_time() -> None: + assert gsr.parse_first_frame(TS_TEXT) == pytest.approx(1794415951.373572, abs=1e-6) + + +@pytest.mark.parametrize( + "text", + ["", "monotonic_microsec\trealtime_microsec\n", TS_TEXT.rstrip("\n"), "x\ty\n1\t2z\n", "1\t2\t3\n"], +) +def test_a_missing_or_partial_file_is_not_a_time_yet(text: str) -> None: + assert gsr.parse_first_frame(text) is None + + +def test_the_measured_capture_latency_is_between_two_and_three_frames_at_30_fps() -> None: + assert 2 / 30 < gsr.CAPTURE_LATENCY_S < 3 / 30 + + +@pytest.mark.parametrize( + ("env", "audio", "want", "have_gsr"), + [ + ({}, "default", "gsr", True), + ({}, "default", "x11grab", False), + ({ENV_NAME: "x11grab"}, "default", "x11grab", True), + ({ENV_NAME: "gsr"}, "default", "gsr", True), + ({}, "lavfi", "x11grab", True), + ], +) +def test_backend_choice(env: dict[str, str], audio: str, want: str, *, have_gsr: bool) -> None: + assert gsr.pick_backend(env, audio, CONFIG, have_gsr=have_gsr) == want + + +def test_the_env_name_comes_from_the_config_prefix() -> None: + assert CONFIG.env_name(gsr.BACKEND_SUFFIX) == ENV_NAME + assert gsr.pick_backend({"OTHER_RECORDER_BACKEND": "x11grab"}, "default", CONFIG, have_gsr=True) == "gsr" diff --git a/game_recording/game_recording/tests/test_gsr_start.py b/game_recording/game_recording/tests/test_gsr_start.py new file mode 100644 index 0000000..970fa7c --- /dev/null +++ b/game_recording/game_recording/tests/test_gsr_start.py @@ -0,0 +1,108 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""gpu-screen-recorder: starting it, and moving a finished part onto the timeline.""" + +from itertools import pairwise +import os +from pathlib import Path +import stat +import subprocess +import sys + +import pytest + +from game_recording import encoder, gsr + +FAKE_GSR = """#!{python} +import os, pathlib, signal, sys, time +args = sys.argv[1:] +out = args[args.index("-o") + 1] +mode = os.environ.get("FAKE_GSR", "ok") +if mode == "die": + sys.exit(1) +if mode == "ok": + pathlib.Path(out + ".ts").write_text("monotonic_microsec\\trealtime_microsec\\n5\\t1800000007250000\\n") +signal.signal(signal.SIGINT, lambda *_: sys.exit(0)) +time.sleep(60) +""" + + +def install_fake(folder: Path) -> None: + path = folder / "gpu-screen-recorder" + path.write_text(FAKE_GSR.format(python=sys.executable), encoding="utf-8") + path.chmod(path.stat().st_mode | stat.S_IXUSR) + + +def _start( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, mode: str, wait_s: float = 5.0 +) -> tuple[subprocess.Popen[bytes], float] | None: + install_fake(tmp_path) + monkeypatch.setenv("PATH", f"{tmp_path}{os.pathsep}{os.environ['PATH']}") + monkeypatch.setenv("FAKE_GSR", mode) + spec = encoder.Spec(window_id=1, fps=30, t0_unix=0.0, out=str(tmp_path / "s.mkv")) + with (tmp_path / "log").open("ab") as log: + return gsr.start(spec, log, "0", wait_s=wait_s) + + +def test_available_follows_the_path(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("PATH", str(tmp_path)) + assert not gsr.available() + install_fake(tmp_path) + assert gsr.available() + + +def test_returns_the_running_recorder_and_its_first_frame_unix_time( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + started = _start(tmp_path, monkeypatch, "ok") + assert started is not None + proc, first = started + try: + assert proc.poll() is None + # gsr stamps its first frame after the screen showed it (measured on :0, bench.sh sync) + assert first == pytest.approx(1_800_000_007.25 - gsr.CAPTURE_LATENCY_S, abs=1e-6) + finally: + proc.kill() + proc.wait() + + +def test_a_recorder_that_dies_at_start_is_a_failure(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + assert _start(tmp_path, monkeypatch, "die") is None + + +def test_a_recorder_that_never_stamps_its_first_frame_is_killed_and_a_failure( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + assert _start(tmp_path, monkeypatch, "nots", wait_s=1.0) is None + assert not (tmp_path / "s.mkv.ts").exists() + + +def test_delta_puts_the_first_frame_on_the_t0_timeline() -> None: + assert gsr.shift_delta(first_unix=107.0, t0=100.0, first_stamp=0.0) == pytest.approx(7.0) + assert gsr.shift_delta(first_unix=107.0, t0=100.0, first_stamp=0.25) == pytest.approx(6.75) + + +def test_shift_command_copies_streams_and_moves_the_stamps() -> None: + cmd = gsr.shift_command(Path("/o/a.mkv"), Path("/o/a.shift.mkv"), 7.0) + pairs = list(pairwise(cmd)) + assert ("-output_ts_offset", "7.000000") in pairs + assert ("-c", "copy") in pairs + assert "-copyts" in cmd + assert cmd[-1] == "/o/a.shift.mkv" + + +def test_align_moves_a_real_file_onto_the_timeline(tmp_path: Path) -> None: + video = tmp_path / "p.mkv" + cmd = ["ffmpeg", "-v", "error", "-y", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=30", "-t", "1"] + subprocess.run([*cmd, "-c:v", "libx264", str(video)], check=True, timeout=30) + assert gsr.video_start(video) == pytest.approx(0.0, abs=1e-3) + gsr.align(video, first_unix=107.0, t0=100.0) + assert gsr.video_start(video) == pytest.approx(7.0, abs=1e-2) + assert [p.name for p in tmp_path.iterdir()] == ["p.mkv"] + + +def test_a_file_already_on_the_timeline_is_left_alone(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + video = tmp_path / "p.mkv" + video.write_bytes(b"not a video") # would make ffprobe/ffmpeg fail if touched + monkeypatch.setattr(gsr, "video_start", lambda _video: 0.0005) + gsr.align(video, first_unix=100.0, t0=100.0) + assert video.read_bytes() == b"not a video" diff --git a/game_recording/game_recording/tests/test_helpers.py b/game_recording/game_recording/tests/test_helpers.py new file mode 100644 index 0000000..060e674 --- /dev/null +++ b/game_recording/game_recording/tests/test_helpers.py @@ -0,0 +1,48 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Shared fixtures for the recorder tests: a made-up game's config and telemetry lines.""" + +from game_recording import moments +from game_recording.config import COMMON_DIRECT, Config, Moment, MomentMap, Row + +SESSION = "1794396071-c6df" +# The game's clock: `ms` counts from the log's creation; the sync entry pairs one +# ms value with the unix time of that same instant. +SYNC_UNIX = 1_800_000_000.250 +SYNC_MS = 200 + +MOMENT_MAP = MomentMap( + direct={ + **COMMON_DIRECT, + "buy": ("buff", "bought", "cost"), + "game_start": ("loadout", "cost", "men", "seed"), + "command": ("order", "pos"), + "lab_result": ("wins", "runs", "mean_seconds"), + "reset_progress": ("files",), + }, + passthrough_prefixes=("evt_", "milestone"), +) +CONFIG = Config(binaries_dir="data/demo_binaries", env_prefix="DEMO", moments=MOMENT_MAP) + + +def entry(event: str, ms: int, seq: int = 0, **fields: object) -> Row: + """One telemetry line as the game writes it.""" + return { + "event": event, + "session": SESSION, + "seq": seq, + "ms": ms, + "frame": ms // 16, + "time": "2026-11-11T12:00:00", + **fields, + } + + +def sync_entry() -> Row: + """The line that pairs the game clock with unix time.""" + return entry("recording_sync", SYNC_MS, 1, unix=SYNC_UNIX) + + +def classify_one(row: Row, moment_map: MomentMap = MOMENT_MAP) -> Moment | None: + """The one moment a line becomes, None when it is not one.""" + found = moments.classify([row], moment_map) + return found[0] if found else None diff --git a/game_recording/game_recording/tests/test_library.py b/game_recording/game_recording/tests/test_library.py new file mode 100644 index 0000000..ba98b06 --- /dev/null +++ b/game_recording/game_recording/tests/test_library.py @@ -0,0 +1,145 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Listing and opening a recording at a moment.""" + +import json +import os +from pathlib import Path +import subprocess +from typing import Any + +import pytest + +from game_recording import library + +DOC: dict[str, Any] = { + "session": "s1", + "tag": "v02", + "video": {"start_s": 0.052, "duration_s": 100.0, "end_s": 100.052, "file": "s1.mkv"}, + "sync": {"approx": False}, + "events": [ + {"t": -2.0, "label": "game_start watch", "before_recording": True}, + {"t": 1.0, "label": "pause_open"}, + {"t": 42.5, "label": "command rally"}, + {"t": 400.0, "label": "late", "after_recording": True}, + ], +} + +PARTED: dict[str, Any] = { + "session": "s2", + "video": { + "start_s": 0.05, + "duration_s": 30.0, + "end_s": 30.05, + "file": "s2.mkv", + "parts": [ + {"file": "s2.mkv", "start_s": 0.05, "duration_s": 10.0}, + {"file": "s2.part2.mkv", "start_s": 20.0, "duration_s": 10.0}, + ], + }, + "sync": {"approx": False}, + "events": [ + {"t": 5.0, "label": "a", "file": "s2.mkv"}, + {"t": 15.0, "label": "in the gap", "in_gap": True}, + {"t": 21.0, "label": "b", "file": "s2.part2.mkv"}, + ], +} + + +def write(folder: Path, name: str, doc: dict[str, Any], mtime: int) -> Path: + path = folder / f"{name}.events.json" + path.write_text(json.dumps(doc), encoding="utf-8") + os.utime(path, (mtime, mtime)) + return path + + +@pytest.mark.parametrize(("seconds", "text"), [(75.5, "01:15.500"), (0.0, "00:00.000"), (-1.5, "-00:01.500")]) +def test_stamp_is_minutes_seconds_millis(seconds: float, text: str) -> None: + assert library.stamp(seconds) == text + + +def test_table_numbers_only_moments_inside_the_file() -> None: + lines = library.table(DOC).splitlines() + assert lines[0] == "s1 v02 01:40.000 s1.mkv" + assert len(lines) == 3 + assert lines[1] == " 1 00:01.000 pause_open" + assert lines[2] == " 2 00:42.500 command rally" + + +def test_open_seeks_a_little_before_the_moment_on_the_files_own_timeline() -> None: + cmd = library.open_command(DOC, Path("/rec"), 2) + assert cmd[0] == "mpv" + assert "--rebase-start-time=no" in cmd + assert "--start=39.500" in cmd + assert cmd[-1] == "/rec/s1.mkv" + + +def test_open_never_seeks_before_the_first_frame() -> None: + assert "--start=0.052" in library.open_command(DOC, Path("/rec"), 1) + + +def test_open_without_a_number_plays_from_the_start() -> None: + assert not any(a.startswith("--start") for a in library.open_command(DOC, Path("/rec"), None)) + + +def test_open_of_a_missing_moment_says_the_range() -> None: + with pytest.raises(IndexError, match=r"no moment 9 \(1\.\.2\)"): + library.open_command(DOC, Path("/rec"), 9) + + +def test_gap_moments_are_not_listed() -> None: + assert [e["label"] for e in library.shown(PARTED)] == ["a", "b"] + + +def test_open_uses_the_part_that_holds_the_moment() -> None: + cmd = library.open_command(PARTED, Path("/rec"), 2) + assert cmd[-1] == "/rec/s2.part2.mkv" + assert "--start=20.000" in cmd, "clamped to the part's first frame, not 18.0" + + +def test_the_table_says_the_window_went_away() -> None: + text = library.table(PARTED) + assert "2 parts" in text + assert "[s2.part2.mkv]" in text + + +def test_sessions_are_listed_newest_first_and_load_back(tmp_path: Path) -> None: + old = write(tmp_path, "old", {**DOC, "session": "old"}, 1_000) + new = write(tmp_path, "new", {**DOC, "session": "new"}, 2_000) + assert library.sessions(tmp_path) == [new, old] + assert library.load(new)["session"] == "new" + + +def test_the_listing_has_one_line_per_session(tmp_path: Path) -> None: + write(tmp_path, "a", DOC, 1_000) + assert library.listing(tmp_path) == "s1 01:40.000 2 moments v02" + assert library.listing(tmp_path / "none") == "" + + +def test_a_png_and_an_approximate_sync_show_in_the_table() -> None: + doc = {**DOC, "sync": {"approx": True}, "events": [{"t": -1.5, "label": "x", "png": "x.png"}]} + lines = library.table(doc).splitlines() + assert "+-1 s" in lines[1] + assert lines[2] == " 1 -00:01.500 x x.png" + + +def test_open_moment_prints_the_command_on_a_dry_run(capsys: pytest.CaptureFixture[str]) -> None: + assert library.open_moment(DOC, Path("/rec"), 2, dry_run=True) == 0 + assert capsys.readouterr().out.split() == [ + "mpv", + "--rebase-start-time=no", + "--force-window=yes", + "--start=39.500", + "/rec/s1.mkv", + ] + + +def test_open_moment_runs_the_player_and_returns_its_exit_code(monkeypatch: pytest.MonkeyPatch) -> None: + seen: list[list[str]] = [] + + def call(cmd: list[str]) -> int: + seen.append(cmd) + return 3 + + monkeypatch.setattr(subprocess, "call", call) + assert library.open_moment(DOC, Path("/rec"), None, dry_run=False) == 3 + assert seen[0][-1] == "/rec/s1.mkv" diff --git a/game_recording/game_recording/tests/test_moment_map.py b/game_recording/game_recording/tests/test_moment_map.py new file mode 100644 index 0000000..96906b7 --- /dev/null +++ b/game_recording/game_recording/tests/test_moment_map.py @@ -0,0 +1,138 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""A second, made-up game adopts the package by configuration alone.""" + +import pytest + +from game_recording import moments +from game_recording.config import COMMON_DIRECT, Config, Moment, MomentMap, Row +from game_recording.tests.test_helpers import entry + + +def boss_hit(row: Row) -> Moment | None: + if row.get("event") != "boss_hit": + return None + return moments.moment(row, "boss", "hit the boss", dmg=row.get("dmg")) + + +def never(_row: Row) -> Moment | None: + return None + + +def hijack_buy(row: Row) -> Moment | None: + return moments.moment(row, "hijacked", "custom") if row.get("event") == "buy" else None + + +def second(_row: Row) -> Moment | None: + return moments.moment({"ms": 1}, "second", "second") + + +def ammo_low(rows: list[Row]) -> list[Moment]: + return [moments.moment(r, "ammo_low", "ammo low") for r in rows if r.get("ammo", 99) < 5] + + +def classify(rows: list[Row], moment_map: MomentMap) -> list[Moment]: + return moments.classify(rows, moment_map) + + +def test_default_map_has_only_the_common_events() -> None: + plain = MomentMap() + assert plain.direct is COMMON_DIRECT + assert plain.passthrough_prefixes == () + assert classify([entry("hub_open", 1)], plain)[0]["kind"] == "hub_open" + assert classify([entry("buy", 1)], plain) == [] + + +def test_a_game_adds_its_own_direct_events() -> None: + game = MomentMap(direct={**COMMON_DIRECT, "loot": ("item",)}) + found = classify([entry("loot", 5, 1, game="g", item="axe")], game) + assert found[0]["label"] == "loot g axe" + assert found[0]["item"] == "axe" + + +def test_empty_passthrough_prefixes_pass_nothing_through() -> None: + assert classify([entry("evt_x", 1), entry("", 2)], MomentMap()) == [] + + +def test_set_passthrough_prefixes_pass_matching_events() -> None: + game = MomentMap(passthrough_prefixes=("quest_",)) + found = classify([entry("quest_done", 1, 1, stars=3), entry("evt_x", 2)], game) + assert [m["kind"] for m in found] == ["quest_done"] + assert found[0]["stars"] == 3 + + +def test_game_end_fields_are_configurable() -> None: + game = MomentMap(game_end_fields=("score",)) + m = classify([entry("game_end", 1, 1, outcome="win", score=9, elapsed_s=4)], game)[0] + assert m["score"] == 9 + assert "elapsed_s" not in m + assert m["label"] == "game_end win" + + +def test_game_end_without_an_outcome_has_a_bare_label() -> None: + assert classify([entry("game_end", 1)], MomentMap())[0]["label"] == "game_end" + + +def test_error_kinds_are_configurable() -> None: + game = MomentMap(error_kinds=frozenset({"stderr"})) + assert classify([entry("engine_error", 1, kind="stderr", message="x")], game)[0]["error_kind"] == "stderr" + assert classify([entry("engine_error", 1, kind="script_error", message="x")], game) == [] + + +def test_hitch_merge_s_override_changes_the_burst() -> None: + rows = [entry("hitch", 1000, 1, dur_ms=1), entry("hitch", 1500, 2, dur_ms=2)] + assert len(moments.derive(rows, MomentMap(hitch_merge_s=0.1))) == 2 + assert len(moments.derive(rows, MomentMap(hitch_merge_s=5.0))) == 1 + assert MomentMap().hitch_merge_s == 2.0 + + +def test_classifier_hook_makes_a_moment_the_built_ins_do_not() -> None: + game = MomentMap(classifiers=(boss_hit,)) + found = classify([entry("boss_hit", 7, 1, dmg=12), entry("hub_open", 8, 2)], game) + assert [m["kind"] for m in found] == ["boss", "hub_open"] + assert found[0]["dmg"] == 12 + + +def test_classifier_hooks_run_before_built_ins() -> None: + game = MomentMap(direct={**COMMON_DIRECT, "buy": ()}, classifiers=(hijack_buy,)) + assert classify([entry("buy", 1)], game)[0]["kind"] == "hijacked" + + +def test_first_non_none_classifier_wins() -> None: + game = MomentMap(classifiers=(never, boss_hit, second)) + assert classify([entry("boss_hit", 1, 1)], game)[0]["kind"] == "boss" + assert classify([entry("other", 1, 1)], game)[0]["kind"] == "second" + + +def test_session_rule_hook_moments_join_the_hitch_burst() -> None: + game = MomentMap(session_rules=(ammo_low,)) + rows = [entry("hitch", 1000, 1, dur_ms=5), entry("shot", 2000, 2, ammo=3), entry("shot", 3000, 3, ammo=40)] + found = moments.derive(rows, game) + assert [m["kind"] for m in found] == ["hitch", "ammo_low"] + assert moments.derive(rows, MomentMap()) == found[:1] + + +def test_moment_builder_fields() -> None: + row = entry("evt_x", 42, 9, game="g") + m = moments.moment(row, "kind", "label", extra=1) + assert m == {"kind": "kind", "label": "label", "event": "evt_x", "seq": 9, "ms": 42, "game": "g", "extra": 1} + + +def test_moment_builder_omits_an_empty_game() -> None: + assert "game" not in moments.moment(entry("evt_x", 42), "k", "l") + + +def test_config_env_names_use_the_prefix() -> None: + cfg = Config(binaries_dir="b", env_prefix="ZED") + assert cfg.env_name("NO_RECORD") == "ZED_NO_RECORD" + assert cfg.blocking_flags == ("ZED_NO_RECORD",) + assert cfg.moments == MomentMap() + + +def test_extra_blocking_flags_follow_the_no_record_flag() -> None: + cfg = Config(binaries_dir="b", env_prefix="ZED", extra_blocking_flags=("ZED_CI",)) + assert cfg.blocking_flags == ("ZED_NO_RECORD", "ZED_CI") + + +@pytest.mark.parametrize(("override", "expected"), [("", "ZED_BINARIES"), ("MY_BINS", "MY_BINS")]) +def test_binaries_var_defaults_and_overrides(override: str, expected: str) -> None: + assert Config(binaries_dir="b", env_prefix="ZED", binaries_env=override).binaries_var == expected diff --git a/game_recording/game_recording/tests/test_policy.py b/game_recording/game_recording/tests/test_policy.py new file mode 100644 index 0000000..781de77 --- /dev/null +++ b/game_recording/game_recording/tests/test_policy.py @@ -0,0 +1,108 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""When a run is recorded (a person's dev play) and when never (bots, tests, headless).""" + +import pytest + +from game_recording import policy +from game_recording.config import Config +from game_recording.tests.test_helpers import CONFIG + +LIVE = {"DISPLAY": ":0"} +DEV = ["godot", "--", "--dev"] + + +def test_dev_run_is_recorded() -> None: + decision = policy.decide(["godot", "--path", "/r", "--", "--dev"], LIVE, CONFIG) + assert decision.record, decision.reason + assert decision.reason == "dev play" + + +def test_exported_dev_build_is_recorded() -> None: + assert policy.decide(["/b/game.x86_64", "--", "--dev", "--dev-tag=v01"], LIVE, CONFIG).record + + +@pytest.mark.parametrize("args", [["godot", "--"], ["godot", "--", "--no-dev", "--dev"]]) +def test_no_dev_flag_means_no_recording(args: list[str]) -> None: + decision = policy.decide(args, LIVE, CONFIG) + assert not decision.record + assert decision.reason == "not a --dev run" + + +@pytest.mark.parametrize( + "marker", ["--autodrive=watch", "--result-file=/t/r", "--expect-window=1280x800", "--save-dir=/t"] +) +def test_each_bot_marker_blocks(marker: str) -> None: + decision = policy.decide(["godot", "--", "--dev", marker], LIVE, CONFIG) + assert not decision.record + assert marker in decision.reason + + +@pytest.mark.parametrize( + "engine", + [["--headless"], ["--audio-driver", "Dummy"], ["--display-driver", "headless"]], +) +def test_headless_and_muted_engine_runs_block(engine: list[str]) -> None: + decision = policy.decide(["godot", *engine, "--", "--dev"], LIVE, CONFIG) + assert not decision.record + assert decision.reason.startswith("headless or muted run") + + +def test_engine_flags_after_the_double_dash_are_the_games_own() -> None: + assert policy.decide(["godot", "--", "--dev", "--headless"], LIVE, CONFIG).record + + +def test_engine_flag_without_a_value_or_with_another_value_does_not_block() -> None: + assert policy.decide(["godot", "--audio-driver", "--dev"], LIVE, CONFIG).record + assert policy.decide(["godot", "--audio-driver", "Pulse", "--dev"], LIVE, CONFIG).record + assert policy.decide(["godot", "--audio-driver"], LIVE, CONFIG).reason == "not a --dev run" + + +def test_no_display_blocks() -> None: + decision = policy.decide(DEV, {}, CONFIG) + assert not decision.record + assert decision.reason == "no DISPLAY" + + +@pytest.mark.parametrize( + ("env", "reason"), + [ + ({"DEMO_NO_RECORD": "1"}, "DEMO_NO_RECORD=1"), + ({"DEMO_FEEDBACK_DIR": "/t"}, "DEMO_FEEDBACK_DIR is set"), + ], +) +def test_env_opt_outs_block(env: dict[str, str], reason: str) -> None: + decision = policy.decide(DEV, {**LIVE, **env}, CONFIG) + assert not decision.record + assert decision.reason == reason + + +def test_flag_set_to_zero_is_off() -> None: + assert policy.decide(DEV, {**LIVE, "DEMO_NO_RECORD": "0"}, CONFIG).record + + +def test_another_games_env_prefix_does_not_block() -> None: + assert policy.decide(DEV, {**LIVE, "OTHER_NO_RECORD": "1"}, CONFIG).record + + +def test_extra_blocking_flags_of_the_config_block() -> None: + config = Config(binaries_dir="b", env_prefix="DEMO", extra_blocking_flags=("DEMO_CI",)) + assert policy.decide(DEV, {**LIVE, "DEMO_CI": "1"}, config).reason == "DEMO_CI=1" + + +def test_force_overrides_bot_rules_but_not_a_missing_display() -> None: + args = ["godot", "--audio-driver", "Dummy", "--", "--dev", "--autodrive", "--save-dir=/t"] + forced = policy.decide(args, LIVE, CONFIG, force=True) + assert forced.record + assert forced.reason == "forced" + assert not policy.decide(args, {}, CONFIG, force=True).record + + +def test_the_reason_names_the_blocker() -> None: + assert "--autodrive" in policy.decide(["godot", "--", "--dev", "--autodrive"], LIVE, CONFIG).reason + + +def test_session_and_feedback_dir_come_from_the_args() -> None: + args = ["godot", "--", "--dev", "--session-id=abc", "--feedback-dir=/fb"] + assert policy.arg_value(args, "--session-id=") == "abc" + assert policy.arg_value(args, "--feedback-dir=") == "/fb" + assert policy.arg_value(args, "--nope=") == "" diff --git a/game_recording/game_recording/tests/test_procs.py b/game_recording/game_recording/tests/test_procs.py new file mode 100644 index 0000000..17938a1 --- /dev/null +++ b/game_recording/game_recording/tests/test_procs.py @@ -0,0 +1,63 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Starting external programs: path lookup, nice wrapper, spawn with log, env and detach.""" + +import os +from pathlib import Path +import shutil +import sys + +import pytest + +from game_recording import procs + + +def test_program_is_the_full_path_when_installed() -> None: + found = shutil.which("sh") + assert found is not None + assert procs.program("sh") == found + + +def test_program_keeps_the_bare_name_when_missing() -> None: + assert procs.program("no-such-program-xyz") == "no-such-program-xyz" + + +def test_niced_prefixes_the_resolved_nice() -> None: + argv = procs.niced("7", ["ffmpeg", "-i", "x"]) + assert argv[1:] == ["-n", "7", "ffmpeg", "-i", "x"] + assert Path(argv[0]).name == "nice" + assert Path(argv[0]).is_absolute() + + +def test_spawn_runs_the_child_without_a_log() -> None: + proc = procs.spawn([sys.executable, "-c", "pass"]) + assert proc.wait(timeout=20) == 0 + + +def test_spawn_sends_output_to_the_log(tmp_path: Path) -> None: + out = tmp_path / "out.log" + with out.open("wb") as log: + proc = procs.spawn([sys.executable, "-c", "import sys; print('o'); print('e', file=sys.stderr)"], log=log) + assert proc.wait(timeout=20) == 0 + assert sorted(out.read_text().split()) == ["e", "o"] + + +def test_spawn_passes_the_given_env(tmp_path: Path) -> None: + out = tmp_path / "env.log" + code = "import os; print(os.environ['SPAWN_PROBE'], 'PATH' in os.environ)" + with out.open("wb") as log: + proc = procs.spawn([sys.executable, "-c", code], env={"SPAWN_PROBE": "yes"}, log=log) + assert proc.wait(timeout=20) == 0 + assert out.read_text().split() == ["yes", "False"] + + +@pytest.mark.parametrize("detach", [False, True]) +def test_spawn_detach_gives_the_child_its_own_session(tmp_path: Path, *, detach: bool) -> None: + out = tmp_path / "sid.log" + with out.open("wb") as log: + proc = procs.spawn( + [sys.executable, "-c", "import os; print(os.getsid(0), os.getpid())"], log=log, detach=detach + ) + assert proc.wait(timeout=20) == 0 + sid, pid = (int(x) for x in out.read_text().split()) + assert (sid == pid) is detach + assert (sid == os.getsid(0)) is (not detach) diff --git a/game_recording/game_recording/tests/test_record.py b/game_recording/game_recording/tests/test_record.py new file mode 100644 index 0000000..5966fee --- /dev/null +++ b/game_recording/game_recording/tests/test_record.py @@ -0,0 +1,139 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The CLI: each subcommand reaches the right module with the right arguments.""" + +import json +from pathlib import Path +from typing import Any + +import pytest + +from game_recording import cli, finalize, library, supervise +from game_recording.options import RunOptions +from game_recording.tests.test_helpers import CONFIG + +DOC = { + "session": "s1", + "tag": "v02", + "video": {"start_s": 0.0, "duration_s": 10.0, "end_s": 10.0, "file": "s1.mkv"}, + "sync": {"approx": False}, + "events": [{"t": 1.0, "label": "pause_open"}], +} + + +@pytest.fixture +def rec_dir(tmp_path: Path) -> Path: + (tmp_path / "s1.events.json").write_text(json.dumps(DOC), encoding="utf-8") + return tmp_path + + +def run_cli(capsys: pytest.CaptureFixture[str], *argv: str) -> tuple[int, str]: + code = cli.main(list(argv), CONFIG) + return code, capsys.readouterr().out + + +def test_wrap_passes_the_command_after_the_double_dash_and_the_options( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + calls: list[tuple[Any, ...]] = [] + + def fake_run(command: list[str], config: object, options: RunOptions) -> int: + calls.append((command, config, options)) + return 4 + + monkeypatch.setattr(supervise, "run", fake_run) + code, _ = run_cli(capsys, "wrap", "--force", "--fps", "60", "--max-seconds", "2", "--", "godot", "--dev") + assert code == 4 + assert calls == [ + (["godot", "--dev"], CONFIG, RunOptions(force=True, session="", audio="default", fps=60, max_seconds=2.0)) + ] + + +def test_wrap_without_a_double_dash_takes_the_command_as_given( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + calls: list[tuple[list[str], RunOptions]] = [] + + def fake_run(command: list[str], config: object, options: RunOptions) -> int: + calls.append((command, options)) + return 0 + + monkeypatch.setattr(supervise, "run", fake_run) + run_cli(capsys, "wrap", "--session", "x", "--audio", "lavfi", "game") + assert calls[0][0] == ["game"] + assert calls[0][1].session == "x" + assert calls[0][1].audio == "lavfi" + + +def test_finalize_rebuilds_the_events_of_one_rec_json( + monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + calls: list[tuple[Path, object]] = [] + monkeypatch.setattr(finalize, "finalize", lambda meta, moment_map: calls.append((meta, moment_map))) + assert run_cli(capsys, "finalize", "/r/s1.rec.json")[0] == 0 + assert calls == [(Path("/r/s1.rec.json"), CONFIG.moments)] + + +def test_list_prints_the_library(rec_dir: Path, capsys: pytest.CaptureFixture[str]) -> None: + assert run_cli(capsys, "list", "--dir", str(rec_dir)) == (0, "s1 00:10.000 1 moments v02\n") + + +def test_latest_prints_the_moments_of_the_session(rec_dir: Path, capsys: pytest.CaptureFixture[str]) -> None: + code, out = run_cli(capsys, "latest", "--dir", str(rec_dir), "--session", "s1") + assert code == 0 + assert "pause_open" in out + + +def test_open_dry_run_prints_the_player_command(rec_dir: Path, capsys: pytest.CaptureFixture[str]) -> None: + code, out = run_cli(capsys, "open", "1", "--dir", str(rec_dir), "--dry-run") + assert code == 0 + assert out.startswith("mpv ") + assert out.strip().endswith("s1.mkv") + + +def test_open_without_dry_run_reaches_the_player( + rec_dir: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + seen: list[tuple[int | None, bool]] = [] + + def fake_open(doc: object, directory: Path, n: int | None, *, dry_run: bool) -> int: + seen.append((n, dry_run)) + return 3 + + monkeypatch.setattr(library, "open_moment", fake_open) + assert run_cli(capsys, "open", "--dir", str(rec_dir))[0] == 3 + assert seen == [(None, False)] + + +def test_open_of_a_missing_moment_exits_with_the_message(rec_dir: Path, capsys: pytest.CaptureFixture[str]) -> None: + with pytest.raises(SystemExit) as raised: + run_cli(capsys, "open", "9", "--dir", str(rec_dir), "--dry-run") + assert str(raised.value) == "no moment 9 (1..1)" + + +def test_a_session_that_matches_nothing_exits_with_the_message( + rec_dir: Path, capsys: pytest.CaptureFixture[str] +) -> None: + with pytest.raises(SystemExit) as raised: + run_cli(capsys, "latest", "--dir", str(rec_dir), "--session", "zzz") + assert str(raised.value) == f"no recordings in {rec_dir}" + + +def test_the_default_dir_is_the_feedback_recordings_folder(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("DEMO_BINARIES", "/b") + assert cli.default_dir(CONFIG) == Path("/b/feedback/recordings") + + +def test_list_without_dir_uses_the_default_folder( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + rec = tmp_path / "feedback" / "recordings" + rec.mkdir(parents=True) + (rec / "s1.events.json").write_text(json.dumps(DOC), encoding="utf-8") + monkeypatch.setenv("DEMO_BINARIES", str(tmp_path)) + assert run_cli(capsys, "list") == (0, "s1 00:10.000 1 moments v02\n") + + +def test_a_missing_subcommand_is_a_usage_error() -> None: + with pytest.raises(SystemExit) as raised: + cli.main([], CONFIG) + assert raised.value.code == 2 diff --git a/game_recording/game_recording/tests/test_recorder.py b/game_recording/game_recording/tests/test_recorder.py new file mode 100644 index 0000000..7ba6c94 --- /dev/null +++ b/game_recording/game_recording/tests/test_recorder.py @@ -0,0 +1,234 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""The launcher's Recorder: backend choice, fallback to x11grab, the t0 of a gsr part, 30 fps.""" + +from collections.abc import Callable, Iterator +import json +import os +import signal +import stat +import sys +import time +from typing import TYPE_CHECKING +from unittest import mock + +import pytest + +from game_recording import gsr, procs, recorder, window +from game_recording.options import DEFAULT_FPS, RecorderOptions +from game_recording.supervise import recording_paths + +FAKE_GSR = """#!{python} +import os, pathlib, signal, sys, time +args = sys.argv[1:] +out = args[args.index("-o") + 1] +mode = os.environ.get("FAKE_GSR", "ok") +if mode == "die": + sys.exit(1) +if mode == "ok": + pathlib.Path(out + ".ts").write_text("monotonic_microsec\\trealtime_microsec\\n5\\t1800000007250000\\n") +signal.signal(signal.SIGINT, lambda *_: sys.exit(0)) +time.sleep(60) +""" +FAKE_FFMPEG = """#!{python} +import signal, sys, time +signal.signal(signal.SIGINT, lambda *_: sys.exit(0)) +time.sleep(60) +""" +if TYPE_CHECKING: + from pathlib import Path + +WIN = window.Window(id=0x4200007, width=1280, height=800) +GSR_T0 = 1_800_000_007.25 - gsr.CAPTURE_LATENCY_S # FAKE_GSR's first-frame stamp, less the latency + +Make = Callable[[str], recorder.Recorder] + + +def install_fake(folder: Path, name: str, body: str) -> None: + path = folder / name + path.write_text(body.format(python=sys.executable), encoding="utf-8") + path.chmod(path.stat().st_mode | stat.S_IXUSR) + + +class Rig: + """A recorder factory over fake gsr and ffmpeg binaries; every recorder it made is stopped at the end.""" + + def __init__(self, root: Path) -> None: + self.feedback = root / "fb" + self.paths = recording_paths(self.feedback, "s1") + self.made: list[recorder.Recorder] = [] + + def make(self, backend: str) -> recorder.Recorder: + opts = RecorderOptions( + session="s1", feedback=self.feedback, fps=30, audio="default", nice="0", + usable=frozenset({"libx264"}), backend=backend, + ) # fmt: skip + rec = recorder.Recorder(mock.Mock(), self.paths, opts) + self.made.append(rec) + return rec + + def meta(self) -> dict[str, object]: + data: dict[str, object] = json.loads(self.paths["meta"].read_text(encoding="utf-8")) + return data + + def running_gsr(self) -> recorder.Recorder: + rec = self.make("gsr") + rec._start_part(WIN) + return rec + + +@pytest.fixture +def rig(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[Rig]: + bin_dir = tmp_path / "bin" + bin_dir.mkdir() + install_fake(bin_dir, "gpu-screen-recorder", FAKE_GSR) + install_fake(bin_dir, "ffmpeg", FAKE_FFMPEG) + monkeypatch.setenv("PATH", f"{bin_dir}{os.pathsep}{os.environ['PATH']}") + monkeypatch.setenv("DISPLAY", ":9") + monkeypatch.setenv("FAKE_GSR", "ok") + made = Rig(tmp_path) + yield made + for rec in made.made: + if rec.proc is not None and rec.proc.poll() is None: + rec.proc.send_signal(signal.SIGKILL) + rec.proc.wait() + + +def stop_quietly(rec: recorder.Recorder) -> None: + """Stops the recorder with the alignment (ffprobe on a fake file) faked out.""" + with mock.patch.object(gsr, "align"): + rec.stop() + + +def test_defaults_are_30_fps() -> None: + assert DEFAULT_FPS == 30 + + +def test_gsr_part_puts_t0_on_its_first_frame(rig: Rig) -> None: + rec = rig.running_gsr() + stop_quietly(rec) + assert rec.backend == "gsr" + assert rec.t0 == pytest.approx(GSR_T0, abs=1e-6) + meta = rig.meta() + assert meta["t0_unix"] == pytest.approx(GSR_T0, abs=1e-6) + assert meta["backend"] == "gsr" + assert meta["parts"] == ["s1.mkv"] + assert meta["fps"] == 30 + + +def test_a_gsr_that_fails_at_start_falls_back_to_x11grab_with_a_fresh_t0( + rig: Rig, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setenv("FAKE_GSR", "die") + rec = rig.make("gsr") + before = time.time() + rec._start_part(WIN) + stop_quietly(rec) + assert rec.backend == "x11grab" + assert rec.t0 >= before + assert rec.t0 < time.time() + 1 + meta = rig.meta() + assert meta["backend"] == "x11grab" + assert meta["parts"] == ["s1.mkv"] + + +def test_gsr_keeps_recording_while_its_window_is_shown(rig: Rig) -> None: + rec = rig.running_gsr() + proc = rec.proc + with mock.patch.object(window, "largest", return_value=WIN): + assert rec.step() + assert rec.proc is proc + stop_quietly(rec) + + +def test_gsr_part_ends_when_its_window_is_hidden_so_a_new_part_follows(rig: Rig) -> None: + # gsr neither exits nor resumes after an unmap (bench.sh gap on :0): the recorder ends the part itself + rec = rig.running_gsr() + proc = rec.proc + assert proc is not None + with ( + mock.patch.object(window, "largest", return_value=None), + mock.patch.object(window, "wait_stable", return_value=None), + ): + assert not rec.step() + assert proc.poll() is not None, "the hidden window's gsr was stopped" + assert rec.proc is None + assert len(rec.gsr.pending) == 1 + stop_quietly(rec) + + +def test_x11grab_backend_never_starts_gsr(rig: Rig) -> None: + rec = rig.make("x11grab") + with mock.patch.object(gsr, "start") as started: + rec._start_part(WIN) + started.assert_not_called() + assert rig.meta()["backend"] == "x11grab" + stop_quietly(rec) + + +def test_stopping_a_gsr_part_aligns_a_later_part_to_the_t0_timeline(rig: Rig) -> None: + rec = rig.make("gsr") + rec.t0 = GSR_T0 - 10.0 + rec.parts = ["s1.mkv"] # a second part: its first frame is 10 s after t0 + with mock.patch.object(gsr, "align") as align: + rec._start_part(WIN) + rec.stop() + align.assert_called_once_with(rig.paths["dir"] / "s1.part2.mkv", first_unix=GSR_T0, t0=GSR_T0 - 10.0) + assert rec.t0 == GSR_T0 - 10.0 + + +def test_a_part_that_ended_during_play_is_aligned_only_after_the_game_exits(rig: Rig) -> None: + rec = rig.make("gsr") + with mock.patch.object(gsr, "align") as align: + rec._start_part(WIN) + assert rec.proc is not None + rec.proc.send_signal(signal.SIGINT) + rec.proc.wait(timeout=5) + rec.close_part() # the window went away; the game still runs + align.assert_not_called() + rec.stop() # the game exited + align.assert_called_once() + + +def test_every_pending_part_is_aligned_once_and_its_first_frame_is_in_rec_json(rig: Rig) -> None: + rec = rig.make("gsr") + with mock.patch.object(gsr, "align") as align: + for _ in range(2): + rec._start_part(WIN) + assert rec.proc is not None + rec.proc.send_signal(signal.SIGINT) + rec.proc.wait(timeout=5) + rec.close_part() + rec.stop() + assert align.call_count == 2 + assert rig.meta()["first_frame_unix"] == {"s1.mkv": GSR_T0, "s1.part2.mkv": GSR_T0} + + +def test_a_dead_proc_still_closes_once(rig: Rig) -> None: + rec = rig.make("gsr") + with mock.patch.object(gsr, "align") as align: + rec._start_part(WIN) + rec.stop() + rec.stop() + assert align.call_count == 1 + + +def test_stop_recorder_returns_true_for_an_already_ended_process() -> None: + done = procs.spawn([sys.executable, "-c", "pass"]) + done.wait(timeout=20) + assert recorder.stop_recorder(done) + + +def test_stop_recorder_interrupts_a_running_process_and_reports_a_clean_finish() -> None: + code = "import signal, sys, time; signal.signal(signal.SIGINT, lambda *_: sys.exit(0)); time.sleep(60)" + proc = procs.spawn([sys.executable, "-c", code]) + time.sleep(0.5) # let the child install its handler + assert recorder.stop_recorder(proc, grace_s=10.0) + assert proc.returncode == 0 + + +def test_stop_recorder_kills_a_process_that_ignores_sigint() -> None: + code = "import signal, time; signal.signal(signal.SIGINT, signal.SIG_IGN); time.sleep(60)" + proc = procs.spawn([sys.executable, "-c", code]) + time.sleep(0.5) + assert not recorder.stop_recorder(proc, grace_s=0.2) + assert proc.returncode == -signal.SIGKILL diff --git a/game_recording/game_recording/tests/test_recorder_steps.py b/game_recording/game_recording/tests/test_recorder_steps.py new file mode 100644 index 0000000..fb3dfe8 --- /dev/null +++ b/game_recording/game_recording/tests/test_recorder_steps.py @@ -0,0 +1,231 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Recorder.step and its failure paths, with the process and window layers faked.""" + +from collections.abc import Callable +from pathlib import Path +import subprocess +from types import SimpleNamespace +from unittest import mock + +import pytest + +from game_recording import gsr, procs, recorder, window +from game_recording.options import RecorderOptions +from game_recording.supervise import recording_paths +from game_recording.tests.test_helpers import SESSION + +WIN = window.Window(id=0x4200007, width=1280, height=800) +OTHER = window.Window(id=0x4200008, width=800, height=600) +MakeRecorder = Callable[..., recorder.Recorder] + + +def proc_of(rec: recorder.Recorder) -> object: + """The recorder's process, read without the type narrowing of an earlier assignment.""" + return rec.proc + + +def open_part_of(rec: recorder.Recorder) -> object: + return rec.gsr.open_part + + +def alive() -> mock.Mock: + return mock.Mock(poll=mock.Mock(return_value=None)) + + +def running_ffmpeg() -> mock.Mock: + """An ffmpeg that is still up when the settle wait ends.""" + proc = mock.Mock() + proc.wait.side_effect = subprocess.TimeoutExpired("ffmpeg", recorder.X11GRAB_SETTLE_S) + return proc + + +@pytest.fixture(autouse=True) +def display(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("DISPLAY", ":9") + + +@pytest.fixture +def make(tmp_path: Path) -> MakeRecorder: + def build(backend: str = "x11grab", usable: frozenset[str] = frozenset({"libx264"})) -> recorder.Recorder: + opts = RecorderOptions( + session=SESSION, feedback=tmp_path, fps=30, audio="default", nice="0", usable=usable, backend=backend + ) + return recorder.Recorder(alive(), recording_paths(tmp_path, SESSION), opts) + + return build + + +def test_an_off_recorder_does_nothing(make: MakeRecorder) -> None: + rec = make() + rec.off = True + assert not rec.step() + + +def test_a_running_x11grab_part_keeps_going(make: MakeRecorder) -> None: + rec = make() + rec.proc = alive() + assert rec.step() + + +def test_no_window_at_the_start_turns_recording_off(make: MakeRecorder, capsys: pytest.CaptureFixture[str]) -> None: + rec = make() + with mock.patch.object(window, "wait_stable", return_value=None): + assert not rec.step() + assert rec.off + assert "no game window found" in capsys.readouterr().err + + +def test_a_window_that_never_returns_leaves_the_session_on(make: MakeRecorder) -> None: + rec = make() + rec.parts = [f"{SESSION}.mkv"] + with mock.patch.object(window, "wait_stable", return_value=None): + assert not rec.step() + assert not rec.off + + +def test_a_found_window_starts_a_part(make: MakeRecorder, capsys: pytest.CaptureFixture[str]) -> None: + rec = make() + proc = running_ffmpeg() + with ( + mock.patch.object(window, "wait_stable", return_value=WIN), + mock.patch.object(procs, "spawn", return_value=proc) as spawn, + ): + assert rec.step() + argv = spawn.call_args.args[0] + assert Path(argv[0]).name == "nice" + assert argv[1:3] == ["-n", "0"] + assert spawn.call_args.kwargs["detach"] is True + proc.wait.assert_called_once_with(timeout=recorder.X11GRAB_SETTLE_S) + assert rec.parts == [f"{SESSION}.mkv"] + assert "recording 1280x800 with libx264" in capsys.readouterr().err + + +def test_a_later_x11grab_part_keeps_the_first_parts_t0(make: MakeRecorder) -> None: + rec = make() + rec.parts, rec.t0 = [f"{SESSION}.mkv"], 123.0 + with mock.patch.object(procs, "spawn", return_value=running_ffmpeg()): + rec._start_part(WIN) + assert (rec.t0, rec.parts) == (123.0, [f"{SESSION}.mkv", f"{SESSION}.part2.mkv"]) + + +def test_no_usable_encoder_stops_recording_with_a_message( + make: MakeRecorder, capsys: pytest.CaptureFixture[str] +) -> None: + rec = make(usable=frozenset()) + with mock.patch.object(window, "wait_stable", return_value=WIN): + assert not rec.step() + assert rec.off + assert "not recording: neither h264_nvenc nor libx264" in capsys.readouterr().err + + +def test_a_program_that_cannot_start_stops_recording(make: MakeRecorder, capsys: pytest.CaptureFixture[str]) -> None: + rec = make() + with ( + mock.patch.object(window, "wait_stable", return_value=WIN), + mock.patch.object(procs, "spawn", side_effect=FileNotFoundError("ffmpeg")), + ): + assert not rec.step() + assert rec.off + assert "not recording: ffmpeg" in capsys.readouterr().err + + +def test_an_ffmpeg_that_dies_at_start_is_retried_then_given_up_on( + make: MakeRecorder, capsys: pytest.CaptureFixture[str] +) -> None: + rec = make() + with mock.patch.object(procs, "spawn", return_value=mock.Mock()): + for attempt in range(1, recorder.MAX_QUICK_DEATHS + 1): + rec._start_part(WIN) + assert (rec.proc, rec.parts, rec.quick_deaths) == (None, [], attempt) + assert rec.off == (attempt == recorder.MAX_QUICK_DEATHS) + assert "ffmpeg died at start" in capsys.readouterr().err + + +def test_a_dead_window_part_is_replaced_by_waiting_for_the_next( + make: MakeRecorder, capsys: pytest.CaptureFixture[str] +) -> None: + rec = make() + rec.parts = [f"{SESSION}.mkv"] + rec.proc = mock.Mock(poll=mock.Mock(return_value=0)) + with mock.patch.object(window, "wait_stable", return_value=None): + assert not rec.step() + assert proc_of(rec) is None + assert "the window went away" in capsys.readouterr().err + + +def test_a_gsr_part_whose_window_changed_is_stopped(make: MakeRecorder) -> None: + rec = make("gsr") + rec.proc = alive() + rec.win = WIN + rec.gsr.open_part = (Path(f"{SESSION}.mkv"), 1.0) + with ( + mock.patch.object(window, "largest", return_value=OTHER), + mock.patch.object(recorder, "stop_recorder", return_value=True) as stopped, + mock.patch.object(window, "wait_stable", return_value=None), + ): + assert not rec.step() + stopped.assert_called_once() + assert open_part_of(rec) is None + assert len(rec.gsr.pending) == 1 + + +def test_a_recorder_that_died_is_not_recording(make: MakeRecorder) -> None: + rec = make() + rec.proc = mock.Mock(poll=mock.Mock(return_value=1)) + assert not rec._still_recording() + + +def test_without_an_open_gsr_part_nothing_is_counted(make: MakeRecorder) -> None: + rec = make("gsr") + rec._count_short_life() + assert rec.gsr.short_lives == 0 + + +def test_short_lived_gsr_parts_switch_the_session_to_x11grab( + make: MakeRecorder, capsys: pytest.CaptureFixture[str] +) -> None: + rec = make("gsr") + rec.gsr.open_part = (Path(f"{SESSION}.mkv"), 1.0) + with mock.patch.object(recorder, "time", SimpleNamespace(monotonic=lambda: 100.0)): + rec.gsr.started = 99.0 + for _ in range(recorder.MAX_QUICK_DEATHS): + assert rec.backend == "gsr" + rec._count_short_life() + assert rec.backend == "x11grab" + assert "keeps stopping" in capsys.readouterr().err + + +def test_a_long_gsr_part_resets_the_count(make: MakeRecorder) -> None: + rec = make("gsr") + rec.gsr.open_part = (Path(f"{SESSION}.mkv"), 1.0) + rec.gsr.short_lives = 2 + with mock.patch.object(recorder, "time", SimpleNamespace(monotonic=lambda: 100.0)): + rec.gsr.started = 100.0 - recorder.SHORT_LIFE_S + rec._count_short_life() + assert (rec.gsr.short_lives, rec.backend) == (0, "gsr") + + +def test_an_alignment_that_fails_is_reported_not_raised(make: MakeRecorder, capsys: pytest.CaptureFixture[str]) -> None: + rec = make("gsr") + rec.gsr.pending = [(Path(f"/v/{SESSION}.part2.mkv"), 5.0)] + with mock.patch.object(gsr, "align", side_effect=OSError("disk full")): + rec._align_pending() + assert f"could not align {SESSION}.part2.mkv to the timeline: disk full" in capsys.readouterr().err + assert rec.gsr.pending == [] + + +@pytest.mark.parametrize(("finalized", "said"), [(False, "ignored SIGINT"), (True, "")]) +def test_stop_says_so_only_when_the_recorder_had_to_be_killed( + make: MakeRecorder, capsys: pytest.CaptureFixture[str], *, finalized: bool, said: str +) -> None: + rec = make("gsr") + rec.proc = mock.Mock() + with mock.patch.object(recorder, "stop_recorder", return_value=finalized): + rec.stop() + err = capsys.readouterr().err + assert (said in err) if said else err == "" + + +def test_nothing_running_stops_quietly(make: MakeRecorder, capsys: pytest.CaptureFixture[str]) -> None: + make("gsr").stop() + assert capsys.readouterr().err == "" diff --git a/game_recording/game_recording/tests/test_supervise.py b/game_recording/game_recording/tests/test_supervise.py new file mode 100644 index 0000000..2174d1d --- /dev/null +++ b/game_recording/game_recording/tests/test_supervise.py @@ -0,0 +1,153 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Launcher logic: session ids, folders, a recorder that finalizes on exit, process helpers.""" + +from pathlib import Path +import signal +import subprocess +import sys +import textwrap +import time +from unittest import mock + +import pytest + +from game_recording import procs, supervise +from game_recording.recorder import stop_recorder +from game_recording.tests.test_helpers import CONFIG + + +@pytest.mark.parametrize( + ("command", "expected"), + [ + (["godot", "--path", "/r", "--", "--dev"], ["godot", "--path", "/r", "--", "--dev", "--session-id=s1"]), + (["/b/game"], ["/b/game", "--", "--session-id=s1"]), + ], +) +def test_session_id_is_added_after_the_double_dash(command: list[str], expected: list[str]) -> None: + assert supervise.with_session(command, "s1") == expected + + +def test_an_existing_session_id_wins() -> None: + cmd = ["godot", "--", "--dev", "--session-id=mine"] + assert supervise.with_session(cmd, "s1") == cmd + assert supervise.session_of(cmd) == "mine" + assert supervise.session_of(["godot"]) == "" + + +def test_feedback_dir_comes_from_the_args_then_the_binaries_dir() -> None: + assert supervise.feedback_dir(["g", "--", "--feedback-dir=/fb"], {}, CONFIG) == Path("/fb") + assert supervise.feedback_dir(["g", "--", "--dev"], {"DEMO_BINARIES": "/bin"}, CONFIG) == Path("/bin/feedback") + assert supervise.feedback_dir(["g"], {"HOME": "/h"}, CONFIG) == Path("/h/data/demo_binaries/feedback") + + +def test_feedback_dir_without_home_falls_back_to_the_users_home() -> None: + assert supervise.feedback_dir(["g"], {}, CONFIG) == Path.home() / "data/demo_binaries/feedback" + + +def test_recordings_land_next_to_the_feedback_log() -> None: + paths = supervise.recording_paths(Path("/fb"), "s1") + assert paths["video"] == Path("/fb/recordings/s1.mkv") + assert paths["events"] == Path("/fb/recordings/s1.events.json") + assert paths["meta"] == Path("/fb/recordings/s1.rec.json") + assert paths["log"] == Path("/fb/recordings/s1.ffmpeg.log") + + +def test_a_new_session_id_is_a_timestamp_and_four_hex_digits() -> None: + assert supervise.new_session().count("-run-") == 1 + assert supervise.new_session().split("-run-")[1].isalnum() + assert len(supervise.new_session().rsplit("-", 1)[1]) == 4 + + +def test_the_recorder_nice_comes_from_the_environment() -> None: + assert supervise._nice({}, CONFIG) == "10" + assert supervise._nice({"DEMO_RECORDER_NICE": "0"}, CONFIG) == "0" + + +def fake_recorder(tmp_path: Path, *, handle_sigint: bool) -> subprocess.Popen[bytes]: + done = tmp_path / "finalized" + body = f""" + import signal, sys, time, pathlib + def stop(*_): + pathlib.Path({str(done)!r}).write_text("trailer written") + sys.exit(0) + signal.signal(signal.SIGINT, {"stop" if handle_sigint else "signal.SIG_IGN"}) + print("up", flush=True) + time.sleep(60) + """ + proc = subprocess.Popen([sys.executable, "-c", textwrap.dedent(body)], stdout=subprocess.PIPE) + assert proc.stdout is not None + proc.stdout.readline() # wait until the handlers are installed + return proc + + +def test_sigint_lets_the_recorder_finalize_its_file(tmp_path: Path) -> None: + proc = fake_recorder(tmp_path, handle_sigint=True) + with proc: + assert stop_recorder(proc, grace_s=5.0) + assert (tmp_path / "finalized").read_text() == "trailer written" + assert proc.poll() is not None + + +def test_a_recorder_that_ignores_sigint_is_killed_after_the_grace(tmp_path: Path) -> None: + proc = fake_recorder(tmp_path, handle_sigint=False) + with proc: + started = time.monotonic() + assert not stop_recorder(proc, grace_s=0.5) + assert time.monotonic() - started < 5.0 + assert proc.poll() is not None + + +def test_a_recorder_that_already_exited_is_fine() -> None: + with subprocess.Popen([sys.executable, "-c", "pass"]) as proc: + proc.wait() + assert stop_recorder(proc, grace_s=1.0) + + +def test_a_blocked_run_just_runs_the_command_and_keeps_its_exit_code() -> None: + env = {"DISPLAY": ":0"} + code = supervise.run([sys.executable, "-c", "import sys; sys.exit(7)", "--autodrive"], CONFIG, env=env) + assert code == 7 + + +def test_run_defaults_to_the_process_environment(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("DISPLAY", raising=False) + assert supervise.run([sys.executable, "-c", "import sys; sys.exit(3)"], CONFIG) == 3 + + +def test_stop_game_terminates_a_running_game_only() -> None: + running = mock.Mock() + running.poll.return_value = None + supervise._stop_game(running) + running.send_signal.assert_called_once_with(signal.SIGTERM) + done = mock.Mock() + done.poll.return_value = 0 + supervise._stop_game(done) + done.send_signal.assert_not_called() + + +def test_program_resolves_a_path_or_keeps_the_bare_name() -> None: + assert Path(procs.program("sh")).is_absolute() + assert procs.program("no-such-program-xyz") == "no-such-program-xyz" + + +def test_niced_puts_the_command_under_nice() -> None: + argv = procs.niced("7", ["ffmpeg", "-i", "x"]) + assert Path(argv[0]).name == "nice" + assert argv[1:] == ["-n", "7", "ffmpeg", "-i", "x"] + + +def test_spawn_passes_the_environment_log_and_session(tmp_path: Path) -> None: + out = tmp_path / "out.log" + with out.open("wb") as log: + child = procs.spawn( + [sys.executable, "-c", "import os; print(os.environ['SPAWN_X'], os.getsid(0) == os.getpid())"], + env={"SPAWN_X": "yes"}, + log=log, + detach=True, + ) + assert child.wait() == 0 + assert out.read_text().split() == ["yes", "True"] + + +def test_spawn_without_an_environment_inherits_ours() -> None: + assert procs.spawn([sys.executable, "-c", "pass"]).wait() == 0 diff --git a/game_recording/game_recording/tests/test_supervise_run.py b/game_recording/game_recording/tests/test_supervise_run.py new file mode 100644 index 0000000..188f06e --- /dev/null +++ b/game_recording/game_recording/tests/test_supervise_run.py @@ -0,0 +1,232 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""supervise.run on the recording path: a real child game, the recorder and encoder probe faked.""" + +import re +import signal +import subprocess +import sys +import time +from typing import TYPE_CHECKING, Any, ClassVar +from unittest import mock + +import pytest + +from game_recording import encoder, finalize, gsr, procs, supervise, timeline +from game_recording.options import RecorderOptions, RunOptions +from game_recording.tests.test_helpers import CONFIG, SESSION + +if TYPE_CHECKING: + from collections.abc import Iterator + from pathlib import Path + +REAL_SLEEP = time.sleep + + +def game(seconds: float, code: int = 0) -> list[str]: + return [sys.executable, "-c", f"import sys, time; time.sleep({seconds}); sys.exit({code})", "--dev"] + + +class FakeRecorder: + """Stands in for Recorder: records what the launcher asked of it.""" + + instances: ClassVar[list[FakeRecorder]] = [] + gives_up: ClassVar[bool] = False + + def __init__(self, game: object, paths: dict[str, Path], opts: RecorderOptions) -> None: + self.paths = paths + self.opts = opts + self.off = FakeRecorder.gives_up + self.steps = 0 + self.stopped = False + FakeRecorder.instances.append(self) + + def step(self) -> bool: + self.steps += 1 + return True + + def stop(self) -> None: + self.stopped = True + + +@pytest.fixture +def env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Iterator[dict[str, str]]: + FakeRecorder.instances = [] + FakeRecorder.gives_up = False + saved = {sig: signal.getsignal(sig) for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP)} + monkeypatch.setattr(supervise, "Recorder", FakeRecorder) + monkeypatch.setattr(encoder, "probe_usable", lambda: {"libx264"}) + monkeypatch.setattr(gsr, "available", lambda: False) + monkeypatch.setattr(time, "sleep", lambda _s: REAL_SLEEP(0.02)) + yield {"DISPLAY": ":9", "HOME": "/nonexistent", "DEMO_BINARIES": str(tmp_path)} + for sig, handler in saved.items(): + signal.signal(sig, handler) + + +def no_finish(monkeypatch: pytest.MonkeyPatch) -> list[dict[str, Path]]: + calls: list[dict[str, Path]] = [] + monkeypatch.setattr(supervise, "_finish", lambda paths, config: calls.append(paths)) + return calls + + +def test_a_recorded_run_steps_the_recorder_and_returns_the_games_exit_code( + env: dict[str, str], monkeypatch: pytest.MonkeyPatch +) -> None: + finished = no_finish(monkeypatch) + code = supervise.run(game(0.3, 5), CONFIG, RunOptions(force=True, session=SESSION, fps=60), env) + assert code == 5 + rec = FakeRecorder.instances[0] + assert rec.stopped + assert rec.steps > 0 + assert (rec.opts.usable, rec.opts.backend, rec.opts.fps, rec.opts.session) == ( + frozenset({"libx264"}), + "x11grab", + 60, + SESSION, + ) + assert rec.opts.nice == "10" + assert rec.paths["meta"].name == f"{SESSION}.rec.json" + assert finished == [rec.paths] + + +def test_the_recorder_nice_value_comes_from_the_given_env(env: dict[str, str], monkeypatch: pytest.MonkeyPatch) -> None: + no_finish(monkeypatch) + supervise.run(game(0.1), CONFIG, RunOptions(force=True), {**env, "DEMO_RECORDER_NICE": "0"}) + assert FakeRecorder.instances[0].opts.nice == "0" + + +def test_the_game_gets_a_session_and_feedback_dir_in_its_args( + env: dict[str, str], tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + no_finish(monkeypatch) + spawned: list[list[str]] = [] + real_spawn = procs.spawn + + def spy(argv: list[str], *, env: dict[str, str]) -> subprocess.Popen[bytes]: + spawned.append(list(argv)) + child: subprocess.Popen[bytes] = real_spawn(argv, env=env) + return child + + monkeypatch.setattr(procs, "spawn", spy) + supervise.run(game(0.1), CONFIG, RunOptions(force=True), env) + argv = spawned[0] + assert argv[-2] == f"--session-id={supervise.session_of(argv)}" + assert argv[-1] == f"--feedback-dir={tmp_path}/feedback" + assert re.fullmatch(r"\d+-run-[0-9a-f]{4}", supervise.session_of(argv)) + + +def test_max_seconds_stops_the_game_once_recording_began(env: dict[str, str], monkeypatch: pytest.MonkeyPatch) -> None: + no_finish(monkeypatch) + options = RunOptions(force=True, session=SESSION, max_seconds=0.1) + assert supervise.run(game(30), CONFIG, options, env) == -signal.SIGTERM + + +def test_a_recorder_that_gave_up_still_starts_the_timer(env: dict[str, str], monkeypatch: pytest.MonkeyPatch) -> None: + no_finish(monkeypatch) + FakeRecorder.gives_up = True + monkeypatch.setattr(FakeRecorder, "step", lambda _self: False) + options = RunOptions(force=True, session=SESSION, max_seconds=0.1) + assert supervise.run(game(30), CONFIG, options, env) == -signal.SIGTERM + + +def test_the_timer_waits_while_the_recorder_is_still_starting( + env: dict[str, str], monkeypatch: pytest.MonkeyPatch +) -> None: + no_finish(monkeypatch) + steps = iter([False, False, True]) + monkeypatch.setattr(FakeRecorder, "step", lambda _self: next(steps, True)) + options = RunOptions(force=True, session=SESSION, max_seconds=0.1) + assert supervise.run(game(30), CONFIG, options, env) == -signal.SIGTERM + + +def test_a_blocked_run_says_why_it_is_not_recorded( + capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch +) -> None: + FakeRecorder.instances = [] + monkeypatch.setattr(supervise, "Recorder", FakeRecorder) + code = supervise.run([sys.executable, "-c", "pass"], CONFIG, env={"DISPLAY": ":9", "DEMO_NO_RECORD": "1"}) + assert code == 0 + assert "off (DEMO_NO_RECORD=1)" in capsys.readouterr().err + assert not FakeRecorder.instances + + +def test_a_forwarded_hangup_reaches_the_game() -> None: + saved = {sig: signal.getsignal(sig) for sig in (signal.SIGINT, signal.SIGTERM, signal.SIGHUP)} + try: + proc = mock.Mock() + supervise._forward_signals(proc) + handler = signal.getsignal(signal.SIGHUP) + assert callable(handler) + handler(signal.SIGHUP, None) + proc.send_signal.assert_called_once_with(signal.SIGHUP) + assert signal.getsignal(signal.SIGINT) == signal.SIG_IGN + finally: + for sig, handler in saved.items(): + signal.signal(sig, handler) + + +def doc(parts: int) -> dict[str, Any]: + events = [{"t": 1.0}, {"t": 2.0, "before_recording": True}] + video = {"file": f"{SESSION}.mkv", "duration_s": 61.4, "parts": [{}] * parts} + return {"events": events, "video": video} + + +@pytest.fixture +def meta_paths(tmp_path: Path) -> dict[str, Path]: + paths = supervise.recording_paths(tmp_path, SESSION) + paths["dir"].mkdir(parents=True) + paths["meta"].write_text("{}") + return paths + + +def test_without_a_rec_json_there_is_nothing_to_finish(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None: + supervise._finish(supervise.recording_paths(tmp_path, SESSION), CONFIG) + assert capsys.readouterr().err == "" + + +@pytest.mark.parametrize(("parts", "tail"), [(1, "1 moments)"), (2, "1 moments, 2 parts)")]) +def test_the_summary_line_counts_the_moments_inside_the_video( + meta_paths: dict[str, Path], + parts: int, + tail: str, + capsys: pytest.CaptureFixture[str], + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr(finalize, "finalize", lambda _meta, _map: doc(parts)) + supervise._finish(meta_paths, CONFIG) + err = capsys.readouterr().err + assert f"{SESSION}.mkv (61 s, {tail}" in err + + +@pytest.mark.parametrize( + "error", + [ + KeyError("video"), + OSError("disk"), + ValueError("bad json"), + TypeError("shape"), + subprocess.SubprocessError("ffmpeg"), + timeline.NoSyncError("no sync"), + ], +) +def test_a_finalize_error_is_reported_not_raised( + meta_paths: dict[str, Path], + error: Exception, + capsys: pytest.CaptureFixture[str], + monkeypatch: pytest.MonkeyPatch, +) -> None: + def boom(_meta: Path, _map: object) -> None: + raise error + + monkeypatch.setattr(finalize, "finalize", boom) + supervise._finish(meta_paths, CONFIG) + assert f"could not build the timeline: {error}" in capsys.readouterr().err + + +def test_an_unexpected_error_is_not_swallowed(meta_paths: dict[str, Path], monkeypatch: pytest.MonkeyPatch) -> None: + def boom(_meta: Path, _map: object) -> None: + msg = "bug" + raise RuntimeError(msg) + + monkeypatch.setattr(finalize, "finalize", boom) + with pytest.raises(RuntimeError, match="bug"): + supervise._finish(meta_paths, CONFIG) diff --git a/game_recording/game_recording/tests/test_timeline.py b/game_recording/game_recording/tests/test_timeline.py new file mode 100644 index 0000000..28fe527 --- /dev/null +++ b/game_recording/game_recording/tests/test_timeline.py @@ -0,0 +1,232 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Timeline builder: telemetry entries -> recording timestamps.""" + +import json +from typing import TYPE_CHECKING, Any + +import pytest + +from game_recording import timeline +from game_recording.tests.test_helpers import MOMENT_MAP, SESSION, SYNC_MS, SYNC_UNIX, entry, sync_entry + +if TYPE_CHECKING: + from pathlib import Path + + from game_recording.config import Moment, Row + +# The recorder started 0.5 s after the game's sync instant (t0 on the unix clock). +T0 = SYNC_UNIX + 0.5 +VIDEO_START_S = 0.052 +ORDER: dict[str, Any] = {"order": "rally", "pos": [1, 2]} + + +def one_part(start_s: float = VIDEO_START_S, duration_s: float = 600.0) -> list[dict[str, Any]]: + """A single unnamed part file, as one uninterrupted recording.""" + return [{"file": "", "start_s": start_s, "duration_s": duration_s}] + + +def build(entries: list[Row], parts: list[dict[str, Any]] | None = None) -> dict[str, Any]: + return timeline.build_events( + entries, + session=SESSION, + t0_unix=T0, + parts=parts or one_part(), + moment_map=MOMENT_MAP, + ) + + +def kinds(doc: dict[str, Any]) -> list[str]: + return [e["kind"] for e in doc["events"]] + + +def command(ms_after_sync: int, seq: int = 2) -> Row: + return entry("command", SYNC_MS + ms_after_sync, seq, **ORDER) + + +def test_event_time_is_sync_unix_plus_ms_delta_minus_t0() -> None: + # event 5000 ms after the sync entry -> unix SYNC+5.0 -> 4.5 s after t0 + doc = build([sync_entry(), command(5000)]) + order = next(e for e in doc["events"] if e["kind"] == "command") + assert order["t"] == pytest.approx(4.5, abs=1e-6) + + +def test_offset_is_exact_to_a_millisecond() -> None: + doc = build([sync_entry(), command(1234)]) + order = next(e for e in doc["events"] if e["kind"] == "command") + assert order["t"] == pytest.approx(1.234 - 0.5, abs=1e-3) + + +def test_unix_us_integer_microseconds_is_read() -> None: + sync = {**sync_entry(), "unix_us": round(SYNC_UNIX * 1_000_000)} + del sync["unix"] + doc = build([sync, command(5000)]) + assert doc["events"][0]["t"] == pytest.approx(4.5, abs=1e-6) + + +def test_sync_entry_itself_is_not_a_moment() -> None: + assert "recording_sync" not in kinds(build([sync_entry()])) + + +def test_events_before_the_recorder_started_are_flagged_not_dropped() -> None: + doc = build([sync_entry(), entry("game_start", SYNC_MS + 100, 2, game="watch")]) + start = next(e for e in doc["events"] if e["kind"] == "game_start") + assert start["t"] < VIDEO_START_S + assert start["before_recording"] + + +def test_events_after_the_file_ended_are_flagged() -> None: + doc = build([sync_entry(), command(700_000)], parts=one_part(duration_s=10.0)) + assert doc["events"][-1]["after_recording"] + + +def test_no_sync_entry_falls_back_to_wall_time_and_says_so() -> None: + doc = build([entry("session_start", 0, 1), entry("command", 3000, 2, **ORDER)]) + assert doc["sync"]["approx"] + assert doc["sync"]["method"] == "session_start.time" + + +@pytest.mark.parametrize( + "rows", + [[], [{"event": "session_start", "ms": 0}], [{"event": "recording_sync", "ms": 5}]], +) +def test_no_usable_sync_entry_is_an_error(rows: list[Row]) -> None: + with pytest.raises(timeline.NoSyncError): + timeline.find_sync(rows) + + +def test_sync_is_a_value_with_keyword_approx() -> None: + sync = timeline.find_sync([sync_entry()]) + assert sync == timeline.Sync(SYNC_UNIX, SYNC_MS, "recording_sync", approx=False) + + +def test_exact_sync_is_not_approx() -> None: + doc = build([sync_entry()]) + assert not doc["sync"]["approx"] + assert doc["sync"]["method"] == "recording_sync" + + +def test_other_sessions_are_ignored() -> None: + other = {**entry("command", 9000, 5, **ORDER), "session": "someone-else"} + assert "command" not in kinds(build([sync_entry(), other])) + + +def test_events_are_sorted_by_time() -> None: + rows = [sync_entry(), entry("pause_open", 9000, 3), entry("pause_close", 4000, 2)] + times = [e["t"] for e in build(rows)["events"]] + assert times == sorted(times) + + +def test_the_tag_comes_from_the_first_entry_that_has_one() -> None: + assert build([sync_entry()])["tag"] == "" + assert build([sync_entry(), entry("hub_open", 300, 2, tag="v01")])["tag"] == "v01" + + +def meta(rows: list[Row]) -> str: + doc = build([sync_entry(), *rows]) + return timeline.chapters_ffmetadata(doc["events"], duration_s=600.0, video_start_s=VIDEO_START_S) + + +def test_events_in_the_same_millisecond_share_one_chapter() -> None: + # the muxer drops a second chapter with the same start + text = meta( + [ + entry("pause_open", SYNC_MS + 10_500, 2), + entry("reset_progress", SYNC_MS + 10_500, 3, files=2), + entry("pause_close", SYNC_MS + 12_500, 4), + ] + ) + assert text.count("[CHAPTER]") == 2 + title = next(line for line in text.splitlines() if line.startswith("title=pause_open")) + assert "reset_progress" in title + + +def test_header_and_chapter_block() -> None: + lines = meta([command(10_500)]).splitlines() + assert lines[0] == ";FFMETADATA1" + assert "[CHAPTER]" in lines + assert "TIMEBASE=1/1000" in lines + assert "START=10000" in lines + assert any(line.startswith("title=") for line in lines) + + +def test_chapters_do_not_overlap_and_end_at_the_next_start() -> None: + lines = meta([command(5500), entry("pause_open", SYNC_MS + 9500, 3)]).splitlines() + starts = [int(x.split("=")[1]) for x in lines if x.startswith("START=")] + ends = [int(x.split("=")[1]) for x in lines if x.startswith("END=")] + assert starts == [5000, 9000] + assert ends[0] == starts[1] - 1 + assert ends[1] >= starts[1] + + +def test_events_outside_the_file_get_no_chapter() -> None: + assert "[CHAPTER]" not in meta([entry("game_start", SYNC_MS + 100, 2, game="watch")]) + + +def test_titles_escape_ffmetadata_specials() -> None: + assert timeline.escape_meta("a=b;c#d\\e\nf") == "a\\=b\\;c\\#d\\\\e\\\nf" + + +def test_load_session_reads_only_that_session(tmp_path: Path) -> None: + other = {**entry("command", 1, 1, **ORDER), "session": "other"} + path = tmp_path / "feedback.jsonl" + rows = [sync_entry(), other, entry("pause_open", 9000, 3)] + path.write_text("\n".join(json.dumps(r) for r in rows) + "\nnot json\n[1]\n", encoding="utf-8") + loaded = timeline.load_session(path, SESSION) + assert [r["event"] for r in loaded] == ["recording_sync", "pause_open"] + + +def test_document_is_json_serialisable() -> None: + doc = build([sync_entry(), command(9000)]) + assert json.loads(json.dumps(doc))["session"] == SESSION + + +# The recorder restarts when the window goes away (workspace switch): one part per run. +PARTS: list[dict[str, Any]] = [ + {"file": "s.mkv", "start_s": 0.05, "duration_s": 10.0}, + {"file": "s.part2.mkv", "start_s": 20.0, "duration_s": 10.0}, +] + + +def parts_doc(ms_after_sync: int) -> dict[str, Any]: + return build([sync_entry(), command(ms_after_sync)], parts=PARTS) + + +def parts_event(t: float) -> Moment: + # t seconds on the file timeline <-> ms in the game clock (t0 is 0.5 s after the sync) + return next(e for e in parts_doc(round((t + 0.5) * 1000))["events"] if e["kind"] == "command") + + +def test_event_in_a_part_names_that_file() -> None: + assert parts_event(5.0)["file"] == "s.mkv" + assert parts_event(25.0)["file"] == "s.part2.mkv" + + +def test_event_between_the_parts_is_flagged_in_gap() -> None: + event = parts_event(15.0) + assert event["in_gap"] + assert "file" not in event + assert not timeline.in_recording(event) + + +def test_before_the_first_and_after_the_last_part() -> None: + assert parts_event(0.0)["before_recording"] + assert parts_event(40.0)["after_recording"] + + +def test_event_in_an_unnamed_part_has_no_file() -> None: + event = build([sync_entry(), command(5000)])["events"][0] + assert "file" not in event + assert timeline.in_recording(event) + + +def test_document_lists_the_parts_and_the_overall_span() -> None: + video = parts_doc(6000)["video"] + assert [p["file"] for p in video["parts"]] == ["s.mkv", "s.part2.mkv"] + assert (video["start_s"], video["end_s"]) == (0.05, 30.0) + + +def test_chapters_are_per_part() -> None: + doc = parts_doc(25_500) + text = timeline.chapters_ffmetadata(doc["events"], 10.0, 20.0, file="s.part2.mkv") + assert "START=25000" in text + assert "[CHAPTER]" not in timeline.chapters_ffmetadata(doc["events"], 10.0, 0.05, file="s.mkv") diff --git a/game_recording/game_recording/tests/test_window.py b/game_recording/game_recording/tests/test_window.py new file mode 100644 index 0000000..8c6de5a --- /dev/null +++ b/game_recording/game_recording/tests/test_window.py @@ -0,0 +1,100 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Finding the game's window by pid: xdotool is faked, the clock is stepped by hand.""" + +from pathlib import Path +import subprocess +from types import SimpleNamespace + +import pytest + +from game_recording import window + +GEOMETRY = { + "1": "WINDOW=1\nX=0\nY=0\nWIDTH=1280\nHEIGHT=800\nSCREEN=0\n", + "2": "WIDTH=32\nHEIGHT=32\n", + "3": "WIDTH=1920\nHEIGHT=1080\n", + "4": "WIDTH=wide\nHEIGHT=1080\n", +} +A = window.Window(1, 1280, 800) +B = window.Window(1, 1920, 1080) + + +def fake_xdotool(*args: str) -> str: + if args[0] == "search": + return "1 2 3 4 5\n" + return GEOMETRY.get(args[-1], "") + + +def test_xdotool_output_is_returned_on_success_and_empty_on_failure(monkeypatch: pytest.MonkeyPatch) -> None: + calls: list[list[str]] = [] + codes = iter([0, 1]) + + def fake_run(argv: list[str], **_kwargs: object) -> subprocess.CompletedProcess[str]: + calls.append(argv) + return subprocess.CompletedProcess(argv, next(codes), stdout="out") + + monkeypatch.setattr("game_recording.window.subprocess", SimpleNamespace(run=fake_run)) + assert window._run("search", "--pid", "7") == "out" + assert Path(calls[0][0]).name == "xdotool" + assert calls[0][1:] == ["search", "--pid", "7"] + assert window._run("search") == "" + + +def test_the_biggest_real_window_wins(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(window, "_run", fake_xdotool) + assert window.largest(7) == window.Window(3, 1920, 1080) + + +def test_helper_and_unreadable_windows_are_not_the_game(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(window, "_run", lambda *_args: "") + assert window.largest(7) is None + + +def test_a_window_with_odd_geometry_text_is_skipped(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr(window, "_run", fake_xdotool) + assert window._geometry("4") is None + assert window._geometry("5") is None + + +def wait( + monkeypatch: pytest.MonkeyPatch, sizes: list[window.Window | None], alive: list[bool] | None = None +) -> window.Window | None: + clock = iter(range(1000)) + sizes_iter = iter(sizes) + sleeps: list[float] = [] + flags = iter(alive or [True] * len(sizes)) + monkeypatch.setattr(window, "largest", lambda _pid: next(sizes_iter)) + monkeypatch.setattr( + "game_recording.window.time", SimpleNamespace(monotonic=lambda: next(clock), sleep=sleeps.append) + ) + result = window.wait_stable(7, 50.0, lambda: next(flags, False)) + assert len(sleeps) <= len(sizes) + return result + + +@pytest.mark.parametrize( + ("sizes", "expected"), + [ + ([A, A, A], A), + ([A, A, B, B, B], B), + ([None, None, A, A, A], A), + ], + ids=["holds-still", "resize-restarts-count", "no-window-yet"], +) +def test_wait_stable_returns_the_settled_window( + monkeypatch: pytest.MonkeyPatch, sizes: list[window.Window | None], expected: window.Window +) -> None: + assert wait(monkeypatch, sizes) == expected + + +def test_a_game_that_exits_ends_the_wait(monkeypatch: pytest.MonkeyPatch) -> None: + assert wait(monkeypatch, [A, A, A], alive=[True, False]) is None + + +def test_the_deadline_ends_the_wait(monkeypatch: pytest.MonkeyPatch) -> None: + clock = iter([0.0, 1.0, 100.0]) + monkeypatch.setattr(window, "largest", lambda _pid: None) + monkeypatch.setattr( + "game_recording.window.time", SimpleNamespace(monotonic=lambda: next(clock), sleep=lambda _s: None) + ) + assert window.wait_stable(7, 5.0, lambda: True) is None diff --git a/game_recording/game_recording/timeline.py b/game_recording/game_recording/timeline.py new file mode 100644 index 0000000..8ed1841 --- /dev/null +++ b/game_recording/game_recording/timeline.py @@ -0,0 +1,150 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Telemetry entries -> timestamps on the recording's timeline (events.json, chapters). + +The game's entries carry `ms` since its log opened. One `recording_sync` entry +pairs an `ms` with the unix time of that same instant, so every entry has an +exact wall-clock time. The recorder's start (`t0_unix`) is on the same unix +clock (ffmpeg's -output_ts_offset puts its media timeline at t0), hence + + t = sync.unix + (entry.ms - sync.ms) / 1000 - t0_unix + +`t` is seconds on the file's media timeline: what mpv shows with +`--rebase-start-time=no` and where MKV chapters sit. The first frame is at +`video_start_s` (a few tens of ms after t0), so earlier events are flagged +`before_recording`, later ones `after_recording`. + +The recorder restarts when the game's window goes away and comes back (an i3 +workspace switch): one part file per run, all on the same t0 timeline. An event +between two parts is `in_gap`; every other recorded event names its `file`. +""" + +from dataclasses import dataclass +from datetime import datetime +import json +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from game_recording import moments + +if TYPE_CHECKING: + from game_recording.config import Moment, MomentMap, Row + + +class NoSyncError(ValueError): + """The session has neither a recording_sync nor a session_start entry.""" + + +@dataclass(frozen=True) +class Sync: + """One pairing of the game clock (`ms`) with unix time.""" + + unix_s: float + ms: int + method: str + approx: bool + + +def load_session(path: Path, session: str) -> list[Row]: + """The entries of one session from a feedback.jsonl (bad lines are skipped).""" + rows: list[Row] = [] + for line in Path(path).read_text(encoding="utf-8").splitlines(): + try: + row = json.loads(line) + except ValueError: + continue + if isinstance(row, dict) and row.get("session") == session: + rows.append(row) + return rows + + +def find_sync(entries: list[Row]) -> Sync: + """The exact pairing from recording_sync, else session_start's whole-second `time`.""" + for row in entries: + if row.get("event") == "recording_sync" and ("unix_us" in row or "unix" in row): + unix = row["unix_us"] / 1_000_000 if "unix_us" in row else float(row["unix"]) + return Sync(unix, int(row["ms"]), "recording_sync", approx=False) + for row in entries: + if row.get("event") == "session_start" and "time" in row: + wall = datetime.fromisoformat(row["time"]).timestamp() + return Sync(wall, int(row.get("ms", 0)), "session_start.time", approx=True) + msg = "no recording_sync or session_start entry" + raise NoSyncError(msg) + + +def _flag(moment: Moment, t: float, parts: list[dict[str, Any]]) -> None: + """Names the part file the moment is in, or says why it is in none.""" + for part in parts: + if part["start_s"] - 1e-6 <= t <= part["start_s"] + part["duration_s"] + 1e-6: + if part["file"]: + moment["file"] = part["file"] + return + if t < parts[0]["start_s"]: + moment["before_recording"] = True + elif t > parts[-1]["start_s"] + parts[-1]["duration_s"]: + moment["after_recording"] = True + else: + moment["in_gap"] = True + + +def build_events( + entries: list[Row], + *, + session: str, + t0_unix: float, + parts: list[dict[str, Any]], + moment_map: MomentMap, +) -> dict[str, Any]: + """The events.json document for one recording (`parts`: file, start_s, duration_s per part file).""" + rows = [r for r in entries if r.get("session") == session] + sync = find_sync(rows) + first, last = parts[0]["start_s"], parts[-1]["start_s"] + parts[-1]["duration_s"] + found = moments.classify(rows, moment_map) + found += moments.derive(rows, moment_map) + events = [] + for moment in found: + t = sync.unix_s + (moment["ms"] - sync.ms) / 1000 - t0_unix + moment["t"] = round(t, 6) + _flag(moment, t, parts) + events.append(moment) + events.sort(key=lambda m: (m["t"], m.get("seq") or 0)) + tag = next((r["tag"] for r in rows if "tag" in r), "") + return { + "session": session, + "tag": tag, + "t0_unix": t0_unix, + "video": {"start_s": first, "duration_s": last - first, "end_s": last, "parts": parts}, + "sync": {"method": sync.method, "approx": sync.approx, "unix": sync.unix_s, "ms": sync.ms}, + "events": events, + } + + +def in_recording(event: Moment) -> bool: + """True when the moment sits inside a recorded part (not before, after or in a gap).""" + return not (event.get("before_recording") or event.get("after_recording") or event.get("in_gap")) + + +def escape_meta(text: str) -> str: + r"""Escape for ffmetadata: backslash-prefix = ; # \ and newline.""" + return "".join("\\" + c if c in "=;#\\\n" else c for c in text) + + +def chapters_ffmetadata(events: list[Moment], duration_s: float, video_start_s: float, file: str | None = None) -> str: + """An ffmetadata file with one chapter per event that lies inside the file (the part `file`).""" + inside = [e for e in events if in_recording(e) and (file is None or e.get("file", file) == file)] + end_ms = round((video_start_s + duration_s) * 1000) + # The muxer drops a second chapter with the same start: events of one millisecond share one. + titles: dict[int, list[str]] = {} + for event in inside: + titles.setdefault(round(event["t"] * 1000), []).append(event["label"]) + starts = list(titles) + lines = [";FFMETADATA1"] + for i, start in enumerate(starts): + nxt = starts[i + 1] - 1 if i + 1 < len(starts) else end_ms + lines += [ + "[CHAPTER]", + "TIMEBASE=1/1000", + f"START={start}", + f"END={max(start, nxt)}", + f"title={escape_meta(' | '.join(titles[start]))}", + ] + return "\n".join(lines) + "\n" diff --git a/game_recording/game_recording/window.py b/game_recording/game_recording/window.py new file mode 100644 index 0000000..ac948ad --- /dev/null +++ b/game_recording/game_recording/window.py @@ -0,0 +1,63 @@ +# Copyright (c) 2026 Krzysztof Rudnicki +"""Finds the game's X11 window by process id (xdotool).""" + +from dataclasses import dataclass +import subprocess +import time +from typing import TYPE_CHECKING + +from game_recording import procs + +if TYPE_CHECKING: + from collections.abc import Callable + +MIN_SIDE = 64 # smaller is a helper window, not the game +STABLE_POLLS = 3 # the same id and size this many polls in a row + + +@dataclass(frozen=True) +class Window: + """A visible X11 window.""" + + id: int + width: int + height: int + + +def _run(*args: str) -> str: + done = subprocess.run([procs.program("xdotool"), *args], capture_output=True, text=True, check=False, timeout=10) + return "" if done.returncode else done.stdout + + +def _geometry(win_id: str) -> Window | None: + fields = dict( + line.split("=", 1) for line in _run("getwindowgeometry", "--shell", win_id).splitlines() if "=" in line + ) + try: + return Window(int(win_id), int(fields["WIDTH"]), int(fields["HEIGHT"])) + except KeyError, ValueError: + return None + + +def largest(pid: int) -> Window | None: + """The biggest visible window of the process, None when it has none yet.""" + found = (_geometry(i) for i in _run("search", "--onlyvisible", "--pid", str(pid)).split()) + sized = [w for w in found if w is not None and w.width >= MIN_SIDE and w.height >= MIN_SIDE] + if not sized: + return None + return max(sized, key=lambda w: w.width * w.height) + + +def wait_stable(pid: int, timeout_s: float, alive: Callable[[], bool], poll_s: float = 0.25) -> Window | None: + """The game's window once its id and size stop changing (it resizes while starting).""" + deadline = time.monotonic() + timeout_s + last: Window | None = None + seen = 0 + while time.monotonic() < deadline and alive(): + current = largest(pid) + seen = seen + 1 if current is not None and current == last else 1 + last = current + if current is not None and seen >= STABLE_POLLS: + return current + time.sleep(poll_s) + return None diff --git a/game_recording/pyproject.toml b/game_recording/pyproject.toml new file mode 100644 index 0000000..94fd361 --- /dev/null +++ b/game_recording/pyproject.toml @@ -0,0 +1,159 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "game_recording" +version = "0.1.0" +description = "Session recorder for a game: records a dev run beside it and stamps telemetry moments onto the video timeline" +requires-python = ">=3.14" +dependencies = [] + +[tool.setuptools.packages.find] +include = ["game_recording*"] + +[tool.ruff] +target-version = "py314" +line-length = 120 +include = ["*.py", "**/*.py"] +exclude = [".git", ".venv", "__pycache__", "build", "dist", ".eggs"] + +[tool.ruff.lint] +select = ["ALL"] +ignore = [ + "D203", + "D213", + "COM812", + "ISC001", + "S603", +] +fixable = ["ALL"] +unfixable = [] + +[tool.ruff.lint.per-file-ignores] +"**/tests/**/*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"] +"**/test_*.py" = ["ARG", "D", "PLC0415", "PLR2004", "S101", "SLF001"] + +[tool.ruff.lint.pydocstyle] +convention = "google" + +[tool.ruff.lint.isort] +force-single-line = false +force-sort-within-sections = true +known-first-party = ["game_recording"] + +[tool.ruff.lint.flake8-quotes] +docstring-quotes = "double" +inline-quotes = "double" + +[tool.ruff.lint.flake8-tidy-imports] +ban-relative-imports = "all" + +[tool.ruff.format] +quote-style = "double" +indent-style = "space" +skip-magic-trailing-comma = false +line-ending = "auto" +docstring-code-format = true + +[tool.mypy] +python_version = "3.14" +strict = true +warn_return_any = true +warn_unused_configs = true +disallow_untyped_defs = true +disallow_incomplete_defs = true +check_untyped_defs = true +disallow_untyped_decorators = true +no_implicit_optional = true +warn_redundant_casts = true +warn_unused_ignores = true +warn_no_return = true +warn_unreachable = true +disallow_any_unimported = true +disallow_any_explicit = false +disallow_any_generics = true +disallow_subclassing_any = true +strict_equality = true +extra_checks = true +ignore_missing_imports = true +show_error_codes = true +color_output = true +exclude = [".venv/"] + +[tool.pylint.main] +# The repo root on the path, so pylint resolves the package's own imports the +# same way pytest does instead of reporting import-error for them. +init-hook = "import sys; sys.path.insert(0, 'game_recording')" +analyse-fallback-blocks = true +persistent = true +jobs = 0 +py-version = "3.14" +ignore = [".venv", "__pycache__"] +# Test suites intentionally use patterns (protected-access, fixture-arg +# shadowing) that don't apply to source code; ruff's per-file-ignores carry +# the equivalent exemptions, so tests stay linted -- by ruff. This is the same +# source-only pylint scope wake-alarm / diet-guard / testsAndMisc use. It has +# to be `ignore-paths`, not `ignore = ["tests"]`: `ignore` only matches the +# basename of what pylint is *given*, and pre-commit hands it explicit file +# paths, so a directory name in `ignore` never fires under the hook. +ignore-paths = ["^(.*/)?tests/.*$"] +ignore-patterns = [".*\\.pyi$"] + +[tool.pylint.messages_control] +enable = "all" +disable = [] + +[tool.pylint.format] +max-line-length = 120 + +[tool.pylint.design] +min-public-methods = 0 +max-module-lines = 1000 +max-attributes = 12 + +[tool.bandit] +exclude_dirs = ["tests", ".venv"] + +[tool.pytest.ini_options] +testpaths = ["game_recording/tests"] +python_files = ["test_*.py", "*_test.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = [ + "-v", + "--strict-markers", + "--strict-config", + "-ra", + ## No --cov here: an addopts source would widen every narrowed run + ## (``--cov=game_recording.score``) back to the whole package. CI and the + ## pre-push hook pass --cov=game_recording explicitly. + "--cov-branch", + "--cov-report=term-missing", + "--cov-report=lcov", +] +filterwarnings = [ + "error", + "ignore::DeprecationWarning", + "default::pytest.PytestUnraisableExceptionWarning", +] + +[tool.coverage.run] +source = ["game_recording"] +branch = true +omit = [ + "*/__pycache__/*", + "*/tests/*", + "*/.venv/*", +] + +[tool.coverage.report] +fail_under = 100 +show_missing = true +skip_covered = false +exclude_lines = [ + "pragma: no cover", + "if TYPE_CHECKING:", + 'if __name__ == "__main__":', +] +partial_branches = ["pragma: no branch"] diff --git a/game_recording/requirements.txt b/game_recording/requirements.txt new file mode 100644 index 0000000..e394e4c --- /dev/null +++ b/game_recording/requirements.txt @@ -0,0 +1,10 @@ +# Exact pins, enforced by the shared dependency-freshness gate: a `>=` +# floor is satisfied by anything newer, so it tells a checker nothing +# about whether this repo is actually current. +bandit[toml]==1.9.4 +mypy==2.4.1 +pre-commit==4.7.0 +pylint==4.1.4 +pytest==9.2.0 +pytest-cov==7.1.0 +ruff==0.17.5