reprostim bids-inject

Inject ReproStim audio/video recordings into a BIDS dataset aligned to scan timing.

Usage

reprostim bids-inject [OPTIONS] PATHS...

Options

-f, --videos <videos>

Required Path to videos.tsv produced by video-audit. Video file paths in the TSV are resolved relative to this file’s location.

-r, --recursive

When a directory is given in PATHS, recurse into subdirectories to find all *_scans.tsv files.

-b, --buffer-before <buffer_before>

Extra video to include before scan onset. Accepts seconds (e.g., ‘10’ or ‘10.5’) or ISO 8601 duration (e.g., ‘PT10S’).

Default:

'0'

-a, --buffer-after <buffer_after>

Extra video to include after scan end. Accepts seconds (e.g., ‘10’ or ‘10.5’) or ISO 8601 duration (e.g., ‘PT10S’).

Default:

'0'

-p, --buffer-policy <buffer_policy>

Policy for handling buffer overflow beyond video boundaries. ‘strict’: error if buffers extend beyond video boundaries. ‘flexible’: trim buffers to fit within video boundaries.

Default:

'flexible'

Options:

strict | flexible

-t, --time-offset <time_offset>

Clock offset in seconds to add to BIDS scans for security reasons. Applied after timezone normalization.

Default:

0.0

-q, --qr <qr>

QR code-based timing refinement mode. ‘none’: timing based solely on acq_time and –time-offset. ‘auto’: use QR data if available, fall back to NTP timing. ‘embed-existing’: use pre-existing parsed QR JSONL files; error if missing. ‘parse’: run qr-parse on-the-fly on the source video.

Default:

'none'

Options:

none | auto | embed-existing | parse

-l, --layout <layout>

Output file placement layout within the BIDS dataset. ‘nearby’: place output next to the corresponding NIfTI in the same datatype folder. ‘top-stimuli’: place output under a top-level stimuli/ directory mirroring the hierarchy.

Default:

'nearby'

Options:

nearby | top-stimuli

-z, --reprostim-timezone <reprostim_timezone>

Timezone for naive ReproStim timestamps in videos.tsv. Use ‘local’ for the OS system timezone, or an IANA name (e.g. ‘America/New_York’, ‘UTC’) for explicit, reproducible results.

Default:

'local'

-Z, --bids-timezone <bids_timezone>

Timezone for naive BIDS acq_time values in _scans.tsv. Use ‘local’ or an IANA name (e.g. ‘UTC’). Defaults to ‘local’; set explicitly when the DICOM exporter uses a different clock than the ReproStim capture machine.

Default:

'local'

-m, --match <match>

Regular expression matched against the filename field of each scan record. Only matching records are processed; all others are skipped. Default ‘.*’ matches every record. Example: ‘func/’ to process functional scans only.

Default:

'.*'

-d, --dry-run

Analyse BIDS data and resolve matches but do not call split-video or write any output files. Prints what would be done to stdout.

-w, --overwrite <overwrite>

Policy for handling existing output files. ‘skip’: skip the scan if output already exists (default). ‘force’: remove existing file/symlink then re-inject (handles git-annex). ‘always’: run split-video as-is without an existence check. ‘error’: treat existing output as an error.

Default:

'skip'

Options:

skip | force | always | error

-k, --lock <lock>

Whether to acquire the advisory file lock (videos.tsv.lock) before reading videos.tsv. Use ‘no’ for dirty-read mode when the lock is held by a different OS user.

Default:

'yes'

Options:

yes | no

-v, --verbose

Enable verbose output.

Arguments

PATHS

Required argument(s)