👏 ClapStart — Smart Workspace Launcher

ClapStart is a Python-based automation tool that prepares your entire development environment (IDE, Browser, Terminal, Folders) with a simple sound trigger — a double clap or finger snap.

📋 What does it do?

Instead of manually opening VS Code, browser tabs, terminals, and folders every time you start working, ClapStart does it for you. It uses real-time audio processing to detect a specific acoustic signal (your double clap) and launches a predefined list of programs and resources.

---

✨ Features

• Real-time Audio Detection: Monitors your microphone for sudden volume spikes.
• Double-Clap Logic: Intelligent "anti-bounce" filter to distinguish between echo and a second deliberate clap.
• Highly Configurable: Launch URLs, VS Code projects, Windows Terminal tabs, and arbitrary shell commands.
• Resource Efficient: Automatically exits after launching your workspace to save system resources.

---

🛠️ Prerequisites

• Python 3.8+
• Windows OS (optimized for Windows paths and commands like start, code, and wt).

---

🚀 Installation

1. Clone the repository:

   git clone https://github.com/borkovranic/ClapStart.git
   cd ClapStart

2. Create a Virtual Environment (Recommended):

   python -m venv .venv
   source .venv/Scripts/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies:

   pip install -r requirements.txt

   Note: If requirements.txt is missing, run: pip install sounddevice numpy

---

⚙️ Configuration

1. Create your config file: Copy config.example.json to a new file named local_config.json:

   cp config.example.json local_config.json

2. Edit local_config.json: Open the file and add your paths and URLs:

   {
     "browser_urls": ["https://github.com", "https://claude.ai"],
     "vscode_projects": ["C:\\Users\\You\\Project"],
     "terminal_projects": ["C:\\Users\\You\\Project"],
     "explorer_folders": ["C:\\Downloads"],
     "custom_commands": [],
     "settings": {
       "threshold": 0.015,
       "max_gap_s": 0.8,
       "cooldown_s": 5.0
     }
   }

Tuning Sensitivity

If the program doesn't respond or triggers too easily, adjust the threshold in settings:

• Too sensitive? Increase threshold (e.g., 0.020).
• Not sensitive enough? Decrease threshold (e.g., 0.010).

---

🏃 How to Run

Simply run the script:

python clap_start.py

1. The console will show your current volume levels (Volume: 0.0001).
2. Clap twice within the max_gap_s window (default 0.8s).
3. Watch your workspace come to life! 🚀

---

🧠 How it Works

No ML, no magic — just physics.

ClapStart listens to your microphone and calculates the volume (RMS) of each audio block in real time.

• First clap crosses the threshold → timer starts
• 0.15s blackout ignores the echo so it doesn't count twice
• Second clap arrives within 0.8s → workspace launches
• Cooldown kicks in so the noise from opening apps doesn't re-trigger it

That's it. Two peaks, one window, zero dependencies beyond sounddevice and numpy.

☕ Support

If this saves you time, a coffee keeps the experiments going. Buy me one and I'll personally help you get it running on your machine.

📜 License

This project is open-source and available under the MIT License.