{
"cells": [
{
"cell_type": "markdown",
"id": "633e398d-28e7-4586-97e2-18e5910393d3",
"metadata": {},
"source": [
"# Audio\n",
"\n",
"This tutorial demonstrates how to use OpenSoundscape to open, inspect, and modify audio files using the `Audio` class.\n",
"\n",
"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. \n",
"\n",
"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`). \n",
"\n",
"## Run this tutorial\n",
"\n",
"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.\n",
"\n",
"|Link to tutorial|How to run tutorial|\n",
"| :- | :- |\n",
"| [](https://colab.research.google.com/github/kitzeslab/opensoundscape/blob/master/docs/tutorials/audio.ipynb) | The link opens the tutorial in Google Colab. Uncomment the \"installation\" line in the first cell to install OpenSoundscape. |\n",
"| [](https://minhaskamal.github.io/DownGit/#/home?url=https://github.com/kitzeslab/opensoundscape/blob/master/docs/tutorials/audio.ipynb) | The link downloads the tutorial file to your computer. Follow the [Jupyter installation instructions](https://opensoundscape.org/en/latest/installation/jupyter.html), then open the tutorial file in Jupyter. |"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6b630803-ee1a-4082-ab8d-489a0dd0642a",
"metadata": {},
"outputs": [],
"source": [
"# if this is a Google Colab notebook, install opensoundscape in the runtime environment\n",
"if 'google.colab' in str(get_ipython()):\n",
" %pip install \"opensoundscape==0.13.0\" \"jupyter-client<8,>=5.3.4\" \"ipykernel==6.17.1\""
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "6a971720",
"metadata": {},
"outputs": [],
"source": [
"# download a sample audio file\n",
"import requests\n",
"\n",
"link = \"https://tinyurl.com/birds60s\"\n",
"r = requests.get(link, allow_redirects=True)\n",
"with open(\"1min_audio.wav\", \"wb\") as f:\n",
" f.write(r.content)"
]
},
{
"cell_type": "markdown",
"id": "9a0b0db6-be54-450a-9046-88a0b72694ce",
"metadata": {
"tags": []
},
"source": [
"Import the `Audio` class from OpenSoundscape. \n",
"\n",
"For more information about Python imports, review [this](https://medium.com/code-85/a-beginners-guide-to-importing-in-python-bb3adbbacc2b) article."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "a5e77714-9f88-4bbb-b344-ac2de374baba",
"metadata": {},
"outputs": [],
"source": [
"# Import Audio class from OpenSoundscape\n",
"from opensoundscape import Audio, audio"
]
},
{
"cell_type": "markdown",
"id": "2a555e9e-b33b-4446-a9d8-b0647324153c",
"metadata": {},
"source": [
"### Load audio files\n",
"\n",
"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](https://pypi.org/project/soundfile/) package). \n",
"\n",
"Saving files is as simple as calling the `.save()` method, and again all common audio formats are supported. \n",
"\n",
"> Note: Loading some formats including `.mp3` may require that you install [FFmpeg](https://www.ffmpeg.org/) 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). \n",
"\n",
"Here we download an example birdsong soundscape recorded by an AudioMoth autonomous recorder in Pennsylvania, USA."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "1795b9cf-24f6-4597-836f-bc31f141bc0b",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
" \n",
" "
],
"text/plain": [
""
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# load an audio file from a file\n",
"# can be any file path to an audio file on your computer\n",
"path = \"./1min_audio.wav\"\n",
"audio_object = Audio.from_file(path)\n",
"\n",
"# returning the audio object from a cell will display a player widget\n",
"audio_object"
]
},
{
"cell_type": "markdown",
"id": "24491c95",
"metadata": {},
"source": [
"This interactive playback widget is displayed when an Audio object is returned from a notebook cell. We can also create the widget with `.show_widget()`:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "f1c80cfd",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"