Metadata-Version: 2.4
Name: p2p-stream-v2-yoyo
Version: 2.0.0
Summary: Decentralized P2P live streaming — AES-256-GCM, LZ4, STUN/UPnP NAT traversal
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: System :: Networking
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: aiortc>=1.9.0
Requires-Dist: opencv-python>=4.9.0
Requires-Dist: click>=8.1.0
Requires-Dist: kademlia>=2.2.2
Requires-Dist: numpy>=1.26.0
Requires-Dist: av>=12.0.0
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# p2p-stream v2

> Decentralized, serverless P2P live streaming SDK.
> AES-256-GCM encrypted · LZ4 compressed · STUN/UPnP/HolePunch NAT traversal · Kademlia DHT · WebRTC mesh

## Features

- **C++ Core**: Frame encryption (AES-256-GCM via OpenSSL) and compression (LZ4), compiled as a native Python extension via pybind11. Falls back to pure-Python when not built.
- **NAT Traversal**: Automatic STUN public-endpoint discovery, UPnP IGD port forwarding, and concurrent UDP hole punching — peers behind NAT routers connect directly with no relay.
- **Kademlia DHT**: Serverless peer discovery and out-of-band signaling. No central server required.
- **WebRTC Mesh**: aiortc-based direct peer connections with DTLS-SRTP transport security and proximity-based peer selection.
- **5-Line API**: `StreamSession` publishes or watches in under 5 lines of Python.

## System Requirements

- Python >= 3.9
- C++17 compiler (GCC >= 10, Clang >= 12, MSVC 2019+)
- CMake >= 3.16
- OpenSSL >= 1.1
- Optional: liblz4 (LZ4 compression), libminiupnpc (UPnP port mapping)

## Install

### From source (builds native C++ extension)

```bash
pip install pybind11 cmake
pip install -e .
```

### With all optional native deps (Ubuntu/Debian)

```bash
sudo apt install libssl-dev liblz4-dev libminiupnpc-dev
pip install pybind11 cmake
pip install -e .
```

### Pure-Python fallback (no native build required)

```bash
pip install -r requirements.txt
```

All P2P streaming, DHT, and STUN features work. AES-256-GCM frame encryption and LZ4 compression require the native build.

## Quick Start

### Publisher (5 lines)

```python
import asyncio, p2p_stream

async def main():
    s = p2p_stream.StreamSession("myroom")
    await s.publish(bootstrap=[("seed.example.com", 8468)])
    await asyncio.Event().wait()

asyncio.run(main())
```

### Watcher (5 lines)

```python
import asyncio, p2p_stream

async def main():
    s = p2p_stream.StreamSession("myroom")
    await s.watch(bootstrap=[("seed.example.com", 8468)])
    await p2p_stream.display_track(s.node.upstream_track)

asyncio.run(main())
```

### E2E Encrypted Stream (requires native build)

```python
from _p2pstream_core import FrameCodec
key = FrameCodec.generate_key()

publisher = p2p_stream.StreamSession("secure-room", key=key)
await publisher.publish(bootstrap=[("seed.example.com", 8468)])

watcher = p2p_stream.StreamSession("secure-room", key=key)
await watcher.watch(bootstrap=[("seed.example.com", 8468)])
```

## CLI

```bash
p2p-stream genkey
```

```bash
export P2P_KEY=$(p2p-stream genkey)
p2p-stream publish --room live --host 0.0.0.0 --port 8468
```

```bash
p2p-stream watch --room live --bootstrap 192.168.1.10:8468 --port 8469
```

```bash
p2p-stream watch --room live --bootstrap node1:8468,node2:8469 --port 8470
```

## Architecture

```
Publisher ──[DHT announce]──► KademliaDHT
                                   │
Watcher  ──[DHT lookup]───────────►│
          ◄──[nearest peer]─────────┘
          ──[request + public EP]──► Publisher
          ◄──[WebRTC offer]──────────┘
          ──[WebRTC answer]─────────► Publisher
          ◄═══[video stream]═══════════╝  (DTLS-SRTP)

C++ DataChannel path (when key= provided):
  capture → LZ4 → AES-256-GCM → packetize(MTU=1200) → DataChannel
  DataChannel → reassemble → AES-256-GCM decrypt → LZ4 decompress → display
```

## NAT Traversal Strategy

1. **STUN** — Query public (IP, port) via multiple Google/Cloudflare servers, pure-Python fallback included
2. **UPnP IGD** — Request port mapping from router via libminiupnpc (silently skipped if unavailable)
3. **UDP Hole Punching** — Concurrent 12-attempt 200ms-interval punching before WebRTC SDP exchange
4. **TURN** — Add TURN credentials to `_ICE` in `node.py` for symmetric NAT environments

## License

MIT
