Metadata-Version: 2.4
Name: TermFace
Version: 3.6.0
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
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: webrtc
Requires-Dist: aiortc<2,>=1.15.0; extra == "webrtc"
Requires-Dist: websockets>=12.0; extra == "webrtc"
Requires-Dist: PyAudio>=0.2.14; extra == "webrtc"
Provides-Extra: full
Requires-Dist: PyAudio>=0.2.14; extra == "full"
Requires-Dist: opuslib>=3.0.1; extra == "full"
Requires-Dist: mss>=9.0; extra == "full"
Requires-Dist: zstandard>=0.20.0; extra == "full"
Requires-Dist: aiortc<2,>=1.15.0; extra == "full"
Requires-Dist: websockets>=12.0; extra == "full"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Dynamic: license-file

# 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

```bash
pip install "TermFace[webrtc]"
```

### Windows

```bash
pip install "TermFace[webrtc]"
```

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

### From Source

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

## Quick Start

### International Call (WebRTC)

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

```bash
ascii-cam
```

### TCP Call (LAN only)

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

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

| Key | Action |
|-----|--------|
| `m` | Toggle microphone mute |
| `v` | Toggle camera on/off |
| `q` | Quit / leave call |
| `t` | Open chat (Enter to send, Esc to cancel) |
| `f` | Send file |
| `p` | Toggle push-to-talk mode |
| `1-4` | Color mode: mono / grayscale / color / invert |
| `e` | Toggle edge detection |
| `b` | Toggle background blur |
| `r` | Toggle recording (connected) / background removal (idle) |
| `c` | Cycle character set |
| `+/-` | Adjust brightness |
| `[/]` | Adjust contrast |
| `s` | Take screenshot (saves .txt and .png) |

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

```bash
cd deployment
npx wrangler deploy
```

### Endpoints

| Endpoint | Description |
|----------|-------------|
| `wss://.../ws/:room` | WebSocket signaling for WebRTC |
| `https://.../room/:room` | Room info (client count, IDs) |
| `https://.../health` | Health check |

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

```bash
termface facetime --no-encrypt
```

## Diagnostics

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

Optional (included with `[full]`):
- mss — screen capture
- zstandard — compression

## Platform Support

| Platform | Status |
|----------|--------|
| macOS (Apple Silicon) | Fully supported |
| macOS (Intel) | Fully supported |
| Windows (Python 3.10+) | Fully supported |
| Linux (Python 3.10+) | Fully supported |

## License

MIT
