Voice Chat System

The voice chat subsystem is the streaming core of Solstice. It interfaces directly with Telegram's WebRTC voice chat protocol using a native CGo libntgcalls engine paired with a GoGram MTProto assistant client (internal/vc/).

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      internal/vc Subsystem                      │
│                                                                 │
│  ┌───────────────────────────┐     ┌─────────────────────────┐  │
│  │ Assistant (assistant.go)  │     │ Engine (engine.go)      │  │
│  │                           │     │                         │  │
│  │ • GoGram MTProto Client   │     │ • CGo libntgcalls binding│  │
│  │ • Universal Session string│────►│ • In-process WebRTC     │  │
│  │ • Join/Leave Group Call   │     │ • Raw PCM/VP8 encoding  │  │
│  │ • Active Sessions Tracker │     │ • FFmpeg input pipeline │  │
│  │ • Alone Timeout Handler   │     │ • OnStreamEnd callback  │  │
│  └─────────────┬─────────────┘     └────────────┬────────────┘  │
│                │                                │               │
│                └───────────────┬────────────────┘               │
│                                │                                │
│                                ▼                                │
│                   Telegram Voice Chat WebRTC                    │
└─────────────────────────────────────────────────────────────────┘

---

Core Components

1. The Assistant Client (internal/vc/assistant.go)

• MTProto Connectivity: Connects to Telegram using github.com/amarnathcjd/gogram/telegram.
• Session Management: Automatically resolves and parses session strings from GoGram, Pyrogram, or Telethon formats without manual conversion.
• Group Call Handshake: Requests group call join parameters (phone.JoinGroupCall) and passes cryptographic WebRTC credentials to the native engine.
• Session Persistence: Maintains open sessions between consecutive tracks so stream switching happens instantaneously with 0ms rejoin latency.
• Alone Detection: Detects when all members leave the voice chat and starts a countdown timer before cleanly leaving to preserve server resources.

2. The Native Engine (internal/vc/engine.go)

• CGo libntgcalls Binding: Calls directly into the high-performance C library without spawning external Python processes or communicating over local network sockets.
• Media Ingestion: Takes YouTube, direct audio/video URLs, or local files and streams them directly into the voice chat.
• Controls:
  • SetStream(chatID, url, isVideo): Swaps the active stream in-place.
  • Pause(chatID) / Resume(chatID): Halts or resumes WebRTC RTP packet transmission.
  • Time(chatID): Reports exact playback timestamp for progress calculation.
  • ChangeVolume(chatID, volume): Adjusts stream gain from 1% to 200%.

---

Playback Lifecycle

1. Dispatcher receives play request
   │
   ▼
2. Assistant checks if already in voice chat
   ├── If not joined: Resolves group call, requests WebRTC credentials
   └── If joined: Reuses active peer connection
   │
   ▼
3. Engine starts FFmpeg media pipeline
   │
   ▼
4. Media frames piped into Telegram WebRTC voice stream
   │
   ▼
5. On track completion:
   - libntgcalls fires OnStreamEnd callback
   - Dispatcher pops current song and advances queue
   - Next track begins in-place with zero reconnect delay

---

Performance & Optimization

• Zero IPC Latency: Eliminates the 50-100ms HTTP round-trip latency of external daemons.
• Memory Efficient: Uses ~80% less RAM than equivalent Python-based voice streaming daemons.
• Thread Safety: All active session maps are guarded by sync.RWMutex to guarantee stability under high concurrency.