{"id":23442298,"url":"https://github.com/repronim/reprostim","last_synced_at":"2025-04-13T11:10:58.810Z","repository":{"id":37679365,"uuid":"243008647","full_name":"ReproNim/reprostim","owner":"ReproNim","description":"Automated capture of audio-visual stimuli into BIDS datasets","archived":false,"fork":false,"pushed_at":"2025-04-07T18:13:49.000Z","size":36440,"stargazers_count":5,"open_issues_count":41,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-07T18:27:28.118Z","etag":null,"topics":["neuroimaging","psychology","reproducible-research"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/reprostim/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ReproNim.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSES/MIT.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-25T13:39:40.000Z","updated_at":"2025-03-18T11:46:22.000Z","dependencies_parsed_at":"2025-03-24T16:36:39.777Z","dependency_job_id":null,"html_url":"https://github.com/ReproNim/reprostim","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReproNim%2Freprostim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReproNim%2Freprostim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReproNim%2Freprostim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ReproNim%2Freprostim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ReproNim","download_url":"https://codeload.github.com/ReproNim/reprostim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248703198,"owners_count":21148118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neuroimaging","psychology","reproducible-research"],"created_at":"2024-12-23T17:29:19.218Z","updated_at":"2025-04-13T11:10:58.801Z","avatar_url":"https://github.com/ReproNim.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ReproStim Introduction\n\nReproStim is a video capture and recording suite for neuroimaging and\npsychology experiments.  Its goal is to provide experimenters with a\ncomplete record of audio and visual stimulation for every data collection\nsession by making it possible to easily collect high fidelity copies of the\nactual stimuli shown to each subject in the form of video files that can be\nstored alongside  behavioral or neuroimaging data in public repositories.\n\nReproStim provides for enhanced experimental reproducibility and a safeguard\nagainst data loss in cases of data-collection irregularites.  Because\nReproStim provides an exact record of the actual stimuli delivered during\nany given experimental session, it makes it possible to precisely reproduce\nexperimental sessions, even if the original trial sets were randomized and\nprecise trial details not recorded. In cases of experimental irregularities,\nsuch as aborted fMRI runs, unexpected glitches in trial timing, or\nprogramming errors that cause records of trial conditions to be lost,\nvaluable data (which can be especially costly in cases of fMRI of ECog, for\nexample) can be recoded and recovered using the audio-visual record provided\nby ReproStim.\n\nReproStim requires minimal effort on behalf of investigators.  Once it is\nsetup as the default mode within a behavioral lab or neuroimaging center,\ninvestigators can reap the benefits of ReproStim without any additional\neffort on the part of invidiual experimenters.  When successfully set up,\nReproStim runs in the background, silently collecting, cataloging, and\nstoring all audio and visual stimulation delivered to experimental subjects.\n\n# Development\n\n## Hardware needed\n\nBefore using ReproStim you will need a minimum of the the following\ncomponents:\n\n1. Magewell USB Capture Plus device (MWC)\n\n2. Stimulus control computer (SC) with A/V out to presentation device\n\n3. External presentation device (EPD)\n\n4. Video capture computer (VC) with USB-C port\n\n5. Supporting cables including A/V splitter cables\n\n### Simple setup schematic\n\nGiven a stimulus presentation computer (SP) that controls the content and\nflow of the experimental presentation and presents A/V to experimental\nsubject on external monitor or projector (EPD), the setup without ReproStim\nwould be something like:\n\n1. Schematic A.\n\n       ------                -------\n       | SC | -- A/V Out --\u003e | EPD |\n       ------                -------\n\n    With the addition of ReprosStim, the setup will look like this:\n\n2. Schematic B.\n\n       ------                                 -------\n       | SC | -- A/V Out --\u003e A/V Splitter --\u003e | EPD |\n       ------                     |           -------\n                                  V\n                               -------              ------\n                               | MWC | -- USB-C --\u003e | VC |\n                               -------              ------\n\n### Original set up without ReproStim\n\nMost experimental setups include something like Schematic A, with a stimulus\ncontrol computer (SC) that sends A/V information to the experimental\nsubject. For example, in the Dartmouth Brain Imaging Center (DBIC),\nexperimenters can use their own laptop or a dedicated computer in the scan\ncontrol room for SC. The External Presentation Device for video (EPDv) in\nthe DBIC MRI suite is a projector that projects through the wall of the\nshielded scan room to a rear-projection screen located at the back of the\nMRI scanner bore; and the EPDa (audio) comprises MRI-safe headphones worn on\nthe subject's head.\n\nThe A/V out connections from SC can be any standard as long as you have the\nappropriate adapters, dongles, etc. However, if your Video out does not\nsupport embedded audio (e.g. VGA), then you will need a separate audio out\nset of splitters and cables. The Magewell device has standard audio ports to\naccommodate this eventuality.\n\nNote: Missing from Schematics A and B, is any connection back to SC that\nrecords subject response information. That's because ReproStim is not\ninterested in how the subject responds. If you like, imagine arrows pointing\nfrom EPD to a \"subject\" node, and then more arrows pointing from the subject\nnode to some response input device (RID?) and back to SC for recording...\nReproStim will not interfere.\n\n#### Magewell USB Capture Plus Family device\n\nThe current version of ReproStim has only been developed and tested for the\nMagewell USB Capture DVI Plus device (MWC) . However, we anticipate that it\nwill be relatively painless to support at least all devices in the USB\nCapture Plus Family. Information about these devices and supporting software\ncan all be found at www.magewell.com\n\n#### Video Capture computer (VC), AKA ReproStim Server\n\nThe video capture computer (VC) does most of the work for ReproStim. The\nsoftware running on this computer runs as a service that is always on as\nlong as the computer is running, which is all the time. Therefore I will\nrefer to VC also as the ReproStim server. In a nutshell, the server software\nmonitors the video signal coming from SC into MWC. If there is any video\ncoming over the connection, it gets recorded for posterity.\n\nCurrent development of ReproStim, including our working setup at the DBIC,\nuses a Linux box running Debian Linux. We anticipate that any Nix/Mac setup\nrunning on a modern desktop will be amply sufficient as a ReproStim Server,\nand should be relatively painless to configure.\n\nThe current DBIC computer is a small-profile desktop that resides in the\ncontrol of the scan suite, quietly recording all video presented to all\nsubjects.\n\n# reprostim-capture\n\nThis subproject is set of native C/C++ tools and utilities to capture\nvideo/audio signals with Magewell USB Capture devices and save it to a file.\nMore detailed information about dependencies and installation provided in\n[reprostim-capture README.md](./src/reprostim-capture/README.md).\n\n\n# reprostim CLI\n\nRepresented as a set of Python tools and utilities under the umbrella of\nthe `reprostim` library, where each tool is a separate subcommand of\nthe `reprostim` CLI.\n\n## Dependencies\n\n`qr-parse` subcommand requires `zbar` to be installed:\n - On Debian\n   ```shell\n       apt-get install -y libzbar0\n   ````\n - On MacOS\n   ```shell\n       brew install zbar\n   ```\n   NOTE: Consider this conversation in case of problems to install it @MacOS:\n         https://github.com/ReproNim/reprostim/pull/124#issuecomment-2599291577\n\n`timesync-stimuli` subcommand requires in `psychopy` and `portaudio` to\nbe installed:\n - On Debian\n   ```shell\n       apt-get install portaudio19-dev\n   ```\n - On MacOS\n   ```shell\n       brew install portaudio\n   ```\n\n\n## Installation\n\nMake sure you have strict Python version/venv especially for subcommands working\nwith psychopy like `timesync-stimuli`. Recommended Python version is 3.10 ATM:\n\n```shell\n    python3.10 -m venv venv\n    source venv/bin/activate\n    pip install --upgrade pip\n    python3 --version\n```\n\nThen it can be installed from PyPI:\n\n```shell\n    pip install reprostim\n```\n\n## Build\n\nTo build the project, use `hatch` and `venv` with preferable Python version:\n\n```shell\n    # first setup python and hatch\n    python3.10 -m venv venv\n    source venv/bin/activate\n    pip install --upgrade pip\n    pip install hatch\n\n    # build reprostim package\n    hatch build reprostim\n\n    # optionally re-create env\n    hatch env remove\n    hatch env create\n\n    # install all extra dependencies\n    hatch run pip install .[all]\n\n    # run some reprostim commands, e.g.:\n    hatch run reprostim --help\n    hatch run reprostim --version\n    hatch run reprostim echo 'Hello ReproStim CLI!'\n```\n\n## Subdirectories Structure\n\n### src/reprostim\n\nContains all code for `reprostim` library.\n\n### src/reprostim-capture\n\nContains all code needed for setting up video capture. This includes C++\ncode for interfacing with the video capture device, and scheme for setting\nup a video-capture \"server\", along with helper utilities.\n\n### tests\n\nDirectory with reprostim pytests and test data.\n\n\n### **_Obsolete:_** QRCoding\n\nContains utilities for embedding QR codes in experimental stimulus-delivery\nprograms, such as PsychoPy, or PsychToolbox scripts.\n\n### **_Obsolete:_**  Parsing\n\nContains code needed for segmenting videos to include just the parts of the\nvideos that are demarcated by embedded QR codes marking the beginning and\nend of experimental runs. There are also helper tools for identifying\nexperimental runs and matching them to the parent experimental paradigm and\nneuroimaging data acquisitions.\n\n# Hardware Installation and Configuration\n\n## Setup USB device with \"udev\" access\n\nThe `reprostim-videocapture` utility internally uses Magewell Capture SDK and to\nmake it working properly should be executed under \"root\" account or in case of\nother account - special \"udev\" rules should be applied there. Program will\nproduce following error when executed in environment without proper ownership\nand permissions for informational purposes:\n\n    ERROR[003]: Access or permissions issue. Please check /etc/udev/rules.d/ configuration and docs.\n\nFor more information refer to item #14 from Magewell FAQ on https://www.magewell.com/kb/detail/010020005/All :\n\n    14. Can the example codes associated with USB Capture (Plus) devices in SDKv3 work\n        without root authority (sudo) on Linux?\n\n    Yes. Click here to download the file \"189-usbdev.rules\" (http://www.magewell.com/files/sdk/189-usbdev.zip) ,\n    move it to the directory \"/etc/udev/rules.d\", and then restart your computer.\n\nNOTE: Also make sure that no other processes like ffmpeg, vlc, etc are using this video device, as\nit can accidentally produce the same error message ERROR[003].\n\n### 1) Identify the USB Device:\n\nThis is optional step, only for information purposes:\n\n```shell\n    lsusb\n```\n\nAnd locate line with device, e.g.:\n\n    Bus 004 Device 012: ID 2935:0008 Magewell USB Capture DVI+\n\nIn this sample, 2935 is the \"Vendor ID\", and 0008 is the \"Product ID\".\n\nOptionally Magewell device name and serial number can be quickly checked with this command:\n\n```shell\n    lsusb -d 2935: -v | grep -E 'iSerial|iProduct'\n```\n\n### 2) Create \"udev\" rules\nCreate text file under \"/etc/udev/rules.d/189-reprostim.rules\" location with\nappropriate content depending on system type.\n\nFor an active/desktop user logged in via session manager it should be like:\n\n    ACTION==\"add\", SUBSYSTEM==\"usb\", ATTR{idVendor}==\"2935\", TAG+=\"uaccess\"\n\nFor a daemon configuration we should provide explicit permissions like:\n\n    SUBSYSTEM==\"usb\", ATTR{idVendor}==\"2935\", MODE=\"0660\", OWNER=\"reprostim\", GROUP=\"plugdev\"\n\nNote: we can see that \"ATTR{idVendor}\" value 2935 is equal to one we got in\nstep 1) from lsusb utility.\n\nAlso sample udev rules configuration added to project under\n\"src/reprostim-capture/etc/udev/189-reprostim.rules\" location.\n\nNote: make sure the file has owner \"root\", group \"root\" and 644 permissions:\n\n```shell\n    ls -l /etc/udev/rules.d/189*\n````\n```\n    -rw-r--r-- 1 root root 72 ... /etc/udev/rules.d/189-reprostim.rules\n```\n\n### 3) Add user to \"plugdev\" group\nMake sure the user running `reprostim-videocapture` utility is a member of the\n\"plugdev\" group, e.g.:\n\n```shell\n    sudo usermod -aG plugdev TODO_user\n```\n\n### 4) Restart computer\nRestart computer to make changes effect.\n\nNote: we tested \"sudo udevadm control --reload-rules\" command without OS\nrestart, but somehow it didn't help, and complete restart was necessary\nanyway.\n\n\n## TODO:\n\n- Build (per above) and install in the PATH\n- TODO: cron job\n- TODO: add user/group\n- ...\n- [Parsing/repro-vidsort](./Parsing/repro-vidsort) script (has hardcoded paths) sorts from `incoming/` to\n  folders per DICOM accession\n-\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frepronim%2Freprostim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frepronim%2Freprostim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frepronim%2Freprostim/lists"}