android_cast/docs/ROADMAP.md

# Android Cast — implementation roadmap

<!-- doc-meta:start -->
| Field | Value |
|---|---|
| Author | Anton Afanasyeu |
| Revision | R1 |
| Creation date | 2026-05-18 |
| Last modification date | 2026-05-18 |
| Co-authored |  |
| Severity | medium |
| State | in progress |
| Document type | pre-requisite to |
<!-- doc-meta:end -->

\newpage
\newpage

---


Last updated: 2026-06-04. Living document — refine as alpha and commercial tracks progress.

---

---

---

---

---

---


---


---

---


---

## Table of contents

<!-- toc -->
- [Alpha definition](#alpha-definition)
  - [Alpha app checklist](#alpha-app-checklist)
  - [Alpha backend checklist](#alpha-backend-checklist)
- [Remote access (alpha — RSSH)](#remote-access-alpha-rssh)
- [Auth & email (alpha)](#auth-email-alpha)
- [Product positioning](#product-positioning)
- [USB-C / HDMI (roadmap D) and USB-tether cast (roadmap E)](#usb-c-hdmi-roadmap-d-and-usb-tether-cast-roadmap-e)
- [Commercial (Play Store prep)](#commercial-play-store-prep)
- [Crash console open API](#crash-console-open-api)
- [Stream protection (FEC / NACK)](#stream-protection-fec-nack)
- [libvpx / Opus / Speex](#libvpx-opus-speex)
- [Transports & protocols](#transports-protocols)
- [Receiver / sender UX](#receiver-sender-ux)
- [Deferred / post-alpha](#deferred-post-alpha)
- [Related docs](#related-docs)
<!-- /toc -->

**Documentation index:** [README.md](README.md)

---

## Alpha definition

| Track | Goal | Status |
|-------|------|--------|
| **Android app** | Stable, feature-rich, **demo-ready** on LAN (discover → PIN → cast → stop; soak two devices) | Core path done; polish UX/docs and gate experimental options for show |
| **Backend** | Deployed **OTA channel** + **crash ingest** + **on-demand remote access (RSSH, prod/hidden)** | WIP — examples under `examples/`; WireGuard v1 lab path done; RSSH implementation in progress |

**Alpha app** can ship before backend is live if the demo is LAN-only. **Full alpha** includes OTA/crash URLs configured in developer settings or `local.properties`.

### Alpha app checklist

**Runbook:** [ALPHA.md](ALPHA.md) (feature freeze, defaults, sign-off tables, log script).

| Checkpoint | Engineering | Manual sign-off |
|------------|---------------|-----------------|
| Happy path: UDP + H.264/AAC + single receiver, protection **None** | Defaults + freeze in code | ☐ [ALPHA.md](ALPHA.md) § A, C1 |
| README matches `CastSettings` / `CastConfig` | Done | — |
| Fix misleading strings (camera permission vs unavailable) | Done | — |
| Two-device QA (rotate, background, notification stop) | Script in `scripts/alpha-qa-logcat.sh` | ☐ [ALPHA.md](ALPHA.md) § B |
| Cap multi-receiver at 1 for alpha | `MULTI_RECEIVER_ENABLED` off while freeze on | — |
| Hide QUIC/WebRTC/USB in settings for alpha | `ALPHA_FEATURE_FREEZE` | — |
| Receiver stuck on rotation / STREAM_CONFIG storm | Debounce + idle grace in code | ☐ B4–B5 |

### Alpha backend checklist

- [ ] Host `examples/ota/v0/` channel JSON + APK artifacts
- [ ] Deploy `examples/crash_reporter/backend/` (see `nginx.conf`, `README.md`)
- [ ] Set `ota.channel.url` and crash upload URL in dev settings / `local.properties`
- [ ] **RSSH remote access (alpha essential):** device opt-in via `heartbeat.php` (`type: ra`, `opt_in_mode: rssh`); outbound SSH reverse tunnel to bastion; **no VPN permission / no status-bar key**; operator whitelist + session open in BE UI; E2E validation per [REMOTE_ACCESS_VALIDATION.md](REMOTE_ACCESS_VALIDATION.md) (RSSH path TBD)
- [ ] WireGuard v1 remains available for lab/E2E; not required for alpha sign-off if RSSH meets owner criteria
- [ ] **Email infra (alpha essential):** `info@` / `admin@` / `root@` on `apps.f0xx.org` → Gmail forward; SPF/DKIM/DMARC — [20260607-2FA-email-mobile-auth-flow.md §9](20260607-2FA-email-mobile-auth-flow.md#9-email-addresses-agent-config)
- [ ] **Registration + 2FA (alpha essential):** email verify + TOTP + mobile-friendly login/register — [§10](20260607-2FA-email-mobile-auth-flow.md#10-registration-2fa-mobile-auth)

---

## Remote access (alpha — RSSH)

**Owner agreement:** production **RSSH** (reverse SSH, hidden — no `VpnService`) is an **essential part of the alpha release**, not post-alpha. WireGuard v1 is implemented for infra/E2E lab work; alpha remote-debug UX targets RSSH.

| Item | Status |
|------|--------|
| BE control plane (`heartbeat.php` `type: ra`, admin UI, RBAC, purge cron) | Done |
| WireGuard v1 (device `VpnService`, UDP DNAT, `WireGuardPeerProvisioner`) | Done (lab) |
| BE `opt_in_mode: rssh` + bastion/session provisioning | TODO |
| Android RSSH mode selectable (no VPN prompt) | TODO |
| Outbound reverse SSH client + foreground service | TODO |
| Operator E2E (whitelist → open session → shell/file on bastion) | TODO |

Implementation notes: [REMOTE_ACCESS_IMPL.md](REMOTE_ACCESS_IMPL.md) · proposal: [20260602_REVERSE_SSH_proposals_summary.md](20260602_REVERSE_SSH_proposals_summary.md).

---

## Auth & email (alpha)

**Owner agreement:** public email aliases + **registration with email verification and 2FA (TOTP)** are **alpha must-have** for the crashes/build consoles.

| Item | Status |
|------|--------|
| DNS forward `info@` / `admin@` / `root@` → Gmail | Ops TODO |
| BE SMTP outbound (`noreply@apps.f0xx.org`) | TODO |
| Migration `008_auth_email_2fa` | TODO |
| Register + verify + TOTP enroll/login | TODO |
| WebAuthn / passkeys (optional alpha) | TODO |
| Admin: recovery email, clear lockouts, audit | TODO |

Full spec: [20260607-2FA-email-mobile-auth-flow.md](20260607-2FA-email-mobile-auth-flow.md).

---

## Product positioning

- **Primary:** Wi‑Fi LAN cast when **USB-C→HDMI** wired mirror fails or is unavailable (common on some tablets).
- **Not in scope for v0:** Internet relay (`gateway_url_hint`), TLS on cast protocol, WebRTC as default transport.

See [USB_HDMI_CAST.md](USB_HDMI_CAST.md) for wired display vs Wi‑Fi cast.

---

## USB-C / HDMI (roadmap D) and USB-tether cast (roadmap E)

| Item | Status |
|------|--------|
| `WiredDisplayMonitor` — detect external displays | Done |
| `ExternalDisplayCapturePolicy` + developer UI | Done (policy stored; capture still default display) |
| `ScreenCastService` display hot-plug hooks | Done |
| Secondary-display MediaProjection capture | TODO |
| `UsbTetherCastTransport` stub + dev-gated transport id | Done |
| USB tether / ADB reverse discovery + framing | TODO |

Details: [USB_HDMI_CAST.md](USB_HDMI_CAST.md).

---

## Commercial (Play Store prep)

All **off by default**. Enable only in **Developer settings** for internal testing.

| Item | Status |
|------|--------|
| `CommercialFeatures` gate | Done |
| `InAppPurchaseCoordinator` (Play Billing 7.x) | Done (connects when dev IAP on; SKU placeholder) |
| `InAppAdCoordinator` (placeholder, no AdMob SDK yet) | Done |
| `PlayStoreIntegration` (listing intent + in-app review API) | Done |
| AdMob / unit IDs / banner layouts in main UI | TODO |
| Play Console products + privacy policy | TODO |

See [COMMERCIAL.md](COMMERCIAL.md). Pro/OSS module split: [PRO_AAR.md](PRO_AAR.md) (design).

---

## Crash console open API

| Item | Status |
|------|--------|
| Workflow triage tags + multi-tag (duplicate+fixed, etc.) | Done — [OPEN_API.md](OPEN_API.md) |
| `GET /api/reports.php?tag=…&tag_mode=and\|or` | Done |
| `ingest.source` / run metadata in payload | Design — [OPEN_API.md](OPEN_API.md) |
| List filters + synthetic tagging | TODO |
| API key upload auth (per company) | TODO |

---

## Stream protection (FEC / NACK)

| Item | Status |
|------|--------|
| GF(256) Reed–Solomon + `ProtectionEnvelope` v1 (monolithic) | Done |
| **v2 per-shard FEC** (`FecShardWire`, one ACUD message per RS shard) | Done |
| NACK + `RetransmitCache` + `MSG_NACK` | Done |
| Post-handshake negotiation | Done |
| Backward compat (defer FEC until negotiated; ignore foreign FEC/NACK) | Done |
| Default protection **NONE** (stable cast) | Done |
| Integration tests (`FecShard*`, `UdpCastTransportFecTest`) | Done |
| Lab soak under loss (HY300 / BL6000) | TODO (manual) |
| NACK rate limit / backoff | Done (`NackRateLimiter`) |
| `MSG_FEC_NACK` by groupId (optional) | Deferred |

Enable in **Settings → Stream protection (UDP)** on both sender and receiver, then reconnect.

---

## libvpx / Opus / Speex

| Item | Status |
|------|--------|
| `libandroidcast_codecs.so` + JNI probes | Done |
| Cross-compile `libvpx.a` (`scripts/build-native-codecs.sh`) | Done |
| JNI encode/decode in `libvpx_bridge.c` | Done (when `libvpx.a` linked per ABI) |
| `LibvpxVideoEncoderSink` (surface + buffer) | Done |
| libvpx decoder on receiver (`LibvpxCapableVideoDecoder`) | Done |
| Surface → libvpx without MediaCodec passthrough on cast | Done (ImageReader) |
| Opus / Speex cross-compile + CMake autolink (`build-native-codecs.sh`) | Done |
| Opus / Speex JNI encode/decode sinks | TODO |

See [ndk/README.md](../ndk/README.md).

---

## Transports & protocols

| Transport | Status |
|-----------|--------|
| UDP (default) | Done |
| TCP | Done |
| QUIC (Cronet, experimental) | Partial |
| WebRTC | Stub (`WebRtcCastTransport`) |
| USB tether (`usb_tether`) | Stub — dev settings only |

---

## Receiver / sender UX

| Item | Status |
|------|--------|
| `ReceiverPlaybackActivity` (primary receiver UI) | Done |
| Settings drawer + themes + RU locale | Done |
| Multi-receiver 1:N | Done (gated off while `ALPHA_FEATURE_FREEZE`) |
| Legacy `ReceiverActivity` in manifest | Orphan — remove or wire |
| Immersive A/V presets (dev) | Experimental |
| Sender resolution UI modes (dev: Separated / Legacy / Combined) | Done (test) |
| True dual-stream encode (480p + 720p simultaneous) | Deferred |

---

## Deferred / post-alpha

- **URL shortener** (`https://s.f0xx.org`) — PHP API in [backend/url-shortener/](../backend/url-shortener/); sync to BE + `seed_bearer.php` + `libqrencode-tools`
- Internet relay gateway
- TLS on cast stream
- Passthrough video codec
- Lab automation under simulated loss
- Full wired-HDMI capture (roadmap D phase 2)
- USB-tether cast production path (roadmap E)

---

## Related docs

- [README.md](README.md) — **documentation index** (all `docs/*.md` with section links)
- [GIT_FLOW.md](GIT_FLOW.md) — green `master` / `next` development cycle ([PDF](GIT_FLOW.pdf))
- [INFRA.md](INFRA.md) — production FE/BE topology
- [../README.md](../README.md) — repo quick start
- [ALPHA.md](ALPHA.md) — alpha freeze & QA sign-off
- [USB_HDMI_CAST.md](USB_HDMI_CAST.md) — D & E
- [COMMERCIAL.md](COMMERCIAL.md) — ads / IAP / Play
- [PRO_AAR.md](PRO_AAR.md) — cast-core / cast-pro entitlements
- [OPEN_API.md](OPEN_API.md) — crash ingest triage API
- [OTA.md](OTA.md) — backend layout v0
- [BUILD_DEPLOY.md](BUILD_DEPLOY.md) — Docker build, staging OTA, deploy flow
- [CRASH_REPORTER.md](CRASH_REPORTER.md) — crash upload
- [GRAFANA_vs_others_graphvis_pivot.md](GRAFANA_vs_others_graphvis_pivot.md) — graphs dashboard pivot
- [20260602_REVERSE_SSH_proposals_summary.md](20260602_REVERSE_SSH_proposals_summary.md) — on-demand remote access
- [AV_QUALITY_QA_SESSION.md](AV_QUALITY_QA_SESSION.md) — AV quality enhancement Q&A