Metadata-Version: 2.4
Name: TermFace
Version: 3.3.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"
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"
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.

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

```bash
pip install TermFace
```

With optional dependencies:

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

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

## Quick Start

### ASCII Webcam (local)

```bash
ascii-cam
```

### Video Call

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

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

### WebRTC Call (Experimental)

```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 |
|-----|--------|
| `t` | Open chat (Enter to send, Esc to cancel) |
| `f` | Send file |
| `m` | Toggle microphone mute |
| `v` | Toggle camera on/off |
| `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) |
| `q` | Quit |

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

```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:
- PyAudio + opuslib — for audio
- mss — for screen capture
- zstandard — for compression
- aiortc — for WebRTC

## License

MIT
