TermFace

Secure terminal video call. Your webcam rendered as color ASCII art, with end-to-end encrypted peer-to-peer calls.

Features

Stable (TCP Transport)

• End-to-end encryption — X25519 key exchange + XSalsa20-Poly1305 (libsodium)
• Opus audio codec — 24kHz at 32kbps, echo cancellation, noise gate
• zstd compression — with backward-compatible header detection
• Session strings — share happy-sunset-ocean instead of IP addresses
• Auto-reconnection — exponential backoff with up to 5 retries
• Call quality stats — real-time RTT, bandwidth, and duration display
• LAN discovery — automatic peer discovery on local network
• Chat — in-call text messaging
• File transfer — with SHA-256 checksum verification and progress display
• Screenshots — save ASCII art as .txt and .png
• Recording — capture video/audio to AVI/WAV files
• Mute/camera controls — toggle mic and camera during calls
• Background effects — blur and removal (requires MediaPipe)

Experimental (WebRTC Transport)

• WebRTC data channel — for chat and control messages
• RTP media tracks — camera and microphone via aiortc
• Remote media rendering — receive and display remote video as ASCII
• ICE configuration — STUN/TURN server support

In Progress

• SFU integration — group calls via LiveKit/Janus (planned)
• Structured terminal UI — status bar, chat panel, participant list (planned)

Install

From PyPI

pip install TermFace

With optional dependencies:

# Full install (audio, screen, compression, WebRTC)
pip install "TermFace[full]"

# Just audio support
pip install "TermFace[audio]"

# Just WebRTC support
pip install "TermFace[webrtc]"

From Source

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

Quick Start

ASCII Webcam (local)

ascii-cam

Video Call

# Person A (receiver) — start first, wait for incoming
termface facetime

# Person B (caller) — connect to A's IP
termface facetime --target 192.168.1.100

With Session Strings

# Person A starts with a session string
termface facetime --session happy-sunset-ocean

# Person B joins using the same session string
termface facetime --session happy-sunset-ocean

WebRTC Call (Experimental)

# Requires: pip install "TermFace[webrtc]"

# 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 (ASCII rendering)              │
├─────────────────────────────────────────────┤
│  Media Layer                                │
│  ├── VideoProcessor (capture → resize → JPEG)│
│  ├── AudioSystem (PyAudio + Opus codec)     │
│  └── FrameCompressor (zstd compression)     │
├─────────────────────────────────────────────┤
│  Protocol Layer                             │
│  ├── Frame (binary framing)                 │
│  ├── Encryptor (XSalsa20-Poly1305)          │
│  └── MediaPacket (sequence numbers)         │
├─────────────────────────────────────────────┤
│  Network Layer                              │
│  ├── TCPMediaServer/Client (TCP transport)  │
│  ├── AiortcTransport (WebRTC, optional)     │
│  └── DiscoveryService (STUN + LAN)          │
├─────────────────────────────────────────────┤
│  Signaling Layer                            │
│  ├── SignalingClient/Server (TLS relay)     │
│  └── Invite tokens (HMAC-SHA256)            │
└─────────────────────────────────────────────┘

Security

• Encryption enabled by default for all calls with session strings
• 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 expiration and room scoping

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:

• PyAudio + opuslib — for audio
• mss — for screen capture
• zstandard — for compression
• aiortc — for WebRTC

License

MIT