triage tags api

README.md

@@ -1,32 +1,37 @@
 # Android Cast (POC)
 
-**Roadmap & alpha scope:** [docs/ROADMAP.md](docs/ROADMAP.md) · USB-C/HDMI: [docs/USB_HDMI_CAST.md](docs/USB_HDMI_CAST.md) · Commercial (dev-gated): [docs/COMMERCIAL.md](docs/COMMERCIAL.md)
+**Roadmap & alpha:** [docs/ROADMAP.md](docs/ROADMAP.md) · **Alpha QA & feature freeze:** [docs/ALPHA.md](docs/ALPHA.md) · USB-C/HDMI: [docs/USB_HDMI_CAST.md](docs/USB_HDMI_CAST.md) · Commercial (dev-gated): [docs/COMMERCIAL.md](docs/COMMERCIAL.md)
 
 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)
+- **UDP (default)** or TCP 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
+- Camera capture modes (API 29+, rear/front) — best-effort
 - Runtime notification permission (Android 13+)
 
-## Quick start
+## Quick start (alpha)
 
 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.
+2. **Receiver:** **Receive** → transport **UDP** → stream protection **None** → **Start listening** (notification *Listening* / *Ready*).
+3. **Sender:** **Send** → **UDP** → protection **None** → discover receiver → PIN → approve screen capture.
+4. Watch **notifications** on both devices for status.
+5. Stop from either notification **Stop** action.
+
+Full sign-off checklist: [docs/ALPHA.md](docs/ALPHA.md).
 
 ### 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).
+- Transport must match on both sides (e.g. both UDP).
+- Stream protection **None** on both sides for alpha.
+- Receiver must show *Listening* or *Ready* before you cast.
+- Sender notification should reach *Casting* with resolution — if it shows *Screen capture data missing*, reinstall (Android 13+ intent fix).
+- Open receiver playback once so the video `Surface` attaches (or return after rotation).
+- On rotation-sensitive senders, try **system rotation lock** during cast.
 
 ## Build
 
@@ -39,22 +44,29 @@ cd "/home/foxx/repos/My Projects/android cast"
 adb install -r app/build/outputs/apk/debug/app-debug.apk
 ```
 
-## Stream options
+## Stream options (defaults)
 
-| 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+) |
+| Option | Default / alpha note |
+|--------|----------------------|
+| **Transport** | **UDP** (`CastConfig.DEFAULT_TRANSPORT`) |
+| **Stream protection** | **None** |
+| **Quality** | Medium — 5 Mbps, 30 fps |
+| **Resolution** | Adaptive (sender) |
+| **Multi-receiver** | **Off** while `CastConfig.ALPHA_FEATURE_FREEZE` |
+| **Audio** | On when API 29+ (`AudioPlaybackCapture` + AAC) |
+
+| Quality | Video bitrate | FPS |
+|---------|---------------|-----|
+| Low | 1.5 Mbps | 24 |
+| Medium | 5 Mbps | 30 |
+| High | 10 Mbps | 30 |
 
 ## Protocol
 
 | Step | Description |
 |------|-------------|
 | Discovery | UDP `41234`, JSON with `magic`, `name`, `port`, `transport` |
-| Connect | TCP or UDP port `41235` |
+| Connect | TCP or UDP port `41235` (QUIC `41236` when enabled post-alpha) |
 | Auth | `HELLO` → `AUTH` → `AUTH_OK` → `CAST_SETTINGS` |
 | Stream | `STREAM_CONFIG`, `VIDEO_FRAME`, `AUDIO_CONFIG`, `AUDIO_FRAME` |
 
@@ -62,12 +74,7 @@ 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.
+**Not viable for this video stream.** Use **Wi‑Fi** for media; BLE could be added later only for discovery/pairing.
 
 ## Persistent services (AIDL)
 
@@ -78,18 +85,16 @@ Casting runs in **foreground services** with tray notifications:
 | `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.
+Activities bind via AIDL for status and (on the receiver) attaching the video `Surface`. Leaving the app does **not** stop the receiver listener; the sender keeps casting until **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
+- UDP mode may glitch under load (try TCP)
+- Audio captures **playback** routed through the system (not microphone)
+- Single receiver per session during alpha freeze
+- No live sender preview while casting (stability)
 
 ## Development (git flow)
 
-We use a **green `master`** plus integration branch **`next`**: features merge to `next` first; releases merge `next` → `master` and are tagged there; production hotfixes branch from `master` and sync back into `next`.
-
-- Narrative: [docs/GIT_FLOW.md](docs/GIT_FLOW.md)
-- PDF: [docs/GIT_FLOW.pdf](docs/GIT_FLOW.pdf) — `pip install -r docs/_pdf_build/requirements-pdf.txt`, then `python3 docs/_pdf_build/build_git_flow_pdf.py`
+Green **`master`** plus integration branch **`next`**. See [docs/GIT_FLOW.md](docs/GIT_FLOW.md).