{"id":18555477,"url":"https://github.com/vocalpy/vocalpy","last_synced_at":"2025-04-07T13:06:44.784Z","repository":{"id":154997154,"uuid":"626466384","full_name":"vocalpy/vocalpy","owner":"vocalpy","description":"A core package for acoustic communication research in Python","archived":false,"fork":false,"pushed_at":"2025-01-13T14:55:30.000Z","size":8807,"stargazers_count":35,"open_issues_count":85,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T12:08:49.800Z","etag":null,"topics":["acoustic-communication","animal-behavior","bioacoustics","python","vocalizations"],"latest_commit_sha":null,"homepage":"https://vocalpy.readthedocs.io/en/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vocalpy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-04-11T14:21:31.000Z","updated_at":"2025-03-28T09:31:15.000Z","dependencies_parsed_at":"2023-12-16T12:05:56.575Z","dependency_job_id":"9586697c-b349-482c-b7f3-27e51947a0c7","html_url":"https://github.com/vocalpy/vocalpy","commit_stats":{"total_commits":111,"total_committers":4,"mean_commits":27.75,"dds":0.2432432432432432,"last_synced_commit":"a12f9c1e7354296e76e6955f26fb1bd7b4a17dae"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vocalpy%2Fvocalpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vocalpy%2Fvocalpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vocalpy%2Fvocalpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vocalpy%2Fvocalpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vocalpy","download_url":"https://codeload.github.com/vocalpy/vocalpy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657281,"owners_count":20974345,"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":["acoustic-communication","animal-behavior","bioacoustics","python","vocalizations"],"created_at":"2024-11-06T21:26:50.136Z","updated_at":"2025-04-07T13:06:44.756Z","avatar_url":"https://github.com/vocalpy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://github.com/vocalpy/vocalpy/blob/main/docs/images/vocalpy-primary.png?raw=True\" width=\"400\"\u003e\n\u003c/div\u003e\n\u003chr\u003e\n\n## A core package for acoustic communication research in Python\n\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![Build Status](https://github.com/vocalpy/vocalpy/actions/workflows/ci.yml/badge.svg)](https://github.com/vocalpy/vocalpy/actions)\n[![Documentation Status](https://readthedocs.org/projects/vocalpy/badge/?version=latest)](https://vocalpy.readthedocs.io/en/latest/?badge=latest)\n[![DOI](https://zenodo.org/badge/159904494.svg)](https://zenodo.org/badge/latestdoi/159904494)\n[![PyPI version](https://badge.fury.io/py/vocalpy.svg)](https://badge.fury.io/py/vocalpy)\n[![PyPI Python versions](https://img.shields.io/pypi/pyversions/vocalpy)](https://img.shields.io/pypi/pyversions/vocalpy)\n[![codecov](https://codecov.io/gh/vocalpy/vocalpy/branch/main/graph/badge.svg?token=TXtNTxXKmb)](https://codecov.io/gh/vocalpy/vocalpy)\n[![All Contributors](https://img.shields.io/github/all-contributors/vocalpy/vocalpy?color=ee8449)](#contributors-)\n\nThere are many great software tools for researchers studying acoustic communication in animals[^1].\nBut our research groups work with a wide range of different data formats: for audio, for array data, for annotations. \nThis means we write a lot of low-level code to deal with those formats, \nand then our code for analyses is *tightly coupled* to those formats.\nIn turn, this makes it hard for other groups to read our code, \nand it takes a real investment to understand our analyses, workflows and pipelines.\nIt also means that it requires significant work to translate from a \npipeline or analysis worked out by a scientist-coder in a Jupyter notebook \ninto a generalized, robust service provided by an application.\n\nIn particular, acoustic communication researchers working with the Python programming language face these problems. \nHow can our scripts and libraries talk to each other?\nLuckily, Python is a great glue language! Let's use it to solve these problems.\n\nThe goals of VocalPy are to:\n- make it easy to work with a wide array of data formats: audio, array (spectrograms, features), annotation\n- provide classes that represent commonly-used data types: audio, spectograms, features, annotations\n- provide classes that represent common processes and steps in pipelines: segmenting audio, computing spectrograms, \n  extracting features\n- make it easier for scientist-coders to flexibly and iteratively build datasets, \n  without needing to deal directly with a database if they don't want to\n- make it possible to re-use code you have already written for your own research group\n- and finally: \n  - make code easier to share and read across research groups, by providing these classes, and *idiomiatic* ways \n    of coding with them; think of VocalPy as an interoperability layer and a common language\n  - facilitate collaboration between scientist-coders writing imperative analysis scripts and \n    [research software engineers](https://www.nature.com/articles/d41586-022-01516-2) \n    developing libraries and applications\n\nA [paper introducing VocalPy and its design](docs/fa2023/Introducing_VocalPy__a_core_Python_package_for_researchers_studying_animal_acoustic_communication.pdf) \nhas been accepted at [Forum Acusticum 2023](https://www.fa2023.org/) \nas part of the session \"Open-source software and cutting-edge applications in bio-acoustics\",\nand will be published in the proceedings.\n\n[^1]: For a curated collection, see \u003chttps://github.com/rhine3/bioacoustics-software\u003e.\n\n## Features\n\n###  Data types for acoustic communication data: audio, spectrogram, annotations, features\n\n#### The `vocalpy.Sound` data type\n\n- Works with a wide array of audio formats, thanks to [soundfile](https://github.com/bastibe/python-soundfile).\n- Also works with the cbin audio format saved by the LabView app EvTAF used by many neuroscience labs studying birdsong,\n  thanks to [evfuncs](https://github.com/NickleDave/evfuncs).\n\n```python\n\u003e\u003e\u003e import vocalpy as voc\n\u003e\u003e\u003e data_dir = ('tests/data-for-tests/source/audio_wav_annot_birdsongrec/Bird0/Wave/')\n\u003e\u003e\u003e wav_paths = voc.paths.from_dir(data_dir, 'wav')\n\u003e\u003e\u003e sounds = [voc.Sound.read(wav_path) for wav_path in wav_paths]\n\u003e\u003e\u003e print(sounds[0])\nvocalpy.Sound(data=array([3.0517...66210938e-04]), samplerate=32000, channels=1))\n```\n\n#### The `vocalpy.Spectrogram` data type\n\n- Save expensive-to-compute spectrograms to array files, so you don't regenerate them over and over again\n\n```python\n\u003e\u003e\u003e import vocalpy as voc\n\u003e\u003e\u003e data_dir = ('tests/data-for-tests/generated/spect_npz/')\n\u003e\u003e\u003e spect_paths = voc.paths.from_dir(data_dir, 'wav.npz')\n\u003e\u003e\u003e spects = [voc.Spectrogram.read(spect_path) for spect_path in spect_paths]\n\u003e\u003e\u003e print(spects[0])\nvocalpy.Spectrogram(data=array([[3.463...7970774e-14]]), frequencies=array([    0....7.5, 16000. ]), times=array([0.008,...7.648, 7.65 ]))\n```\n\n#### The `vocalpy.Annotation` data type\n\n- Load many different annotation formats using the pyOpenSci package [crowsetta](https://crowsetta.readthedocs.io/en/latest/)\n\n```python\n\u003e\u003e\u003e import vocalpy as voc\n\u003e\u003e\u003e data_dir = ('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/')\n\u003e\u003e\u003e notmat_paths = voc.paths.from_dir(data_dir, '.not.mat')\n\u003e\u003e\u003e annots = [voc.Annotation.read(notmat_path, format='notmat') for notmat_path in notmat_paths]\n\u003e\u003e\u003e print(annots[1])\nAnnotation(data=Annotation(annot_path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin.not.mat'), \nnotated_path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin'), \nseq=\u003cSequence with 57 segments\u003e), path=PosixPath('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/gy6or6_baseline_230312_0809.141.cbin.not.mat'))\n```\n\n### Classes for common steps in your pipelines and workflows\n\n#### A `Segmenter` for segmentation into sequences of units\n\n```python\n\u003e\u003e\u003e import evfuncs\n\u003e\u003e\u003e import vocalpy as voc\n\u003e\u003e\u003e data_dir = ('tests/data-for-tests/source/audio_cbin_annot_notmat/gy6or6/032312/')\n\u003e\u003e\u003e cbin_paths = voc.paths.from_dir(data_dir, 'cbin')\n\u003e\u003e\u003e audios = [voc.Sound.read(cbin_path) for cbin_path in cbin_paths]\n\u003e\u003e\u003e segment_params = {'threshold': 1500, 'min_syl_dur': 0.01, 'min_silent_dur': 0.006}\n\u003e\u003e\u003e segmenter = voc.Segmenter(callback=evfuncs.segment_song, segment_params=segment_params)\n\u003e\u003e\u003e seqs = segmenter.segment(audios, parallelize=True)\n[  ########################################] | 100% Completed | 122.91 ms\n\u003e\u003e\u003e print(seqs[1])\nSequence(units=[Unit(onset=2.19075, offset=2.20428125, label='-', audio=None, spectrogram=None),\n                Unit(onset=2.35478125, offset=2.38815625, label='-', audio=None, spectrogram=None),\n                Unit(onset=2.8410625, offset=2.86715625, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.48234375, offset=3.49371875, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.57021875, offset=3.60296875, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.64403125, offset=3.67721875, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.72228125, offset=3.74478125, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.8036875, offset=3.8158125, label='-', audio=None, spectrogram=None),\n                Unit(onset=3.82328125, offset=3.83646875, label='-', audio=None, spectrogram=None),\n                Unit(onset=4.13759375, offset=4.16346875, label='-', audio=None, spectrogram=None),\n                Unit(onset=4.80278125, offset=4.814, label='-', audio=None, spectrogram=None),\n                Unit(onset=4.908125, offset=4.922875, label='-', audio=None, spectrogram=None),\n                Unit(onset=4.9643125, offset=4.992625, label='-', audio=None, spectrogram=None),\n                Unit(onset=5.039625, offset=5.0506875, label='-', audio=None, spectrogram=None),\n                Unit(onset=5.10165625, offset=5.1385, label='-', audio=None, spectrogram=None),\n                Unit(onset=5.146875, offset=5.16203125, label='-', audio=None, spectrogram=None),\n                Unit(onset=5.46390625, offset=5.49409375, label='-', audio=None, spectrogram=None),\n                Unit(onset=6.14503125, offset=6.1565625, label='-', audio=None, spectrogram=None),\n                Unit(onset=6.31003125, offset=6.346125, label='-', audio=None, spectrogram=None),\n                Unit(onset=6.38996875, offset=6.4018125, label='-', audio=None, spectrogram=None),\n                Unit(onset=6.46053125, offset=6.4796875, label='-', audio=None, spectrogram=None),\n                Unit(onset=6.83525, offset=6.8643125, label='-', audio=None, spectrogram=None)], method='segment_song',\n         segment_params={'threshold': 1500, 'min_syl_dur': 0.01, 'min_silent_dur': 0.006},\n         audio=vocalpy.Sound(data=None, samplerate=None, channels=None), path=tests / data -\nfor -tests / source / audio_cbin_annot_notmat / gy6or6 / 032312 / gy6or6_baseline_230312_0809.141.cbin), spectrogram=None)\n```\n \n#### A `SpectrogramMaker` for computing spectrograms\n\n```python\n\u003e\u003e\u003e import vocalpy as voc\n\u003e\u003e\u003e wav_paths = voc.paths.from_dir('wav')\n\u003e\u003e\u003e audios = [voc.Sound(wav_path) for wav_path in wav_paths]\n\u003e\u003e\u003e spect_params = {'fft_size': 512, 'step_size': 64}\n\u003e\u003e\u003e spect_maker = voc.SpectrogramMaker(spect_params=spect_params)\n\u003e\u003e\u003e spects = spect_maker.make(audios, parallelize=True)\n```\n\n### And more!\n\nFor a crash course in VocalPy, please see the [quickstart](https://vocalpy.readthedocs.io/en/latest/getting_started/quickstart.html) \nin the [documentation](https://vocalpy.readthedocs.io/en/latest/index.html). \nAnd for walkthroughs on how to use VocalPy for common tasks, please see the [How-Tos](https://vocalpy.readthedocs.io/en/latest/user/howto/index.html) \nsection of the [user guide](https://vocalpy.readthedocs.io/en/latest/user/index.html).\n\n## Installation\n#### With `pip`\n```\npip install vocalpy\n```\n#### With `conda`\n```\nconda install vocalpy -c conda-forge\n```\nFor more detail see [Getting Started - Installation](https://vocalpy.readthedocs.io/en/latest/getting_started/installation.html)\n\n### Support\n\nTo report a bug or request a feature, \nplease use the issue tracker on GitHub:  \n\u003chttps://github.com/vocalpy/vocalpy/issues\u003e\n\nTo ask a question about vocalpy, discuss its development, \nor share how you are using it, \nplease start a new topic on the VocalPy forum \nwith the vocalpy tag:  \n\u003chttps://forum.vocalpy.org/\u003e\n\n### Contribute\n\n#### Code of conduct\n\nPlease note that this project is released with a [Contributor Code of Conduct](./CODE_OF_CONDUCT.md).\nBy participating in this project you agree to abide by its terms.\n\n#### Contributing Guidelines\n\nBelow we provide some quick links, \nbut you can learn more about how you can help and give feedback  \nby reading our [Contributing Guide](./CONTRIBUTING.md).\n\nTo ask a question about vocalpy, discuss its development, \nor share how you are using it, \nplease start a new \"Q\u0026A\" topic on the VocalPy forum \nwith the vocalpy tag:  \n\u003chttps://forum.vocalpy.org/\u003e\n\nTo report a bug, or to request a feature, \nplease use the issue tracker on GitHub:  \n\u003chttps://github.com/vocalpy/vocalpy/issues\u003e\n\n### CHANGELOG\nYou can see project history and work in progress in the [CHANGELOG](./docs/CHANGELOG.md)\n\n### License\n\nThe project is licensed under the [BSD license](./LICENSE).\n\n### Citation\nIf you use vocalpy, please cite the DOI:  \n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7905426.svg)](https://doi.org/10.5281/zenodo.7905426)\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/ralphpeterson\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/4031329?v=4?s=100\" width=\"100px;\" alt=\"Ralph Emilio Peterson\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRalph Emilio Peterson\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-ralphpeterson\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"#userTesting-ralphpeterson\" title=\"User Testing\"\u003e📓\u003c/a\u003e \u003ca href=\"https://github.com/vocalpy/vocalpy/commits?author=ralphpeterson\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/vocalpy/vocalpy/issues?q=author%3Aralphpeterson\" title=\"Bug reports\"\u003e🐛\u003c/a\u003e \u003ca href=\"https://github.com/vocalpy/vocalpy/commits?author=ralphpeterson\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/tkoyama010\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/7513610?v=4?s=100\" width=\"100px;\" alt=\"Tetsuo Koyama\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eTetsuo Koyama\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/vocalpy/vocalpy/commits?author=tkoyama010\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/avanikop\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/39831515?v=4?s=100\" width=\"100px;\" alt=\"avanikop\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eavanikop\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"#ideas-avanikop\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvocalpy%2Fvocalpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvocalpy%2Fvocalpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvocalpy%2Fvocalpy/lists"}