snap

docs/USB_HDMI_CAST.md

@@ -0,0 +1,51 @@
+# USB-C / HDMI and USB-tether cast (roadmap D & E)
+
+Android Cast streams over **Wi‑Fi** (UDP/TCP/QUIC). USB-C→HDMI adapters use Android’s **wired external display** stack, which is separate from the cast protocol.
+
+## Layer model
+
+| Layer | Mechanism | This app today |
+|-------|-----------|----------------|
+| Wired mirror | `DisplayManager` + HDMI/DP alt mode | Not encoded by us; OS drives the sink |
+| Wi‑Fi cast | MediaProjection + `CastTransport` | Primary product path |
+| USB-tether cast (E) | IP over USB (RNDIS/ADB reverse) + same framing | **Stub** (`usb_tether` transport) |
+
+## Phase D — external display awareness & future capture
+
+**Implemented (foundation):**
+
+- `WiredDisplayMonitor` — tracks non-default displays (HDMI, presentation, etc.).
+- `ExternalDisplayCapturePolicy` — developer preference for future capture routing.
+- Developer settings: live wired-display status + capture policy selector.
+- `ScreenCastService` registers extended display listener (rotation + hot-plug).
+
+**Not implemented yet (post-alpha):**
+
+- Capture **secondary display** via `MediaProjection` / `createVirtualDisplay` on non-default `Display`.
+- Android 14+ per-app capture rules and extend-vs-mirror modes.
+- Automatic switch to external display when passive/active USB-C adapter works.
+
+**User workaround when HDMI dongle fails:** LAN cast to a receiver (phone/box) connected to the projector by HDMI or built-in Android on the projector.
+
+## Phase E — USB-tether transport
+
+**Implemented (foundation):**
+
+- `UsbTetherCastTransport` stub implementing `CastTransport`.
+- `CastConfig.TRANSPORT_USB_TETHER` — selectable only when **Developer settings → USB-tether transport** is on.
+- Factory routes to stub; connect/listen throw until RNDIS/ADB tunnel + discovery are wired.
+
+**Future work:**
+
+- Detect USB tether / ADB TCP forward (`adb reverse`).
+- Optional discovery on `127.0.0.1` or tether interface IP.
+- Same `CastProtocol` framing as UDP/TCP.
+
+## Tablet + adapter checklist (e.g. Doogee Tab G6 Max → HY300)
+
+1. **Settings → Display** — does a second screen appear when the dongle is plugged in?
+2. **Passive** adapter: requires USB-C **DisplayPort Alt Mode** on the tablet port.
+3. **Active** adapter: needs a chip/firmware pair the tablet supports (often still DP alt mode internally).
+4. If the OS never sees an external display, **no app feature** can fix the cable path; use Wi‑Fi cast or receiver-on-HDMI.
+
+See [ROADMAP.md](ROADMAP.md) for alpha and commercial tracks.