Metadata-Version: 2.4
Name: freq-cli
Version: 0.1.2
Summary: Secure, stateless TUI chat and voice. Drop into a frequency and broadcast.
Project-URL: Homepage, https://github.com/antares699/freq
Author: antares699
License-Expression: MIT
Keywords: audio,encrypted,radio,secure,terminal,tui,walkie-talkie
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Multimedia :: Sound/Audio
Requires-Python: >=3.10
Requires-Dist: cryptography>=44.0.0
Requires-Dist: miniaudio
Requires-Dist: numpy
Requires-Dist: textual
Requires-Dist: websockets
Description-Content-Type: text/markdown


# freq

Secure, stateless TUI chat and voice. Drop into a frequency and broadcast. Zero logs, zero identity, end-to-end encrypted.

## Fullscreen and unmute for better experience 
[![Watch the Freq Demo](https://github.com/user-attachments/assets/7a2144db-721b-486e-ad66-2d1cd00882f3)](https://github.com/user-attachments/assets/e15cb0b0-852b-46e6-a058-f46177dee5e6)

*This is between two different devices on different Operating Systems and different terminals*

## Install

```bash
pip install freq-cli
```

## Usage

```bash
freq
```

Inside the app:

| Command | Action | Example |
|---|---|---|
| `/tune <frequency>` | Join a frequency | `/tune 104.5` or `/tune flavortown` |
| `/nick <name>` | Set your display name | `/nick flavorpheus` |
| `/leave` | Disconnect | `/leave` |
| `Ctrl+R` | Toggle audio streaming | *Press `Ctrl+R` to start/stop* |
| *(Type anything else)* | Send an encrypted message | `Hello!` |

## How it works

- You type a frequency. The client uses **Argon2id** to derive a 32-byte AES key from that string.
- The client connects to the relay server and joins a room identified by the **SHA-256 hash** of the AES key. The server never sees the frequency or the key.
- All messages and audio are encrypted with **AES-256-GCM** before leaving your machine.
- Audio uses **real-time streaming** — each ~100ms chunk is encrypted and sent individually. Multiple voices are mixed with numpy for overlapping audio.
- The server is a stateless blind relay. It broadcasts encrypted blobs to the room and stores nothing.

## Security

| Layer | Implementation |
|---|---|
| Key derivation | Argon2id (64 MiB, 3 iterations) |
| Encryption | AES-256-GCM with random 12-byte nonce |
| Room identity | SHA-256 of AES key (server never sees frequency) |
| Transport | WSS (TLS) to relay server |
| Identity | None. No accounts, no keys on disk, no persistent state. |

## Requirements

- Python 3.10+
- A microphone (for audio streaming)
- A terminal that supports 256 colors
