sing4me 2.0.0

Python package for online and laboratory singing experiments

sing4me — Singing Experiments

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

sing4me is a Python package for singing extraction, optimized for laboratory and online singing experiments. It provides signal-processing code for sung-pitch extraction, plus a bundled Praat syllable_extract.praat script for syllable / rhythm extraction.

Quick Links

• Source code
• Issues

Citation

Please cite this package if you use it:

Anglada-Tort, M., Harrison, P. M., Lee, H., & Jacoby, N. (2023). Large-scale iterated singing experiments reveal oral transmission mechanisms underlying music evolution. https://doi.org/10.1016/j.cub.2023.02.070

Analysis code and datasets supporting the paper (2023): https://doi.org/10.17605/OSF.IO/UANGD

Installation

Prerequisites

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

Setting up a Virtual Environment

pip3 install virtualenv virtualenvwrapper

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

mkvirtualenv sing4me --python $(which python3)

The virtual environment is now active. To activate it later:

workon sing4me

Installing sing4me

To install the published package from PyPI:

pip install sing4me

To install from a source checkout in editable mode (this also installs the runtime dependencies declared in pyproject.toml):

git clone [e-mail]:computational-audition/sing4me.git
cd sing4me
pip install -e .

Optional extras:

• dev — flake8, black
• notebook — jupyter, sounddevice, soundfile (needed for the demo notebooks)
• publish — build, twine (only needed if you intend to build and upload a release to PyPI)

Install an extra with, e.g.:

pip install -e ".[notebook]"

Verify installation

sing4me --version

Running Demos

The demo notebooks in demos/ rely on the local input/ directory of sample audio. Those audio assets are not shipped with the PyPI distribution — clone the repository if you want to run the demos:

git clone [e-mail]:computational-audition/sing4me.git
cd sing4me
pip install -e ".[notebook]"
jupyter notebook

Then open one of:

• demos/singing_demo.ipynb
• demos/debug_singing_extract.ipynb

Sample Audio

The directory sing4me/tests/ in the source checkout contains a large collection of sample .wav / .png / .txt files used for manual / pilot inspection. Those samples are kept in the repository for development but are not shipped with the PyPI distribution (they would exceed PyPI's per-file limits). To use them, work from a source checkout.

A simple helper called generate_pilot_analysis_suite will generate plots and analysis for a directory of recordings:

generate_pilot_analysis_suite(
    audio_dir=os.path.dirname(here) + "/tests/good_2int/",
)

License

MIT License

Future Improvements

• Rename / clean up sing4me/tests/test_sing4me.py — it is a misleadingly-named manual debug script, not a real pytest test
• Add a tag-triggered PyPI publish job to the GitLab CI pipeline (using PyPI Trusted Publishing) so releases don't need to be uploaded from a developer's local venv
• Automate creation of a GitLab Release (with changelog and built artifacts) on every tagged version
• 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