# Clap Launcher

Double-clap file launcher using real-time microphone input

---

Overview

Clap Launcher is a lightweight Python utility that listens to microphone input in real time and reacts to two consecutive hand claps by launching a predefined file, image, or application.

The project is intentionally built without machine learning or external services.
Instead, it relies on deterministic audio amplitude analysis with carefully tuned timing and threshold heuristics.

The main goals of this project are:

• predictability
• transparency of logic
• minimal dependencies
• easy modification and experimentation

---

Key Features

• Real-time microphone audio processing
• Double-clap detection using amplitude heuristics
• Automatic background noise calibration
• Configurable thresholds and timing parameters
• Cross-platform file launching
  (Windows / macOS / Linux)
• Fully local execution, no network usage

---

How It Works

At a high level, the script performs the following steps:

1. Continuously reads audio frames from the selected microphone.
2. Calculates peak amplitude for each frame.
3. Tracks short, high-energy sound bursts.
4. Filters out long or continuous sounds.
5. Validates timing between detected sound events.
6. Triggers an action when two valid claps are detected within the allowed window.

The algorithm intentionally favors false negatives over false positives.

---

Detection Model (Conceptual)

This project uses a heuristic-based audio detection model, not machine learning.

A sound is considered a valid clap if:

• Its peak amplitude exceeds a dynamic threshold
• Its duration is short (impulsive, not sustained)
• It is followed by a silence phase
• It does not overlap with another sound event
• It satisfies minimum and maximum timing constraints

This approach keeps the system:

• fast
• deterministic
• easy to debug
• easy to tune

---

Configuration

All behavior is controlled via constants at the top of the script.

Core Parameters

BASE_THRESHOLD = 0.15
CLAP_TIMEOUT = 2.5
MIN_CLAP_INTERVAL = 0.15
SILENCE_THRESHOLD = 0.05
AUTO_CALIBRATE = True

TARGET_FILENAME = "dota2.png"

MAX_CLAP_DURATION = 0.2
MIN_CLAP_PEAK = 0.25

Parameter breakdown:

BASE_THRESHOLD Base amplitude threshold. Everything below this value is ignored.

CLAP_TIMEOUT Maximum time (in seconds) between claps for them to be considered part of the same sequence.

MIN_CLAP_INTERVAL Minimum allowed time (in seconds) between claps. Helps avoid counting echoes or rebound noise.

SILENCE_THRESHOLD Amplitude level considered silence. Used to detect when a sound event has ended.

AUTO_CALIBRATE Enables automatic background noise calibration on startup.

TARGET_FILENAME File to open when a valid double clap is detected. Can be an image, executable, or any file supported by the OS.

MAX_CLAP_DURATION Maximum allowed duration (seconds) for a single clap. Longer sounds are treated as noise.

MIN_CLAP_PEAK Minimum required peak amplitude for a sound to be considered a valid clap.