Metadata-Version: 2.4
Name: fastpluggy-audio-transcript-client
Version: 0.1.2
Summary: Client for FastPluggy audio transcription plugin
Author: FastPluggy Team
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
Requires-Dist: pyaudio
Requires-Dist: websockets==16.0
Requires-Dist: numpy
Requires-Dist: questionary
Requires-Dist: pydantic<3,>=2.12

# 🎤 Audio Streaming Client

A powerful, user-friendly audio streaming client that captures audio from any device (microphone, system audio, virtual cables) and streams it to a transcription server with real-time compression and intelligent configuration management.

## ✨ Features

### 🎵 **Audio Capture**
- **Multi-device support** - Microphones, loopback devices, virtual audio cables
- **Real-time streaming** - Configurable chunk sizes from 1-30 seconds
- **High-quality audio** - Support for 16kHz to 48kHz sample rates
- **Smart compression** - Opus codec with ~80-90% size reduction

### 🔧 **Configuration Management**
- **Pydantic validation** - Type-safe configuration with automatic validation
- **Interactive setup** - Beautiful questionary-based configuration wizard
- **Persistent settings** - Automatic save/load of configuration
- **Command-line override** - Mix saved config with CLI arguments

### 🌐 **Network & Transport**
- **WebSocket streaming** - Real-time bidirectional communication
- **Connection resilience** - Automatic reconnection with configurable attempts
- **Connection testing** - Pre-flight server reachability checks
- **Live statistics** - Real-time bandwidth and transmission monitoring

### 🎨 **User Experience**
- **Device categorization** - Visual icons for different device types
- **Progress feedback** - Live streaming statistics and status
- **Error handling** - Graceful error recovery and user guidance
- **Cross-platform** - Works on Windows, macOS, and Linux

## 🚀 Quick Start

### 1. Installation

```bash
# Install system dependencies for PyAudio
# Windows: No additional steps required
# macOS: brew install portaudio
# Debian/Ubuntu: sudo apt-get install portaudio19-dev
# Fedora/RHEL: sudo dnf install portaudio-devel

# Install Python dependencies
pip install pydantic pyaudio websockets numpy questionary

# Install FFmpeg (required for audio compression)
# Windows: Download from https://ffmpeg.org/download.html
# macOS: brew install ffmpeg  
# Linux: sudo apt install ffmpeg
```

### 2. Interactive Setup (Recommended)

```bash
python client.py
```

This launches the interactive configuration wizard that will:
- 🔍 Scan and display all available audio devices
- ⚙️ Guide you through optimal settings
- 💾 Save configuration for future use
- 🌐 Test server connectivity

### 3. Quick Command Line

```bash
# List available audio devices
python client.py --list-devices

# Start streaming with specific device
python client.py --device 0 --url ws://myserver:8765/audio

# Use saved configuration
python client.py --config ~/my_setup.json
```

## 📋 Configuration Options

### **Audio Settings**
| Option | Default | Description |
|--------|---------|-------------|
| `device` | `"0"` | Audio device index or name |
| `chunk_duration` | `5.0` | Chunk size in seconds (1.0-30.0) |
| `sample_rate` | `16000` | Sample rate: 8000, 16000, 22050, 44100, 48000 Hz |
| `codec` | `"opus"` | Compression: `opus` (recommended) or `raw` |
| `compression_quality` | `64` | Opus bitrate in kbps (32-320) |

### **Network Settings**
| Option | Default | Description |
|--------|---------|-------------|
| `url` | `ws://localhost:8765/audio` | WebSocket server URL |
| `transport` | `"websocket"` | Protocol: `websocket` or `tcp` |
| `reconnect_attempts` | `3` | Number of reconnection attempts (0-10) |
| `reconnect_delay` | `2.0` | Delay between reconnects in seconds |

## 💻 Usage Examples

### Interactive Configuration
```bash
# First-time setup or reconfiguration
python client.py --interactive

# Use saved config if available
python client.py
```

### Command Line Usage
```bash
# Basic streaming
python client.py --device "CABLE Output" --chunk 5

# High quality streaming
python client.py --device 0 --sample-rate 48000 --compression-quality 128

# Quick speech capture
python client.py --device 1 --chunk 3 --sample-rate 16000 --compression-quality 64

# Remote server
python client.py --url ws://192.168.1.100:8765/audio --no-test
```

### Configuration File
```bash
# Save to custom location
python client.py --config ~/audio_configs/meeting_setup.json

# Load specific configuration
python client.py --config ~/audio_configs/podcast_setup.json --device 2
```

## 🎵 Audio Device Setup

### **Windows**
- **System Audio**: Use VoiceMeeter or Virtual Audio Cable
- **Applications**: Route app audio through virtual cables
- **Discord/Teams**: Use "CABLE Input" as microphone in app settings

### **macOS**
- **System Audio**: Install BlackHole or SoundFlower
- **Applications**: Use Audio MIDI Setup for routing
- **Multi-output**: Combine system + virtual for monitoring

### **Linux**
- **System Audio**: Use PulseAudio loopback modules
- **Applications**: Configure ALSA/PulseAudio routing
- **Jack**: Advanced audio routing for professional setups

## ⚙️ Advanced Configuration

### Configuration File Format
```json
{
  "device": "0",
  "device_name": "CABLE Output (VB-Audio Virtual Cable)",
  "chunk_duration": 5.0,
  "sample_rate": 16000,
  "codec": "opus",
  "url": "ws://localhost:8765/audio",
  "transport": "websocket",
  "reconnect_attempts": 3,
  "reconnect_delay": 2.0,
  "compression_quality": 64
}
```

### Pydantic Validation
The client uses Pydantic for configuration validation:
- ✅ **Type checking** - Automatic type conversion and validation
- ✅ **Range validation** - Ensures values are within acceptable ranges
- ✅ **URL validation** - Validates WebSocket URL format
- ✅ **Custom validators** - Ensures configuration consistency

### Environment Variables (Future)
```bash
export AUDIO_CLIENT_DEVICE="CABLE Output"
export AUDIO_CLIENT_URL="ws://production-server:8765/audio"
export AUDIO_CLIENT_SAMPLE_RATE="22050"
```

## 🔧 Troubleshooting

### **No Audio Devices Found**
```bash
# Check system audio
python client.py --list-devices

# Install virtual audio cable
# Windows: VB-Audio Virtual Cable
# macOS: BlackHole
# Linux: PulseAudio loopback
```

### **Connection Issues**
```bash
# Test server connectivity
python client.py --no-test  # Skip connection test

# Check server URL format
# Correct: ws://hostname:port/audio
# Incorrect: http://hostname or hostname:port
```

### **Audio Quality Issues**
```bash
# Increase sample rate
python client.py --sample-rate 48000

# Increase compression quality  
python client.py --compression-quality 128

# Use raw audio (no compression)
python client.py --codec raw
```

### **Performance Issues**
```bash
# Reduce chunk size for lower latency
python client.py --chunk 2

# Increase chunk size for efficiency
python client.py --chunk 10

# Lower sample rate for efficiency
python client.py --sample-rate 16000
```

## 📊 Technical Details

### **Audio Processing Pipeline**
1. **Device Capture** → Audio device via `soundcard`
2. **PCM Conversion** → 16-bit mono audio at specified sample rate  
3. **Compression** → Opus encoding via FFmpeg (optional)
4. **Packetization** → JSON metadata + binary audio data
5. **Transport** → WebSocket streaming to server

### **Compression Stats**
| Sample Rate | Raw Size/sec | Opus 64kbps | Compression |
|-------------|--------------|-------------|-------------|
| 16 kHz | 32 KB/s | 8 KB/s | 75% reduction |
| 22 kHz | 44 KB/s | 8 KB/s | 82% reduction |
| 44.1 kHz | 88 KB/s | 8 KB/s | 91% reduction |
| 48 kHz | 96 KB/s | 8 KB/s | 92% reduction |

### **Network Protocol**
```javascript
// Metadata packet (JSON)
{
  "timestamp": 1640995200.123,
  "sample_rate": 16000,
  "duration": 5.0,
  "codec": "opus",
  "data_size": 8192,
  "chunk_id": 42,
  "compression_quality": 64
}

// Followed by binary audio data
<audio_bytes>
```

## 🤝 Contributing

### **Development Setup**
```bash
git clone <repository>
cd audio-client
pip install -e ".[dev]"
```

### **Code Style**
- **Type hints** - Full type annotations required
- **Pydantic models** - Use for all configuration objects
- **Async/await** - Use for all I/O operations
- **Error handling** - Graceful error recovery

### **Testing**
```bash
# Unit tests
pytest tests/

# Integration tests with mock server
pytest tests/integration/

# Device tests (requires audio hardware)
pytest tests/devices/ --audio-hardware
```

## 📝 License

MIT License - See LICENSE file for details.

## 🔗 Related Projects

- **Server Component** - Audio transcription server with Whisper
- **Web Dashboard** - Real-time transcription monitoring
- **Mobile Client** - iOS/Android audio streaming apps

---

**Made with ❤️ for real-time audio processing**
