TermFace

Secure terminal video call. Your webcam rendered as color ASCII art, with end-to-end encrypted peer-to-peer calls — works internationally, no Docker required.

Features

International Calls (WebRTC)

• Free TURN relay — OpenRelay servers handle NAT traversal, no setup needed
• Cloudflare Worker signaling — deployed at wss://termface-signaling.termface.workers.dev
• Server-assigned roles — the signaling server atomically assigns offerer/answerer roles
• Welcome with peers list — server tells you who's already in the room
• Auto-reconnect — 2.5s retry on disconnect
• Remote video as ASCII art — receive and display peer's webcam in your terminal
• Audio playback — hear your peer through speakers (PyAudio)
• 10fps optimized rendering — smooth display without freezing the terminal

End-to-End Encryption

• X25519 key exchange — shared secret derivation
• XSalsa20-Poly1305 — authenticated encryption (AEAD)
• Sequence numbers with replay protection
• Key rotation every 256 messages
• Encryption enabled by default for all calls

Audio & Video

• Opus audio codec — 24kHz at 32kbps, echo cancellation, noise gate
• Camera capture — OpenCV-backed, multiple device support
• Screen sharing — share your terminal or desktop
• Mute/camera controls — toggle mic and camera during calls

Compression & Transport

• zstd compression — with backward-compatible header detection
• TCP fallback — for LAN calls when no signaling server is available
• Session strings — share happy-sunset-ocean instead of IP addresses

In-Call Features

• Structured terminal UI — status bar, participant list, chat panel, controls
• Chat — in-call text messaging via data channel
• File transfer — cancel, pause/resume, disk preflight, SHA-256 verification
• Screenshots — save ASCII art as .txt and .png
• Recording — crash-safe pause/resume, atomic writes, live indicator
• Background effects — blur and removal (requires MediaPipe)
• Call quality stats — real-time RTT, bandwidth, packet loss, jitter
• Adaptive bitrate — auto-adjusts quality based on network conditions
• Audio jitter buffer — smooth playback despite uneven network arrivals
• Mesh SFU — group call relay for 3+ participants
• Peer state broadcasting — mute/video/screen status shared with peers

Install

Mac / Linux

pip install TermFace

Windows

pip install TermFace

That's it. No Docker, no workarounds, no extra configuration.

From Source

git clone https://github.com/Yash12b/TermFace.git
cd TermFace
pip install -e ".[dev]"

Quick Start

International Call (WebRTC)

# Person A
termface call --room happy-ocean-sunset

# Person B (same room name)
termface call --room happy-ocean-sunset

The second person to join automatically becomes the answerer. No role selection needed.

Local ASCII Webcam

ascii-cam

TCP Call (LAN only)

# Person A (starts server)
termface facetime --session myroom

# Person B (connects to A's IP)
termface facetime --session myroom --target 192.168.1.100

WebRTC Call (manual roles)

# Person A (answerer)
termface webrtc --role answerer --room myroom

# Person B (offerer)
termface webrtc --role offerer --room myroom --camera --microphone

Keyboard Controls

Architecture

┌──────────────────────────────────────────────────┐
│  Terminal UI (TerminalUI + ASCII rendering)       │
├──────────────────────────────────────────────────┤
│  WebRTC Layer                                    │
│  ├── AiortcTransport (camera/mic RTP tracks)    │
│  ├── MeshSFU (group call relay)                 │
│  ├── WebSocketSignaling (Cloudflare Worker)      │
│  ├── Generation-based reconnect (2.5s delay)    │
│  └── Server-assigned roles (offerer/answerer)   │
├──────────────────────────────────────────────────┤
│  Media Layer                                     │
│  ├── VideoProcessor (capture → resize → JPEG)   │
│  ├── AdaptiveBitrate (AIMD quality control)     │
│  ├── AudioSystem (PyAudio + Opus codec)          │
│  ├── JitterBuffer (adaptive depth playback)     │
│  ├── ASCIIRenderer (color/mono/grayscale)        │
│  └── FrameCompressor (zstd compression)         │
├──────────────────────────────────────────────────┤
│  Protocol Layer                                  │
│  ├── Frame (binary framing)                      │
│  ├── Encryptor (XSalsa20-Poly1305)               │
│  ├── MediaPacket (sequence numbers)              │
│  └── FileTransferManager (cancel/pause/resume)  │
├──────────────────────────────────────────────────┤
│  Network Layer                                   │
│  ├── AiortcTransport (WebRTC, default)           │
│  ├── TCPMediaServer/Client (TCP fallback)        │
│  └── DiscoveryService (STUN + LAN)              │
├──────────────────────────────────────────────────┤
│  ICE Configuration                               │
│  ├── Google STUN servers (free)                  │
│  ├── OpenRelay TURN servers (free)               │
│  └── Cloudflare Worker signaling                 │
└──────────────────────────────────────────────────┘

Cloudflare Worker Signaling

The signaling server is a Cloudflare Worker with Durable Objects, deployed at:

wss://termface-signaling.termface.workers.dev

Deploy your own

cd deployment
npx wrangler deploy

Endpoints

Security

• Encryption enabled by default for all calls
• X25519 key exchange for shared secret derivation
• XSalsa20-Poly1305 authenticated encryption (AEAD)
• Sequence numbers with replay protection
• Key rotation every 256 messages
• Invite tokens with HMAC-SHA256 signatures and room scoping
• Rate limiting — 200 messages per 10s per client on the signaling server
• Message schema validation — only valid WebRTC/chat/file messages are forwarded
• Room capacity limit — max 2 peers per room for direct P2P calls

To disable encryption (not recommended):

termface facetime --no-encrypt

Diagnostics

# Check system requirements
termface doctor

# Update to latest version
termface update

Requirements

• Python 3.10+
• OpenCV (opencv-python)
• NumPy (numpy)
• PyNaCl (PyNaCl) — for encryption

Optional (included with [webrtc]):

• aiortc — WebRTC transport
• websockets — WebSocket signaling
• PyAudio — audio playback
• opuslib — Opus audio codec
• mss — screen capture
• zstandard — compression

Platform Support

License

MIT