VideoSpec

class hrtfpykit.datasets.VideoSpec(path=None, grouped_by=('subject',), extensions=None, ear_one_hot=False, ear_index=False, transform=None, name=None)

Define subject video paths or transformed video values.

VideoSpec asks a dataset to index video files by subject, or by subject and ear when videos are stored in left and right groups. Video resources can come from a dataset configuration or from a custom folder aligned with the dataset subject IDs, such as turntable captures, rendered sequences, or measurement recordings used alongside acoustic targets. The dataset scans the video root, intersects available subjects with the other requested resources, and returns the selected video value in each sample.

path selects the video root used by this resource family. When path is provided, it overrides the video root declared by the active dataset configuration for this spec. Absolute paths are used directly and relative paths are resolved from the dataset root. When path is None, the configured video path is used if the dataset declares one. If neither location is available and a video spec is requested, dataset construction raises an error. If several video specs are requested, the first one controls the video root and extension scan used for the resource family.

If the spec is passed to inputs, its value appears under dataset[0]["inputs"][name]. If it is passed to target, its value appears under dataset[0]["target"][name]. When name is None, the default key is "video".

By default, the returned value is a str path when one file matches the subject key, or a list[str] when multiple files match. The video is not decoded by hrtfpykit unless transform is provided. A transform receives each video path and returns the video representation chosen by the user.

Returning paths by default is intentional. hrtfpykit organizes video files by subject or by subject and ear, while the user decides how videos should be opened, sampled, preprocessed, augmented, or converted for a particular experiment. The transform callable is the hook for that custom video pipeline.

Video roots must contain one folder per dataset subject. Subject folders can be named with the canonical dataset subject ID, subjectN, or subject_N. When grouped_by=("subject", "ear"), each subject folder must contain ear folders such as left and right. Files are discovered recursively inside the matched subject or ear folder.

Notes

Video availability and semantic meaning are defined by the dataset or the user-provided resource folder. VideoSpec does not assume a particular capture protocol; it only defines how files are aligned, grouped, and returned.

Parameters:

  • path (str, Path, or None, default=None) – Optional video root path. None uses the active dataset video configuration when available. Absolute paths are used directly. Relative paths are resolved from the dataset root.

  • grouped_by ({subject} or (subject, ear), default=(subject,)) – Whether videos are grouped only by subject or by subject and ear.

  • extensions (tuple of str or None, default=None) – Optional video extensions to search.

  • ear_one_hot (bool, default=False) – Whether ear context encodings are exposed in sample inputs.

  • ear_index (bool, default=False) – Whether ear context encodings are exposed in sample inputs.

  • transform (callable or None, default=None) – Optional transform applied to each video path string. Use it to define how each video should be opened, sampled, preprocessed, or converted before it is returned in the sample.

  • name (str or None, default=None) – Optional public key used in sample dictionaries.

Returns:

Specification object consumed by dataset construction.

Return type:

VideoSpec

Examples

>>> from pathlib import Path
>>> from hrtfpykit.datasets import HUTUBS, VideoSpec
>>> dataset = HUTUBS(
...     root="datasets/hutubs",
...     inputs=VideoSpec(
...         path="ear_videos",
...         grouped_by="subject",
...         name="video",
...     ),
... )
>>> video_value = dataset[0]["inputs"]["video"]
>>> first_video_path = video_value[0] if isinstance(video_value, list) else video_value
>>> print(type(first_video_path).__name__)
str
>>> print(Path(first_video_path).suffix)
.mp4