Add game_recording 0.1.0

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V
This commit is contained in:
Krzysztof Rudnicki 2026-11-16 14:29:47 +01:00
parent 1194517702
commit 65e72d8ded
40 changed files with 4480 additions and 0 deletions

View File

@ -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

View File

@ -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

View File

@ -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

91
game_recording/README.md Normal file
View File

@ -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 `<session>.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: `<binaries_dir>/feedback`; recordings go in its `recordings/`. |
| `Config.env_prefix` | Variables derive from it: `<P>_NO_RECORD` (`1` = never record), `<P>_FEEDBACK_DIR` (any value = never record), `<P>_BINARIES` (binaries folder override), `<P>_RECORDER_BACKEND` (`auto`, `gsr`, `x11grab`), `<P>_RECORDER_NICE` (default 10). |
| `Config.binaries_env` | Overrides the `<P>_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=<id>` and `--feedback-dir=<dir>`
appended to its user args (after `--`); a recorded run needs `--dev`.
- It writes `<feedback-dir>/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: `<feedback-dir>/recordings/<session>.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] -- <game command>
finalize <session>.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`.

View File

@ -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__"]

View File

@ -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] -- <game command>
finalize <rec.json> 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|<pulse source>")
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)

View File

@ -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 `<prefix>_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 `<prefix>_<suffix>`."""
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")

View File

@ -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

View File

@ -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 <session>.events.json and each part's chapters from <session>.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

View File

@ -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 `<out>.ts` ("monotonic_microsec<TAB>realtime_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 <prefix>_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)

View File

@ -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 <n>` 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)

View File

@ -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

View File

@ -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 | <pulse source>
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

View File

@ -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 `<prefix>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")

View File

@ -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 <nice>`: 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
)

View File

@ -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 <session>.mkv; each restart (window came back) adds <session>.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()

View File

@ -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; `<prefix>_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)

View File

@ -0,0 +1,2 @@
# Copyright (c) 2026 Krzysztof Rudnicki
"""Tests of game_recording."""

View File

@ -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) == []

View File

@ -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")

View File

@ -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({}) == ""

View File

@ -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)

View File

@ -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"

View File

@ -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"

View File

@ -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

View File

@ -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"

View File

@ -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

View File

@ -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=") == ""

View File

@ -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)

View File

@ -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

View File

@ -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

View File

@ -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 == ""

View File

@ -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

View File

@ -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)

View File

@ -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")

View File

@ -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

View File

@ -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"

View File

@ -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

View File

@ -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"]

View File

@ -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