TermFace

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

What's New in v2.0

• Authenticated encryption — XSalsa20-Poly1305 (libsodium), enabled for shared sessions or an explicit key
• Opus audio codec — 24kHz at 32kbps (10x compression over raw PCM), echo cancellation, noise gate
• zstd compression — 3-5x compression for ASCII frames over the wire
• TCP media transport — reliable delivery with flow control (no more UDP packet drops)
• Session strings — share happy-sunset-ocean instead of IP addresses
• Multi-client grid renderer — ready for a future relay-based group-call service
• 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

Install

From PyPI

pip install TermFace

If you use pipx, install and update it with:

pipx install TermFace
pipx upgrade TermFace

After the initial install, update TermFace without Git or a project folder:

termface update

The updater uses the same Python interpreter that launched TermFace, so it updates the correct installation on Windows, macOS, and Linux.

From Source

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

Quick Start

ASCII Webcam (local)

ascii-cam
# or
termface ascii

Video Call

# Person A (call 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 --target 192.168.1.100

All Options

termface facetime --help
termface ascii --help

Controls (during call)

Architecture

terminal_webcam/
├── protocol.py     # Binary protocol (10-byte header, length-prefixed)
├── crypto.py       # libsodium XSalsa20-Poly1305 encryption
├── audio.py        # Opus codec + echo cancellation + noise gate
├── video.py        # ASCII renderer + zstd compression + background effects
├── network.py      # TCP multiplexed transport + auto-reconnect
├── discovery.py    # LAN discovery + session strings + STUN
├── quality.py      # Adaptive quality + call stats
├── terminal_facetime.py  # Main app
└── webcam_ascii.py       # Local webcam viewer

Security

• Authenticated encryption using libsodium when a shared session or key is supplied
• XSalsa20-Poly1305 AEAD cipher
• Key rotation every 256 messages
• Shared session strings should be treated as secrets and exchanged over a trusted channel
• Calls using --session derive the same encryption key from the shared session string. Direct IP calls can use --encrypt-key; otherwise they run without encryption.

Testing

pip install -e ".[dev]"
pytest tests/ -v

License

MIT