# Camera TRNG

**TL;DR:** Turn any webcam into a true random number generator. Cover the lens, run the server, get random bytes.

## What is this?

Your webcam generates electrical noise even when the lens is covered. This noise comes from quantum effects in the sensor. This tool captures that noise and turns it into random numbers - the same approach used by [LavaRnd](https://www.lavarnd.org/).

## Quick Start

### 1. Install

```bash
# Clone and build
git clone https://git.nixc.us/colin/camera-trng.git
cd camera-trng
cargo build --release
```

### 2. Cover Your Camera Lens

Use tape, a lens cap, or put the camera in a dark box. The camera should see nothing but blackness.

### 3. Run

**macOS (native camera access via AVFoundation):**
```bash
./scripts/run-mac.sh
```

**Linux (native):**
```bash
./target/release/camera-qrng
```

**Linux (Docker with camera device):**
```bash
docker compose up -d
```

Server starts at `http://localhost:8787`

**Start with the OS (macOS LaunchAgent):**
```bash
./scripts/install-launchagent.sh
```
Runs the compiled binary at login and keeps it running. Logs go to `logs/`. To remove: `./scripts/uninstall-launchagent.sh`.

### 4. Get Random Bytes

```bash
# Get 32 random bytes (hex)
curl "http://localhost:8787/random?bytes=32&hex=true"

# Get 1KB of raw random data
curl "http://localhost:8787/random?bytes=1024" -o random.bin

# Continuous stream
curl -N "http://localhost:8787/stream"
```

## Is it actually random?

Yes. This tool passes all NIST SP 800-22 statistical tests for randomness:

```bash
# Run the built-in test suite
./scripts/test-randomness.py --server http://localhost:8787
```

The output is cryptographic quality - suitable for generating encryption keys, secure tokens, etc.

## API

| Endpoint | Description |
|----------|-------------|
| `GET /random?bytes=N` | Get N random bytes (max 1MB) |
| `GET /random?bytes=N&hex=true` | Get N random bytes as hex string |
| `GET /stream` | Continuous stream of random bytes |
| `GET /stream?bytes=N` | Stream exactly N bytes then stop |
| `GET /dice?d=6&count=3` | Roll quantum-random dice |
| `GET /password?length=24` | Generate quantum-random password |
| `GET /coin` | Quantum coin flip |
| `GET /8ball?question=...` | Quantum Magic 8 Ball |
| `GET /cameras` | List available camera devices |
| `GET /health` | Health check with pool stats |
| `GET /docs` | API documentation page |
| `GET /.well-known/mcp.json` | MCP discovery endpoint |

## Troubleshooting

**macOS "Camera in use" error:**
```bash
./scripts/release-camera.sh
./scripts/run-mac.sh
```

**Docker on macOS:** Docker on Mac runs Linux containers and cannot access the Mac camera. Use `./scripts/run-mac.sh` instead.

**Docker on Linux (explicit device):**
```bash
docker run -d --device /dev/video0 -p 8787:8787 camera-trng
```

## More Info

- [TECHNICAL.md](TECHNICAL.md) - Full API docs, CI/CD, configuration options
- [RESEARCH.md](RESEARCH.md) - The science behind camera-based random number generation

## License

CC-BY 4.0. See [LICENSE](LICENSE).