# Loud Noise Detector
[](https://pypi.org/project/loud-noise-detector/)
[](https://pypi.org/project/loud-noise-detector/)
[](https://opensource.org/licenses/MIT)
[](https://buymeacoffee.com/endika2i)
A Python system designed to detect and record significant noises in your home when you're away. Inspired by the need to monitor our pets when they're left alone at home for short periods, detecting barks or other sounds that might indicate distress or discomfort. It's also an ideal practical solution for parents who need to know if their baby is crying in another room. Perfect for any situation where you need to be informed about important sounds occurring in spaces where you can't be physically present.
## 🚀 Features
- Real-time detection of significant sounds (barking, crying, etc.)
- Customizable noise thresholds to match your needs
- Automatic recording when relevant sounds are detected
- Instant notification system
- Detailed event logging
- Easy to configure and customize
## 📋 Requirements
- Python 3.6 or higher
- PortAudio (for PyAudio) Ubuntu: `sudo apt install python3-dev portaudio19-dev`
- Working microphone
## 🔧 Installation
### From PyPI
```bash
pip install loud-noise-detector
```
### From Source
1. Clone the repository:
```bash
git clone https://github.com/Endika/loud-noise-detector.git
cd loud-noise-detector
```
2. Create and activate a virtual environment:
```bash
python -m venv .venv
# On Windows
.\.venv\Scripts\activate
# On Unix or MacOS
source .venv/bin/activate
```
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Install development dependencies (optional):
```bash
pip install -r dev-requirements.txt
```
## ⚙️ Configuration
### Command Line Arguments
| Argument | Default Value | Description |
| -------------------- | ---------------------------- | ------------------------------------ |
| `--config` | `config/default_config.yaml` | Path to configuration file |
| `--verbose`, `-v` | `False` | Enable verbose output |
| `--output-dir`, `-o` | `data/recordings` | Directory to save recordings |
| `--threshold`, `-t` | - | RMS threshold to trigger detection |
| `--language`, `-l` | `en` | Language for messages (`en` or `es`) |
| `--no-keep-files` | `False` | Delete recording files after sending |
### Configuration File Options
| Parameter | Default Value | Description |
| -------------------- | --------------- | -------------------------------------------- |
| `threshold` | `0.1` | Sound level threshold to trigger detection |
| `cooldown_seconds` | `5` | Time to wait between detections |
| `seconds_to_record` | `5` | Duration of recording after detection |
| `pre_buffer_seconds` | `2` | Seconds of audio to keep before detection |
| `rate` | `44100` | Audio sampling rate |
| `channels` | `1` | Number of audio channels (1=mono, 2=stereo) |
| `format` | `8` | Audio format (pyaudio.paInt16) |
| `chunk_size` | `1024` | Size of audio chunks to process |
| `keep_files` | `True` | Whether to keep recording files |
| `verbose` | `False` | Enable detailed logging |
| `timestamp_format` | `%Y%m%d_%H%M%S` | Format for timestamp in filenames |
| `language` | `en` | Interface language (`en` or `es`) |
| `notifier_options` | `{}` | Additional options for notification services |
## 🔐 Environment Setup
Generate your `.env` file with all necessary configurations:
```bash
# Generate .env file
cat > .env << EOL
# Slack configuration (required for Slack notifications)
SLACK_TOKEN=xoxb-your-token-here
SLACK_CHANNEL=CHANNEL-ID-HERE
EOL
```
#### Environment Variables Description
| Variable | Required | Default | Description |
| --------------- | -------- | ------- | ------------------------------------------ |
| `SLACK_TOKEN` | Yes | - | Your Slack bot token (starts with `xoxb-`) |
| `SLACK_CHANNEL` | Yes | - | Channel where notifications will be sent |
> **Note**: For Slack notifications, you'll need to:
>
> 1. Create a Slack App in your workspace
> 2. Add `chat:write` and `files:write` OAuth scopes
> 3. Install the app to your workspace
> 4. Copy the Bot User OAuth Token to `SLACK_TOKEN`
> 5. Copy the Channel ID to `SLACK_CHANNEL`
### Configuration Examples
#### For Pet Monitoring
```yaml
threshold: 0.2 # Higher threshold for louder sounds like barking
cooldown_seconds: 30 # Longer cooldown to avoid too many notifications
seconds_to_record: 10 # Longer recording to capture context
pre_buffer_seconds: 3 # Capture sound before the bark
notifier_options:
slack_channel: CHANNEL-ID-HERE
```
#### For Baby Monitoring
```yaml
threshold: 0.15 # Lower threshold to detect crying
cooldown_seconds: 10 # Shorter cooldown for more frequent checks
seconds_to_record: 5 # Shorter recording duration
pre_buffer_seconds: 1 # Less pre-recording needed
notifier_options:
slack_channel: CHANNEL-ID-HERE
```
You can create a configuration file in either YAML or JSON format. Place it in the `config/` directory or specify its location using the `--config` argument.
## 🎯 Usage
### Basic Usage
```bash
# Start the noise detector with default settings
loud-noise-detector
# Start with custom configuration file
loud-noise-detector --config path/to/config.yml
# Run in debug mode
loud-noise-detector --debug
```
### As a Python Module
```shell
python -m src.main
```
## 📊 Development
### Running Tests
```bash
# Run all tests
make test
```
### Code Quality
```bash
# Run linting
make lint
# Run type checking
make quality
```
## 🤝 Contributing
This project uses [Semantic Release](https://python-semantic-release.readthedocs.io/) for versioning.
### Commit Message Format
Your commit messages must follow this format to trigger automatic version updates:
### Development Workflow
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Commit with appropriate message format
5. Push to your branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Thanks to all contributors who have helped shape this project
- Built with Python and PyAudio
- Inspired by the need for reliable noise monitoring solutions
## 📫 Contact
Endika Iglesias - endika2@gmail.com
Project Link: [https://github.com/Endika/loud-noise-detector](https://github.com/Endika/loud-noise-detector)
Raw data
{
"_id": null,
"home_page": "https://github.com/Endika/loud-noise-detector",
"name": "loud-noise-detector",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "AudioMonitoring, PetCare, BabyMonitor, SoundDetection, DigitalParenting, SmartSolution, audio, detection, recording, notification",
"author": "Endika Iglesias",
"author_email": "endika2@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/67/7a8a7b744f640db9dd4796ab3b14f129a4d218268e4b4a9eb358269b1ae3/loud_noise_detector-2.0.2.tar.gz",
"platform": null,
"description": "# Loud Noise Detector\n\n[](https://pypi.org/project/loud-noise-detector/)\n[](https://pypi.org/project/loud-noise-detector/)\n[](https://opensource.org/licenses/MIT)\n\n[](https://buymeacoffee.com/endika2i)\n\nA Python system designed to detect and record significant noises in your home when you're away. Inspired by the need to monitor our pets when they're left alone at home for short periods, detecting barks or other sounds that might indicate distress or discomfort. It's also an ideal practical solution for parents who need to know if their baby is crying in another room. Perfect for any situation where you need to be informed about important sounds occurring in spaces where you can't be physically present.\n\n## \ud83d\ude80 Features\n\n- Real-time detection of significant sounds (barking, crying, etc.)\n- Customizable noise thresholds to match your needs\n- Automatic recording when relevant sounds are detected\n- Instant notification system\n- Detailed event logging\n- Easy to configure and customize\n\n## \ud83d\udccb Requirements\n\n- Python 3.6 or higher\n- PortAudio (for PyAudio) Ubuntu: `sudo apt install python3-dev portaudio19-dev`\n- Working microphone\n\n## \ud83d\udd27 Installation\n\n### From PyPI\n\n```bash\npip install loud-noise-detector\n```\n\n### From Source\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/Endika/loud-noise-detector.git\ncd loud-noise-detector\n```\n\n2. Create and activate a virtual environment:\n\n```bash\npython -m venv .venv\n# On Windows\n.\\.venv\\Scripts\\activate\n# On Unix or MacOS\nsource .venv/bin/activate\n```\n\n3. Install dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n4. Install development dependencies (optional):\n\n```bash\npip install -r dev-requirements.txt\n```\n\n## \u2699\ufe0f Configuration\n\n### Command Line Arguments\n\n| Argument | Default Value | Description |\n| -------------------- | ---------------------------- | ------------------------------------ |\n| `--config` | `config/default_config.yaml` | Path to configuration file |\n| `--verbose`, `-v` | `False` | Enable verbose output |\n| `--output-dir`, `-o` | `data/recordings` | Directory to save recordings |\n| `--threshold`, `-t` | - | RMS threshold to trigger detection |\n| `--language`, `-l` | `en` | Language for messages (`en` or `es`) |\n| `--no-keep-files` | `False` | Delete recording files after sending |\n\n### Configuration File Options\n\n| Parameter | Default Value | Description |\n| -------------------- | --------------- | -------------------------------------------- |\n| `threshold` | `0.1` | Sound level threshold to trigger detection |\n| `cooldown_seconds` | `5` | Time to wait between detections |\n| `seconds_to_record` | `5` | Duration of recording after detection |\n| `pre_buffer_seconds` | `2` | Seconds of audio to keep before detection |\n| `rate` | `44100` | Audio sampling rate |\n| `channels` | `1` | Number of audio channels (1=mono, 2=stereo) |\n| `format` | `8` | Audio format (pyaudio.paInt16) |\n| `chunk_size` | `1024` | Size of audio chunks to process |\n| `keep_files` | `True` | Whether to keep recording files |\n| `verbose` | `False` | Enable detailed logging |\n| `timestamp_format` | `%Y%m%d_%H%M%S` | Format for timestamp in filenames |\n| `language` | `en` | Interface language (`en` or `es`) |\n| `notifier_options` | `{}` | Additional options for notification services |\n\n## \ud83d\udd10 Environment Setup\n\nGenerate your `.env` file with all necessary configurations:\n\n```bash\n# Generate .env file\ncat > .env << EOL\n# Slack configuration (required for Slack notifications)\nSLACK_TOKEN=xoxb-your-token-here\nSLACK_CHANNEL=CHANNEL-ID-HERE\nEOL\n```\n\n#### Environment Variables Description\n\n| Variable | Required | Default | Description |\n| --------------- | -------- | ------- | ------------------------------------------ |\n| `SLACK_TOKEN` | Yes | - | Your Slack bot token (starts with `xoxb-`) |\n| `SLACK_CHANNEL` | Yes | - | Channel where notifications will be sent |\n\n> **Note**: For Slack notifications, you'll need to:\n>\n> 1. Create a Slack App in your workspace\n> 2. Add `chat:write` and `files:write` OAuth scopes\n> 3. Install the app to your workspace\n> 4. Copy the Bot User OAuth Token to `SLACK_TOKEN`\n> 5. Copy the Channel ID to `SLACK_CHANNEL`\n\n### Configuration Examples\n\n#### For Pet Monitoring\n\n```yaml\nthreshold: 0.2 # Higher threshold for louder sounds like barking\ncooldown_seconds: 30 # Longer cooldown to avoid too many notifications\nseconds_to_record: 10 # Longer recording to capture context\npre_buffer_seconds: 3 # Capture sound before the bark\nnotifier_options:\n slack_channel: CHANNEL-ID-HERE\n```\n\n#### For Baby Monitoring\n\n```yaml\nthreshold: 0.15 # Lower threshold to detect crying\ncooldown_seconds: 10 # Shorter cooldown for more frequent checks\nseconds_to_record: 5 # Shorter recording duration\npre_buffer_seconds: 1 # Less pre-recording needed\nnotifier_options:\n slack_channel: CHANNEL-ID-HERE\n```\n\nYou can create a configuration file in either YAML or JSON format. Place it in the `config/` directory or specify its location using the `--config` argument.\n\n## \ud83c\udfaf Usage\n\n### Basic Usage\n\n```bash\n# Start the noise detector with default settings\nloud-noise-detector\n\n# Start with custom configuration file\nloud-noise-detector --config path/to/config.yml\n\n# Run in debug mode\nloud-noise-detector --debug\n```\n\n### As a Python Module\n\n```shell\npython -m src.main\n```\n\n## \ud83d\udcca Development\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n```\n\n### Code Quality\n\n```bash\n# Run linting\nmake lint\n\n# Run type checking\nmake quality\n```\n\n## \ud83e\udd1d Contributing\n\nThis project uses [Semantic Release](https://python-semantic-release.readthedocs.io/) for versioning.\n\n### Commit Message Format\n\nYour commit messages must follow this format to trigger automatic version updates:\n\n### Development Workflow\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Commit with appropriate message format\n5. Push to your branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Thanks to all contributors who have helped shape this project\n- Built with Python and PyAudio\n- Inspired by the need for reliable noise monitoring solutions\n\n## \ud83d\udceb Contact\n\nEndika Iglesias - endika2@gmail.com\n\nProject Link: [https://github.com/Endika/loud-noise-detector](https://github.com/Endika/loud-noise-detector)\n",
"bugtrack_url": null,
"license": null,
"summary": "Audio monitoring system that detects and alerts you about important sounds in your home while you're away. Perfect for pet owners and parents who need to stay connected to their space.",
"version": "2.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/Endika/loud-noise-detector/issues",
"Homepage": "https://github.com/Endika/loud-noise-detector",
"Source Code": "https://github.com/Endika/loud-noise-detector"
},
"split_keywords": [
"audiomonitoring",
" petcare",
" babymonitor",
" sounddetection",
" digitalparenting",
" smartsolution",
" audio",
" detection",
" recording",
" notification"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "98eb196d0de10dc4a5892f8850eeef502f5208e5c39e8b0d52ca001118a307ae",
"md5": "2e8eacc4839157b7299f76048317d16d",
"sha256": "5cb68b3f26ebe30481690bfb81553745e0b6e81b4e533eae45356ad90ca1278a"
},
"downloads": -1,
"filename": "loud_noise_detector-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e8eacc4839157b7299f76048317d16d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 28407,
"upload_time": "2025-07-10T14:38:25",
"upload_time_iso_8601": "2025-07-10T14:38:25.981494Z",
"url": "https://files.pythonhosted.org/packages/98/eb/196d0de10dc4a5892f8850eeef502f5208e5c39e8b0d52ca001118a307ae/loud_noise_detector-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "54677a8a7b744f640db9dd4796ab3b14f129a4d218268e4b4a9eb358269b1ae3",
"md5": "24c005bb06b99f0c6677251eb2a89202",
"sha256": "af3a2fcdbd1743e2de02c6f9cdfd04aeaad23b8c66dbc73a9015cabd5b32566e"
},
"downloads": -1,
"filename": "loud_noise_detector-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "24c005bb06b99f0c6677251eb2a89202",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 21511,
"upload_time": "2025-07-10T14:38:26",
"upload_time_iso_8601": "2025-07-10T14:38:26.819887Z",
"url": "https://files.pythonhosted.org/packages/54/67/7a8a7b744f640db9dd4796ab3b14f129a4d218268e4b4a9eb358269b1ae3/loud_noise_detector-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 14:38:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Endika",
"github_project": "loud-noise-detector",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pyaudio",
"specs": [
[
"==",
"0.2.14"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"==",
"6.0.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.0.2"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.1.1"
]
]
}
],
"lcname": "loud-noise-detector"
}
JSON
