mirror of
https://github.com/kuhyx/utils.git
synced 2026-11-17 22:05:17 +01:00
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WzxdWXs4gEhEUMr9rgYG9V |
||
|---|---|---|
| .. | ||
| game_recording | ||
| .pre-commit-config.yaml | ||
| pyproject.toml | ||
| README.md | ||
| requirements.txt | ||
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 withgpu-screen-recorder(elseffmpegx11grab) 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.
finalizewrites<session>.events.jsonnext to the video and remuxes chapters in without re-encoding.latest,listandopen Nshow moments and open the video inmpvthree 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:
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 withsession,event,seqandms(its own clock). Onerecording_syncline (msplusunixorunix_us) pins that clock to unix time. - Output layout:
<feedback-dir>/recordings/<session>.mkv(.partN.mkvfor 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.