Open source, scalable acoustic classification for ecology and conservation
Project description
OpenSoundscape
OpenSoundscape is a utility library for analyzing bioacoustic data. It consists of Python modules for tasks such as preprocessing audio data, training machine learning models to classify vocalizations, estimating the spatial location of sounds, identifying which species' sounds are present in acoustic data, and more.
These utilities can be strung together to create data analysis pipelines. OpenSoundscape is designed to be run on any scale of computer: laptop, desktop, or computing cluster.
OpenSoundscape is currently in active development. If you find a bug, please submit an issue. If you have another question about OpenSoundscape, please email Sam Lapp (sam.lapp
at pitt.edu
).
Suggested Citation
Lapp, Rhinehart, Freeland-Haynes, Khilnani, and Kitzes, 2022. "OpenSoundscape v0.7.0".
Installation
OpenSoundscape can be installed on Windows, Mac, and Linux machines. It has been tested on Python 3.7 and 3.8.
Most users should install OpenSoundscape via pip: pip install opensoundscape==0.7.0
. Contributors and advanced users can also use Poetry to install OpenSoundscape.
For more detailed instructions on how to install OpenSoundscape and use it in Jupyter, see the documentation.
Features & Tutorials
OpenSoundscape includes functions to:
- load and manipulate audio files
- create and manipulate spectrograms
- train CNNs on spectrograms with PyTorch
- run pre-trained CNNs to detect vocalizations
- detect periodic vocalizations with RIBBIT
- load and manipulate Raven annotations
OpenSoundscape can also be used with our library of publicly available trained machine learning models for the detection of 500 common North American bird species.
For full API documentation and tutorials on how to use OpenSoundscape to work with audio and spectrograms, train machine learning models, apply trained machine learning models to acoustic data, and detect periodic vocalizations using RIBBIT, see the documentation.
Quick Start
Using Audio and Spectrogram classes
from opensoundscape.audio import Audio
from opensoundscape.spectrogram import Spectrogram
#load an audio file and trim out a 5 second clip
my_audio = Audio.from_file("/path/to/audio.wav")
clip_5s = my_audio.trim(0,5)
#create a spectrogram and plot it
my_spec = Spectrogram.from_audio(clip_5s)
my_spec.plot()
Load audio starting at a real-world timestamp
from datetime import datetime; import pytz
start_time = pytz.timezone('UTC').localize(datetime(2020,4,4,10,25))
audio_length = 5 #seconds
path = '/path/to/audiomoth_file.WAV' #an AudioMoth recording
Audio.from_file(path, start_timestamp=start_time,duration=audio_length)
Using a pre-trained CNN to make predictions on long audio files
from opensoundscape.torch.models.cnn import load_model
#get list of audio files
files = glob('./dir/*.WAV')
#generate predictions with a model
model = load_model('/path/to/saved.model')
scores, _, _ = model.predict(files)
#scores is a dataframe with MultiIndex: file, start_time, end_time
#containing inference scores for each class and each audio window
Training a CNN with labeled audio data
from opensoundscape.torch.models.cnn import CNN
from sklearn.model_selection import train_test_split
#load a DataFrame of one-hot audio clip labels
df = pd.read_csv('my_labels.csv') #index: paths; columns: classes
train_df, validation_df = train_test_split(df,test_size=0.2)
#create a CNN and train on 2-second spectrograms for 2 epochs
model = CNN('resnet18',classes=df.columns,sample_duration=2.0)
model.train(
train_df,
validation_df,
epochs=2
)
#the best model is automatically saved to a file `./best.model`
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file opensoundscape-0.7.0.tar.gz
.
File metadata
- Download URL: opensoundscape-0.7.0.tar.gz
- Upload date:
- Size: 97.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 901ab6de37339cef42a7c0583154a64efc0921a4eb5807cf50e304299f59b9d8 |
|
MD5 | 110e0b452ca537a16e769e64ec2bfe32 |
|
BLAKE2b-256 | 45008be44a4925104bd0193c6c65719c3390ec2a921228373aa050b269f3790c |
File details
Details for the file opensoundscape-0.7.0-py3-none-any.whl
.
File metadata
- Download URL: opensoundscape-0.7.0-py3-none-any.whl
- Upload date:
- Size: 108.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.8.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.61.2 CPython/3.9.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ae3c96240bd45edaf69290f1b7de15a410879e94fb9e477dc65789e3484050a7 |
|
MD5 | 3a66bda5899a69579392dd06a6803af4 |
|
BLAKE2b-256 | 59c6af640d15a238d088627ab35a722da934b6c3b224bb687633816a1053480f |