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.
SidecarFormat(value)	Format for sidecar JSON output.
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)

Policy for handling buffer overflow beyond video boundaries.

FLEXIBLE = 'flexible'

STRICT = 'strict'

class reprostim.qr.split_video.SidecarFormat(value)

Format for sidecar JSON output.

BIDS = 'bids'

RAW = 'raw'

class reprostim.qr.split_video.SpecEntry(*, start_str: str, duration_str: str | None = None, end_str: str | None = None)

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)

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', video_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')

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_codec: str

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)

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, sidecar_format: str = 'bids', sidecar_metadata: dict | 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>) → Tuple[int, List[SplitResult]]

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.

• sidecar_format (str) – Format for the sidecar JSON. ‘bids’ (default) uses BEP044/BEP047 field names; ‘raw’ dumps the SplitResult model directly.

• sidecar_metadata (dict | None) – Optional dict with extra BIDS fields to inject into the BIDS sidecar (e.g. {"TaskName": "rest"}). Ignored in RAW format.

• 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