By Nathan Wolek - @LowkeyNW - http://nathanwolek.com
A small collection of Bash scripts for audio collected by the AudioMoth acoustic monitoring device.
IMPORTANT NOTE: These scripts were designed to work with recordings from an early version of the AudioMoth firmware. More recent versions no longer use the hexadecimal file names (e.g., 5EC5A158.WAV). I'll be working on an update for the new system in the near future.
The AudioMoth is a small, programmable audio recorder designed for acoustic monitoring. After deploying my AudioMoths for several weeks during Florida's COVID-19 Stay at Home order, I began developing these scripts to analyze, visualize, and share the audio I collected. I am not affiliated with Open Acoustic Devices, producers of the AudioMoth. Any questions about the device itself should be directed to them.
I realize that many users of the AudioMoth may have minimal experience using the Bash shell. Therefore, I have done my best to clearly document the steps for using these scripts in hopes of encouraging more people in acoustic ecology and bioacoustics to explore this amazing tool for batch processing large collections of audio files. If you are looking for a good general resource for learning more about the Bash shell, I highly recommend The Missing Semester, a collection of lessons by 3 MIT grad students.
These scripts require the following command line tools:
- SoX - "the Swiss Army knife of sound processing programs"
- ImageMagick - "create, edit, compose, or convert bitmap images"
- ffmpeg - "solution to record, convert and stream audio and video"
If you are an experienced shell user who already has these tools installed and configured, you can easily add the AudioMoth scripts to your home folder using something like following commands:
cd ~/bin
git clone https://github.com/nwolek/audiomoth-scripts.git
echo -e "PATH=\"\$PATH\":\"~/bin/audiomoth-scripts\"" >> ~/.bash_profile
If you are an occasional shell user on the MacOS or Windows, you will have a few more steps. Microsoft has recently provided a Terminal for Windows users, but I have no experience with it. MacOS users can access the shell via the built-in Terminal application, which is the method I use. I have checked the following steps on MacOS 10.14 Mojave.
Once you are in the terminal, I recommend installing Homebrew, which allows you to more easily add command line tools. If you go this route, you can have the required tools for the AudioMoth scripts installed by stepping through the following commands:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install sox
brew install imagemagick
brew install ffmpeg
brew install git
After that, you can install the AudioMoth scripts in your home directory. It's good practice to keep your Bash scripts together in a folder called bin. You can create that folder and download the AudioMoth scripts like this:
cd ~
mkdir bin
cd bin
git clone https://github.com/nwolek/audiomoth-scripts.git
Finally, you will want to add these scripts to your search path. This saves you from having to type the whole path every time you want to run the script. You can add the relevant folders to your search path using the following commands:
echo -e "PATH=\"\$PATH\":\"~/bin\"" >> ~/.bash_profile
echo -e "PATH=\"\$PATH\":\"~/bin/audiomoth-scripts\"" >> ~/.bash_profile
That should finish the installation!
These scripts are designed to work on files in batches, using syntax like the following:
bash rename-by-date.sh *.WAV
bash make-spectrogram-image.sh 5EC5A*.WAV
bash make-spectrogram-movie.sh 2020-06-01-*.wavThe first script in this collection provides AudioMoth recordings with a more helpful filenames based on the date and time they were captured. The original files are left unaltered and copies are made with their new filenames in a subdirectory named output.
Example:
[audiomoth-demo]$ ls
5EC5A158.WAV 5EC5A3B0.WAV 5EC5A608.WAV 5EC5A860.WAV
[audiomoth-demo]$ bash rename-by-date.sh *.WAV
[audiomoth-demo]$ cd output
[output]$ ls
2020-05-20-21-30-00-UTC.wav 2020-05-20-21-50-00-UTC.wav
2020-05-20-21-40-00-UTC.wav 2020-05-20-22-00-00-UTC.wav
[output]$Additional details:
- To achieve this, it gets "birth time" from the
statcommand, which can have some variations in syntax between operating systems. - Since the AudioMoth uses UTC, that time zone is preserved in the renaming.
This script is used to generate basic spectrogram images of AudioMoth recordings. It generates PNG images of the whole recording that are saved alongside the original WAV files with a same filename.
Example:
[audiomoth-demo]$ ls
5EC5A158.WAV 5EC5A3B0.WAV 5EC5A608.WAV 5EC5A860.WAV
[audiomoth-demo]$ bash make-spectrogram-image.sh *.WAV
making spectrogram for 5EC5A158.WAV...
making spectrogram for 5EC5A3B0.WAV...
making spectrogram for 5EC5A608.WAV...
making spectrogram for 5EC5A860.WAV...
[audiomoth-demo]$ ls -g
total 49208
-rwxrwxrwx 1 staff 5760192 May 20 21:31 5EC5A158.WAV
-rw-r--r-- 1 staff 539916 Jun 30 16:42 5EC5A158.png
-rwxrwxrwx 1 staff 5760192 May 20 21:41 5EC5A3B0.WAV
-rw-r--r-- 1 staff 538542 Jun 30 16:42 5EC5A3B0.png
-rwxrwxrwx 1 staff 5760192 May 20 21:51 5EC5A608.WAV
-rw-r--r-- 1 staff 526156 Jun 30 16:42 5EC5A608.png
-rwxrwxrwx 1 staff 5760192 May 20 22:01 5EC5A860.WAV
-rw-r--r-- 1 staff 532306 Jun 30 16:42 5EC5A860.png
[audiomoth-demo]$ Additional details:
- To achieve this, the script uses SoX, a cross-platform command line utility for audio operations. Make sure that SoX is installed and properly configured before using this script.
- The images generated will be 1280 by 720 pixels, although it looks like the script asks for 1136 by 642 pixels. This is because SoX adds some padding to the images for the graph axes and unit labels. Be aware that changing the size may require some experimenting to get the right dimensions.
Output:
A variation on script number 2 that produces small thumbnail spectrograms that are useful for the web. It generates PNG images of the first 30 seconds that are saved alongside the original WAV files with a same filename.
Example:
[output]$ ls
2020-05-20-21-50-00-UTC.wav 2020-05-20-22-00-00-UTC.wav
[output]$ bash make-spectrogram-thumbnail.sh *.wav
making fullsize spectrogram for 2020-05-20-21-50-00-UTC.wav...
making thumbnail spectrogram for 2020-05-20-21-50-00-UTC.wav...
deleting fullsize spectrogram for 2020-05-20-21-50-00-UTC.wav...
making fullsize spectrogram for 2020-05-20-22-00-00-UTC.wav...
making thumbnail spectrogram for 2020-05-20-22-00-00-UTC.wav...
deleting fullsize spectrogram for 2020-05-20-22-00-00-UTC.wav...
[output]$ ls -g
total 22560
-rw-r--r-- 1 staff 11317 Jun 29 18:20 2020-05-20-21-50-00-UTC-thumbnail.png
-rwxr-xr-x 1 staff 5760192 Jun 29 18:02 2020-05-20-21-50-00-UTC.wav
-rw-r--r-- 1 staff 11010 Jun 29 18:20 2020-05-20-22-00-00-UTC-thumbnail.png
-rwxr-xr-x 1 staff 5760192 Jun 29 18:02 2020-05-20-22-00-00-UTC.wav
[output]$ Additional details:
- To achieve this, the script uses both SoX and ImageMagick. Make sure these tools are installed and properly configured before using this script.
- If a recording is shorter than 30 seconds, the whole file is used to generate the spectrogram.
- The script actually creates a full-size image first then resizes it to produce the 128 by 72 pixels thumbnail version. The full-size 1280 by 720 pixels version is then deleted to save space, but you could easily keep it by commenting out these lines.
This script creates a spectrogram slideshow and pairs it with the original audio to produce an MP4 movie file. Each slide visualizes 30 seconds of sound and displays information about when and where the audio was captured.
Example:
[output]$ bash make-spectrogram-movie.sh 2020-05-20-22-*.wav
Starting movie for 2020-05-20-22-00-00-UTC.wav...
making spectrogram from 0 to 30 seconds...
making spectrogram from 30 to 60 seconds...
creating full length movie...
[output]$ ls -g
total 21824
-rw-r--r-- 1 staff 1176220 Jun 30 17:51 2020-05-20-22-00-00-UTC-slide0.png
-rw-r--r-- 1 staff 1160476 Jun 30 17:51 2020-05-20-22-00-00-UTC-slide1.png
-rw-r--r-- 1 staff 1115565 Jun 30 17:51 2020-05-20-22-00-00-UTC.mp4
-rwxr-xr-x 1 staff 5760192 Jun 30 17:35 2020-05-20-22-00-00-UTC.wav
[output]$ Additional details:
- To achieve this, the script uses both SoX, ImageMagick and ffmpeg. Make sure these tools are installed and properly configured before using this script.
- This script expects the filenames that are output from
rename-by-date.sh, so make sure you run that script first. The date and time of recording for the text on each slide is actually taken from the filename. - Information about the recording location is set by these two variables at the top of the bash script.
Output:
This script is used to create an HTML interface for reviewing spectrograms in a collection of AudioMoth recordings. It does this by generating an index.html file that contains a table of thumbnail images organized with dates in columns and times in rows.
Example:
[output]$ find *.wav | wc -l # how many wav files?
2297
[output]$ bash make-html-table.sh *.wav
[output]$ open index.html
[output]$ Additional details:
- This script expects the filenames from
rename-by-date.shand thumbnails frommake-spectrogram-thumbnail.sh, so make sure you run those scripts first. The dates and times used for constructing the table are actually taken from the filenames, so this script will not work on the unaltered AudioMoth recordings. - Several formatting features of the HTML table depend on the
spectrogram-table.cssfile included in this repo. It was adapted from this CodePen example by Paul O'Brien.
Output:
A variation on script number 5 that adds the ability to click through thumbnails to access the slideshow movies generated by script 4. The MP4 movies are displayed in a lightbox overlay on top of the HTML table to provide a unified interface for browsing material gathered by the AudioMoth.
Example:
[output]$ find *.wav | wc -l # how many wav files?
2297
[output]$ bash make-html-lightbox-table.sh *.wav
[output]$ open index.html
[output]$ Additional details:
- Since this is really a variation of
make-html-table.sh, be advised that all of the notes in that section of the README apply this script too. - This script makes use of materials generated by several other scripts in the collection, so make sure you run these scripts first:
rename-by-date.shmake-spectrogram-thumbnail.shmake-spectrogram-movie.sh
- The lightbox effect is enabled by another CSS file, the
perfundo.min.cssfile included in this repo. It was copied from this GitHub repo by Markus Oberlehner.
Output:
My research into using the AudioMoth for acoustic ecology is supported by the following:
- Stetson University's Institute for Water and Environmental Resilience