🎧 nonoice

A smart macOS menubar application that listens to your environment and automatically plays masking sounds to help you focus by blocking out distractions.

📋 Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Usage
• How It Works
• Project Architecture
• Development
• Building from Source
• Release Notes
• Contributing
• License

🎯 Overview

nonoice is an intelligent audio environment manager that uses machine learning to detect distracting sounds in your environment and automatically plays appropriate masking sounds to help you maintain focus. It runs quietly in your macOS menubar, listening to ambient sounds and reacting dynamically based on what it detects.

Key Capabilities

• Real-time Audio Classification: Uses YAMNet embeddings and a trained ESC-50 classifier to identify 50 different environmental sounds
• Intelligent Audio Mixing: Automatically adjusts masking sounds (brown noise, flowing river) based on distraction levels
• Three-Level Distraction System:
  • 🔴 High Distraction: Voices, alarms, sudden sounds → Strong water masking
  • 🟡 Medium Distraction: Mechanical sounds, drones → Brown noise masking
  • 🟢 Low Distraction: Background nature sounds → Minimal masking
• Privacy-Focused: All audio processing happens locally on your machine

✨ Features

• 🎤 Real-time Audio Processing: Continuously listens and classifies sounds
• 🧠 AI-Powered Classification: Uses TensorFlow Hub's YAMNet for state-of-the-art audio embeddings
• 🔊 Adaptive Audio Masking: Automatically adjusts masking sound levels based on detected distractions
• 🎛️ Smooth Audio Transitions: Gradual fading between masking sound levels for a pleasant experience
• 📊 Status Monitoring: Real-time status updates showing detected sounds and confidence levels
• 🔔 Native macOS Notifications: Get notified when the app starts/stops or detects significant events
• 🎨 Native Menubar Integration: Runs discreetly in your menubar (no dock icon)

🚀 Quick Start

For End Users

1. Download the Latest Release

   • Go to the Releases page
   • Download nonoice-v1.0.dmg
   • Open the DMG and drag nonoice.app to your Applications folder

2. First Launch

   • Open nonoice.app from Applications
   • Grant microphone permissions when prompted
   • The app will appear in your menubar (top-right)

3. Start Using

   • Click the menubar icon
   • Select "Start Listening"
   • The app will automatically detect and mask distracting sounds

System Requirements

• macOS 11.0 (Big Sur) or later
• Microphone access permissions
• ~500MB free disk space

📦 Installation

Option 1: DMG Installer (Recommended for Users)

1. Download nonoice-v1.0.dmg from Releases
2. Open the downloaded DMG file
3. Drag nonoice.app to your Applications folder
4. Launch from Applications (you may need to allow the app in Security & Privacy settings on first launch)

Option 2: Build from Source (For Developers)

See the Building from Source section below.

📖 Usage

Basic Operation

1. Launch the App: Open nonoice.app from your Applications folder
2. Start Listening: Click the menubar icon → "Start Listening"
3. Monitor Status: View the current status and detected sounds in the menu
4. Stop Listening: Click "Stop Listening" when you're done

Menu Options

• Start Listening: Begin audio detection and masking
• Stop Listening: Stop all audio processing
• Status: Shows current state:
  • 🟢 Ready
  • 🟢 Listening...
  • 🟢 Safe / Background Noise
  • 🟡 Medium Distraction
  • 🔴 HIGH DISTRACTION

Understanding Status Messages

The app categorizes detected sounds into three levels:

• 🔴 HIGH DISTRACTION (e.g., voices, alarms, crying)

  • Plays strong water masking sounds (80% volume)
  • Mixes with light brown noise (20%)

• 🟡 Medium Distraction (e.g., vacuum, engine, airplane)

  • Plays brown noise (90% volume)
  • No water sounds

• 🟢 Background Noise (e.g., rain, wind, nature sounds)

  • Minimal masking
  • Fades out masking sounds

🔧 How It Works

Audio Processing Pipeline

1. Audio Capture: Captures audio from your microphone at 16kHz (YAMNet's required sample rate)
2. Feature Extraction: Uses YAMNet (TensorFlow Hub) to extract 1024-dimensional embeddings
3. Feature Aggregation: Combines mean, max, and std pooling to create 3072-dimensional features
4. Normalization: Applies the same scaler used during training
5. Classification: Predicts sound class using a trained Random Forest classifier on ESC-50 dataset
6. Prediction Smoothing: Averages predictions over the last 5 samples for stability
7. Reaction Logic: Categorizes sounds and adjusts audio mixer accordingly

Technical Stack

• Audio Processing: PyAudio, NumPy
• ML Framework: TensorFlow 2.x, TensorFlow Hub (YAMNet)
• Classification: scikit-learn (Random Forest)
• Audio Mixing: Pygame mixer
• UI Framework: rumps (macOS native menubar)
• Packaging: PyInstaller

Sound Categories (ESC-50 Dataset)

The app recognizes 50 environmental sound classes including:

• Human sounds (breathing, coughing, laughing, crying)
• Domestic sounds (washing machine, vacuum cleaner, clock tick)
• Exterior sounds (airplane, train, car horn, siren)
• Animals (dog, cat, rooster, pig)
• Natural sounds (rain, wind, sea waves, thunderstorm)

🏗️ Project Architecture

Directory Structure

nonoice/
├── menubar/                    # Main application
│   ├── app.py                  # Menubar app entry point (rumps)
│   ├── core/
│   │   ├── listener.py         # Audio listener & classifier
│   │   └── audio_mixer.py      # Masking sound mixer
│   ├── models/                 # Trained classifier
│   ├── scaler/                 # Feature scaler
│   ├── class_names/            # ESC-50 class names
│   ├── images/                 # App icons
│   ├── masking_sounds/         # Brown noise & water sounds
│   └── requirements.txt        # Python dependencies
│
├── jupyternote/                # Development notebooks
│   ├── yamnet_trainer.ipynb    # Model training notebook
│   ├── esc50_jupyter.ipynb     # ESC-50 dataset exploration
│   └── realtime_audio_classifier.py
│
├── assets/                     # Shared assets
│   └── images/                 # Icon files
│
├── soundclassifier/            # ESC-50 dataset
│   └── ESC-50-master/
│       ├── audio/              # 2000 audio files
│       └── audio_organized/    # Organized by class
│
└── README.md                   # This file

Core Components

1. app.py - Menubar Application

• Main entry point using rumps framework
• Handles menubar UI and menu interactions
• Manages application lifecycle (start/stop)
• Displays status updates

2. core/listener.py - Audio Listener

• Captures audio from microphone using PyAudio
• Loads YAMNet model from TensorFlow Hub
• Extracts audio embeddings with combined pooling
• Runs trained classifier for sound classification
• Implements prediction smoothing
• Categorizes sounds and triggers audio mixer

3. core/audio_mixer.py - Audio Mixer

• Manages masking sounds (brown noise, flowing river)
• Implements smooth volume transitions (fading)
• Three modes: HIGH, MEDIUM, LOW
• Threaded audio playback for smooth operation

💻 Development

Prerequisites

• Python 3.8 or later
• macOS 11.0+ (for development and testing)
• pip package manager

Setting Up Development Environment

1. Clone the Repository

   git clone <repository-url>
   cd nonoice

2. Create a Virtual Environment (Recommended)

   python3 -m venv venv
   source venv/bin/activate

3. Install Dependencies

   cd menubar
   pip install -r requirements.txt

4. Ensure Model Files Are Present Make sure you have:

   • menubar/models/esc50_yamnet_classifier_best.pkl
   • menubar/scaler/esc50_scaler.pkl
   • menubar/class_names/esc50_class_names.pkl
   • menubar/masking_sounds/brown-noise.wav
   • menubar/masking_sounds/flowing-river.wav
   • menubar/images/icon.png
   • menubar/images/app_icon.icns

5. Run in Development Mode

   python app.py

Training the Model

If you need to retrain the classifier:

1. Prepare ESC-50 Dataset

   • Download ESC-50 from Kaggle or GitHub
   • Place in soundclassifier/ESC-50-master/

2. Run Training Notebook

   jupyter notebook jupyternote/yamnet_trainer.ipynb

   This will:

   • Extract YAMNet embeddings for all ESC-50 samples
   • Train a Random Forest classifier
   • Save the model, scaler, and class names

3. Copy Trained Models

   cp jupyternote/esc50_yamnet_classifier_final.pkl menubar/models/esc50_yamnet_classifier_best.pkl
   cp jupyternote/esc50_scaler.pkl menubar/scaler/esc50_scaler.pkl
   cp jupyternote/esc50_class_names.pkl menubar/class_names/esc50_class_names.pkl

🔨 Building from Source

Requirements for Building

• Python 3.8+
• PyInstaller 6.0+
• All development dependencies installed

Build Steps

1. Prepare the Environment

   cd menubar
   pip install -r requirements.txt

2. Create PyInstaller Spec File (if not exists) The spec file (nonoice.spec) should already be in the repository. If not, create it with:

   pyinstaller --name nonoice \
     --onedir \
     --windowed \
     --icon images/app_icon.icns \
     --add-data "images:images" \
     --add-data "masking_sounds:masking_sounds" \
     --add-data "scaler:scaler" \
     --add-data "models:models" \
     --add-data "class_names:class_names" \
     app.py

3. Build the App

   pyinstaller nonoice.spec --clean --noconfirm

4. Verify Build

   ls -la dist/nonoice.app

5. Test the App

   open dist/nonoice.app

Creating a DMG for Distribution

1. Build the App (see above)

2. Create DMG

   hdiutil create -volname nonoice \
     -srcfolder dist/nonoice.app \
     -ov -format UDZO \
     dist/nonoice-v1.0.dmg

3. DMG is Ready The DMG file will be in dist/nonoice-v1.0.dmg and ready for distribution.

Build Configuration

The nonoice.spec file configures:

• Data Files: Includes all assets (images, sounds, models, scaler)
• Hidden Imports: All required Python packages
• macOS Bundle:
  • LSUIElement=1 (menubar app, no dock icon)
  • Microphone permissions in Info.plist
  • App icon configuration
• Optimizations: UPX compression, binary stripping

📝 Release Notes

Version 1.0.0

Initial Release

• ✨ Real-time audio classification using YAMNet + ESC-50
• 🎛️ Three-level distraction detection (High/Medium/Low)
• 🔊 Adaptive audio masking with smooth transitions
• 🎨 Native macOS menubar integration
• 🔔 System notifications for app events
• 📊 Real-time status display
• 🔒 Local-only processing (privacy-focused)

Download: Available as nonoice-v1.0.dmg in Releases

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the Repository
2. Create a Feature Branch (git checkout -b feature/amazing-feature)
3. Commit Your Changes (git commit -m 'Add amazing feature')
4. Push to the Branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Areas for Contribution

• 🎵 Additional masking sounds
• 🎯 Improved classification accuracy
• 📱 Additional platform support
• 🐛 Bug fixes and performance improvements
• 📚 Documentation improvements

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• YAMNet: Google's TensorFlow Hub audio classification model
• ESC-50 Dataset: Karol Piczak's Environmental Sound Classification dataset
• rumps: Native macOS menubar app framework
• PyInstaller: Application packaging tool

📧 Contact & Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📝 Documentation: See project files and notebooks

---

Made with ❤️ for focused work