OpenSpeak/openspec/specs/005-client-application.md

# Feature Specification: Client Application (Desktop GUI)

**ID:** CLIENT-001
**Version:** 1.0
**Status:** Planned
**Priority:** Critical

## Overview
Desktop GUI client application for OpenSpeak, providing user interface for voice communication, channel browsing, and user presence.

## Platform & Technology

### Target Platform
- **Windows:** Primary development target
- **macOS:** Future support
- **Linux:** Future support

### Technology Stack
- **Language:** Go
- **GUI Framework:** Fyne (cross-platform, native look-and-feel)
  - Alternative: Gio or Ebiten if Fyne limitations encountered
- **Architecture:** Modular, single binary with embedded assets

### System Requirements
- Go 1.21+
- Audio device support (built-in or USB)
- Minimum 100MB disk space
- 2GB RAM minimum

## UI Layout

### Main Window Structure
```
┌─────────────────────────────────────────────────────┐
│ OpenSpeak 1.0.0                              [_][□][x]│
├─────────────────┬───────────────────────────────────┤
│  SERVER SETUP   │       CHANNEL LIST                 │
│  ───────────    │       ─────────────────            │
│  Host: ____     │  # general                         │
│  Port: ____     │  # announcements                   │
│  Token: ____    │  # random-games                    │
│  [Connect ▶]    │  # off-topic                       │
│                 │                                    │
│  STATUS         │  CURRENT CHANNEL: general          │
│  Connected ✓    │  ────────────────────             │
│  User: admin    │  Members (3):                      │
│  Uptime: 2h 5m  │  • Alice 🔊 🎤                     │
│                 │  • Bob   🔇 🎤                     │
│                 │  • Charlie 🔊 🎤                   │
│                 │                                    │
│  VOICE CONTROL  │  [Leave Channel] [Mute ▼] [Vol ▼] │
│  ─────────────  │                                    │
│  🎤 Microphone  │ CHAT (Future):                     │
│  • Off          │ ─────────────────                  │
│  • Low          │ [Text message box]                 │
│  • Medium ✓     │                                    │
│  • High         │                                    │
│                 │                                    │
│  🔊 Speaker     │                                    │
│  • Mute         │                                    │
│  • 50% ✓        │                                    │
│  • 100%         │                                    │
└─────────────────┴───────────────────────────────────┘
```

## Screens & Views

### 1. Connection Setup Screen
**Initial screen when app launches or not connected.**

**Components:**
- Server Host input field (default: localhost)
- Server Port input field (default: 50051)
- Admin Token input field (masked)
- Connection status indicator
- Connect button
- Settings button

**Functionality:**
- Validate inputs before connecting
- Show connection progress spinner
- Display error messages clearly
- Save last used host/port (not token)
- Disable inputs while connecting

### 2. Main Window (Connected State)

**Left Sidebar:**
- Server connection status
- Current user info
- Uptime counter
- Voice control (microphone selection, mute toggles)
- Volume sliders

**Center Panel - Channels:**
- Scrollable list of all channels
- Channel icons/indicators
- Unread message count (future)
- Right-click context menu for private channels
- Search/filter channels

**Right Panel - Channel View:**
- Channel name and description
- Member list with status indicators
- Audio activity visualization
- Mute/unmute controls
- Leave channel button
- Channel settings (if owner)

### 3. Settings Dialog
**Accessible from main window menu/button.**

**Sections:**
- Audio Settings
  - Microphone device selection
  - Speaker device selection
  - Microphone volume
  - Speaker volume
  - Enable/disable voice activity detection
  - Bitrate preference
- Network Settings
  - Proxy configuration (future)
  - Network timeout settings
  - Bandwidth limiting (future)
- Appearance
  - Theme (light/dark)
  - Language
  - Font size
- Advanced
  - Log level
  - Enable debug mode
  - Cache location

### 4. Connection Failed Dialog
**Shown when connection fails.**

**Components:**
- Error message explanation
- Error code/details
- Retry button
- Settings button (to check server info)
- Exit button

## User Interactions

### Initial Connection Flow
```
Launch App
    ↓
Show Setup Screen
    ↓
User enters server details and token
    ↓
User clicks Connect
    ↓
Validate inputs
    ↓
Attempt gRPC connection to server
    ↓
Success: Load main window, fetch channel list
    ↓
Failure: Show error dialog with retry
```

### Joining a Voice Channel
```
User sees channel list
    ↓
User clicks on channel
    ↓
Client requests JoinChannel
    ↓
Server adds user to channel
    ↓
Server sends member list to user
    ↓
Client switches to channel view
    ↓
Client subscribes to voice stream for channel
    ↓
User can now speak/hear
```

### Speaking in Channel
```
User unmutes microphone (if muted)
    ↓
Audio captured from microphone device
    ↓
Audio encoded with Opus codec
    ↓
Packets sent to server voice stream
    ↓
Server receives and broadcasts to channel
    ↓
Other clients in channel decode and play audio
```

### Leaving Channel
```
User clicks Leave Channel button
    ↓
Client sends LeaveChannel request
    ↓
Stop sending voice packets
    ↓
Stop receiving voice stream
    ↓
Clean up audio decoders for channel members
    ↓
Return to channel list view
```

## Audio Subsystem Integration

### Audio Device Management
- Enumerate available audio devices on startup
- Allow user to select microphone and speaker
- Handle device hotplug (future)
- Fallback to default device if selected unavailable

### Microphone Input
- Capture from selected device
- Apply gain adjustment
- Encode to Opus
- Send to server as voice packets
- Display audio level visualization (optional VU meter)

### Speaker Output
- Receive voice packets from server
- Decode Opus streams
- Mix multiple speakers
- Apply volume adjustment
- Play through selected speaker device

### Mute Controls
- Toggle microphone mute (spacebar toggle, button click)
- Toggle speaker mute
- Show mute status in UI

## Visual Indicators

### User Status in Channel
- Online circle (green)
- Idle circle (yellow)
- Away circle (gray)
- Microphone icon: On/Off/Muted
- Speaker icon: On/Off/Muted

### Audio Activity
- Animated waveform or bars for speaking users
- Visual feedback when detecting microphone input
- Volume level indicator

## Notifications & Alerts

### User Joined/Left Channel
- Toast notification in corner (optional)
- Activity log in channel view
- Sound notification (optional, configurable)

### Connection Issues
- Reconnection attempts with exponential backoff
- Show connection status in UI (Connecting..., Reconnecting..., Connected)
- Display latency/ping time

### Permission Denied
- Clear error message if user can't join channel
- Suggestion to contact admin

## Error Handling & Recovery

**Connection Lost:**
- Mark as "Disconnected" immediately
- Attempt automatic reconnection every 5 seconds
- Show reconnection progress
- Queue voice packets locally (discard after 30 seconds)
- Clear channel member list

**Audio Device Error:**
- Notify user that audio device is unavailable
- Suggest to select different device
- Provide option to retry

**Invalid Token:**
- Show authentication error
- Return to setup screen
- Clear saved host/port (not token, store separately)

**Crashed/Ungraceful Disconnect:**
- Server timeout (30 seconds): mark user offline, remove from channel
- Client crash: reconnect with same session if within timeout

## Performance Requirements
- UI responsiveness: <100ms for user input feedback
- Channel list loads: <1 second for 100 channels
- Member list updates: Real-time, <100ms delay
- Voice latency: <100ms end-to-end
- Memory footprint: <200MB typical usage
- CPU: <10% on modern dual-core for typical usage

## Configuration Files

### Client Config (`~/.openspeak/config.json`)
```json
{
  "last_server_host": "localhost",
  "last_server_port": 50051,
  "audio": {
    "microphone_device": "Default",
    "speaker_device": "Default",
    "microphone_volume": 80,
    "speaker_volume": 100,
    "enable_vad": false,
    "bitrate_kbps": 64
  },
  "ui": {
    "theme": "light",
    "font_size": 12,
    "language": "en"
  },
  "advanced": {
    "log_level": "info",
    "debug_mode": false
  }
}
```

## Future Enhancements
- Text chat within channels
- Direct messages between users
- Screen sharing
- Video (future, significant feature)
- Custom emojis/status
- User profiles with avatars
- Channel favorites/pinning
- Search functionality
- Notification settings per channel
- Audio recording