reprostim.qr.qr_parse

API to parse (*.mkv) video files recorded by reprostim-videocapture utility and extract embedded video media info, QR-codes and audiocodes into JSONL format.

Functions

calc_time(ts, pos_sec)	Calculate a new timestamp by adding seconds to a given datetime.
do_info(path)	Yields summary information for a video file or all *.mkv files in a directory.
do_info_file(path[, ignore_errors])	Extracts summary information from a single video file.
do_main(path, mode[, grayscale, scale, ...])	Entry point for the qr-parse command.
do_parse(ctx, path_video[, summary_only, ...])	Parse a video file to extract QR code-encoded segments and video metadata.
finalize_record(ps, vti, record, iframe, pos_sec)	Internal API, finalizes the QR code record by setting its end time, duration, and index.
get_iso_time(ts)	Parse an ISO 8601 datetime string and return a naive datetime object.
get_video_time_info(path_video)	Extract start and end timestamps from a video filename and compute duration.

Classes

Grayscale(value)	Grayscale conversion method applied to each frame before QR decoding.
InfoSummary(*[, path, rate_mbpm, ...])	Summary information about a video file.
ParseContext(*[, grayscale, scale, skip, ...])	Configuration context for the QR parsing process.
ParseSummary(*[, type, qr_count, ...])	Summary of the QR parsing process and video metadata.
QrDecoder(value)	QR decoding backend.
QrRecord(*[, type, index, frame_start, ...])	Represents a decoded QR code segment extracted from a video stream.
VideoDecoder(value)	Video frame decoding backend.
VideoTimeInfo(*, success[, error, ...])	Metadata for inferred or extracted timing information from a video file.

class reprostim.qr.qr_parse.Grayscale(value)

Grayscale conversion method applied to each frame before QR decoding.

NONE = 'none'

Pass the raw BGR frame directly — may cause errors with single-channel decoders.

NUMPY = 'numpy'

Use np.mean(frame, axis=2) — legacy, slower (~34 fps).

OPENCV = 'opencv'

Use cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY) — recommended (~330 fps).

class reprostim.qr.qr_parse.InfoSummary(*, path: str | None = None, rate_mbpm: float | None = None, duration_sec: float | None = None, size_mb: float | None = None)

Summary information about a video file.

Provides video media info details. Contains basic metadata such as path, duration, size, and data rate.

duration_sec: float | None

Duration of the video in seconds

model_config: ClassVar[ConfigDict] = {}

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

path: str | None

Video file path.

rate_mbpm: float | None

Video file byterate in MB per minute.

size_mb: float | None

Video file size in MB.

class reprostim.qr.qr_parse.ParseContext(*, grayscale: Grayscale = Grayscale.OPENCV, scale: float = 1.0, skip: int = 0, std_threshold: float = 10.0, qr_decoder: QrDecoder = QrDecoder.PYZBAR, video_decoder: VideoDecoder = VideoDecoder.OPENCV, qrdet: bool = False, qrdet_model_size: str = 's', qr_decoder_workers: int = 0)

Configuration context for the QR parsing process.

Passed to do_parse() to control frame processing behaviour. Fields are added as new CLI options are implemented.

grayscale: Grayscale

model_config: ClassVar[ConfigDict] = {}

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

qr_decoder: QrDecoder

qr_decoder_workers: int

qrdet: bool

qrdet_model_size: str

scale: float

skip: int

std_threshold: float

video_decoder: VideoDecoder

class reprostim.qr.qr_parse.ParseSummary(*, type: str | None = 'ParseSummary', qr_count: int | None = 0, parsing_duration: float | None = 0.0, exit_code: int | None = -1, video_full_path: str | None = None, video_file_name: str | None = None, video_isotime_start: datetime | None = None, video_isotime_end: datetime | None = None, video_duration: float | None = None, video_frame_width: int | None = None, video_frame_height: int | None = None, video_frame_rate: float | None = None, video_frame_count: int | None = None)

Summary of the QR parsing process and video metadata.

This model captures information about the parsing results and properties of the video being processed.

exit_code: int | None

Exit code of the parsing process.

model_config: ClassVar[ConfigDict] = {}

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

parsing_duration: float | None

Duration of the parsing in seconds.

qr_count: int | None

Number of QR codes found.

type: str | None

JSON record type/class.

video_duration: float | None

Duration of the video in seconds.

video_file_name: str | None

Name of the video file.

video_frame_count: int | None

Number of frames in the video file.

video_frame_height: int | None

Height of the video frame in pixels.

video_frame_rate: float | None

Frame rate of the video in frames per second.

video_frame_width: int | None

Width of the video frame in pixels.

video_full_path: str | None

Full path to the video file.

video_isotime_end: datetime | None

ISO datetime when the video ended.

video_isotime_start: datetime | None

ISO datetime when the video started.

class reprostim.qr.qr_parse.QrDecoder(value)

QR decoding backend.

NONE = 'none'

Disable QR decoding entirely — frame processing (std filter, scaling, skipping) still runs, useful for benchmarking or dry-run profiling.

OPENCV = 'opencv'

Use cv2.QRCodeDetector().detectAndDecode.

PYZBAR = 'pyzbar'

Use pyzbar.decode — default, generally more robust.

class reprostim.qr.qr_parse.QrRecord(*, type: str | None = 'QrRecord', index: int | None = None, frame_start: int | None = None, frame_end: int | None = None, isotime_start: datetime | None = None, isotime_end: datetime | None = None, time_start: float | None = None, time_end: float | None = None, duration: float | None = None, data: dict | None = None)

Represents a decoded QR code segment extracted from a video stream.

Contains timing, frame location, and content metadata for each detected QR code.

data: dict | None

QR code data.

duration: float | None

Duration of the QR code in seconds.

frame_end: int | None

Frame number where QR code ends.

frame_start: int | None

Frame number where QR code starts.

index: int | None

Zero-based index of the QR code.

isotime_end: datetime | None

ISO datetime where QR code ends.

isotime_start: datetime | None

ISO datetime where QR code starts.

model_config: ClassVar[ConfigDict] = {}

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

time_end: float | None

Position in seconds where QR code ends.

time_start: float | None

Position in seconds where QR code starts.

type: str | None

JSON record type/class.

class reprostim.qr.qr_parse.VideoDecoder(value)

Video frame decoding backend.

OPENCV = 'opencv'

Use cv2.VideoCapture — default, currently the only supported backend.

class reprostim.qr.qr_parse.VideoTimeInfo(*, success: bool, error: str | None = None, start_time: datetime | None = None, end_time: datetime | None = None, duration_sec: float | None = None)

Metadata for inferred or extracted timing information from a video file.

This model is populated after parsing video filename timestamps or media metadata.

duration_sec: float | None

Duration of the video in seconds.

end_time: datetime | None

End time of the video.

error: str | None

Error message if any.

model_config: ClassVar[ConfigDict] = {}

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

start_time: datetime | None

Start time of the video.

success: bool

Success flag.

reprostim.qr.qr_parse.calc_time(ts: datetime, pos_sec: float) → datetime

Calculate a new timestamp by adding seconds to a given datetime.

Parameters:

• ts (datetime) – The original timestamp.

• pos_sec (float) – The number of seconds to add (can be fractional).

Returns:

The resulting timestamp after adding the specified seconds.

Return type:

datetime

reprostim.qr.qr_parse.do_info(path: str)

Yields summary information for a video file or all *.mkv files in a directory.

If the given path is a file, returns its summary. If the path is a directory, recursively processes *.mkv files within it.

Parameters:

path (str) – Path to a video file or directory containing video files.

Yield:

InfoSummary object for each video file processed.

Return type:

Generator[InfoSummary, None, None]

reprostim.qr.qr_parse.do_info_file(path: str, ignore_errors: bool = False)

Extracts summary information from a single video file.

Parses the filename to extract start and end times, computes duration, file size, and average data rate in MB per minute.

Parameters:

• path (str) – Path to the video file.

• ignore_errors – If True, ignores parsing errors and returns incomplete data. Default is False.

Returns:

A tuple containing an InfoSummary object and a VideoTimeInfo object.

reprostim.qr.qr_parse.do_main(path: str, mode: str, grayscale: str = Grayscale.OPENCV, scale: float = 1.0, skip: int = 0, std_threshold: float = 10.0, qr_decoder: str = QrDecoder.PYZBAR, video_decoder: str = VideoDecoder.OPENCV, qrdet: bool = False, qrdet_model_size: str = 's', qr_decoder_workers: int = 0, out_func=<built-in function print>)

Entry point for the qr-parse command.

Initialises a ParseContext, dispatches to do_parse() or do_info() depending on mode, and writes each result to out_func.

Parameters:

• path – Path to the video file or directory to process.

• mode – Execution mode — "PARSE" or "INFO".

• grayscale – Grayscale conversion method (see Grayscale).

• scale – Frame downscale factor in (0, 1]; 1.0 = no resize.

• skip – Frames to skip after each processed frame; 0 = process every frame.

• std_threshold – Grayscale std-deviation threshold; 0 or less = disabled.

• qr_decoder – QR decoding backend (see QrDecoder).

• video_decoder – Video frame decoding backend (see VideoDecoder).

• qrdet – Enable qrdet GPU frame pre-filter.

• qrdet_model_size – qrdet model size ('n', 's', 'm', 'l').

• qr_decoder_workers – Worker threads for parallel QR decoding; 0 or 1 = sequential.

• out_func – Callable used to emit each output line (default: print).

Returns:

Exit code (0 on success, non-zero on error).

reprostim.qr.qr_parse.do_parse(ctx: ParseContext, path_video: str, summary_only: bool = False, ignore_errors: bool = False)

Parse a video file to extract QR code-encoded segments and video metadata.

The function performs the following steps: - Parses the filename to extract start and end timestamps. - Extracts video metadata such as resolution, frame rate, frame count, and duration. - Iterates through video frames to detect and decode QR codes. - Yields finalized records when a QR code is detected or ends. - At the end, yields a summary object with parsing stats and video info.

QR codes are expected to be embedded as visual markers in the video. Each QR code corresponds to a data payload which is yielded as a finalized record.

Parameters:

• ctx (ParseContext) – Parse context holding configuration for frame processing (grayscale method, std-threshold, scale, skip, QR decoder, etc.). Initialised once by the caller and shared across the entire parse run.

• path_video (str) – Path to the input video file (e.g., *.mkv, *.mp4).

• summary_only – If True, only video metadata summary is returned without parsing for QR codes. Default is False.

• ignore_errors – If True, ignores parsing errors and returns incomplete data. Default is False.

Yield:

Individual finalized records (InfoRecord) and a final ParseSummary object.

Return type:

Generator[Union[InfoRecord, ParseSummary], None, None]

reprostim.qr.qr_parse.finalize_record(ps: ParseSummary, vti: VideoTimeInfo, record: QrRecord, iframe: int, pos_sec: float) → QrRecord

Internal API, finalizes the QR code record by setting its end time, duration, and index.

Parameters:

• ps – parse summary object

• vti – video time info object

• record – QR code record object

• iframe – current frame number

• pos_sec – current position in seconds

Returns:

QR code record object

reprostim.qr.qr_parse.get_iso_time(ts: str) → datetime

Parse an ISO 8601 datetime string and return a naive datetime object.

Parameters:

ts (str) – An ISO 8601 formatted datetime string.

Returns:

A naive datetime object (timezone information is removed).

Return type:

datetime

reprostim.qr.qr_parse.get_video_time_info(path_video: str) → VideoTimeInfo

Extract start and end timestamps from a video filename and compute duration.

The function supports two timestamped filename formats: 1. YYYY.MM.DD.HH.MM.SS.mmm_YYYY.MM.DD.HH.MM.SS.mmm.ext 2. YYYY.MM.DD-HH.MM.SS.mmm--YYYY.MM.DD-HH.MM.SS.mmm.ext

Valid extensions are *.mkv and *.mp4.

Parameters:

path_video (str) – Full path to the video file with timestamped filename.

Returns:

A VideoTimeInfo object containing success flag, optional error, start and end times, and the duration in seconds.

Return type:

VideoTimeInfo

Raises:

ValueError – If timestamps cannot be parsed or are in invalid order.