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)

{
  "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