Metadata-Version: 2.4
Name: TermFace
Version: 2.0.6
Summary: Secure terminal video call — TCP media, Opus audio, libsodium E2E encryption, session strings
Author: Yash12b
License-Expression: MIT
Project-URL: Homepage, https://github.com/Yash12b/TermFace
Project-URL: Repository, https://github.com/Yash12b/TermFace
Project-URL: Issues, https://github.com/Yash12b/TermFace/issues
Keywords: ascii,webcam,terminal,videocall,encryption,opus,color,art
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Communications
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opencv-python>=4.8
Requires-Dist: numpy>=1.24
Requires-Dist: PyNaCl>=1.5.0
Provides-Extra: audio
Requires-Dist: PyAudio>=0.2.14; extra == "audio"
Requires-Dist: opuslib>=3.0.1; extra == "audio"
Provides-Extra: screen
Requires-Dist: mss>=9.0; extra == "screen"
Provides-Extra: compression
Requires-Dist: zstandard>=0.20.0; extra == "compression"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install TermFace
```

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

```bash
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

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

## Quick Start

### ASCII Webcam (local)

```bash
ascii-cam
# or
termface ascii
```

### Video Call

```bash
# 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

```bash
# 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

```bash
termface facetime --help
termface ascii --help
```

## Controls (during call)

| Key | Action |
|-----|--------|
| `t` | Chat (type message, Enter to send) |
| `f` | Send file |
| `1-4` | Color mode: mono / grayscale / color / invert |
| `e` | Toggle edge detection |
| `b` | Toggle background blur |
| `r` | Toggle recording / background removal |
| `s` | Screenshot (ASCII .txt + .png) |
| `c` | Cycle character set |
| `+/-` | Brightness |
| `[/]` | Contrast |
| `q` | Hang up / quit |

## 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

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

## License

MIT
