# Project VoiceMQTT

NAME: voicemqtt
GOAL: Create a voice recording application that activates on MQTT topic, records audio with real-time sound level display, automatically stops after 3 seconds of silence, transcribes using local Whisper, and copies text to Wayland clipboard

## Status: ✅ COMPLETED

All features implemented and tested.

## Implemented Features
- ✅ MQTT-based activation trigger
- ✅ MQTT recording status publishing (2=sound, 1=silence, 0=idle)
- ✅ Public MQTT config support (--public-mqtt from ~/.config/influxdb/totalconfig.conf)
- ✅ MQTT security: TLS/SSL encryption and username/password authentication
- ✅ Real-time audio level visualization in CLI
- ✅ Voice Activity Detection (VAD) with configurable silence timeout
- ✅ Local Whisper transcription (offline, privacy-focused)
- ✅ Wayland clipboard integration via wl-copy (with timeout fix)
- ✅ CLI interface with --help and --version
- ✅ Silence threshold calibration tool (--calibrate)
- ✅ Support for multiple recordings in continuous mode
- ✅ 46 unit tests with pytest

## Technical Stack
- Python 3.12+
- faster-whisper (local Whisper implementation)
- paho-mqtt (MQTT client)
- sounddevice (audio recording)
- rich (CLI UI)
- click (CLI framework)
- pytest (testing)

## Usage Examples

### Basic Usage
```bash
voicemqtt
```

### Public MQTT from Config
```bash
voicemqtt --public-mqtt
```

### Remote MQTT with Security
```bash
voicemqtt \
  --mqtt-host mqtt.example.com \
  --mqtt-port 8883 \
  --mqtt-tls \
  --mqtt-user myuser \
  --mqtt-pass mypass
```

### Calibrate Silence Threshold
```bash
voicemqtt --calibrate
```

### Use Better Model
```bash
voicemqtt --model small
```

### Monitor Recording Status
Subscribe to the recording status topic:
```bash
mosquitto_sub -h localhost -t "voicemqtt/recording"
```

Customize the status topic:
```bash
voicemqtt --recording-status-topic "home/voice/status"
```

## Configuration File
For `--public-mqtt` option, create `~/.config/influxdb/totalconfig.conf`:
```ini
[mqtt public]
server=e8e0ba24f711428496f3008e9e57a07f.s1.eu.hivemq.cloud:8883
username=test1
password=TESTtest123
```

## Model Cache
Location: `~/.cache/whisper/`
- tiny: ~39 MB
- base: ~74 MB (default)
- small: ~244 MB
- medium: ~769 MB
- large-v3: ~1.5 GB

## Files Structure
```
src/voicemqtt/
├── __init__.py
├── cli.py           # Main CLI with all options and status publishing
├── audio.py         # Recording with VAD and calibration
├── mqtt_client.py   # MQTT with TLS, auth, and publish support
├── transcriber.py   # Whisper transcription
└── clipboard.py     # Wayland clipboard with timeout

tests/
├── test_audio.py
├── test_cli.py
├── test_clipboard.py
├── test_mqtt_client.py
└── test_transcriber.py
```

## Testing
```bash
uv run pytest tests/ -v
```

## Completed: 2025-02-16
