Develop a script to "slice" videos to "match" DICOM series timing

[yarikoptic]

• blocked by Oddity of "jumping offset" of DICOM's AcquisitionTime across sequences #109 to produce purely based on DICOMs timing data. Most likely need to rely on QR codes embediment
• initial script: can assume that all clocks (of reproiner and in DICOMs) are perfectly synchronized
  • I think the script should have an option to allow for a "buffer" time at the beginning/end and record that in some sidecar json file, on how many s.econds of buffer were added. This would allow later to adjust those numbers to account for in the anslysis of the video without changing/reslicing video itself
• exact alignment would dependent on the outcome of findings in Synchronization (or tracking of offset) of involved clocks #13 on either we could establish exact account of the DICOMs clock drift/offset or should resort to additional workarounds

[yarikoptic]

Might be worth aiming right away for BIDS datasets - information from _scans.tsv an possibly side car .json files (on duration).

[yarikoptic]

Script (ideally in python) should take

• location of not sliced videos
• beginning absolute time parameter
• end time or duration parameter
• optional "parameters" of how much of "buffer" to take before/after video begins/ends so we could account for time imprecision
  • all durations should accept either simple float for seconds (e.g. 121) , or ISO 8601 duration (P2M1S. note: isodurations does not take this value - wants a date! odd)
  • precision of ms is enough
  • if buffers go outside of the video times -- trim to video (so to 0 on the left, and total length on the right) and store (see below) actual values in the .json
  • if video itself doesn't overlap fully with desired time/duration -- for now just error
    • specific case: it was multiple (more than 1 video) videos captured for the single desired time duration -- we do not bother ATM to somehow join them.
• output .mkv filename.
  • in addition to .mkv generate or update (if exists) side car .json file with annotation of the parameters etc provided into "reprostim-videocapture" field. Should contain "onset" (ISO 8601 time, no date), "duration", "buffer-before", "buffer-after" in seconds (up to .ms), all reprostim-videocapture metadata from the log (log reprostim metadata as json #83) .
  • Do not store absolute dates anywhere. Times are ok, not dates

example:

reprostim-slice --buffer-before 10 --buffer-after 10 --start 2024-02-02T17:30:00 --duration P3M  --input $VIDEOS/2024.02.02.17.20.38.680_2024.02.02.17.20.44.774.mkv --output $BIDS/sub-01/func/sub-01_task-rest_bold.mkv 

in case of input filename not satisfying the pattern to have starting time -- error

@jwodder -- please provide guidance on the python project template to start with, or tools to use. I would expect you to provide review of this work in the future.

[jwodder]

@yarikoptic

please provide guidance on the python project template to start with, or tools to use

What kind of guidance? Most decisions about Python project tooling are ultimately opinion-based, as there is no One True Packaging Tool.

[yarikoptic]

Continuing on above: I think that overall we need multiple tools

1. split-video which could be used independently of the overall setup with videos.tsv etc. Should take specification for splitting, template for output filename(s), and overloads on command line (like buffer durations). It should have option to produce .json file with result records depicting exact buffers etc durations (e.g. if we specified buffer of 10 sec, but start from 2nd second, we could have only 2 seconds buffer in the beginning). May be add an option --buffers=flexible,strict so if strict, would error out if buffer cannot be fulfilled
   • likely might be just a wrapper around ffmpeg invocation
   • input specification should have set of records with starttime, endtime, filename template which could potentially embed all those + extra metadata field in the record like title or some other.
   • think about it to be used to produce files for a BIDS dataset (next command), so filename pattern would be to be placed into a BIDS dataset, see [ENH] BEP044 - Stim-BIDS bids-standard/bids-specification#2022
   • think also that this tool could potentially be used to cut up a longer video into shorter ones, like was done for full conference sessions on distribits: https://hub.datalad.org/distribits/recordings/src/branch/master/code/video_job.sh
2. bids-inject -- this will analyze provided videos.tsv and should craft invocation(s) for split-video command to place files into a provided BIDS dataset.
   • as I described in https://github.com/bids-standard/bids-specification/pull/2022/changes#r2623971414, we will just need for every data file (.nii.gz) in the dataset (there might be multiple for the same acquisition like for different _echo etc), take invocation from _scans.tsv file from above folder on when it was acquired, and then split-video corresponding video files to match the duration of that data file(s).
   • datetime for the beginning of the data file acquisition could be found in the _scans.tsv file like ../dbic-QA/sub-qa/ses-20250814/sub-qa_ses-20250814_scans.tsv and the tricky part is only "duration", for which we will use following procedure
     • if sidecar .json file for the data file has FrameAcquisitionDuration -- use that one
     • otherwise ... (to be decided so it is robust for anatomicals as well, may be would do first in heudiconv Add helper to populate FrameAcquisitionDuration field nipy/heudiconv#844)
   • if to process .tsv files, should get a regex to select only some files (e.g. only func/) and default to all
   • add option --time-offset so we could specify what was anonymization offset used in that BIDS dataset (like e.g. we did for https://github.com/spatialtopology/ds005256/blob/master/sub-0001/ses-01/sub-0001_ses-01_scans.tsv)
   • add column in _scans.tsv for that data file(s) on the offsets before/after (names of column(s) to be decided)
   • think-for-future: we might have QR codes already in the videos, and analysis one and reflected in videos.tsv, thus we might do better analysis based on them for splitting the video thus potentially pairing with next command efficiently (not requiring re-scanning).
3. bids-qr-sync - given a video recording, we could analyze for QR codes and
   • extract into some supplemental file e.g. _stim-reprostim_qrcodes.tsv for all those records found
   • expand information in _scans.tsv with exact timepoints in the _stim- video file for beginning/end of stimuli recording (since we have buffers at beginning/end based solely on NTP sync, and we know that there is odd jitter of trigger pulses relative to AcquisionTime, Oddity of "jumping offset" of DICOM's AcquisitionTime across sequences #109 )