reprostim.bids.properties

Extraction of BIDS media-file properties (sidecar-JSON-key-keyed values) from ffprobe results, split-video results, and in future from cached VaRecord (videos.tsv) rows and file paths. The single place bids-inject-sidecar, bids-inject, and split-video produce BIDS sidecar properties from, instead of each reimplementing the AudioInfo/VideoInfo/SplitResult/VaRecord -> BIDS-dict mapping independently.

See .ai/bids/properties-spec.md for the full specification.

Functions

bids_properties_from_audio_video_info(audio, ...)

Map ffprobe-derived stream info to BIDS media-file properties.

bids_properties_from_ffprobe(path[, props])

Run ffprobe on path and map the result to BIDS media-file properties.

bids_properties_from_split_result(sr[, ...])

Convert a split-video result to a BEP044/BEP047 BIDS sidecar dict.

bids_properties_from_video_audit(path[, ...])

Look up a cached VaRecord for path in path_tsv (a videos.tsv produced by video-audit) and map it to BIDS media-file properties.
reprostim.bids.properties.bids_properties_from_audio_video_info(audio: AudioInfo | None, video: VideoInfo | None, props: Dict[str, Any] | None = None) → Dict[str, Any][source]

Map ffprobe-derived stream info to BIDS media-file properties.

Fields that cannot be determined (no matching stream, field absent from ffprobe output) are simply omitted from the result rather than written as "n/a" or None, matching the BEP044 sidecar convention (see .ai/bids/media-spec.md).

Parameters:

  • audio (Optional[AudioInfo]) – Audio stream info from get_audio_video_info_ffprobe, or None if the file has no audio stream.

  • video (Optional[VideoInfo]) – Video stream info from get_audio_video_info_ffprobe, or None if the file has no video stream.

  • props (Optional[Dict[str, Any]]) – Optional dict to populate/merge into instead of creating a fresh one — lets a caller accumulate properties from several bids_properties_from_* calls into one shared dict. Existing keys are overwritten by non-None values from this call (like dict.update()); when composing multiple sources, priority is controlled by call order, not by this parameter.

Returns:

props (or a new dict if props was None), with mappable properties set; only properties that could be determined are present.

Return type:

Dict[str, Any]

reprostim.bids.properties.bids_properties_from_ffprobe(path: str, props: Dict[str, Any] | None = None) → Dict[str, Any][source]

Run ffprobe on path and map the result to BIDS media-file properties.

Convenience wrapper combining get_audio_video_info_ffprobe and bids_properties_from_audio_video_info().

Parameters:

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

  • props (Optional[Dict[str, Any]]) – Optional dict to populate/merge into instead of creating a fresh one; see bids_properties_from_audio_video_info().

Returns:

props (or a new dict if props was None); see bids_properties_from_audio_video_info().

Return type:

Dict[str, Any]

reprostim.bids.properties.bids_properties_from_split_result(sr, sidecar_metadata: Dict[str, Any] | None = None) → Dict[str, Any][source]

Convert a split-video result to a BEP044/BEP047 BIDS sidecar dict.

Maps a video-splitting result’s fields to BIDS metadata field names as defined in the common media file definitions (bids-standard/bids-specification PR #2367).

sr is intentionally untyped: annotating it as reprostim.video.split.SplitResult would make this module import from video.split — but split.py is the caller of this function, so that import would be circular. sr is expected to expose the same attributes as SplitResult: orig_device, orig_device_serial_number, buffer_duration, video_codec, video_frame_rate, video_width, video_height, audio_codec, audio_sample_rate, audio_bit_depth, audio_channel_count.

Parameters:

  • sr – Split-result-like object to convert (see note above).

  • sidecar_metadata (Optional[Dict[str, Any]]) – Optional dict with extra BIDS fields to inject. Supports TaskName (written as the first field when present), VideoCodecRFC6381, AudioCodecRFC6381, ImageBitDepth, ImagePixelFormat, and VideoFrameCount (see BidsMediaProperty for the field-name constants backing these keys).

Returns:

Dict with BIDS-compliant metadata field names.

Return type:

Dict[str, Any]

reprostim.bids.properties.bids_properties_from_video_audit(path: str, path_tsv: str | None = None, props: Dict[str, Any] | None = None) → Dict[str, Any][source]

Look up a cached VaRecord for path in path_tsv (a videos.tsv produced by video-audit) and map it to BIDS media-file properties.

Wraps get_file_video_audit(path, path_tsv, cached=True, use_lock=False): prefers already-loaded, cached TSV data over reloading from disk, and skips the advisory file lock (dirty read) — appropriate for read-mostly batch tooling (e.g. bids-inject-sidecar) rather than the video-audit writer itself. Falls back to auditing the file directly when path has no matching row in path_tsv, or path_tsv is not given/found — see reprostim.video.audit.get_file_video_audit().

Uses the VaRecord’s duration/video_res_recorded/ video_fps_recorded/audio_sr fields (derived from the media stream itself via ffprobe/QR parsing), not the *_detected ones (derived from the psychopy display-capture log), since the sidecar should describe the file, not what was displayed. Fields absent or "n/a" in the VaRecord are omitted, matching every other bids_properties_from_* function in this module.

VaRecord/videos.tsv has no Device/DeviceSerialNumber columns yet, so those two are instead recovered the same way video.split does: by looking for a session_begin REPROSTIM-METADATA-JSON entry in <path>.log (see reprostim.capture.metadata.find_metadata_by_class()) and reading its vDev/serial fields. Omitted if <path>.log doesn’t exist, has no session_begin entry, or that entry lacks the field.

VaRecord also has no codec column, so VideoCodec is set to "h264" whenever video_res_recorded is present (not "n/a"), reflecting that reprostim-videocapture always encodes with -c:v libx264 — matching SplitResult.video_codec’s inference in bids_properties_from_split_result.

Parameters:

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

  • path_tsv (Optional[str]) – Optional path to videos.tsv.

  • props (Optional[Dict[str, Any]]) – Optional dict to populate/merge into instead of creating a fresh one; see bids_properties_from_audio_video_info().

Returns:

props (or a new dict if props was None); see bids_properties_from_audio_video_info().

Return type:

Dict[str, Any]