docs: add QA-verified how-to guides for player capabilities by dylanjha · Pull Request #1945 · videojs/v10

dylanjha · 2026-08-04T22:59:47Z

Replaces #1939 (same content, reframed: no RFC and no new "Handbook" section — these are just more how-to guides).

Closes #1854 — this PR's how-to/autoplay.mdx supersedes #1534, which is closed in favor of this one.

Summary

A set of fleshed-out how-to guides in the existing How-to section, each solving one "job to be done" with copy-pasteable code for both HTML and React — now QA'd end to end: every code example was executed in a real browser and every API claim checked against the package source, and the bugs that QA found are fixed in this PR.

What these guides solve

✅ Solve for a "job to be done" — an actual task that a human or a coding agent is trying to accomplish
✅ Combine the lower-level APIs into a single solution that can often be copy/pasted as-is
✅ Show the quick wins / easy implementation / most common happy-path up-front, so it's easy for coding agents to find
✅ SEO/AEO/GEO — rank for these tasks so humans and agents get working code from one page
✅ Cross-linking / pointing visitors to the right places when they need to go beyond the happy path

QA pass (`b012a1c`)

All 22 how-to guides went through a line-for-line QA pass (HTML and React variants): each guide's code ran as a real page in a browser (playback, menus, persistence across reloads, error dialogs, hotkeys, PiP/fullscreen, i18n locale switching), every import/API/prop was verified against packages/ source, every link was status-checked, and changed snippets were type-checked with tsc.

QA found 8 reader-blocking bugs (dead imports, a nonexistent API, examples that crash on load) plus ~20 major accuracy issues; all docs-side findings are fixed in this PR. Notable fixes:

Working examples restored in play-live-streams, remember-user-preferences, keyboard shortcuts, cast, i18n (CDN registry pinning), and error handling
Closed popover menus no longer float over the page (quality/audio demos), and menus hide when selection is unavailable, as the prose promises
Browser-support claims updated (Chrome 142 native HLS, Firefox 153 PiP) and availability unions corrected (available | unavailable | unsupported)
pnpm -F site astro check passes with 0 errors; shared demo consumers (reference pages) verified intact

Known issues intentionally NOT fixed here (they are player/site-tooling bugs, to be filed as separate issues): errorFeature initial-error sync, i18n override merge order, CDN i18n dual-registry design, CastButton/AirPlayButton visibility inconsistency, ejected-skins generator tsc failure, EjectedSkin.astro file label, DocsLinkCard anchor prop, and the visible biome-ignore comment in the poster demo.

Remaining tasks

audit the list of guides — is this a good list? anything we should remove / re-word / or anything missing we should add?
review copy & code samples — done via the QA pass above (every example executed in a browser; findings fixed in b012a1c)
file issues for the player/site-tooling bugs the QA pass surfaced (list above)

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only changes plus 301 redirects for merged i18n pages; no player runtime, auth, or data-handling code is modified.

Overview
Adds a suite of QA-verified how-to guides for player capabilities—autoplay, live streams, captions, quality, cast, PiP/fullscreen, hotkeys/gestures, errors, preferences, sources, and more—each with a recommended approach, constraints, troubleshooting, and HTML/React examples.

Consolidates four i18n guides into internationalize-the-player, with Netlify 301 redirects from the old URLs, and rewrites existing guides (build-your-own-component, customize-skins, self-host-the-player) to the same section template.

Supporting docs infrastructure: shared CustomUiNote, optional components/api/keywords frontmatter, updated how-to template/skill, new demos (autoplay, text-tracks, sources), and small demo fixes (hide unavailable menus, include GoogleCast, Mux storyboard VTT placeholder).

^{Reviewed by Cursor Bugbot for commit 0a5db62. Bugbot is set up for automated code reviews on this repo. Configure here.}

Adds rfc/docs-handbook.md proposing the Handbook information architecture (Getting Started / Handbook / Components / API / Examples), and a dev-only Autoplay pilot page validating the capability-page template, stable anchors, discovery frontmatter, and demo wiring end to end. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Sätteri 0.3.4 (bumped in videojs#1868) applies the MDX `code` component mapping to the highlighter-generated <code> inside fenced blocks, so MarkdownCode's inline chip styling (border, manila background, padding) rendered on every line of every code block. Production is unaffected only because it was last built before the bump. Neutralize the chip styles for code inside .astro-code with an unlayered rule so it wins over the utility-layer classes. Inline code in prose keeps its styling. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Three more capability pages following the Handbook template from rfc/docs-handbook.md, each with live demos verified in the browser (controls render, source switching works, captions track loads). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…k pages Four more capability pages following the Handbook template. These reuse the existing component demos (quality-radio-group, fullscreen-button, pip-button, cast-button) as their primary examples rather than duplicating demo files. All eight Handbook pages verified to share the same stable h2 anchor set. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Adds the remaining eight capability pages: Live Playback, Audio Tracks, Posters and Thumbnails, Controls and User Activity, Keyboard and Pointer Input, Localization, Storage and Persistence, and Errors and Recovery. Removes devOnly from the Handbook sidebar section so it ships in production builds. Storage and Persistence documents the subscribe-and-restore pattern explicitly because the player has no built-in persistence (verified: no storage usage in any @videojs package). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Same structure and substance; shorter sentences, jargon removed, and Diátaxis defined inline on first mention. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Capability guides fit the existing How-to section, so no restructure or RFC is needed. Links, headings, sidebar, and schema comments updated; the machine-readable frontmatter fields stay. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The new demos sized the video from its intrinsic dimensions, so pages shifted heavily when metadata loaded. Match the established demo pattern of aspect-ratio: 16 / 9. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

netlify · 2026-08-04T22:59:51Z

👷 Deploy request for vjs10-site pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	`0a5db62`

vercel · 2026-08-04T22:59:51Z

@dylanjha is attempting to deploy a commit to the Mux Team on Vercel.

A member of the Team first needs to authorize it.

# Conflicts: # site/src/styles/shiki-transformers.css

The 16 new capability guides follow a shared template that the authoring doctrine didn't describe; writers would still be told to default to concept pages and never mix explanation into a how-to. write-guides.mdx owns the doctrine; the skill routes to it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ack guide Per docs sync with Steve: titles now complete 'How to…' in the reader's words, timeline thumbnail previews get their own guide, the playback guide is removed (overlaps custom-controls content), How-to moves above Concepts, and the section states its assumption that the reader is building their own player UI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Slugs now match the goal-oriented titles (nothing deployed, so no redirects needed). Every capability guide opens with a shared note: pre-built skins handle this; the guide is for building your own UI. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Localize the player, Go fullscreen and lock orientation, Use picture-in-picture, Cast to AirPlay and Chromecast, Add keyboard shortcuts and gestures, Remember user preferences, and Handle playback errors. Slugs and cross-links renamed to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor · 2026-08-06T22:50:00Z

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

# Conflicts: # site/src/docs.config.ts

The four small i18n guides (register locale, override translations, switch locale, SSR) fold into the capability guide as variations, so one page answers the whole question. Their live URLs 301 to the combined guide; the Translation keys reference moves under API Reference > Utilities. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Fix the documentation bugs surfaced by an in-depth QA pass over all 22 how-to guides (both HTML and React variants), where every code example was executed in a real browser and every API claim was checked against the package source. Broken examples (readers previously got a dead player or a crash): - play-live-streams: correct the live-button import path, use live-video-player instead of video-player, and add streamTypeFeature wherever streamType state is read - remember-user-preferences: defer restore until the store attaches (both examples threw StoreError: NO_TARGET), stop the React save effect overwriting saved values on mount, fix the stale muted guard, and rewrite captions persistence so users can switch tracks and turn captions off - add-keyboard-shortcuts-and-gestures: replace the nonexistent @videojs/html/ui/gesture import with manual GestureElement definition - cast-to-airplay-and-chromecast: replace the nonexistent config.googleCast API with GoogleCast component props, add the missing google-cast component to the demos, and correct the "built in" and button-visibility claims - internationalize-the-player: pin the CDN i18n import to the same versioned module the player uses (the unversioned URL creates a second, disconnected registry) and pass a default to t() - handle-playback-errors: add the alert-dialog child parts so the error dialog renders visible content Demo fixes: - quality/audio-track menus: stop .menu display overriding the popover hidden state (closed menus floated over the page) and hide the menu bar when selection is unavailable, as the prose promises - thumbnails: document the slider thumbnail wiring in the guide, add a VJS10_DEMO_STORYBOARD_VTT placeholder so copied code works outside the docs site, and add the required default track attribute - captions/thumbnails: add default to track snippets (non-default tracks never load cues in Chrome) Accuracy fixes: - update outdated browser claims (Chrome 142 plays HLS natively; Firefox 153 ships the standard picture-in-picture API) - correct the availability unions to available | unavailable | unsupported and the iOS Safari volume case to unsupported across autoplay, fullscreen, PiP, and preferences - type-level fixes in build-your-own-component (typed Player.usePlayer, guarded store access) and assorted prose corrections Verification: each fixed example re-run in the browser, changed snippets type-checked with tsc, affected reference pages that share demo files confirmed intact, and pnpm -F site astro check passes with 0 errors. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit b012a1c. Configure here.}

Skip toggleMuted when the saved volume is zero, since the player treats volume zero as muted and toggling would unmute at 0.25. Import selectVolume from @videojs/html instead of exposing @videojs/core/dom. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Drop the capability-guide vs task-guide distinction: one how-to template in the write-docs skill, one shape in write-guides.mdx. Delete the stale step-by-step template that matched no page, and remove the category frontmatter field nothing consumed. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Customize skins, Build your own UI component, and Self-host the player now follow the shared section order. Content is unchanged apart from a troubleshooting entry and keywords each gained. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

luwes · 2026-08-12T15:02:04Z

+import { BackgroundVideo } from '@videojs/react/media/background-video';
+
+export default function Hero() {
+  return <BackgroundVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />;


should this example use a m3u8? that's one of the primary goals of the component

luwes · 2026-08-12T15:03:04Z

+<FrameworkCase frameworks={["html"]}>
+
+```html
+<background-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"></background-video>


dylanjha and others added 9 commits July 28, 2026 23:54

Merge fix/fenced-code-inline-style into docs/handbook-rfc

d5719c0

docs: rewrite Handbook RFC in plain language

c8045db

Same structure and substance; shorter sentences, jargon removed, and Diátaxis defined inline on first mention. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

fix(site): reserve video space in capability-guide demos

8091d7e

The new demos sized the video from its intrinsic dimensions, so pages shifted heavily when metadata loaded. Match the established demo pattern of aspect-ratio: 16 / 9. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

cursor Bot reviewed Aug 4, 2026

View reviewed changes

Comment thread site/src/content/docs/how-to/remember-user-preferences.mdx Outdated

Merge remote-tracking branch 'upstream/main' into docs/more-how-tos

284b13c

# Conflicts: # site/src/styles/shiki-transformers.css

cursor Bot reviewed Aug 4, 2026

View reviewed changes

Comment thread site/src/content/docs/how-to/internationalize-the-player.mdx Outdated

dylanjha and others added 5 commits August 5, 2026 10:10

docs: use plainer language in guide-authoring docs

35e1ab5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

dylanjha and others added 4 commits August 7, 2026 09:27

docs: retitle localization guide to Internationalize the player

13f6c62

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Merge remote-tracking branch 'upstream/main' into docs/more-how-tos

60b2a21

# Conflicts: # site/src/docs.config.ts

cursor Bot reviewed Aug 11, 2026

View reviewed changes

Comment thread site/src/content/docs/how-to/remember-user-preferences.mdx Outdated

dylanjha changed the title ~~docs: more how-to guides for player capabilities~~ docs: add QA-verified how-to guides for player capabilities Aug 11, 2026

dylanjha and others added 3 commits August 11, 2026 10:00

luwes reviewed Aug 12, 2026

View reviewed changes

decepulis mentioned this pull request Aug 12, 2026

docs(site): add autoplay how-to guide #1534

Closed

Navigation Menu

Uh oh!

docs: add QA-verified how-to guides for player capabilities - #1945

docs: add QA-verified how-to guides for player capabilities#1945
dylanjha wants to merge 22 commits into
videojs:mainfrom
dylanjha:docs/more-how-tos

dylanjha commented Aug 4, 2026 •

edited by decepulis

Loading

Uh oh!

netlify Bot commented Aug 4, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 4, 2026

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Aug 6, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

Uh oh!

luwes Aug 12, 2026

Uh oh!

luwes Aug 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

dylanjha commented Aug 4, 2026 • edited by decepulis Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What these guides solve

QA pass (b012a1c)

Remaining tasks

Uh oh!

netlify Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy request for vjs10-site pending review.

Uh oh!

vercel Bot commented Aug 4, 2026

Uh oh!

Uh oh!

Uh oh!

cursor Bot commented Aug 6, 2026

Bugbot is paused — on-demand spend limit reached

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

luwes Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

luwes Aug 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dylanjha commented Aug 4, 2026 •

edited by decepulis

Loading

QA pass (`b012a1c`)

netlify Bot commented Aug 4, 2026 •

edited

Loading