Skip to content

Which documentation does the native Android engine change? #427

Closed

Description

@patricktree

Question

Which ADRs, architecture pages, glossary terms and READMEs does the native Android engine change? At least: a new ADR superseding ADR 0011's single <audio> element for Android, the signed position URL beside the signed media URL, the conversion architecture's Playback and positions sections, and apps/mobile-app/README.md.


Written by @patricktree's agent (Claude Code, Claude Opus 5.5).

Activity

  1. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Input from How is Cup's native Android playback tested on the emulator and the Pixel?: the documentation set also includes the following.

    • The review gate gains JDK 21 and the Android SDK as prerequisites, because apps/mobile-app gets a turbo:test running ./gradlew testDebugUnitTest. That affects AGENTS.md (Validation gates) and the validation gates runner README.
    • The mobile E2E suite README needs:
      • the new Android playback cases
      • the debug-only seams: short URL lifetimes, FocusProbePlugin and the shortened grace
      • a link to the new manual Pixel protocol checklist in qa/mobile-e2e/
    • ADR 0018 may need a note that a manual physical-device protocol complements the suite.

    Written by @patricktree's agent (Claude Code, Claude Opus 5.5).

  2. self-assigned this
    on Nov 16, 2026
  3. patricktree commented on Nov 16, 2026

    @patricktree
    CollaboratorAuthor

    Written by @patricktree's agent (Claude Code, Claude Opus 5.5).

    Resolution

    Decided with the operator on 2026-11-16. Each build slice updates the pages its own change makes untrue, in the same change. The new ADR and ADR 0011's status line land with the first slice that contradicts ADR 0011, so the map's landing only verifies and closes.

    Decisions

    • New architecture page docs/architecture/playback.md. It takes over conversion.md's Playback section and the player parts of "Delivery, positions, and lifecycle": position saves and the CUP-71 retry, the player host's loading and unloading, the mini player and the sheet. It adds:

      • the web media-session port (actions and position state on every platform)
      • the Android native engine: the Player port seam from PlayerHostServices.createPlayer, ExoPlayer in MediaPlaybackService, the service lifecycle, focus and headphone-disconnect handling, native position saves, and how a starting page adopts a running session
      • iOS's current state: WebView <audio>, best effort, with a link to the iOS map

      conversion.md keeps the track join, streaming and the delivery route, and links to the new page. The page is indexed in docs/README.md and in the architecture README's responsibilities table. This also shrinks conversion.md, which is about 4,000 words against the 1,500-word budget.

    • One new ADR (0029 unless another lands first). Working title: "Play the narration track in the Android app with a native Media3 ExoPlayer". It records:

      • the engine and the options ruled out: the WebView with a mirroring session, a TWA, paid plugins (#376)
      • the page–player seam (#423)
      • the service lifecycle, as amended (#389)
      • focus and headphone-disconnect handling (#390)
      • native position saves through the signed position URL (#424, #425)
      • the testing approach (#426)
      • a clearly marked "Every platform" section for the web media-session handlers and position state (#388, web part), which the iOS map can cite

      Its Consequences record the manual Pixel protocol that complements the Appium suite, and JDK 21 plus the Android SDK becoming review-gate prerequisites.

    • ADR 0011. Its status becomes partially superseded by ADR 0013 and ADR 0029. The intro names the superseded bullets: "One <audio> element" and "Native players removed" for Android only, and "System media controls use browser defaults" for every platform. The rest and the rationale stay.

    • ADR 0018 and ADR 0020 stay untouched, because both changes are additions, not reversals. The current state goes in AGENTS.md (Validation gates), the validation gates README and the prerequisite in tooling/validation-gates/src/gates.ts.

    • authentication.md

      • A new "Signed position URL" subsection beside "Signed media URL" covers:
        • the "purpose": "position" binding
        • same key and lifetime as the media URL
        • exactly one of a bearer token or a URL token on the route
        • the browser-mutation header check, which stays
        • the active-account-owns-conversion check, which now applies on both paths
        • that sign-out does not revoke the URL
      • "Signed media URL" changes:
        • the CORP sentence: Android no longer embeds the track in <audio>, though covers still use <img>
        • the renewal paragraph: on Android, only the page renews the URL on its own Plays, and track URL expiry or a 403 stops the service
    • Signing key wording. production-configuration.md (MEDIA_URL_SIGNING_KEY) and libs/api-server/AGENTS.md say the key also signs position URLs.

    • Glossary: no change. The signed position URL stays an architecture term, as the signed media URL is. "Listening position" still holds, because a page adopting a running native session is not a player loading.

    • apps/mobile-app/README.md

      • Playback: rewritten to cover the plugin's location, its manifest entries (FOREGROUND_SERVICE, FOREGROUND_SERVICE_MEDIA_PLAYBACK, the service), the debug-only seams, and a link to playback.md for behaviour. "Nothing detects or gates WebView playback until Android and iOS apps that play the narration track #55" is removed.
      • "After changing native Android code": now says turbo:test runs the JVM unit tests.
      • Automated checks: adds Android playback.
      • CUP-44's manual item 1: split, so the Android part points to the protocol and the iOS part stays in CUP-44.
    • New qa/mobile-e2e/android-playback-protocol.md. The manual Pixel checklist from How is Cup's native Android playback tested on the emulator and the Pixel? #426, including when it must be rerun.

    • qa/mobile-e2e/README.md. A new "Playback (Android)" section with the cases and the debug-only seams (short URL lifetimes, FocusProbePlugin, the shortened grace), linking the protocol.

    • Research.

      • webview-audio-playback.md and android-background-network-access.md each get a dated note linking the ADR as the outcome.
      • At landing, only the probes the ADR cites as rationale are copied into docs/research/: the emulator foreground-service probe (#373) and the frozen-page probe on the Pixel (#397).
      • The plugin survey (#372) stays a permalink in the landing description.
    • Claims that are already untrue, fixed in the same change.

      • web-app.md's gap that says CORP probably blocks the track and that "shell playback is native-app work". It contradicts authentication.md's cross-origin CORP.
      • The architecture README's runtime map adds the native player's requests with signed URLs to the mobile app's edge.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions