Files
video.js-mirror/rfc/react-native-player-api.md
2026-11-04 17:04:59 -08:00

103 lines
4.4 KiB
Markdown

---
status: draft
---
# React Native Player Public API
> **STUB** — opened to get buy-in on the RN player's public API surface. The
> owned design (architecture, native construction, decisions) lives in
> [`.agents/plans/react-native/`](../.agents/plans/react-native/index.md);
> this RFC exists for the cross-package, user-facing contract that needs
> alignment.
## Problem Statement
The planned `@videojs/react-native` package needs a public API. The design doc
commits to a [parity principle](../.agents/plans/react-native/index.md#guiding-principle-parity-with-the-react-player):
the RN player should match `@videojs/react` as closely as the platform allows —
same component names, prop names, hook signatures, layer split, and feature set.
That principle is a public-API and product-direction commitment across packages,
so it needs buy-in rather than being decided unilaterally:
- It constrains the RN API to track the React API (and arguably the reverse — RN
needs may push capabilities like external-store ownership back onto web).
- It introduces platform-only surface (a separate `<BackgroundablePlayer.Provider>`
and a persistent `backgroundSession`) that has no web equivalent.
- It defines where divergence is allowed (styling, accessibility mapping).
What happens if we do nothing: the RN package gets built with an ad-hoc API that
drifts from the React player, and cross-platform users re-learn the player per
platform.
## Customer Salience
*(To be filled in.)* Initial read:
- **Who:** player integrators building on both web and native; teams
standardizing on Video.js across platforms.
- **How many:** a meaningful minority today (RN is unbuilt), growing as RN ships.
- **How strongly:** parity strongly reduces cross-platform learning cost; API
drift would be a persistent friction for anyone targeting both.
## Options Considered
*(To be filled in. Sketch:)*
**Option 1: Strict parity** — RN mirrors React API 1:1 except where the platform
makes it impossible. Lowest cross-platform learning cost; constrains RN to React
shapes that may not always fit native idiom.
**Option 2: RN-idiomatic API** — design RN's API to native conventions, parity
as a non-goal. Best native feel; highest divergence and learning cost.
**Option 3: Parity-by-default with documented exceptions (design-doc lean)** —
match React wherever the platform allows; each divergence (styling, a11y
mapping, platform-only capabilities) is justified and documented.
## Recommendation
*(To be filled in.)* Design-doc lean is Option 3. RFC exists to confirm that's
the right cross-package tradeoff and to align on the divergence list.
## Open items to resolve here
- The exact divergence list (styling, accessibility mapping, platform-only
capabilities).
- Whether external/hoisted-store ownership (needed for the RN persistent
session) is also exposed on the web for true parity.
- Public shape of platform-only surface: the separate
`<BackgroundablePlayer.Provider>` (vs. a `backgroundPlayback` boolean on the
shared provider), the `backgroundSession` imperative API, and the
persistent-session model. Whether two providers (over a shared core) is the
right web-parity tradeoff vs. distinguishing by a `store` prop on a single
provider.
- **Playlists / source queue — cross-platform feature or RN-only?** v10 is
single-source and the web deliberately left queues out of scope, but native
players make a gapless queue trivial (see
[design § Future work: playlists](../.agents/plans/react-native/index.md#future-work-playlists--source-queue)).
Adding it to RN gets *ahead* of web on feature set (not platform-forced
divergence), so the question is whether `MediaQueueCapability` + a
`playlistFeature` become the shared cross-platform concept (web adopting a
`loadSource`-backed fallback later) or stay RN-only. Decide the shared state
shape here to avoid drift.
## Final Decision
*(Completed after review)*
**Decision:**
**Rationale:**
**Date:**
## See Also
- [`.agents/plans/react-native/index.md`](../.agents/plans/react-native/index.md)
— owned design (architecture + API surface).
- [`.agents/plans/react-native/decisions.md`](../.agents/plans/react-native/decisions.md)
— debated native-construction decisions.
- [`.agents/plans/react-native/persistent-session.md`](../.agents/plans/react-native/persistent-session.md)
— implementation plan for the persistent session.
- [`rfc/player-api/`](./player-api.md) — the web player API RFC this aims
for parity with.