reprostim.capture.metadata

API to extract REPROSTIM-METADATA-JSON entries embedded in reprostim-videocapture log files.

See .ai/capture/metadata-spec.md for the full specification.

Functions

find_metadata_by_class(path, cls)	Find the first metadata entry for cls's MetadataType and parse it as cls.
find_metadata_json(path, key, value)	Find the first metadata JSON entry with a specific key-value pair.
iter_metadata_json(log_path)	Iterate over all REPROSTIM-METADATA-JSON lines in the log file.

Classes

MetadataBase(*[, type, version, json_ts, ...])	Fields common to every REPROSTIM-METADATA-JSON entry, regardless of MetadataType.
MetadataCaptureStop(*[, type, version, ...])	type: capture_stop — written when capture stops.
MetadataSessionBegin(*[, type, version, ...])	type: session_begin — written once when a recording session starts.
MetadataSessionEnd(*[, type, version, ...])	type: session_end — written once the session logger closes, after the ffmpeg thread has terminated.
MetadataType(value)	type field values emitted via _METADATA_LOG in src/reprostim-capture/videocapture/src/VideoCapture.cpp.

class reprostim.capture.metadata.MetadataBase(*, type: str | None = None, version: str | None = None, json_ts: str | None = None, json_isotime: str | None = None, cap_ts_start: str | None = None, cap_isotime_start: str | None = None)

Fields common to every REPROSTIM-METADATA-JSON entry, regardless of MetadataType.

All fields are Optional[str] for now, mirroring the raw JSON as written by _METADATA_LOG in src/reprostim-capture/videocapture/src/VideoCapture.cpp — no semantic typing (e.g. parsed timestamps, numeric resolution) yet. Values that aren’t already JSON strings (cx/cy are JSON numbers, autoRecovery is a JSON bool) are coerced to str on load.

cap_isotime_start: str | None

cap_ts_start: str | None

json_isotime: str | None

json_ts: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

type: str | None

version: str | None

class reprostim.capture.metadata.MetadataCaptureStop(*, type: str | None = None, version: str | None = None, json_ts: str | None = None, json_isotime: str | None = None, cap_ts_start: str | None = None, cap_isotime_start: str | None = None, message: str | None = None, cap_ts_stop: str | None = None, cap_isotime_stop: str | None = None)

type: capture_stop — written when capture stops.

cap_isotime_stop: str | None

cap_ts_stop: str | None

message: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class reprostim.capture.metadata.MetadataSessionBegin(*, type: str | None = None, version: str | None = None, json_ts: str | None = None, json_isotime: str | None = None, cap_ts_start: str | None = None, cap_isotime_start: str | None = None, appName: str | None = None, serial: str | None = None, vDev: str | None = None, aDev: str | None = None, cx: str | None = None, cy: str | None = None, frameRate: str | None = None, autoRecovery: str | None = None)

type: session_begin — written once when a recording session starts.

aDev: str | None

appName: str | None

autoRecovery: str | None

cx: str | None

cy: str | None

frameRate: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

serial: str | None

vDev: str | None

class reprostim.capture.metadata.MetadataSessionEnd(*, type: str | None = None, version: str | None = None, json_ts: str | None = None, json_isotime: str | None = None, cap_ts_start: str | None = None, cap_isotime_start: str | None = None, message: str | None = None)

type: session_end — written once the session logger closes, after the ffmpeg thread has terminated.

message: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class reprostim.capture.metadata.MetadataType(value)

type field values emitted via _METADATA_LOG in src/reprostim-capture/videocapture/src/VideoCapture.cpp. Keep in sync with that file — these are the only three values reprostim-videocapture currently writes.

CAPTURE_STOP = 'capture_stop'

Emitted when capture stops (message explains why); carries cap_ts_start/cap_isotime_start and cap_ts_stop/cap_isotime_stop.

SESSION_BEGIN = 'session_begin'

Emitted once when a recording session starts; carries device/session info (serial, vDev, aDev, cx, cy, frameRate, autoRecovery, cap_ts_start/cap_isotime_start).

SESSION_END = 'session_end'

Emitted once when the session logger closes, after the ffmpeg thread has terminated; carries message and cap_ts_start/cap_isotime_start.

reprostim.capture.metadata.find_metadata_by_class(path: str, cls: Type[T]) → T | None

Find the first metadata entry for cls’s MetadataType and parse it as cls.

Looks up cls’s corresponding MetadataType (via _find_metadata_type_by_class()) and calls find_metadata_json(path, "type", metadata_type.value).

Parameters:

• path (str) – Path to the log file

• cls (Type[T]) – MetadataBase subclass to search for and parse the result into, e.g. MetadataSessionBegin

Returns:

An instance of cls for the first matching entry, or None if cls has no corresponding MetadataType (logged as an error) or no matching metadata entry exists in the log

Return type:

Optional[T]

reprostim.capture.metadata.find_metadata_json(path: str, key: str, value) → Dict | None

Find the first metadata JSON entry with a specific key-value pair.

Parameters:

• path (str) – Path to the log file

• key (str) – Key to search for

• value (Any) – Value to match

Returns:

The first matching dictionary or None if not found

Return type:

Optional[Dict]

reprostim.capture.metadata.iter_metadata_json(log_path: str) → Generator[Dict, None, None]

Iterate over all REPROSTIM-METADATA-JSON lines in the log file. Yields parsed JSON dictionaries.

Parameters:

log_path (str) – Path to the log file

Returns:

Generator of parsed JSON dictionaries

Return type:

Generator[Dict, None, None]