REPP: Large-Scale Online Tapping Experiments

Manuel Anglada-Tort, Peter Harrison, and Nori Jacoby
Computational Auditory Perception Group
Max Planck Institute for Empirical Aesthetics

REPP (Rhythm ExPeriment Platform) is a Python package for measuring sensorimotor synchronization (SMS) in laboratory and online settings.

Quick Links

• Documentation
• Source Code
• Dataset - Tapping datasets supporting the paper (2022)

Citation

If you use this package, please cite:

Anglada-Tort, M., Harrison, P.M.C. & Jacoby, N. REPP: A robust cross-platform solution for online sensorimotor synchronization experiments. Behavior Research Methods (2022). https://doi.org/10.3758/s13428-021-01722-2

Installation

Prerequisites

• Python 3.9 or newer (tested with 3.9–3.13)
• macOS (primary testing platform)

Setting up a Virtual Environment

1. Install virtualenv and virtualenvwrapper:

pip3 install virtualenv virtualenvwrapper

2. Configure virtualenvwrapper:

export WORKON_HOME=$HOME/.virtualenvs
mkdir -p $WORKON_HOME
export VIRTUALENVWRAPPER_PYTHON=$(which python3)
source $(which virtualenvwrapper.sh)

3. Create and activate virtual environment:

mkvirtualenv repp --python $(which python3)

Optional: Add to shell configuration (~/.zshrc):

echo "export VIRTUALENVWRAPPER_PYTHON=$(which python3)" >> ~/.zshrc
echo "source $(which virtualenvwrapper.sh)" >> ~/.zshrc

To activate the environment later:

workon repp

Installing REPP

The published distribution name is repp-tapping, while the Python import namespace and CLI remain repp for compatibility.

1. Clone the repository:

git clone git@gitlab.com:computational-audition-lab/repp.git

2. Navigate to the project directory:

cd repp

3. Install REPP in editable mode (this also installs all runtime dependencies declared in pyproject.toml):

pip3 install -e .

To install the published package from an index instead of a local checkout:

pip3 install repp-tapping

4. Verify installation:

repp --version

Running Tests

Basic test execution:

# Run all tests in the project
pytest -v -s

# Run a specific test file
pytest tests/test_repp.py
pytest tests/test_signal_processing.py -v
pytest tests/test_analysis.py -v
pytest tests/test_stimulus.py -v

Requirements

Runtime dependencies (installed automatically with pip install repp-tapping):

• numpy
• scipy
• matplotlib
• click

Optional extras:

• dev — pytest, flake8, black
• docs — sphinx, sphinx-rtd-theme
• notebook — jupyter, sounddevice, soundfile (needed to run the demo notebooks)

Install an extra with, e.g.:

pip install -e ".[dev]"

The full list and any version constraints are declared in pyproject.toml.

Contributors

• Vani Rajendran: Developed analysis and plotting methods for beat detection tasks (see beatfinding_cyclic demo)

Contributing

We welcome contributions supporting new paradigms or improvements to the current code. Please contact the authors if you would like to contribute.

Running Demos

REPP comes with several demo notebooks to help you get started. The demos live in the source repository (under demos/) and rely on sample audio assets in input/. Those assets are kept in the repository but are not shipped with the PyPI distribution (they are too large for PyPI's per-file limits). To run the demos you need a source checkout of the GitLab repository.

1. Activate your virtual environment if not already active:

workon repp

2. Install the notebook extras:

pip install -e ".[notebook]"

3. Start Jupyter Notebook:

jupyter notebook

4. Navigate to the demos/ directory in the Jupyter interface and open any of the available demos:

• sms_tapping.ipynb: SMS tapping experiments, including metronome and music
• unconstrained_tapping.ipynb: Unconstrained tapping paradigms, including free and fast tapping
• debug_recording.ipynb: Debugging and troubleshooting examples
• beat_detection.ipynb: Beat-detection workflow using repp.extensions.beat_detection
• beat_finding.ipynb: Beat-finding demo using a repeating audio token
• beat_finding_prerecorded.ipynb: Beat-finding analysis using prerecorded audio
• beatfinding_cyclic.ipynb: Cyclic beat-finding analysis and visualization
• iterated_tapping.ipynb: Iterated tapping workflow using repp.extensions.iterated_tapping
• itap_memory.ipynb: Memory-based iterated tapping workflow

License

MIT License

Future Improvements

• Add type hints and a py.typed marker
• Add code-formatting and linting configuration (black/ruff/flake8)
• Add CONTRIBUTING.md and CODE_OF_CONDUCT.md
• Add a tag-triggered PyPI publish job to the GitLab CI pipeline (using PyPI Trusted Publishing)
• Automate creation of a GitLab Release (with changelog and built artifacts) on every tagged version
• Add more robust error handling
• Improve demos