This tutorial demonstrates how to use OpenSoundscape to open, inspect, and modify audio files using the Audio class.

The class stores audio data (.samples: a 1d array containing the digital waveform signal) and metadata (.metadata, a dictionariy containing information such as sample rate, recording start time, etc). The .sample_rate attribute stores the audio sample rate in Hz.

The class’s methods give access to modifications such as trimming (.trim()), filtering (.bandpass(), .lowpass(), .highpass()) , resampling (.resample()), or extending (.loop(), .extend_to(), extend_by()) the signal. Properties provide measurements such as signal level (.dBFS, .rms) and duration (.duration).

Run this tutorial

This tutorial is more than a reference! It’s a Jupyter Notebook which you can run and modify on Google Colab or your own computer.

Link to tutorial

How to run tutorial

Open In Colab

The link opens the tutorial in Google Colab. Uncomment the “installation” line in the first cell to install OpenSoundscape.

Download via DownGit

The link downloads the tutorial file to your computer. Follow the Jupyter installation instructions, then open the tutorial file in Jupyter.

# if this is a Google Colab notebook, install opensoundscape in the runtime environment
if 'google.colab' in str(get_ipython()):
  %pip install opensoundscape
# download a sample audio file
import requests
link = ''
r = requests.get(link, allow_redirects=True)
with open('1min_audio.wav', 'wb') as f:

Import the Audio class from OpenSoundscape.

For more information about Python imports, review this article.

# Import Audio class from OpenSoundscape
from opensoundscape import Audio, audio
/Users/SML161/opensoundscape/opensoundscape/ml/ TqdmExperimentalWarning: Using `tqdm.autonotebook.tqdm` in notebook mode. Use `tqdm.tqdm` instead to force console mode (e.g. in jupyter console)
  from tqdm.autonotebook import tqdm

Load audio files

The Audio class can load local files with .from_file() and online audio files with .from_url(). All common audio formats are supported (via the underlying SoundFile package).

Saving files is as simple as calling the .save() method, and again all common audio formats are supported.

Note: Loading some formats including .mp3 may require that you install FFmpeg first. FFmpeg comes pre-installed on many machines including on Google Colab. Note that .mp3 files cause some operations to slow down (e.g. loading a segment from a long file).

Here we download an example birdsong soundscape recorded by an AudioMoth autonomous recorder in Pennsylvania, USA.

# load an audio file from a file
# can be any file path to an audio file on your computer
path = './1min_audio.wav'
audio_object = Audio.from_file(path)

# returning the audio object from a cell will display a player widget