mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-17 21:25:05 +01:00
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:
parent
1194517702
commit
65e72d8ded
71
.github/workflows/game-recording-precommit.yml
vendored
Normal file
71
.github/workflows/game-recording-precommit.yml
vendored
Normal 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
|
||||
35
.github/workflows/game-recording-tests.yml
vendored
Normal file
35
.github/workflows/game-recording-tests.yml
vendored
Normal 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
|
||||
131
game_recording/.pre-commit-config.yaml
Normal file
131
game_recording/.pre-commit-config.yaml
Normal 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
91
game_recording/README.md
Normal 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`.
|
||||
11
game_recording/game_recording/__init__.py
Normal file
11
game_recording/game_recording/__init__.py
Normal 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__"]
|
||||
95
game_recording/game_recording/cli.py
Normal file
95
game_recording/game_recording/cli.py
Normal 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)
|
||||
102
game_recording/game_recording/config.py
Normal file
102
game_recording/game_recording/config.py
Normal 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")
|
||||
124
game_recording/game_recording/encoder.py
Normal file
124
game_recording/game_recording/encoder.py
Normal 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
|
||||
91
game_recording/game_recording/finalize.py
Normal file
91
game_recording/game_recording/finalize.py
Normal 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
|
||||
133
game_recording/game_recording/gsr.py
Normal file
133
game_recording/game_recording/gsr.py
Normal 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)
|
||||
93
game_recording/game_recording/library.py
Normal file
93
game_recording/game_recording/library.py
Normal 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)
|
||||
162
game_recording/game_recording/moments.py
Normal file
162
game_recording/game_recording/moments.py
Normal 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
|
||||
34
game_recording/game_recording/options.py
Normal file
34
game_recording/game_recording/options.py
Normal 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
|
||||
75
game_recording/game_recording/policy.py
Normal file
75
game_recording/game_recording/policy.py
Normal 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")
|
||||
33
game_recording/game_recording/procs.py
Normal file
33
game_recording/game_recording/procs.py
Normal 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
|
||||
)
|
||||
223
game_recording/game_recording/recorder.py
Normal file
223
game_recording/game_recording/recorder.py
Normal 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()
|
||||
177
game_recording/game_recording/supervise.py
Normal file
177
game_recording/game_recording/supervise.py
Normal 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)
|
||||
2
game_recording/game_recording/tests/__init__.py
Normal file
2
game_recording/game_recording/tests/__init__.py
Normal file
@ -0,0 +1,2 @@
|
||||
# Copyright (c) 2026 Krzysztof Rudnicki
|
||||
"""Tests of game_recording."""
|
||||
38
game_recording/game_recording/tests/test_derived.py
Normal file
38
game_recording/game_recording/tests/test_derived.py
Normal 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) == []
|
||||
113
game_recording/game_recording/tests/test_encoder.py
Normal file
113
game_recording/game_recording/tests/test_encoder.py
Normal 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")
|
||||
96
game_recording/game_recording/tests/test_events.py
Normal file
96
game_recording/game_recording/tests/test_events.py
Normal 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({}) == ""
|
||||
150
game_recording/game_recording/tests/test_finalize.py
Normal file
150
game_recording/game_recording/tests/test_finalize.py
Normal 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)
|
||||
87
game_recording/game_recording/tests/test_gsr.py
Normal file
87
game_recording/game_recording/tests/test_gsr.py
Normal 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"
|
||||
108
game_recording/game_recording/tests/test_gsr_start.py
Normal file
108
game_recording/game_recording/tests/test_gsr_start.py
Normal 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"
|
||||
48
game_recording/game_recording/tests/test_helpers.py
Normal file
48
game_recording/game_recording/tests/test_helpers.py
Normal 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
|
||||
145
game_recording/game_recording/tests/test_library.py
Normal file
145
game_recording/game_recording/tests/test_library.py
Normal 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"
|
||||
138
game_recording/game_recording/tests/test_moment_map.py
Normal file
138
game_recording/game_recording/tests/test_moment_map.py
Normal 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
|
||||
108
game_recording/game_recording/tests/test_policy.py
Normal file
108
game_recording/game_recording/tests/test_policy.py
Normal 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=") == ""
|
||||
63
game_recording/game_recording/tests/test_procs.py
Normal file
63
game_recording/game_recording/tests/test_procs.py
Normal 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)
|
||||
139
game_recording/game_recording/tests/test_record.py
Normal file
139
game_recording/game_recording/tests/test_record.py
Normal 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
|
||||
234
game_recording/game_recording/tests/test_recorder.py
Normal file
234
game_recording/game_recording/tests/test_recorder.py
Normal 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
|
||||
231
game_recording/game_recording/tests/test_recorder_steps.py
Normal file
231
game_recording/game_recording/tests/test_recorder_steps.py
Normal 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 == ""
|
||||
153
game_recording/game_recording/tests/test_supervise.py
Normal file
153
game_recording/game_recording/tests/test_supervise.py
Normal 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
|
||||
232
game_recording/game_recording/tests/test_supervise_run.py
Normal file
232
game_recording/game_recording/tests/test_supervise_run.py
Normal 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)
|
||||
232
game_recording/game_recording/tests/test_timeline.py
Normal file
232
game_recording/game_recording/tests/test_timeline.py
Normal 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")
|
||||
100
game_recording/game_recording/tests/test_window.py
Normal file
100
game_recording/game_recording/tests/test_window.py
Normal 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
|
||||
150
game_recording/game_recording/timeline.py
Normal file
150
game_recording/game_recording/timeline.py
Normal 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"
|
||||
63
game_recording/game_recording/window.py
Normal file
63
game_recording/game_recording/window.py
Normal 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
|
||||
159
game_recording/pyproject.toml
Normal file
159
game_recording/pyproject.toml
Normal 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"]
|
||||
10
game_recording/requirements.txt
Normal file
10
game_recording/requirements.txt
Normal 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
|
||||
Loading…
Reference in New Issue
Block a user