reprostim.qr.split_video

API to split and audit video files recorded by reprostim-videocapture, along with their corresponding log files and QR/audio metadata.

Functions

do_main(input_path, output_path[, ...])

Main entry point for split_video module.

Classes

BufferPolicy(value)

Policy for handling buffer overflow beyond video boundaries.

SpecEntry(*, start_str[, duration_str, end_str])

Parsed representation of a single --spec argument.

SplitData(*[, success, path, fps, ...])

Specifies metadata necessary to split single video file.

SplitResult(*[, success, input_path, ...])

Specifies result of video split operation.

VideoSegment(*[, start_ts, end_ts, ...])

Specifies a video segment data.
class reprostim.qr.split_video.BufferPolicy(value)[source]

Policy for handling buffer overflow beyond video boundaries.

FLEXIBLE = 'flexible'
STRICT = 'strict'
class reprostim.qr.split_video.SpecEntry(*, start_str: str, duration_str: str | None = None, end_str: str | None = None)[source]

Parsed representation of a single –spec argument.

duration_str: str | None
end_str: str | None
model_config: ClassVar[ConfigDict] = {}

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

start_str: str
class reprostim.qr.split_video.SplitData(*, success: bool = False, path: str = 'n/a', fps: float | None = None, resolution: str | None = None, audio_sr: str | None = None, device: str = 'n/a', device_serial_number: str = 'n/a', full_seg: VideoSegment | None = None, sel_seg: VideoSegment | None = None, buf_seg: VideoSegment | None = None)[source]

Specifies metadata necessary to split single video file.

audio_sr: str | None
buf_seg: VideoSegment | None
device: str
device_serial_number: str
fps: float | None
full_seg: VideoSegment | None
model_config: ClassVar[ConfigDict] = {}

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

path: str
resolution: str | None
sel_seg: VideoSegment | None
success: bool
class reprostim.qr.split_video.SplitResult(*, success: bool = False, input_path: str = 'n/a', output_path: str = 'n/a', buffer_before: float | None = None, buffer_after: float | None = None, buffer_duration: float | None = None, start_time: datetime | None = None, end_time: datetime | None = None, duration: float | None = None, video_width: str = 'n/a', video_height: str = 'n/a', video_frame_rate: float | None = None, video_size_mb: float | None = None, video_rate_mbpm: float | None = None, audio_sample_rate: str = 'n/a', audio_bit_depth: str = 'n/a', audio_channel_count: str = 'n/a', audio_codec: str = 'n/a', orig_buffer_start: str = 'n/a', orig_buffer_end: str = 'n/a', orig_buffer_offset: float | None = None, orig_start: str = 'n/a', orig_end: str = 'n/a', orig_offset: float | None = None, orig_device: str = 'n/a', orig_device_serial_number: str = 'n/a')[source]

Specifies result of video split operation.

audio_bit_depth: str
audio_channel_count: str
audio_codec: str
audio_sample_rate: str
buffer_after: float | None
buffer_before: float | None
buffer_duration: float | None
duration: float | None
end_time: datetime | None
input_path: str
model_config: ClassVar[ConfigDict] = {}

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

orig_buffer_end: str
orig_buffer_offset: float | None
orig_buffer_start: str
orig_device: str
orig_device_serial_number: str
orig_end: str
orig_offset: float | None
orig_start: str
output_path: str
start_time: datetime | None
success: bool
video_frame_rate: float | None
video_height: str
video_rate_mbpm: float | None
video_size_mb: float | None
video_width: str
class reprostim.qr.split_video.VideoSegment(*, start_ts: datetime | None = None, end_ts: datetime | None = None, offset_sec: float | None = None, offset_frame: int | None = None, duration_sec: float | None = None, frame_count: int | None = None)[source]

Specifies a video segment data.

duration_sec: float | None
end_ts: datetime | None
frame_count: int | None
model_config: ClassVar[ConfigDict] = {}

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

offset_frame: int | None
offset_sec: float | None
start_ts: datetime | None
reprostim.qr.split_video.do_main(input_path: str, output_path: str, start_time: str | None = None, duration: str | None = None, end_time: str | None = None, buffer_before: str | None = None, buffer_after: str | None = None, buffer_policy: str = 'strict', sidecar_json: str | None = None, video_audit_file: str | None = None, raw: bool = False, verbose: bool = False, specs: tuple = (), lock: bool = True, out_func=<built-in function print>) → int[source]

Main entry point for split_video module.

Parameters:

  • input_path (str) – Path to the input video file. Filename must contain timestamp in format: YYYY.MM.DD.HH.MM.SS.mmm_YYYY.MM.DD.HH.MM.SS.mmm.mkv

  • output_path (str) – Path to the output .mkv file. A sidecar .json file will be created with the same basename containing metadata.

  • start_time (str) – Start time in ISO 8601 format (e.g., ‘2024-02-02T17:30:00’).

  • duration (str | None) – Duration of the output video. Accepts seconds (e.g., ‘180’) or ISO 8601 duration (e.g., ‘P3M’ for 3 minutes). Mutually exclusive with end_time.

  • end_time (str | None) – End time in ISO 8601 format (e.g., ‘2024-02-02T17:33:00’). Mutually exclusive with duration.

  • buffer_before (str | None) – Duration buffer to include before the start time. Accepts seconds (e.g., ‘10’) or ISO 8601 duration (e.g., ‘P10S’).

  • buffer_after (str | None) – Duration buffer to include after the end time. Accepts seconds (e.g., ‘10’) or ISO 8601 duration (e.g., ‘P10S’).

  • buffer_policy (str) – Policy for handling buffer overflow: ‘strict’ (error on overflow) or ‘flexible’ (trim buffers to fit). Defaults to ‘strict’.

  • sidecar_json (str | None) – Path to write sidecar JSON file with split metadata. If None, no sidecar file is created.

  • video_audit_file (str | None) – Path to video audit TSV file. If provided, uses this file instead of generating video metadata on-the-fly. Passed to get_file_video_audit as path_tsv parameter.

  • raw (bool) – Enable raw mode for video splitting. Defaults to False.

  • verbose (bool) – Enable verbose output.

  • specs (tuple) – Tuple of –spec argument strings. If non-empty, uses spec mode instead of legacy start_time/duration/end_time.

  • lock (bool) – When True (default), acquire the advisory file lock before reading the video audit TSV file. When False, skip the lock (dirty-read mode) — useful when the lock file is owned by a different OS user.

  • out_func (callable) – Output function for printing messages.

Notes

  • All durations support float seconds or ISO 8601 duration format

  • Precision is milliseconds (ms)

  • Buffers are trimmed if they extend beyond video boundaries

  • If video doesn’t overlap with desired time range, an error is raised

  • Multiple videos for a single time range are not supported yet

  • A sidecar .json file is created with metadata including: * onset (ISO 8601 time, no date) * duration (seconds with ms precision) * buffer-before (seconds with ms precision) * buffer-after (seconds with ms precision) * reprostim-videocapture metadata from the log

  • No absolute dates are stored, only times