android_cast/README.md

# Android Cast (POC)

Minimal LAN screen-casting proof of concept in **Java**. Captures screen + playback audio, encodes **H.264 + AAC**, streams over **TCP or UDP** to a receiver that decodes and plays back.

## Features

- UDP broadcast discovery on the local network
- TCP or UDP stream transport (selectable; must match on both devices)
- PIN auth (SHA-256 hash, default `1234`)
- Screen capture → H.264 (AVC) with quality presets and scaled capture resolution
- Playback audio capture (API 29+) → AAC-LC
- Runtime notification permission (Android 13+)

## Quick start

1. Install the same APK on two devices on the **same Wi‑Fi**.
2. **Receiver** (TV): **Receive** → match transport (TCP/UDP) & options → tap **Start listening** (notification appears; service keeps running).
3. **Sender** (tablet): **Send** → **same transport** → pick receiver → PIN → approve screen capture.
4. Watch the **notification** on both devices for connection status (not only the toast).
5. Stop from the notification **Stop** action.

### If video never appears

- Transport must match on both sides (e.g. both TCP).
- Receiver must show *Listening* or *Ready* in the notification before you cast.
- Sender notification should reach *Casting via TCP · WxH* — if it shows *Screen capture data missing*, reinstall and try again (Android 13+ intent fix).
- Keep the receiver UI open once so the video `Surface` attaches (or return to it after rotation).

## Build

Use **JDK 17 or 21** (Gradle does not run on JDK 25 yet):

```bash
export JAVA_HOME=/usr/lib/jvm/openjdk-bin-21
cd "/home/foxx/repos/My Projects/android cast"
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk
```

## Stream options

| Option | Effect |
|--------|--------|
| **Transport TCP** | Reliable delivery; default |
| **Transport UDP** | Lower latency, may drop frames (POC) |
| **Quality Low/Med/High** | Video bitrate 0.8 / 2 / 4 Mbps and FPS 20 / 24 / 30 |
| **Resolution** | Scales VirtualDisplay before encode (full, 75%, 50%, or max 720p height) |
| **Audio** | `AudioPlaybackCapture` + AAC (Android 10+) |

## Protocol

| Step | Description |
|------|-------------|
| Discovery | UDP `41234`, JSON with `magic`, `name`, `port`, `transport` |
| Connect | TCP or UDP port `41235` |
| Auth | `HELLO` → `AUTH` → `AUTH_OK` → `CAST_SETTINGS` |
| Stream | `STREAM_CONFIG`, `VIDEO_FRAME`, `AUDIO_CONFIG`, `AUDIO_FRAME` |

UDP frames use `ACUD` header and fragmentation for payloads > ~1.2 KB.

## Bluetooth / BLE

**Not viable for this video stream.** Practical throughput:

- **BLE**: ~100–300 kb/s — fine for control/metadata only
- **Bluetooth Classic (SPP)**: often ~1–3 Mb/s theoretical — still far below 720p H.264 (~2–8 Mb/s), with high latency

A phone cannot “passthrough” a live encoded screen stream over BLE to another device for playback without a custom high-bandwidth profile (which consumer Android does not expose for arbitrary apps). Use **Wi‑Fi** for media; BT could be added later only for discovery/pairing if needed.

## Persistent services (AIDL)

Casting runs in **foreground services** with tray notifications:

| Service | Role |
|---------|------|
| `ScreenCastService` | Sender — capture, encode, stream |
| `ReceiverCastService` | Receiver — listen, decode, play |

Activities bind via AIDL (`ICastSenderService` / `ICastReceiverService`) for status updates and (on the receiver) attaching the video `Surface`. Rotating the screen or leaving the app does **not** stop the receiver listener; the sender keeps casting until you tap **Stop** in the notification.

## Limitations

- No TLS encryption (LAN cleartext POC)
- UDP mode may glitch under load
- Audio captures **playback** routed through the system (not microphone); some apps may be silent by policy
- Single sender → single receiver