🎙️ Viz - Decentralized P2P Voice Communication via UDP Tunnels

Viz is a decentralized P2P voice communication application written in Go. It solves the Symmetric NAT problem through UDP tunneling services, allowing users to choose any intermediary servers, UDP reverse proxies, or use their own VPS.

✨ Features

• 🌐 Decentralized Architecture: P2P communication utilizing UDP tunneling services
• 🚫 NAT Bypass: Solves Symmetric NAT problems via UDP relay/tunneling
• 🔧 Server Flexibility: Works with any UDP-capable tunneling services or custom proxies
• 🚀 Low Latency: Migrated from WebSockets (TCP) to raw UDP for optimized real-time voice performance
• 🎛️ Modern Audio Core: Powered by the custom Votline/Go-audio engine featuring an integrated ringbuffer module
• ⚡ Lock-Free Hotpath: Uses atomic.Value for error/warning communication and aggressive buffer reuse to completely eliminate allocations and mutex contention in the hotpath
• 🎵 High-Quality Audio: OPUS codec with 32 kbps bitrate
• 📦 Aggressive Compression: OPUS + Zstandard for traffic minimization
• ⏱️ Optimized Chunks: 40ms audio chunks with 320ms batch delay to stay tunnel-friendly
• 🔄 Bidirectional Communication: Simultaneous recording and playback
• 🛡️ Thread-Safe: Safe multi-threaded audio processing with atomic state management
• 📊 Detailed Logging: Zap integration with an optional debug mode

🏗️ Architecture

┌──────────────────┐    Tunnel Service    ┌──────────────────┐
│   User1 (srv)    │ ◄─────────────────►  │   User2 (clt)    │
│                  │     (ngrok/CF/etc)   │                  │
│ ┌──────────────┐ │                      │ ┌──────────────┐ │
│ │ AudioStream  │ │                      │ │ AudioStream  │ │
│ │              │ │                      │ │              │ │
│ │ ┌─────────┐  │ │                      │ │ ┌─────────┐  │ │
│ │ │ Buffer  │  │ │                      │ │ │ Buffer  │  │ │
│ │ └─────────┘  │ │                      │ │ └─────────┘  │ │
│ │ ┌──────────┐ │ │                      │ │ ┌──────────┐ │ │
│ │ │Compressor│ │ │                      │ │ │Compressor│ │ │
│ │ └──────────┘ │ │                      │ │ └──────────┘ │ │
│ └──────────────┘ │                      │ └──────────────┘ │
└──────────────────┘                      └──────────────────┘
           │                                        │
           └─────────── NAT Problem ────────────────┘
               (Solved via tunneling services)

How it works:

1. User1 starts the application in server mode (srv)
2. User1 tunnels their server through any service (ngrok, cloudflare, localhost.run)
3. User1 shares the tunnel URL with User2
4. User2 starts the client (clt) and connects to the URL
5. Connection established through the tunneling service, bypassing Symmetric NAT

Core Components:

• AudioStream: Audio flow management (recording/playback)
• Buffer: Ring buffer for audio data with thread-safe operations
• Compressor: Dual compression (OPUS → Zstandard) for traffic optimization
• Batch: Batching system that packs multiple audio frames (8 frames per batch) into single packets
• Queue: Queue for buffering incoming audio packets
• Server: WebSocket server for accepting connections
• Client: WebSocket client for connecting to server

🚀 Quick Start

Using Pre-built Releases (Recommended)

If you download pre-built releases from GitHub Releases, PortAudio and Opus libraries are already embedded in the binary. You don't need to install any additional dependencies - just download and use the binary.

Dependencies

If you want to build the application yourself, you need to install system dependencies first:

Required System Dependencies:

• PortAudio: Cross-platform audio I/O library

  • Official website: http://www.portaudio.com/
  • GitHub: https://github.com/PortAudio/portaudio
  • Installation:
    • Linux:
      • sudo apt-get install portaudio19-dev (Debian/Ubuntu)
      • sudo yum install portaudio-devel (Fedora/RHEL)
      • sudo pacman -S portaudio (Arch Linux)
    • macOS: brew install portaudio
    • Windows: Download from PortAudio downloads

• Opus: High-quality audio codec library

  • Official website: https://opus-codec.org/
  • Installation:
    • Linux:
      • sudo apt-get install libopus-dev (Debian/Ubuntu)
      • sudo yum install opus-devel (Fedora/RHEL)
      • sudo pacman -S opus (Arch Linux)
    • macOS: brew install opus
    • Windows: Use pre-built libraries from Opus downloads

How it works:

1. User1 starts the application in server mode specifying the port via CLI flags.
2. User1 tunnels their UDP server through a tunnel service or custom VPS proxy.
3. User1 shares the public UDP tunnel URL/address with User2.
4. User2 starts the application in client mode and connects directly to the tunnel address.
5. Connection established through raw UDP, bypassing Symmetric NAT.

Core Components:

• Go-audio Core: High-performance audio engine (Votline/Go-audio) managing core streams and native I/O.
• RingBuffer: Specialized module for streaming audio data with thread-safe, optimized operations.
• Compressor: Dual compression (OPUS → Zstandard) for traffic optimization.
• Batch: Packetizer that groups 8 audio frames (320ms total delay) into a single UDP datagram to minimize tunnel overhead.
• Network Layer: Pure net.UDP implementation replacing legacy WebSocket over TCP.

🚀 Quick Start

CLI Arguments & Usage

Viz completely relies on CLI flags instead of interactive stdin prompts. Tunneling and port forwarding are handled by the user.

# Display help message
./viz -h
# or
./viz help

# Start Server on port 8080 with Debug logging enabled
./viz -s 8080 -d

# Start Client and connect to the server/tunnel address with Debug logging enabled
./viz -c remote-tunnel-url:8080 -d

⚙️ Configuration

Audio Parameters:

• Sample Rate: 48 kHz
• Channels: Mono (1 channel)
• Bitrate: 32 kbps
• Buffer Size: 2048 samples
• Chunk Duration: 40 ms (optimal for OPUS codec, supports 2ms-120ms range)

Tunnel Optimization:

• Batching: 8 frames × 40ms = 320ms delay (optimized for tunneling services)
• Dual Compression: OPUS + Zstandard to minimize packet size
• Rare Requests: Prevents bans from tunneling services

Network Parameters:

• Port: 8443
• Read Timeout: 28 seconds
• Write Timeout: 28 seconds
• Idle Timeout: 28 seconds

🔧 Technical Details

Audio Processing:

1. Recording: PortAudio → Float32 → Int16 → OPUS → Zstandard → (E2EE encryption at network layer, not in audio processing chain)
2. Playback: (E2EE decryption at network layer) → Zstandard → OPUS → Int16 → Float32 → PortAudio

Note: End-to-End Encryption (E2EE) is applied at the network transport layer after audio compression, not within the audio processing pipeline itself.

Compression (tunnel optimization):

• OPUS: Audio codec for voice communication (32 kbps)
• Zstandard: Additional compression to minimize traffic
• Result: Maximum compression to avoid tunnel bans

Buffering:

• Ring Buffers: Circular buffers used for both recording and playback operations
  • Thread-safe operations with mutexes
  • Automatic overflow management
  • Separate read/write positions for efficient data flow
• Batching: Multiple compressed audio frames (8 frames × 40ms = 320ms total delay) are packed into single packets
  • Reduces WebSocket overhead
  • Creates ~320ms delay optimized for tunneling services (avoids bans)
• Chunks: 40ms audio chunks (optimal value for OPUS codec, which supports 2ms-120ms range)

📄 Licenses

Main License

This project is distributed under the MIT License. See the LICENSE file for details.

📦 Dependencies

Package	Version	Purpose
github.com/gorilla/websocket	v1.5.3	WebSocket connections
go.uber.org/zap	v1.27.0	Structured logging
golang.org/x/crypto	v0.43.0	Encryption (NaCl Box)
github.com/Votline/Go-audio	v1.1.0	Audio (Compress, record, play)

• Gorilla WebSocket: BSD 2-Clause License - see licenses/gorilla-websocket_LICENSE.txt
• Uber Zap: MIT License - see licenses/uber-zap_LICENSE.txt
• Go-audio: MIT License - see licenses/Votline-Go-audio_LICENSE.txt