API Reference
These are the public classes and functions exposed by boris-clip. Useful if you want to use boris-clip programmatically rather than through the CLI.
Models
boris_clip.models.Bout
dataclass
A single annotated behavioural bout.
with_padding(pre=0.0, post=0.0, video_duration=None)
Return a new Bout with padding applied, clamped to video bounds.
boris_clip.models.ParsedAnnotations
dataclass
Result of parsing a BORIS file.
boris_clip.models.VideoInfo
dataclass
Metadata extracted from a video file via ffprobe.
Parsing
boris_clip.parse.parse_boris_file(path)
Parse a BORIS annotation file in any supported format.
Supported formats are detected automatically:
.boris— BORIS project file (JSON)- CSV tabular events export
- CSV aggregated events export
Always returns a list. For .boris files each observation is a separate
entry; for CSV exports the list contains a single entry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Path to the BORIS file. |
required |
Returns:
| Type | Description |
|---|---|
list[ParsedAnnotations]
|
Parsed annotations, one per observation. |
Extraction
boris_clip.clip.extract_all_clips(bouts, video, output_dir, padding_pre=0.0, padding_post=0.0, point_padding_pre=5.0, point_padding_post=5.0, max_duration=None, max_clips=None, fast=False, progress_callback=None)
Extract clips for all bouts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bouts
|
list[Bout]
|
Bouts to extract. |
required |
video
|
VideoInfo
|
Source video metadata. |
required |
output_dir
|
Path
|
Directory to write clips into. |
required |
padding_pre
|
float
|
Seconds to add before each state event bout. |
0.0
|
padding_post
|
float
|
Seconds to add after each state event bout. |
0.0
|
point_padding_pre
|
float
|
Seconds to add before each point event. |
5.0
|
point_padding_post
|
float
|
Seconds to add after each point event. |
5.0
|
max_duration
|
float | None
|
If set, clips longer than this many seconds are truncated from the end. Applied after padding. |
None
|
max_clips
|
int | None
|
If set, at most this many clips are extracted per (behaviour, subject) group. Earlier bouts take priority. |
None
|
fast
|
bool
|
Use stream-copy instead of re-encoding. |
False
|
progress_callback
|
Optional callable |
None
|
Returns:
| Type | Description |
|---|---|
list[Path]
|
Paths to all successfully created clips. |
Validation
boris_clip.validate.validate(annotations, video, force=False)
Validate that BORIS annotations are consistent with the video file.
Performs a series of checks with escalating severity. Hard errors call
:func:abort unless force is True, in which case they become
warnings. Soft mismatches always produce warnings.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
annotations
|
ParsedAnnotations
|
Parsed BORIS annotations. |
required |
video
|
VideoInfo
|
Video metadata from ffprobe. |
required |
force
|
bool
|
If |
False
|
Video probing
boris_clip.probe.probe_video(video_path)
Extract metadata from a video file using ffprobe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
video_path
|
str
|
Path to the video file. |
required |
Returns:
| Type | Description |
|---|---|
VideoInfo
|
Parsed metadata including duration, fps, and filename. |