cuju-render 0.1.0__py3-none-any.whl

cuju/render/_export/video_jobs.py

@@ -0,0 +1,408 @@
+# Copyright 2026 The cuju Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""The video exports that the page asks the server for, one at a time, each in a child process.
+
+Each export runs `python -m cuju.render._export.video` on a recording of the library and writes into
+the folder `videos` of the renderer, where the page downloads the file. The browser that the export
+opens encodes the video itself, MP4 where it encodes H.264 and WebM otherwise, so the server needs a
+Chrome, Edge or Chromium and nothing beside it. The folder holds the videos
+of the running server alone, the latest few, and the server empties it of older files before its
+first export.
+"""
+
+from __future__ import annotations
+
+import collections
+import contextlib
+import json
+import re
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from cuju.errors import ArgumentError
+
+from .._store import home as _home
+from .._store import library as _library
+from .._text import messages as _messages
+from .._text.messages import MessageError
+from . import sizes as _sizes
+from . import video as _video
+
+# The videos that the folder keeps, the latest ones, beside the export that runs.
+KEPT = 3
+# An export ends after this many seconds, longer than the longest range takes on a slow machine.
+_EXPORT_SECONDS = 3 * 60 * 60
+# The frame rates that the page's dialog offers. An export over HTTP takes any whole rate from 1
+# to `_video.MAX_FPS`, as the command line does. The page offers the sizes of `_sizes`, and any
+# other size with even sides within its limits.
+RATES = (24, 25, 30, 50, 60)
+
+
+class BusyError(_messages.Message, Exception):
+    """Raised when an export is asked for while another one runs, with the id of its message."""
+
+
+def _seconds(value: Any, name: str) -> float:
+    """Returns a number of seconds from the page, or raises `ArgumentError`."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or not 0 <= value < 1e6:
+        raise MessageError('server.video.seconds', name=name, value=repr(value))
+    return float(value)
+
+
+def options_from(document: dict[str, Any]) -> tuple[list[str], _video.Options]:
+    """Returns the command line arguments of an export that the page asks for, and its options.
+
+    The page names the start and end in seconds, the camera, the size, the frame rate as a whole
+    number from 1 to `_video.MAX_FPS`, the quality, the scale and safe area of the graphics,
+    whether the scoreboard and the annotations show and the arena and hour of its field.
+
+    Raises:
+        ArgumentError: If a field is missing, unknown or invalid.
+    """
+    known = {
+        'start',
+        'end',
+        'camera',
+        'width',
+        'height',
+        'fps',
+        'quality',
+        'score',
+        'annotations',
+        'arena',
+        'time',
+        'scale',
+        'safe',
+    }
+    unknown = set(document) - known
+    if unknown:
+        raise MessageError(
+            'server.video.fields', known=', '.join(sorted(known)), unknown=sorted(unknown)
+        )
+    start = _seconds(document.get('start', 0), 'start')
+    end = _seconds(document.get('end'), 'end')
+    if end <= start:
+        raise MessageError('server.video.range', start=f'{start:g}', end=f'{end:g}')
+    size = _sizes.check_size(document.get('width', 1280), document.get('height', 720), even=True)
+    graphics = document.get('scale', 1.0)
+    if isinstance(graphics, bool) or not isinstance(graphics, (int, float)):
+        raise MessageError('server.video.scale', graphics=repr(graphics))
+    safe = document.get('safe', 'auto')
+    if isinstance(safe, bool) or not isinstance(safe, (str, int, float)):
+        raise MessageError('server.video.safe', safe=repr(safe))
+    fps = document.get('fps', _video.DEFAULT_FPS)
+    if isinstance(fps, bool) or not isinstance(fps, int) or not 1 <= fps <= _video.MAX_FPS:
+        raise MessageError('server.video.rate', most=_video.MAX_FPS, fps=repr(fps))
+    score = document.get('score', True)
+    if not isinstance(score, bool):
+        raise MessageError('server.video.score', score=repr(score))
+    annotations = document.get('annotations', False)
+    if not isinstance(annotations, bool):
+        raise MessageError('server.video.annotations', annotations=repr(annotations))
+    options = _video.Options(
+        start=_video.Moment(start),
+        end=_video.Moment(end),
+        camera=str(document.get('camera', 'broadcast')),
+        width=size[0],
+        height=size[1],
+        fps=fps,
+        quality=str(document.get('quality', 'standard')),
+        score=score,
+        annotations=annotations,
+        arena=None if document.get('arena') is None else str(document['arena']),
+        hour=document.get('time'),
+        graphics=graphics,
+        safe=safe,
+    ).check()
+    arguments = [
+        '--start',
+        f'{start:.3f}',
+        '--end',
+        f'{end:.3f}',
+        '--camera',
+        options.camera,
+        '--size',
+        f'{options.width}x{options.height}',
+        '--fps',
+        str(options.fps),
+        '--quality',
+        options.quality,
+    ]
+    if options.graphics != 1:
+        arguments += ['--scale', f'{options.graphics:g}']
+    if options.safe != 'auto':
+        arguments += ['--safe', str(options.safe)]
+    if not options.score:
+        arguments.append('--no-score')
+    if options.annotations:
+        arguments.append('--annotations')
+    if options.arena is not None:
+        arguments += ['--arena', options.arena]
+    if options.hour is not None:
+        arguments += ['--time', repr(float(options.hour))]
+    return arguments, options
+
+
+def availability() -> dict[str, Any]:
+    """Returns whether this machine can export videos, and what is missing when it cannot.
+
+    The export needs a browser alone, which encodes the video itself, so ffmpeg is never missing.
+    `missing` holds the English text of the missing browser, and `missing_labels` the same as
+    labels of `_messages.label`, which the page shows in its own language.
+    """
+    try:
+        labels = [] if _video.find_chrome() else [_video.chrome_missing(server=True)]
+    except _video.VideoError as error:
+        found = _messages.id_fields(error)
+        labels = [
+            _messages.label(found['error_id'], **found['error_values'])
+            if found
+            else {'id': None, 'text': str(error), 'values': {}}
+        ]
+    return {
+        'available': not labels,
+        'missing': [label['text'] for label in labels],
+        'missing_labels': labels,
+    }
+
+
+def _filename(title: str, start: float, end: float) -> str:
+    """Returns the name that a downloaded video suggests, from the title and the range."""
+    stem = re.sub(r'[^A-Za-z0-9 _.,-]+', '', title).strip(' .') or 'match'
+    first, last = (f'{int(value) // 60}m{int(value) % 60:02d}' for value in (start, end))
+    return f'{stem[:60]} {first}-{last}.mp4'
+
+
+class VideoJobs:
+    """The exports of the page, one running at a time, each in a child process.
+
+    The folder is touched on the first export alone, so a server that never exports leaves it as
+    it was.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._entries: list[dict[str, Any]] = []
+        self._process: subprocess.Popen | None = None
+        self._cleaned = False
+
+    def _folder(self) -> Path:
+        folder = _home.folder('videos')
+        if not self._cleaned:
+            # The videos of an earlier server have no entry to download them by.
+            for path in folder.iterdir():
+                if path.is_file():
+                    with contextlib.suppress(OSError):
+                        path.unlink()
+            self._cleaned = True
+        return folder
+
+    @staticmethod
+    def _public(entry: dict[str, Any]) -> dict[str, Any]:
+        return {key: value for key, value in entry.items() if not key.startswith('_')}
+
+    def entries(self) -> list[dict[str, Any]]:
+        """Returns a copy of every export, newest first."""
+        with self._lock:
+            return [self._public(entry) for entry in reversed(self._entries)]
+
+    def entry(self, identifier: str) -> dict[str, Any] | None:
+        """Returns a copy of one export, or `None`."""
+        with self._lock:
+            found = next((e for e in self._entries if e['id'] == identifier), None)
+            return None if found is None else self._public(found)
+
+    def file(self, identifier: str) -> tuple[Path, str] | None:
+        """Returns the file and the suggested name of a finished export, or `None`."""
+        with self._lock:
+            found = next((e for e in self._entries if e['id'] == identifier), None)
+            if found is None or found['state'] != 'done':
+                return None
+            path = Path(found['_path'])
+            return (path, found['filename']) if path.is_file() else None
+
+    def start(self, match: str, document: dict[str, Any]) -> dict[str, Any]:
+        """Starts an export of a recording of the library and returns its entry.
+
+        Raises:
+            ArgumentError: If the recording is unknown or an option is invalid.
+            BusyError: If another export runs.
+        """
+        path = _library.path_of(match)
+        if path is None:
+            raise MessageError('server.video.unknown_match', match=repr(match))
+        arguments, options = options_from(document)
+        try:
+            facts = _video.recording_facts(path)
+        except _video.VideoError as error:
+            raise _messages.argument_error(error) from error
+        start, end = _video.resolve_range(options, facts)
+        if end - start > _video.DEFAULT_MAX_SECONDS:
+            raise MessageError(
+                'server.video.length',
+                most=f'{_video.DEFAULT_MAX_SECONDS:g}',
+                length=f'{end - start:.0f}',
+            )
+        status = availability()
+        if not status['available']:
+            labels = status.get('missing_labels') or []
+            if labels and all(label.get('id') for label in labels):
+                found = _video.missing_label(labels)
+                raise MessageError(found['id'], **found['values'])
+            raise ArgumentError(' '.join(status['missing']))
+        with self._lock:
+            if self._process is not None and self._process.poll() is None:
+                raise BusyError('server.video.busy')
+            folder = self._folder()
+            identifier = _home.new_identifier('v')
+            output = folder / f'{identifier}.mp4'
+            entry = {
+                'id': identifier,
+                'match': match,
+                'title': facts.title,
+                'start': start,
+                'end': end,
+                'state': 'running',
+                'progress': 0.0,
+                'frame': 0,
+                'frames': _video.frame_count(start, end, options.fps),
+                'error': None,
+                'error_id': None,
+                'error_values': None,
+                'bytes': None,
+                'filename': _filename(facts.title, start, end),
+                'created': time.time(),
+                '_path': str(output),
+            }
+            command = [
+                *_home.python_command(),
+                '-m',
+                'cuju.render._export.video',
+                match,
+                '-o',
+                str(output),
+                '--format',
+                'auto',
+            ]
+            # The child runs in the renderer's folder, so no module beside the server's working
+            # folder shadows cuju, and reads its cancellation from a pipe of its own.
+            process = subprocess.Popen(
+                [*command, *arguments],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding='utf-8',
+                errors='replace',
+                cwd=_home.process_folder(),
+                env=_home.process_environment(),
+            )
+            self._process = process
+            self._entries.append(entry)
+            self._prune()
+        threading.Thread(target=self._watch, args=(entry, process), daemon=True).start()
+        return self._public(entry)
+
+    def _prune(self) -> None:
+        """Removes the files and entries of older exports beyond `KEPT`, with the lock held."""
+        finished = [e for e in self._entries if e['state'] != 'running']
+        for entry in finished[: max(0, len(finished) - KEPT)]:
+            with contextlib.suppress(OSError):
+                Path(entry['_path']).unlink(missing_ok=True)
+            self._entries.remove(entry)
+
+    @staticmethod
+    def _moved(entry: dict[str, Any], reported: Any) -> None:
+        """Follows the file of an export to the suffix of the container that it was written in.
+
+        The child process names the file it wrote, which keeps the folder and the name of the
+        export and may take the suffix of another container, with the lock held.
+        """
+        if not isinstance(reported, str):
+            return
+        planned = Path(entry['_path'])
+        written = Path(reported)
+        if written.parent == planned.parent and written.stem == planned.stem:
+            if written.suffix in _video.SUFFIXES.values():
+                entry['_path'] = str(written)
+                entry['filename'] = str(Path(entry['filename']).with_suffix(written.suffix))
+
+    def _watch(self, entry: dict[str, Any], process: subprocess.Popen) -> None:
+        """Follows the reports of an export's process until it ends."""
+        stderr: collections.deque[str] = collections.deque(maxlen=20)
+        threading.Thread(target=lambda: stderr.extend(process.stderr), daemon=True).start()
+        timer = threading.Timer(_EXPORT_SECONDS, process.kill)
+        timer.daemon = True
+        timer.start()
+        try:
+            for line in process.stdout:
+                try:
+                    report = json.loads(line)
+                except ValueError:
+                    continue
+                if not isinstance(report, dict):
+                    continue
+                with self._lock:
+                    if isinstance(report.get('progress'), (int, float)):
+                        entry['progress'] = float(report['progress'])
+                    if isinstance(report.get('frame'), int):
+                        entry['frame'] = report['frame']
+                    if isinstance(report.get('error'), str):
+                        entry.update(_messages.report_fields(report))
+                    if report.get('stage') == 'encoding':
+                        entry['progress'] = 1.0
+                    if isinstance(report.get('bytes'), int):
+                        entry['bytes'] = report['bytes']
+                    self._moved(entry, report.get('path'))
+            code = process.wait()
+        finally:
+            timer.cancel()
+        with self._lock:
+            if entry['state'] == 'running':
+                if code == 0 and Path(entry['_path']).is_file():
+                    entry['state'] = 'done'
+                elif entry.get('_cancelled'):
+                    entry['state'] = 'cancelled'
+                    entry.update(_messages.entry_fields(None))
+                else:
+                    entry['state'] = 'failed'
+                    if not entry['error']:
+                        tail = ''.join(stderr).strip()[-400:]
+                        entry.update(_messages.exit_fields('server.video.exit', code, tail))
+            if self._process is process:
+                self._process = None
+
+    def cancel(self, identifier: str) -> bool:
+        """Cancels a running export, or removes a finished one and its file.
+
+        A running export reads the cancellation, closes Chrome and removes its partial file, and
+        one that does not end within half a minute is ended.
+        """
+        with self._lock:
+            entry = next((e for e in self._entries if e['id'] == identifier), None)
+            if entry is None:
+                return False
+            if entry['state'] != 'running':
+                with contextlib.suppress(OSError):
+                    Path(entry['_path']).unlink(missing_ok=True)
+                self._entries.remove(entry)
+                return True
+            entry['_cancelled'] = True
+            process = self._process
+        if process is not None:
+            with contextlib.suppress(OSError, ValueError):
+                process.stdin.write('cancel\n')
+                process.stdin.flush()
+
+            def end() -> None:
+                try:
+                    process.wait(30)
+                except subprocess.TimeoutExpired:
+                    process.kill()
+
+            threading.Thread(target=end, daemon=True).start()
+        return True

cuju/render/_format/__init__.py

@@ -0,0 +1,3 @@
+# Copyright 2026 The cuju Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The recording format, its codec, the recorder's writer, filters and annotations."""

cuju/render/_format/annotations.py

@@ -0,0 +1,235 @@
+# Copyright 2026 The cuju Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Annotations, the numbers and text that a training loop or a policy attaches to steps.
+
+An annotation belongs to a frame and, optionally, to one player of the header. It holds named
+numbers such as a value estimate or a reward, a short text, the chosen action and the most likely
+actions with their probabilities. A recording of version 2 keeps them in a section of their own,
+and a live source streams them beside its frames. Annotating reads nothing of the batch and
+changes nothing of it.
+
+A record keeps short keys, as the file stores them. `f` is the frame, `p` the player, `v` the
+named numbers, `t` the text, `a` the action and `k` the likely actions, each a pair of an action
+and its probability, the most likely first.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import struct
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from cuju.errors import ArgumentError
+
+TAG = b'ANNO'
+# The limits of one annotation.
+MAX_VALUES = 16
+NAME_LENGTH = 40
+TEXT_LENGTH = 200
+MAX_ACTIONS = 1000
+# The likely actions that an annotation keeps.
+TOP = 3
+
+
+def _number(value: Any, what: str) -> float | int:
+    """Returns a finite number from a Python, numpy or torch scalar, to six significant digits."""
+    if hasattr(value, 'item') and not isinstance(value, int | float):
+        value = value.item()
+    if isinstance(value, bool) or not isinstance(value, int | float) or not math.isfinite(value):
+        raise ArgumentError(f'expected {what} as a finite number, found {value!r}')
+    rounded = float(f'{value:.6g}')
+    return int(rounded) if rounded.is_integer() and abs(rounded) < 2**53 else rounded
+
+
+def player_index(lineup: list[dict[str, Any]], player: Any) -> int:
+    """Returns the index in the header of a player given by number or as a pair of team and index.
+
+    A number counts the players of the left team first, then those of the right team, each team in
+    the order of its indices, as the rewards and observations of a batch count them. The header may
+    list the teams in another order, which the returned index follows.
+    """
+    if isinstance(player, int) and not isinstance(player, bool):
+        if 0 <= player < len(lineup):
+            order = sorted(
+                range(len(lineup)),
+                key=lambda k: (lineup[k].get('team', 0), lineup[k].get('index', k), k),
+            )
+            return order[player]
+    elif isinstance(player, tuple | list) and len(player) == 2:
+        for index, entry in enumerate(lineup):
+            if [entry.get('team'), entry.get('index')] == list(player):
+                return index
+    raise ArgumentError(
+        f'expected a player from 0 to {len(lineup) - 1} or a pair of team and index, '
+        f'found {player!r}'
+    )
+
+
+def player_number(lineup: list[dict[str, Any]], index: int) -> int:
+    """Returns the number of the player at `index` of the header, the left team's players first.
+
+    The number is the one that `player_index` reads, so a player given by number comes back as
+    that number whatever order the header lists the teams in.
+    """
+    order = sorted(
+        range(len(lineup)),
+        key=lambda k: (lineup[k].get('team', 0), lineup[k].get('index', k), k),
+    )
+    return order.index(index) if 0 <= index < len(lineup) else index
+
+
+def _likely(probabilities: Any) -> list[list[float | int]]:
+    """Returns the most likely actions with their probabilities, from a sequence or a mapping."""
+    if hasattr(probabilities, 'tolist'):
+        probabilities = probabilities.tolist()
+    if isinstance(probabilities, Mapping):
+        pairs = list(probabilities.items())
+    elif isinstance(probabilities, Iterable) and not isinstance(probabilities, str | bytes):
+        pairs = list(enumerate(probabilities))
+    else:
+        raise ArgumentError(
+            f'expected probabilities as a sequence or mapping, found {probabilities!r}'
+        )
+    if len(pairs) > MAX_ACTIONS:
+        raise ArgumentError(f'expected at most {MAX_ACTIONS} probabilities, found {len(pairs)}')
+    checked = []
+    for action, probability in pairs:
+        if isinstance(action, bool) or not isinstance(action, int) or action < 0:
+            raise ArgumentError(f'expected actions as whole numbers, found {action!r}')
+        checked.append((action, _number(probability, 'a probability')))
+    checked.sort(key=lambda pair: (-pair[1], pair[0]))
+    return [[action, float(f'{probability:.4g}')] for action, probability in checked[:TOP]]
+
+
+def note(
+    lineup: list[dict[str, Any]],
+    values: Mapping[str, Any] | None = None,
+    text: str | None = None,
+    player: Any = None,
+    probabilities: Any = None,
+    action: Any = None,
+) -> dict[str, Any]:
+    """Returns the record of one annotation without its frame, after checking every part.
+
+    Raises:
+        ArgumentError: If a part is invalid or the annotation holds nothing.
+    """
+    record: dict[str, Any] = {}
+    if player is not None:
+        record['p'] = player_index(lineup, player)
+    if values is not None:
+        if not isinstance(values, Mapping) or len(values) > MAX_VALUES:
+            raise ArgumentError(f'expected values as a mapping of at most {MAX_VALUES} names')
+        named = {}
+        for name, value in values.items():
+            if not isinstance(name, str) or not 0 < len(name) <= NAME_LENGTH:
+                raise ArgumentError(
+                    f'expected names of 1 to {NAME_LENGTH} characters, found {name!r}'
+                )
+            named[name] = _number(value, f'the value {name!r}')
+        if named:
+            record['v'] = named
+    if text is not None:
+        if not isinstance(text, str):
+            raise ArgumentError(f'expected text as a string, found {text!r}')
+        record['t'] = text[:TEXT_LENGTH]
+    if action is not None:
+        if hasattr(action, 'item'):
+            action = action.item()
+        if isinstance(action, bool) or not isinstance(action, int) or action < 0:
+            raise ArgumentError(f'expected the action as a whole number, found {action!r}')
+        record['a'] = action
+    if probabilities is not None:
+        record['k'] = _likely(probabilities)
+    if not record.keys() - {'p'}:
+        raise ArgumentError('expected values, text, an action or probabilities to annotate')
+    return record
+
+
+def merge(
+    records: dict[tuple[int, int], dict[str, Any]], frame: int, record: dict[str, Any]
+) -> dict[str, Any]:
+    """Adds an annotation of `frame` to `records`, merged with an earlier one of the same player.
+
+    Named numbers join those already there, and the text, action and likely actions replace
+    theirs. Returns the merged record.
+
+    Raises:
+        ArgumentError: If the merged record would hold more than `MAX_VALUES` names.
+    """
+    key = (frame, record.get('p', -1))
+    merged = dict(records.get(key) or {'f': frame})
+    for name, value in record.items():
+        merged[name] = {**merged.get('v', {}), **value} if name == 'v' else value
+    if len(merged.get('v', ())) > MAX_VALUES:
+        raise ArgumentError(f'expected at most {MAX_VALUES} named values on a step')
+    records[key] = merged
+    return merged
+
+
+def frame_of(frames: list[bytes], step: int | None) -> int:
+    """Returns the index of the frame of `step`, the last frame for `None`.
+
+    Raises:
+        ArgumentError: If no frame holds the step.
+    """
+    if step is not None:
+        if isinstance(step, bool) or not isinstance(step, int):
+            raise ArgumentError(f'expected the step as a whole number, found {step!r}')
+        for index in range(len(frames) - 1, -1, -1):
+            if struct.unpack_from('<i', frames[index])[0] == step:
+                return index
+        raise ArgumentError(f'expected a step of the current episode, found {step}')
+    return len(frames) - 1
+
+
+def encode(records: Iterable[dict[str, Any]]) -> bytes:
+    """Returns the payload of an annotations section, its records in order of frame and player."""
+    ordered = sorted(records, key=lambda record: (record['f'], record.get('p', -1)))
+    return json.dumps({'records': ordered}, separators=(',', ':')).encode()
+
+
+def decode(payload: bytes) -> list[dict[str, Any]]:
+    """Returns the records of an annotations section, leaving out any that is malformed."""
+    try:
+        records = json.loads(payload)['records']
+    except (ValueError, KeyError, TypeError, RecursionError):
+        return []
+    return (
+        [record for record in records if _frame(record) is not None]
+        if isinstance(records, list)
+        else []
+    )
+
+
+def _frame(record: Any) -> int | None:
+    """Returns the frame of a record, a whole number from 0, or `None` for a malformed record."""
+    frame = record.get('f') if isinstance(record, dict) else None
+    whole = isinstance(frame, int) and not isinstance(frame, bool)
+    return frame if whole and frame >= 0 else None
+
+
+def public(
+    record: dict[str, Any], frames: list[bytes], lineup: list[dict[str, Any]] | None = None
+) -> dict[str, Any]:
+    """Returns a record with long keys and the step of its frame, as a filter reads it.
+
+    With the header's `lineup`, the player is its number with the left team's players first, as
+    `annotate` takes it, and without one the index in the header.
+    """
+    frame = record['f']
+    player = record.get('p')
+    if lineup is not None and isinstance(player, int):
+        player = player_number(lineup, player)
+    return {
+        'frame': frame,
+        'step': struct.unpack_from('<i', frames[frame])[0] if 0 <= frame < len(frames) else None,
+        'player': player,
+        'values': dict(record.get('v', {})),
+        'text': record.get('t'),
+        'action': record.get('a'),
+        'probabilities': [list(pair) for pair in record.get('k', ())],
+    }