ArtPlayer/packages/artplayer-vitepress

ArtPlayer documentation site

This workspace builds the static API documentation served at /document/. The separate repository docs/index.html is the online player/editor; it is not a VitePress page. Keep both URL surfaces compatible.

Sources and generated files

Source	Responsibility	Output or consumer
docs/index.md, docs/start, docs/component, docs/advanced	Chinese API documentation	/document/
docs/en	English counterparts	/document/en/
docs/plugin/danmuku.md, docs/en/plugin/danmuku.md	Danmuku options, callbacks, commands, heatmap and types in both languages	/document/plugin/danmuku.html, /document/en/plugin/danmuku.html
docs/plugin/hls-control.md, docs/en/plugin/hls-control.md	HLS SDK setup, menus, lifecycle and types	/document/plugin/hls-control.html, /document/en/plugin/hls-control.html
docs/plugin/dash-control.md, docs/en/plugin/dash-control.md	DASH SDK generations, menus, lifecycle and types	/document/plugin/dash-control.html, /document/en/plugin/dash-control.html
docs/plugin/audio-track.md, docs/en/plugin/audio-track.md	Separate audio synchronization, ownership and update types	/document/plugin/audio-track.html, /document/en/plugin/audio-track.html
docs/plugin/vtt-thumbnail.md, docs/en/plugin/vtt-thumbnail.md	Sprite index format, timing boundaries, asynchronous registration and types	/document/plugin/vtt-thumbnail.html, /document/en/plugin/vtt-thumbnail.html
docs/plugin/chapter.md, docs/en/plugin/chapter.md	Chapter ranges, caller-data mutation, replacement updates, cleanup and types	/document/plugin/chapter.html, /document/en/plugin/chapter.html
docs/plugin/ambilight.md, docs/en/plugin/ambilight.md	Sampling options, start/stop ownership, pixel access and compatible type entries	/document/plugin/ambilight.html, /document/en/plugin/ambilight.html
docs/plugin/document-pip.md, docs/en/plugin/document-pip.md	Window ownership, video fallback, events and compatible async type views	/document/plugin/document-pip.html, /document/en/plugin/document-pip.html
docs/plugin/asr.md, docs/en/plugin/asr.md	PCM/WAV callbacks, subtitle rendering, audio routing, lifecycle and runtime types	/document/plugin/asr.html, /document/en/plugin/asr.html
docs/plugin/auto-thumbnail.md, docs/en/plugin/auto-thumbnail.md	Progressive JPEG extraction, limits, decoder ownership and asynchronous runtime types	/document/plugin/auto-thumbnail.html, /document/en/plugin/auto-thumbnail.html
docs/plugin/multiple-subtitles.md, docs/en/plugin/multiple-subtitles.md	Track loading, selection, shared subtitle configuration and compatible type views	/document/plugin/multiple-subtitles.html, /document/en/plugin/multiple-subtitles.html
docs/plugin/ads.md, docs/en/plugin/ads.md	Preroll options, countdown-only controls, events and approved type-inference migration	/document/plugin/ads.html, /document/en/plugin/ads.html
docs/plugin/vast.md, docs/en/plugin/vast.md	Published/workspace initialization, request contexts, SDK ownership and accurate runtime types	/document/plugin/vast.html, /document/en/plugin/vast.html
docs/plugin/jassub.md, docs/en/plugin/jassub.md	Worker resources, ASS queries, actual method signatures, ownership and compatible declarations	/document/plugin/jassub.html, /document/en/plugin/jassub.html
docs/plugin/danmuku-mask.md, docs/en/plugin/danmuku-mask.md	Segmentation configuration, start/stop, mask ownership and preserved type shape	/document/plugin/danmuku-mask.html, /document/en/plugin/danmuku-mask.html
docs/plugin/chromecast.md, docs/en/plugin/chromecast.md	SDK loading, callbacks, shared sessions, receiver limitations and runtime types	/document/plugin/chromecast.html, /document/en/plugin/chromecast.html
docs/tool/iframe.md, docs/en/tool/iframe.md	Parent/child setup, serialized requests, navigation cancellation, trust and type views	/document/tool/iframe.html, /document/en/tool/iframe.html
docs/tool/thumbnail.md, docs/en/tool/thumbnail.md	Local file extraction, approved defaults, PNG sheets, events and URL ownership	/document/tool/thumbnail.html, /document/en/tool/thumbnail.html
docs/proxy/canvas.md, docs/en/proxy/canvas.md	Backing video, draw callbacks/events, Canvas priority, subtitles and compatible types	/document/proxy/canvas.html, /document/en/proxy/canvas.html
docs/proxy/mediabunny.md, docs/en/proxy/mediabunny.md	Input, HLS pairing, synthetic media state, lifecycle and explicit type views	/document/proxy/mediabunny.html, /document/en/proxy/mediabunny.html
docs/.vitepress/config.js	Navigation, base URL, output path, page head	Repository docs/document/
docs/vite.config.ts, build/search.ts	Search configuration and pinned upstream interaction adapter	Preserves the search template, CSS hooks, index and result URLs
docs/public/main.js	Run Code links and first-visit language redirect	Copied into the built site
docs/public/style.css	Documentation presentation	Copied into the built site

Edit Markdown and public sources here. Do not edit the generated repository HTML directly. After adding a guide, rebuild the site, record its new HTML path in refactor/baselines/demo-additions.json with its owner task and either the known introducedBy commit or the pre-change HEAD as introducedAfter for a new page, and run node refactor/scripts/demos.mjs --check. Preserve the frozen BASE-04 inventory. Also refresh and check the current site inventory; the two inventories serve different purposes. Neither path check replaces browser navigation tests.

The generated site lives in docs/document/. The current inventory contains 66 Markdown pages: 33 Chinese and 33 English. All 16 plugins, both tools and both proxies have dedicated guides and navigation in both languages. SITE-04 completed the 963 core declaration mappings and cross-checked all 40 ecosystem guides. Full site execution and delivery remain in SITE-05/SITE-06; navigation links alone do not establish player or plugin playback compatibility.

Local documentation search

vitepress-plugin-search 1.0.4-alpha.22 supplies the shared Chinese/English index and existing search UI. Its FlexSearch peer is pinned to 0.7.43 in this workspace, within the declared ^0.7.31 range. The plugin also embeds its own index implementation, so changing this peer alone does not fix UI behavior. Its existing token matching is retained; Chinese substring segmentation is not promised. The Algolia/search-insights peer warnings originate from VitePress's unused hosted-search dependencies; this site does not configure that provider.

build/search.ts runs before Vue compilation. It checks the exact installed component hash, normalizes CRLF for patch matching, and requires each replacement to match once. It prevents Enter from submitting the HTML form, navigates the selected result through the router, handles empty results and composition, resets selection when queries change, and makes Escape close the modal and restore button focus. Focus waits for Vue's DOM update rather than a timer. The component owns its shortcut listener and removes it on unmount; a late index import cannot attach it after unmount. Upstream HTML/CSS and third-party attribution stay intact. Do not modify node_modules or simply update the hash on an upgrade: review these interactions and the new upstream component first.

Use yarn test:site-build for the pinned-component compilation and drift guard, yarn typecheck:docs-tools for the adapter, and rebuild with yarn build:docs before yarn test:browser:source document-search.spec.js document-site.spec.js. Browser checks cover both language URLs, pointer navigation, keyboard selection, Escape, focus, no results, and retained document identity (no form reload). They isolate external scripts and do not validate AdSense or physical devices. yarn check:site-links separately checks every built page's local href/src and every shipped search-index target/anchor. The site-editor, site-loading and editor declaration suites exercise the actual Monaco UI and worker. Remote GitHub edit links for new guides require those source paths to reach master; an unpublished local guide is not proof that its external edit link is available.

Tools have their own navigation group. Iframe explains the required child inject step and serialized commit body, without treating the protocol as a sandbox or promising legacy document identity. Thumbnail explains published fixed-height defaults, explicit workspace mode, synchronous failures, density limits and owned Blob URLs. Original examples are retained; their navigation is not extraction or cross-window player acceptance. The thumbnail package's stale default-behavior sentence was corrected alongside these guides, requiring its candidate refresh.

Canvas documents its real backing video and synchronous post-draw callback; Mediabunny documents SDK input, pairable HLS selections and synthetic ranges/frame metadata. Native Canvas members take precedence in both proxies. An Auto menu or canPlayType result is not an adaptive-bitrate or decoder-capability guarantee. Proxy guide navigation does not establish media playback or device acceptance.

JASSUB documents actual resize argument order, query callbacks and resource ownership separately from preserved historical declarations. Danmuku Mask keeps both plugin dependencies in its Run Code link and explains initialization versus first-mask completion. Chromecast distinguishes retained sessions from receiver playback, and player destruction from ending a shared Cast session. These guide checks do not validate actual ASS pixels, segmentation inference or Cast hardware.

Ads and VAST keep their original demos and approved compatibility decisions. Ads play/pause affect its countdown, and its programmatic skip does not enforce the close button's delay. VAST distinguishes default pre-callback allocation from explicit workspace lazy allocation and separates session release from terminal core destruction. Its external IMA example must not be reported as a local or offline playback fixture. Guide navigation tests do not exercise SDK playback.

Auto Thumbnail and Multiple Subtitles preserve their original runnable examples. Both registrars are asynchronous, but their Promises cover different work: Auto Thumbnail installs subscriptions before extraction, while Multiple Subtitles downloads and merges tracks without waiting for host subtitle loading. Their guides explain these boundaries, retained historical declarations and opt-in runtime types. Navigation verification does not prove decoded thumbnail pixels or native subtitle display; keep those package-specific checks separate.

Document PiP keeps its required root factory and void historical result types; the guide explains the accurate opt-in views without inventing a runtime subpath. ASR documents the actual /runtime entry, nonterminal stop, direct/capture audio ownership, CORS and trusted HTML rendering. Its embedded asr.local demo uses simulated subtitles and never claims to run a recognition service. Preserve both original examples and the distinction between navigation and media verification.

Chapter and Ambilight guides preserve their original demo code and explicitly document the mutation, lifecycle and historical type boundaries. Keep their language pairs together; the content mapping is in refactor/site-content-review.md. Run Code markers need visible text as well as the existing className/data-libs hooks. Navigation checks verify exact code forwarding, not playback in the editor. The documented core version in the shared navigation is 6.0.0, marked unreleased.

VTT Thumbnail guides preserve the original vtt.thumbnail demo. The document-vtt suite checks actual screenshot crop pixels, a shared time boundary, a gap and cleanup using the original video, controlled VTT/SVG resources and real progress hover on both cores. The exact endpoint uses public setBar with a MouseEvent to avoid pointer pixel rounding while satisfying the core's event contract. This does not establish physical touch or full playback acceptance.

Audio Track guide examples match the actual audio.track demo. The dedicated document-audio browser suite substitutes local Range-served media, then checks native video pixels and AAC playback, pause, offset seek, volume/rate, source updates and teardown with both core generations. The navigation suite separately checks both generated guide URLs and the Run Code destination. Tests do not measure physical audibility or replace the package's full device matrix.

Danmuku guides describe the refactor branch and explicitly distinguish unpublished /runtime declarations from current CDN releases. Preserve old Chinese heading anchors when editing. Rebuild site assets (the English route inventory), the LLM corpus and VitePress after changing these pages. The generated readiness smoke excludes plugin pages; test/browser/document-danmuku.spec.js extracts and runs both guides separately with the local distribution and real sample media. These checks cover readiness and cleanup, not every interaction or complete playback. The translation CLI does not select plugin pages; maintain the two Danmuku guides together manually. SITE-DANMUKU-01 covers this guide; full bilingual package coverage remains SITE-04.

Site-owned browser behavior now lives in browser/; its README maps the shared loader, desktop editor, mobile entry and Run Code/language navigation. docs/public/main.js is a generated input to VitePress. Run root yarn build:site-assets after changes, or yarn check:site-assets for drift. Desktop common.js and bootstrap.js are generated from typed modules, with Monaco models/emit, Run ordering, file imports, preferences and page cleanup separated by responsibility. No player package APIs move here.

Related tooling

Run commands from the repository root with its pinned Node version and Yarn Classic 1.22.22. Maintain the root lockfile only.

yarn workspace artplayer-vitepress dev
yarn build:docs
yarn workspace artplayer-vitepress preview
node refactor/scripts/site-inventory.mjs --check

build:docs uses the current pinned Yarn executable to run this workspace's VitePress script into a temporary directory. A successful build replaces the generated site, with backups for caught replacement failures. See build maintenance for module ownership, failure recovery and the explicit limits of directory replacement.

The repository generators have different ownership:

• scripts/build-types.mjs: core public declaration sources to existing types/.
• scripts/build-ts.js: standalone editor declarations and the editor library list. Checked TS modules in scripts/editor-declarations/ validate all selected declarations together with current and historical compilers before writing. Use yarn check:editor-types for drift checks; see that module's README.
• scripts/build-test.js: extracts Chinese core Run Code blocks into docs/test/test.js; plugin and English pages are excluded. The TS implementation in scripts/docs-smoke/ produces deterministic readiness smoke cases with owned frames, error observation and cleanup. It does not prove complete playback or plugin behavior. See its maintenance README and SITE-SMOKE-01.
• scripts/build-i18n.js: typed standalone language builds, staged before replacing distribution and docs/compiled/i18n/ together; legacy globals and paths remain.
• scripts/build-docs.js: this VitePress build through pinned Yarn and staged output.
• scripts/build-console.mjs: owned desktop console TS entry/view and shared log lifecycle, keeping the original React/Parcel runtime. Run build:console after edits and check:console for drift. See console maintenance.
• scripts/build-llm.js: offline source-preserving docs/llms.txt and fingerprint manifest. yarn check:llm checks drift in CI; ci:build regenerates after types.
• scripts/trans-docs.js: local plan by default; explicit --remote creates a reviewable draft, --validate <draft> checks edited drafts, and --apply <draft> replaces selected English files with stale-input and rollback checks. Remote translation is never part of CI. See tool maintenance for the migration from destructive translation, module boundaries and limits.

Browser boundaries and ownership

The editor's prod choice is stored in localStorage and changes the core script only. The libs query still selects plugin scripts independently. example takes precedence over code. Editor Run dispatches the example cleanup event, destroys existing players, then evaluates the code. Preserve these contracts when moving its JS to TypeScript; use an isolated origin for automated tests.

The mobile page preserves the query during redirect but has its own loader and uses the development core. The ESM, i18n, iframe and generated smoke pages each have separate dependencies. See the repository site inventory for the full entrypoint map, source fingerprints, asset provenance and assigned follow-up work.

Generated main.js installs one document click listener under window['run-code-init']; its lifetime is the page. Run Code opens the separate editor and recognizes localhost, 127.0.0.1 and IPv6 loopback. First-language navigation preserves existing English counterparts and explicit later choices; unavailable storage keeps the requested page. See browser/README.md for the current rules and verified scope. Full site/search acceptance remains SITE-05.

Delivery and remaining acceptance

SITE-07 now checks frozen Monaco/vConsole files and generates verbatim upstream texts under docs/licenses/ with build:site-notices / check:site-notices. See scripts/site-vendor/README.md: vConsole sources/notices and its destruction fix now have separate evidence. The notices index explicitly does not clear the console bundle, fonts, media or the rest of the site.

scripts/projects.js excludes this workspace from the 21 library builds. VitePress emits the static site; CI-02 stages docs/, refreshes old demo entries, and validates that separate Pages artifact before deployment. The manifest currently has neither library entrypoints nor private: true; that absence is not npm publication intent. REL-01 must explicitly classify its release handling. Its independent planned major still advances from 1.1.0 to 2.0.0 under the agreed version policy.

SITE-02/03 own generators and browser source organization; SITE-04 owns bilingual API completeness; SITE-05 owns build, links and real search; SITE-07 owns vendor provenance and distribution notices; EX-03 owns complete demo execution. Three release review rounds and remote CI/Pages evidence remain separate requirements.

The HLS guides at docs/plugin/hls-control.md and docs/en/plugin/hls-control.md share the exact runnable docs/assets/example/hls.control.js source at repository root. test/browser/document-hls.spec.js enforces that parity and checks the source lifecycle with frozen real SDKs. document-site.spec.js checks both sidebar links and the two-library Run Code destination. Preserve the native-HLS capability boundary and SDK ownership explanation when editing either language.

The DASH guides use the same exact-example rule with docs/assets/example/dash.control.js and test/browser/document-dash.spec.js. Their formatter has one argument, unlike the optional HLS list index. Preserve the distinction between SDK 4 qualityIndex and SDK 5 representation IDs, nullable language fields, and synchronous update.