Installation¶

reprostim is packaged and available from many different sources.

Dependencies¶

Make sure you have strict Python version/venv especially for sub-commands working with PsychoPy like timesync-stimuli. Recommended Python version is 3.10 ATM:

qr-parse subcommand requires zbar to be installed:

On Debian
```
    apt-get install -y libzbar0
```
On MacOS
```
    brew install zbar
```
NOTE: Consider this conversation in case of problems to install it @MacOS: https://github.com/ReproNim/reprostim/pull/124#issuecomment-2599291577

timesync-stimuli sub-command requires in psychopy and portaudio to be installed:

On Debian
```
    apt-get install portaudio19-dev
```
On MacOS
```
    brew install portaudio
```

reprostim-videocapture utility works only on Linux and requires in the following packages (build and runtime):

    apt-get install -y ffmpeg libudev-dev libasound-dev libv4l-dev libyaml-cpp-dev libspdlog-dev catch2 v4l-utils libopencv-dev libcurl4-openssl-dev nlohmann-json3-dev cmake g++

Optionally, con/duct tool is used to monitor and log system info for the video capture with ffmpeg:

    pip install con-duct
    duct --version

Local¶

Released versions of reprostim are available on PyPI and conda. If installing through PyPI, e.g. :

    pip install reprostim[all]

On Debian-based systems, we recommend using NeuroDebian as a basic environment.

reprostim-videocapture utility is not available as a separate package at the moment, and it should be built from the source manually like described below in Developers Install section.

Then, to install the project binaries under /usr/local/bin, once the build done, run the following command:

    cd src/reprostim-capture

    cmake --install build

And make sure the system in configured as described in Hardware Setup section.

Singularity¶

If Singularity is available on your system, you can use it to run pre-built containers available at DataLad.

Note: at this moment the latest containers are not uploaded to the DataLad.

Container binaries stored in format like repronim-reprostim-{VERSION}.sing there, e.g.: repronim-reprostim-0.7.27.sing.

So, download containers first from DataLad:

datalad install https://datasets.datalad.org/repronim/containers
datalad update
cd ./containers/images/repronim
datalad get .

And use necessary container binary to run reprostim commands.

export REPROSTIM_PATH={Specify path to the reprostim repo}

singularity exec \
  --cleanenv --contain \
  -B /run/user/$(id -u)/pulse \
  -B ${REPROSTIM_PATH} \
  --env DISPLAY=$DISPLAY \
  --env PULSE_SERVER=unix:/run/user/$(id -u)/pulse/native \
  ./containers/images/repronim/repronim-reprostim-0.7.27.sing \
  reprostim timesync-stimuli -t 10 --mode interval

More details can be found in Container repronim-reprostim section.

Reproiner¶

We have installed and configured reprostim-videocapture utility on reproiner Debian box manually as it’s not available as a package yet.

Utility configuration and captured video files are stored under /data/reprostim/ location. The config.yaml file was copied from default GitHub version and manually modified to match the system, connected devices and reproiner environment. This directory should be used as working directory for reprostim-videocapture utility.

  ssh reprostim@reproiner

  cd /data/reprostim

Video files are stored under /data/reprostim/Videos/ location.

We use screen utility to run sessions in the background, under reprostim user and share it between other users. The command below will list all available sessions:

    screen -ls

And connect to the target session with reprostim-videocapture utility with:

    screen -r <SESSION_ID>

To create the latest build - checkout reprostim project, build and install it as described in Developers Install and Local sections.

    git clone https://github.com/ReproNim/reprostim.git

    cd src/reprostim-capture

    mkdir build
    cd build
    cmake ..
    make

    cd ..
    cmake --install build

As result, it will install reprostim package under /usr/local/bin location.

Usually in screen we have multiple sessions running under /data/reprostim/ location like listed below:

(A) reprostim proc to run reprostim-videocapture utility:

  reprostim-videocapture -d /data/reprostim -f /data/reprostim/logs/$(date --iso=minutes).log

Note: when manually restarting reprostim-videocapture utility, make sure that old ffmpeg and reprostim-videocapture processes are killed first, e.g.:

  ps aux | grep videocapture
  ps aux | grep ffmpeg

(B) reprostim logs to view logs in realtime, e.g.:

  tail -f /data/reprostim/logs/2024-06-21T08:38-04:00.log

(C) repromon podman to run repromon service.

  cd /home/reprostim/repromon

  ( set -a &&  source ./.env.dev && podman-compose  -f docker-compose.dev.yml up -d  ; )

  podman ps -a
  podman logs repromon_db_1
  podman logs repromon_web_1

(D) bash to monitor system and run miscellaneous tasks.

Recently were added cron job to run reprostim-videocapture utility automatically under /data/reprostim/code/reprostim-videocapture-cron location.

Videos captured by reprostim-videocapture utility @reproiner under /data/reprostim/Videos location are populated and distributed to other servers (like rolando or typhon) with git-annex assistant help. E.g. @typhon git-annex repository is stored under /data/repronim/reprostim-reproiner location.

Developers Install¶

reprostim-videocapture utility can be built from source with CMake:

    cd src/reprostim-capture

    mkdir build
    cd build
    cmake ..
    make

If you want to build reprostim from source locally for development purposes, you can do this by cloning the repository . To build the project, use hatch and venv with preferable Python 3.10 version:

    # first setup python and hatch
    python3.10 -m venv venv
    source venv/bin/activate
    pip install --upgrade pip
    pip install hatch

    # build reprostim package
    hatch build reprostim

    # optionally re-create env
    hatch env remove
    hatch env create

    # install all extra dependencies
    hatch run pip install -e .[all]

    # run some reprostim commands, e.g.:
    hatch run reprostim --help
    hatch run reprostim --version
    hatch run reprostim echo 'Hello ReproStim CLI!'

Note: in case hatch run pip install -e .[all] fails with errors like ERROR: Failed building wheel for wxPython, try to install wxPython package manually from https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ specifying appropriate OS and Python version, e.g.:

    hatch run pip install https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-24.04/wxpython-4.2.3-cp310-cp310-linux_x86_64.whl
    sudo apt install libsdl2-2.0-0

Hardware Setup¶

Setup USB device with “udev” access¶

The reprostim-videocapture utility internally uses Magewell Capture SDK and to make it working properly should be executed under “root” account or in case of other account - special “udev” rules should be applied there. Program will produce following error when executed in environment without proper ownership and permissions for informational purposes:

ERROR[003]: Access or permissions issue. Please check /etc/udev/rules.d/ configuration and docs.

For more information refer to item #14 from Magewell FAQ on https://www.magewell.com/kb/detail/010020005/All :

14. Can the example codes associated with USB Capture (Plus) devices in SDKv3 work
    without root authority (sudo) on Linux?

Yes. Click here to download the file "189-usbdev.rules" (http://www.magewell.com/files/sdk/189-usbdev.zip) ,
move it to the directory "/etc/udev/rules.d", and then restart your computer.

NOTE: Also make sure that no other processes like ffmpeg, vlc, etc. are using this video device, as it can accidentally produce the same error message ERROR[003].

1) Identify the USB Device:¶

This is optional step, only for information purposes:

    lsusb

And locate line with device, e.g.:

Bus 004 Device 012: ID 2935:0008 Magewell USB Capture DVI+

In this sample, 2935 is the “Vendor ID”, and 0008 is the “Product ID”.

Optionally Magewell device name and serial number can be quickly checked with this command:

    lsusb -d 2935: -v | grep -E 'iSerial|iProduct'

2) Create “udev” rules¶

Create text file under “/etc/udev/rules.d/189-reprostim.rules” location with appropriate content depending on system type.

For an active/desktop user logged in via session manager it should be like:

ACTION=="add", SUBSYSTEM=="usb", ATTR{idVendor}=="2935", TAG+="uaccess"

For a daemon configuration we should provide explicit permissions like:

SUBSYSTEM=="usb", ATTR{idVendor}=="2935", MODE="0660", OWNER="reprostim", GROUP="plugdev"

Note: we can see that “ATTR{idVendor}” value 2935 is equal to one we got in step 1) from lsusb utility.

Also sample udev rules configuration added to project under “src/reprostim-capture/etc/udev/189-reprostim.rules” location.

Note: make sure the file has owner “root”, group “root” and 644 permissions:

    ls -l /etc/udev/rules.d/189*

    -rw-r--r-- 1 root root 72 ... /etc/udev/rules.d/189-reprostim.rules

3) Add user to “plugdev” group¶

Make sure the user running reprostim-videocapture utility is a member of the “plugdev” group, e.g.:

    sudo usermod -aG plugdev TODO_user

4) Restart computer¶

Restart computer to make changes effect.

Note: we tested “sudo udevadm control –reload-rules” command without OS restart, but somehow it didn’t help, and complete restart was necessary anyway.