Web application for ecoacoustics to manage, navigate, visualise, annotate, and analyse soundscape recordings.
Designed by Kevin Darras, developed by Noemi Perez and Dilong Liu. ecoSound-web was forked from BioSounds and is licensed under the GNU General Public License, v3.
The corresponding updatable scientific publication is in F1000Research.
A working instance of ecoSound-web can be accessed here with limited functionality within the open collections.
You may learn about the basic functionality in the user guide (see Wiki).
Contact us for a collaboration.
We use Docker to run the app in your computer. We provide install.sh and run.sh files with all necessary commands, and a Makefile with extra commands to access the docker containers.
You need to install docker and docker-compose standalone directly in your machine. Please read the documentation and follow the instructions carefully. We don't offer support for docker installation and configuration.
Important: this setup is intended for developing and testing purposes ONLY. It is in no way ready for production. Please read the Server Installation section.
Disk Space: Ensure a minimum of 40 GB is available before installation, particularly on the partition holding Docker data (typically /var)
This is due to Docker images containing machine learning libraries (TensorFlow 2.20.0 + PyTorch 2.4.1) and audio processing tools (~22GB for biosounds-apache image alone).
sh install.sh
sh run.sh
This starts all services and launches the queue worker with automatic restart capability. Run this script only once (typically at server startup). The worker processes jobs sequentially from the queue. If the worker crashes, it will automatically restart within 5 seconds, ensuring continuous processing without manual intervention.
Note: Do not run run.sh multiple times - this would create duplicate workers processing jobs in parallel.
If you're upgrading to this version and have existing data, you need to migrate your database from the old Docker named volume to a bind mount before running install.sh.
Important: Back up your data first!
# 1. Pull the latest changes
git pull origin merged-terraform-audio
# 2. Back up database
docker-compose exec database mysqldump -ubiosounds -pbiosounds --single-transaction --quick biosounds > backup.sql
# 3. Back up media files
tar -czf sounds_backup.tar.gz src/sounds/
# 4. Stop containers
docker-compose down
# 5. Switch to this branch (use -f to force overwrite Docker-created root-owned files)
git checkout -f merged-terraform-audio
# 6. Initialize new data directories
bash init-data-dirs.sh
# 7. Start containers and initialize database schema
docker-compose up -d
# 8. Wait for database to be ready
docker-compose exec apache bash -c 'while ! (nc -z database 3306); do echo "Database is not ready..."; sleep 2; done;'
# 9. Initialize database schema (required for fresh database)
docker-compose exec -i database mysql -ubiosounds -pbiosounds biosounds < init.sql
docker-compose exec -i database mysql -ubiosounds -pbiosounds biosounds < data.sql
docker-compose exec -i database mysql -ubiosounds -pbiosounds biosounds < gadm.sql
docker-compose exec -i database mysql -ubiosounds -pbiosounds biosounds < world_seas.sql
# 10. Restore your backed-up database data (optional, if you have backup.sql from step 2)
# Only run this if you want to restore your previous recordings and data
# cat backup.sql | docker-compose exec -T database mysql -uroot -proot biosounds
# 11. Restore media files to new folders
tar -xzf sounds_backup.tar.gz
sudo mv src/sounds/sounds/* sounds/ 2>/dev/null || true
sudo mv src/sounds/images/* sound_images/ 2>/dev/null || true
sudo mv src/sounds/projects/* project_images/ 2>/dev/null || true
# 12. Verify database and media
docker-compose exec database mysql -ubiosounds -pbiosounds biosounds -e "SHOW TABLES;"
ls -la sounds/ sound_images/ project_images/
# 13. Restart the queue worker to reconnect to migrated database
docker-compose restart apache
# Wait for Apache to be ready
docker-compose exec apache bash -c 'while ! (nc -z database 3306); do echo "Database is not ready..."; sleep 2; done;'
# Start the worker process
docker-compose exec -T -u www-data apache nohup php worker.php > files_update.log 2>&1 &
# 14. Clear browser cache and localStorage (important!)
# In your browser console (F12 → Console):
# localStorage.clear()
# Then refresh the page (Ctrl+R or Cmd+R)
# 15. Test file uploads
# Try uploading a new recording to verify the worker is processing uploads correctly
# 16. Clean up old files (optional)
rm -rf src/sounds
docker volume rm biosounds-mysql 2>/dev/null || trueIf you have no existing data, simply run ./install.sh normally.
sh run.sh
Log in with username: admin, password: Administrator20
Important: please change the password of this administrator user or delete it once you have ecoSound-web running on production and have your own admin users.
docker-compose stop
docker container prune
If you want to use Docker for your own server installation, please consult with a devOps engineer or someone with the necessary knowledge to manage it properly, depending on your hosting setup.
The current Docker configuration Dockerfile can be used for your preferred setup.
Like any other web app, ecoSound-web can be installed without Docker (see Wiki).
For both cases (with and without Docker), you'll need to set the configuration values in the config.ini file, according to your server setup.