mirror of
https://github.com/videojs/video.js.git
synced 2026-11-20 06:29:27 +01:00
Co-authored-by: Emily Dixon <edixon@mux.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Emily Dixon <puterbaugh0@gmail.com>
103 lines
4.4 KiB
Markdown
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.
|