{"id":39028117,"url":"https://github.com/earthtoolsmaker/forest-elephants-rumble-detection","last_synced_at":"2026-01-17T17:34:52.939Z","repository":{"id":238130283,"uuid":"795945597","full_name":"earthtoolsmaker/forest-elephants-rumble-detection","owner":"earthtoolsmaker","description":"This repository contains a collection of software packages designed for the passive acoustic monitoring (PAM) of forest elephant rumbles. These tools facilitate the detection, classification, and analysis of elephant vocalizations, aiding in conservation and research efforts.","archived":false,"fork":false,"pushed_at":"2024-12-22T13:08:23.000Z","size":16632,"stargazers_count":4,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-22T14:19:40.450Z","etag":null,"topics":["bioacoustic-analysis","bioacoustics","computer-vision","machine-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/earthtoolsmaker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-04T13:23:49.000Z","updated_at":"2024-12-22T13:08:27.000Z","dependencies_parsed_at":"2024-12-22T14:29:35.198Z","dependency_job_id":null,"html_url":"https://github.com/earthtoolsmaker/forest-elephants-rumble-detection","commit_stats":null,"previous_names":["earthtoolsmaker/forest-elephants-rumble-detection"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/earthtoolsmaker/forest-elephants-rumble-detection","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthtoolsmaker%2Fforest-elephants-rumble-detection","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthtoolsmaker%2Fforest-elephants-rumble-detection/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthtoolsmaker%2Fforest-elephants-rumble-detection/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthtoolsmaker%2Fforest-elephants-rumble-detection/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/earthtoolsmaker","download_url":"https://codeload.github.com/earthtoolsmaker/forest-elephants-rumble-detection/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthtoolsmaker%2Fforest-elephants-rumble-detection/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioacoustic-analysis","bioacoustics","computer-vision","machine-learning"],"created_at":"2026-01-17T17:34:52.862Z","updated_at":"2026-01-17T17:34:52.925Z","avatar_url":"https://github.com/earthtoolsmaker.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Forest Elephants Rumble Detection 🐘\n\nContains a collection of software packages for passive acoustic monitoring\n(PAM) of forest elephants rumbles.\n\n![Elephant rumbles](./docs/assets/images/spectrograms/rumbles_intro.png)\n\nThe low fundamental frequencies of elephant rumbles are located at the bottom\nof the spectrogram and typically range from 14-35 Hz. These are the primary\nfrequencies of the rumbles. Harmonics, which are integer multiples of the\nfundamental frequencies, appear as several horizontal lines above the\nfundamental frequency. For example, if the fundamental frequency is 20 Hz, the\nharmonics will be at 40 Hz, 60 Hz, 80 Hz, and so on. These harmonic lines are\nspaced at regular intervals and are usually less intense (lighter) than the\nfundamental frequency.\n\n[\u003cimg src=\"./docs/assets/images/ml_space.png\" /\u003e](https://www.earthtoolsmaker.org/spaces/forest_elephant_rumble_detection/)\n\n## Introduction\n\nElephant rumbles are low-frequency vocalizations produced by elephants,\nprimarily for communication. These rumbles are a fundamental part of elephant\nsocial interactions and serve various purposes within their groups. Here’s a\ndetailed explanation:\n\n### Characteristics of Elephant Rumbles\n\n1. __Low Frequency__: Elephant rumbles typically fall in the infrasound range,\n   below 20 Hz, which is often below the threshold of human hearing. However,\nsome rumbles can also be heard by humans as a low, throaty sound.\n\n2. __Long Distance Communication__: Due to their low frequency, rumbles can\n   travel long distances, sometimes several kilometers, allowing elephants to\ncommunicate with each other across vast areas, even when they are out of sight.\nIt can also travel through dense forests as the wavelength is very large.\n\n3. __Vocal Production__: Rumbles are produced by the larynx and can vary in\n   frequency, duration, and modulation. Elephants use different types of\nrumbles to convey different messages.\n\n### Functions of Elephant Rumbles\n\n1. __Coordination and Social Bonding__: Elephants use rumbles to maintain\n   contact with members of their herd, coordinate movements, and reinforce\nsocial bonds. For example, a matriarch might use a rumble to lead her group to\na new location.\n\n2. __Reproductive Communication__: Male elephants, or bulls, use rumbles to\n   communicate their reproductive status and readiness to mate. Females also\nuse rumbles to signal their estrus status to potential mates.\n\n3. __Alarm and Distress Calls__: Rumbles can signal alarm or distress, warning\n   other elephants of potential danger. These rumbles can mobilize the herd and\nprompt protective behavior.\n\n4. __Mother-Calf Communication__: Mothers and calves use rumbles to stay in\n   contact, especially when they are separated. Calves may rumble to signal\nhunger or distress, prompting a response from their mothers.\n\n### Importance of Understanding Elephant Rumbles\n\n1. __Conservation Efforts__: Understanding elephant communication helps in\n   conservation efforts by providing insights into their social structure,\nhabitat needs, and responses to environmental changes.\n\n2. __Human-Elephant Conflict Mitigation__: By recognizing alarm rumbles,\n   conservationists can better manage and mitigate conflicts between humans and\nelephants, especially in regions where their habitats overlap.\n\n3. __Enhancing Animal Welfare__: For elephants in captivity, understanding\n   their rumbles can help caretakers improve their welfare by addressing their\nsocial and environmental needs more effectively.\n\nOverall, elephant rumbles are a vital aspect of their complex communication\nsystem, reflecting the sophistication of their social interactions and the\nimportance of acoustic signals in their daily lives.\n\n## Collaboration\n\nThis work is a collaboration with [The Elephant Listening\nProject](https://www.elephantlisteningproject.org/) and [The Cornell\nLab](https://www.birds.cornell.edu/home/).\n\n\u003e To conserve the tropical forests of Africa through acoustic monitoring, sound\n\u003e science, and education, focusing on forest elephants\n\u003e\n\u003e - The Elephant Listening Project\n\nFifty microphones are arranged in a grid within the Tropical Forest of Gabon,\ncontinuously recording forest sounds around the clock. The provided software is\nan advanced sound analyzer capable of processing these extensive audio\nrecordings at high speed, allowing for the analysis of terabytes of audio data\nin just a few days.\n\n## Run\n\n### Python Code\n\nOnce one has followed the setup section below, it is possible to test the\nrumble detector using the following command:\n\n```sh\npython ./scripts/model/yolov8/predict_raven.py \\\n   --input-dir-audio-filepaths ./data/08_artifacts/audio/rumbles/ \\\n   --output-dir ./data/05_model_output/yolov8/predict/ \\\n   --model-weights-filepath ./data/08_artifacts/model/rumbles/yolov8/weights/best.pt \\\n   --verbose \\\n   --loglevel \"info\"\n```\n\n### Docker Image for Rumble Detector\n\nThe Rumble Detector is also available as a Docker image, ensuring portability\nacross different operating systems and setups as long as Docker is installed.\n\n#### Pull the Docker Image\n\nTo pull the Docker image, use the following command:\n\n```sh\ndocker pull earthtoolsmaker/elephantrumbles-detector:latest\n```\n\n#### Run the Docker Container\n\nTo run the Docker container, execute:\n\n```sh\ndocker run --rm earthtoolsmaker/elephantrumbles-detector:latest\n```\n\nNote: By default, audio files and predictions are contained within the\ncontainer, which limits its practical use. However, this command demonstrates\nthe detector's functionality.\n\n#### Using Custom Audio Files and Saving Results\n\nTo analyze your own audio files and save the results to your machine, you need\nto mount two directories into the Docker container:\n\n- __input-dir-audio_filepaths__: The directory containing the audio files to be analyzed.\n- __output-dir__: The directory where the artifacts and predictions will be saved.\n\nIn the example below, the `input-dir-audio_filepaths` is\n`./data/03_model_input/sounds/rumbles/` and the `output-dir` is\n`./runs/predict/`. The program will analyze the audio files in the input\ndirectory and save the results in the output directory.\n\n```sh\ndocker run --rm \\\n  -v ./data/03_model_input/sounds/rumbles/:/app/data/08_artifacts/audio/rumbles/ \\\n  -v ./runs/predict/:/app/data/05_model_output/yolov8/predict \\\n  earthtoolsmaker/elephantrumbles-detector:latest\n```\n\n### Pipeline overview and outputs\n\nThe pipeline will do the following:\n\n1. Generate spectrograms in the frequency range 0-250Hz, where all the elephant\n   rumbles are located\n2. Run the rumble object detector on batches of spectrograms\n3. Save the predictions as a CSV\n\n__Note__: The verbose flag tells the command to also persist the generated\nspectrograms and predictions, they will be located in the `output-dir`.\n\n| Spectrogram | Prediction |\n|:-----------:|:----------:|\n| ![Spectrogram 0](./docs/assets/images/spectrograms/spectrogram_0.png) | ![Prediction 0](./docs/assets/images/predictions/prediction_0.png) |\n| ![Spectrogram 1](./docs/assets/images/spectrograms/spectrogram_1.png) | ![Prediction 1](./docs/assets/images/predictions/prediction_1.png) |\n| ![Spectrogram 2](./docs/assets/images/spectrograms/spectrogram_2.png) | ![Prediction 2](./docs/assets/images/predictions/prediction_2.png) |\n\nBelow is a sample of a generated CSV file:\n\n| probability | freq_start | freq_end | t_start | t_end | audio_filepath | instance_class |\n|:-----------:|:----------:|:--------:|:-------:|:-----:|:--------------:|:--------------:|\n| 0.7848126888275146 | 185.34618616104126 | 238.925039768219 | 6.117525324225426 | 11.526521265506744 | data/08_artifacts/audio/rumbles/sample_0.wav | rumble |\n| 0.7789380550384521 | 187.46885657310486 | 237.14002966880798 | 107.4117157459259 | 112.39507365226746 | data/08_artifacts/audio/rumbles/sample_0.wav | rumble |\n| 0.6963282823562622 | 150.82329511642456 | 238.47350478172302 | 89.08285737037659 | 94.3071436882019 | data/08_artifacts/audio/rumbles/sample_0.wav | rumble |\n| 0.6579649448394775 | 203.18885147571564 | 231.6151112318039 | 44.13426876068115 | 47.50721764564514 | data/08_artifacts/audio/rumbles/sample_0.wav | rumble |\n| ... | ... | ... | ... | ... | ... | ... |\n\n## Benchmark\n\nThe aim of this project is to enable the rapid analysis of large-scale audio\ndatasets, potentially reaching terabyte scales. By leveraging multiprocessing\nand utilizing the maximum number of CPU and GPU cores, we strive to optimize\nprocessing speed and efficiency. Benchmark analyses have been conducted on both\nCPU and GPU to ensure optimal performance.\n\n### CPU\n\nProcessing a 24-hour audio file on an 8-core CPU takes approximately 35 seconds\nin total:\n\n- __Loading the audio file__: ~4 seconds\n- __Generating spectrograms__: ~11 seconds\n- __Running model inference__: ~19 seconds\n- __Miscellaneous tasks__: ~1 second\n\n### GPU + CPU\n\nProcessing a 24-hour audio file using a GPU (T4) and an 8-core CPU takes\napproximately 20 seconds in total:\n\n- __Loading the audio file__: ~4 seconds\n- __Generating spectrograms__: ~11 seconds\n- __Running model inference__: ~4 seconds\n- __Miscellaneous tasks__: ~1 second\n\n### Back of the envelope calculation\n\n- Number of sound recorders: $`N_{sr} = 50`$\n- Number of days to analyze: $`N_{d} = 30`$  (1 month)\n- Size of a 24hour audio recording $`W = 657`$ MB\n- Amount of data to analyze: $`N_{sr} \\times N_{d} \\times W = 986`$ GB (1 month)\n- Time to process a 24h audio file with a CPU: $`T_{CPU} = 35`$s\n- Time to process a 24h audio file with a GPU: $`T_{GPU} = 20`$s\n\n#### With CPU\n\nOn a CPU setup with 8 cores, analyzing 1 month of sound data - ~1TB - would\nrequire:\n$`N_{sr} \\times N_{d} \\times T_{CPU} = 50 \\times 30 \\times 35 = 14.6`$ hours\n\nTo analyze 6 months of sound data - ~6TB - it would require:\n$`N_{sr} \\times N_{d} \\times T_{CPU} = 50 \\times 180 \\times 35 = 3.6`$ days\n\n#### With CPU + GPU\n\nOn a CPU setup with 8 cores, analyzing 1 month of sound data would require:\n$`N_{sr} \\times N_{d} \\times T_{GPU} = 50 \\times 30 \\times 20 = 8.3`$ hours\n\nTo analyze 6 months of sound data - ~6TB - it would require:\n$`N_{sr} \\times N_{d} \\times T_{GPU} = 50 \\times 180 \\times 20 = 2.1`$ days\n\n## Setup\n\n### Dependencies\n\n- [Poetry](https://python-poetry.org/): Python packaging and dependency\nmanagement - Install it with something like `pipx`\n- [Git LFS](https://git-lfs.com/): Git Large File Storage replaces large\nfiles such as jupyter notebooks with text pointers inside Git while\nstoring the file contents on a remote server like github.com\n- [DVC](https://dvc.org/): Data Version Control  - This will get\ninstalled automatically\n- [MLFlow](https://mlflow.org/): ML Experiment Tracking - This will get\ninstalled automatically\n\n### Install\n\n#### Poetry\n\nFollow the [official documentation](https://python-poetry.org/docs/) to install `poetry`.\n\n#### Git LFS\n\nMake sure [`git-lfs`](https://git-lfs.com/) is installed on your system.\n\nRun the following command to check:\n\n```sh\ngit lfs install\n```\n\nIf not installed, one can install it with the following:\n\n##### Linux\n\n```sh\nsudo apt install git-lfs\ngit-lfs install\n```\n\n##### Mac\n\n```sh\nbrew install git-lfs\ngit-lfs install\n```\n\n##### Windows\n\nDownload and run the latest [windows installer](https://github.com/git-lfs/git-lfs/releases).\n\n#### Project Dependencies\n\nCreate a virtualenv and install python version with conda - or use a\ncombination of pyenv and venv:\n\n```sh\nconda create -n pyronear-mlops python=3.12\n```\n\nActivate the virtual environment:\n\n```sh\nconda activate pyronear-mlops\n```\n\nInstall python dependencies\n\n```sh\npoetry install\n```\n\n## Project structure and conventions\n\nThe project is organized following mostly the [cookie-cutter-datascience\nguideline](https://drivendata.github.io/cookiecutter-data-science/#directory-structure).\n\n### Data\n\nAll the data lives in the `data` folder and follows some [data engineering\nconventions](https://docs.kedro.org/en/stable/faq/faq.html#what-is-data-engineering-convention).\n\n### Library Code\n\nThe library code is available under the `src/forest_elephants_rumble_detection` folder.\n\n### Notebooks\n\nThe notebooks live in the `notebooks` folder. They are automatically synced to\nthe Git LFS storage.\nPlease follow [this\nconvention](https://drivendata.github.io/cookiecutter-data-science/#notebooks-are-for-exploration-and-communication)\nto name your Notebooks.\n\n`\u003cstep\u003e-\u003cghuser\u003e-\u003cdescription\u003e.ipynb` - e.g., `0.3-mateo-visualize-distributions.ipynb`.\n\n### Scripts\n\nThe scripts live in the `scripts` folder, they are\ncommonly CLI interfaces to the library\ncode.\n\n## DVC\n\nDVC is used to track and define data pipelines and make them\nreproducible. See `dvc.yaml`.\n\nTo get an overview of the pipeline DAG:\n\n```sh\ndvc dag\n```\n\nTo run the full pipeline:\n\n```sh\ndvc repro\n```\n\n## MLFlow\n\nAn MLFlow server is running when running ML experiments to track\nhyperparameters and performances and to streamline model\nselection.\n\nTo start the mlflow UI server, run the following command:\n\n```sh\nmake mlflow_start\n```\n\nTo stop the mlflow UI server, run the following command:\n\n```sh\nmake mlflow_stop\n```\n\nTo browse the different runs, open your browser and navigate to the URL:\n[http://localhost:5000](http://localhost:5000)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthtoolsmaker%2Fforest-elephants-rumble-detection","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fearthtoolsmaker%2Fforest-elephants-rumble-detection","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthtoolsmaker%2Fforest-elephants-rumble-detection/lists"}