Metadata-Version: 2.3
Name: mic-control
Version: 2.1.0
Summary: Automatic microphone volume control for macOS calls and meetings
License: MIT
Author: Robin Schulz
Author-email: bulletinmybeard@gmail.com
Requires-Python: >=3.12,<3.14
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: chalkbox (>=2.4.0,<3.0.0)
Requires-Dist: numpy (>=2.5.0,<3.0.0)
Requires-Dist: sounddevice (>=0.5.5,<0.6.0)
Project-URL: Homepage, https://rschu.me/
Project-URL: Repository, https://github.com/bulletinmybeard/mic-control
Description-Content-Type: text/markdown

# mic-control

[![CI](https://github.com/bulletinmybeard/mic-control/actions/workflows/ci.yml/badge.svg)](https://github.com/bulletinmybeard/mic-control/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/bulletinmybeard/mic-control?display_name=tag&sort=semver)](https://github.com/bulletinmybeard/mic-control/releases)
[![PyPI](https://badge.fury.io/py/mic-control.svg)](https://pypi.org/project/mic-control/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/)
[![Platform](https://img.shields.io/badge/platform-macOS-lightgrey)](https://www.apple.com/macos/)
[![Poetry](https://img.shields.io/badge/packaging-poetry-informational)](https://python-poetry.org/)

[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/types-mypy-2A6DB0.svg)](https://mypy-lang.org/)

Automatic microphone volume control for macOS calls and meetings.

## What It Does

- Monitors and maintains mic input level during calls
- Two-tier call detection: quick checks between full audio sampling passes
- Rich terminal output with live status
- Low resource usage, runs in background
- Native macOS integration via osascript

## Quick Start

### Install mic-control

Install with `pipx` (recommended):

```bash
pipx install mic-control
```

Or with pip in a virtual environment:

```bash
pip install mic-control
```

> **Tip:** `pipx` is recommended for global CLI tools as it provides isolated environments.

Or with Poetry (for development):

```bash
git clone https://github.com/bulletinmybeard/mic-control.git
cd mic-control
poetry install
```

### Run mic-control

```bash
# Start with default settings
mic-control

# Custom target volume
mic-control --target-volume 70

# Use a specific input device (index or name)
mic-control --input-device 1

# Verbose debug output
mic-control --verbose

# Run in background
mic-control &
```

## CLI Commands

| Command | Description |
| ---------------------------------- | ---------------------------------------- |
| `mic-control` | Start with default settings (80% volume) |
| `mic-control --target-volume 70` | Set custom target volume (0-100) |
| `mic-control --active-interval 5` | Seconds between checks during calls (>= 1) |
| `mic-control --idle-interval 15` | Seconds between checks when idle (>= 1) |
| `mic-control --call-interval 30` | Seconds between full detection passes (>= 1) |
| `mic-control --input-device DEVICE` | Input device index or name for detection |
| `mic-control --log-path PATH` | Custom log file location |
| `mic-control --verbose` | Enable debug output |
| `mic-control --version` | Show version |

## Example Output

```
╭──────────────────────────────────────────╮
│        mic-control v2.1.0                │
│                                          │
│  Target Volume: 80                       │
│  Active Interval: 5s                     │
│  Idle Interval: 15s                      │
│  Call Interval: 30s                      │
│  Input Device: system default            │
│  Log Path: /Users/.../.mic-control/...   │
╰──────────────────────────────────────────╯

⠋ Detecting call activity...
-> Not in call (detection took 5.2s)

⠋ Confirming call activity...
-> In call (detection took 5.1s)
ℹ Adjusting volume: 50 -> 80

^C
Shutting down gracefully...
Microphone controller stopped
```

## How Call Detection Works

mic-control uses a two-tier strategy:

1. **Full detection**: runs every `--call-interval` seconds (default 30s). It records five 1-second audio samples and treats persistent activity as a call.
1. **Quick checks**: run between full passes. When idle, a short sample can trigger a faster confirmation pass. When in a call, consecutive inactive quick checks end call mode without waiting for the next full pass.

This keeps volume adjustments responsive while limiting CPU and microphone usage.

## Limitations

- **macOS only**: volume control relies on `osascript`.
- **Audio-based detection**: music, notifications, or background noise can be mistaken for a call. Quiet calls may be missed.
- **Default input device**: unless `--input-device` is set, detection uses the system default microphone. Meeting apps that use a different device may not be detected reliably.
- **Microphone permission**: macOS must grant microphone access. Permission or device errors are logged and treated as "no activity" during quick checks.

List available input devices from Python:

```bash
poetry run python -c "import sounddevice as sd; print(sd.query_devices())"
```

## Requirements

- macOS 10.0+
- Python 3.12+

## Troubleshooting

### If the script can't access your mic

- Check the mic permissions in your `System Preferences`
- Make sure no other app or script is exclusively using the mic
- Try `--input-device` with the device your meeting app uses

### If volume adjustments don't work

- Verify you have permission to run `osascript`

### For logging issues

- Ensure the log file location has the correct write permissions
- Check available disk space

## Links

- [Changelog](https://github.com/bulletinmybeard/mic-control/blob/master/CHANGELOG.md)

## License

MIT License - see the [LICENSE](https://github.com/bulletinmybeard/mic-control/blob/master/LICENSE) file for details.

