GuideGetting Started
HTML Installation Guide
Install Video.js with HTML custom elements and build an accessible, customizable video player
Video.js is an HTML video player built on custom elements: lightweight, framework-free components for building accessible, customizable players with minimal bundle sizes, advanced features, and consistency across browsers.
AI Quickstart
Copy this prompt into your coding agent. It works as is, or tell it what you're building first.
Your prompt
Install the Video.js skill:
`npx @videojs/cli agents skills`
.Run it and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project.
Add a Video.js player to this project:
`npx @videojs/cli agents init --skin default --source-url demo`
.Run it to print version-matched instructions for these choices without changing files. The command detects the package manager, framework, app setup, and installation method from the project and explains how to choose the starting point, preset, and media, so follow its output for those. If a choice conflicts with the project, ask me before changing it.
Install the Video.js skill: `npx @videojs/cli agents skills`. Run it and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --framework html` to print the version-matched choices and instructions without changing files.Installation options for coding agents
The web Markdown page contains the default installation. Add the query parameters below to its .md URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.
This page fixes the installation method to packaged and the framework to html.
npx @videojs/cli agents initQuery parameters
project: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values:new,existing. Default: existing.preset: The player configuration and control set. Values:video,audio,live-video,live-audio,background-video. Default: video.skin: The visual skin. Neutral has cleaner surfaces and the same controls as Default. Values:default,neutral,compat,scaffold,none. Default: default. Applies when preset is not background-video.media: The media source or playback adapter. See the preset compatibility map below. Values:background-video,hls-background-video,cloudflare,dash,hls,html5-audio,html5-video,mux-audio,mux-background-video,mux-video,spotify,tiktok,twitch,vimeo,youtube. Default: the selected preset's first compatible media source.extensions: A comma-separated list of optional player extensions compatible with the selected player. Passnonewhen no extension is needed. Values:none,google-cast,mux-data. Default: mux-data for Mux media; none otherwise (reported as defaulted).features: A comma-separated list of player features to add, each with the guide that shows how. Features depend on the preset: audio has no poster or thumbnails, and live streams have no thumbnails. Values:none,captions,quality,thumbnails,poster,autoplay,keyboard-shortcuts,user-preferences,internationalization. Default: none.source-url: The http:// or https:// media URL placed in the generated player example. Passdemoto choose the Video.js demo source for the selected media explicitly. With Mux media, a local file such as./intro.mp4adds a step that uploads it with the Mux CLI. Default: the Video.js demo source for the selected media (reported as defaulted).package-manager: The command runner used for app setup, packages, Shadcn, and the development server. Values:npm,pnpm,yarn,bun. Default: pnpm. Applies when method is not cdn with template none.template: The app setup and file layout. Packagednoneneeds an existing bundler; use CDN for a site without a build step. Values:vite,astro,laravel,none. Default: vite.from: The player an existing project migrates from. The plan adds the migration guide, the checks before changing code, and the cleanup after. Values:video-js-8,mux-player,plyr,media-chrome,vidstack,video-react. Default: none (a new installation). Applies when project=existing.
Run the command above without flags to see the corresponding CLI flags for every framework.
Decide in this order
- Check for a migration. When the project already plays media with Video.js 8, Mux Player, Plyr, Media Chrome, Vidstack, or Video-React, pass from with that player, and keep its media URLs as the source.
- Inspect the project. Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
- Choose the starting point. Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
- Choose the player. Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video (hls or mux-video) or live-audio (mux-audio only); a muted, looping decorative video uses background-video. Content hosted on another platform keeps that platform's player even when it is live: youtube, vimeo, twitch, tiktok, and cloudflare use video, and spotify uses audio. Treat comparisons to other products, such as "like Netflix", as describing the experience rather than the media source: build only what Video.js provides, and name anything out of scope, such as chat, playlists, or DRM. Ask only when those signals conflict.
- Choose the skin. Decide whether the project applies its brand to our design or builds its own. When it applies its brand, or asks for a minimal, cleaner, or more subtle look, use neutral: an opinionated design that's easy to brand. When it builds its own design, use none and build the controls from components. When either works or the request doesn't say, use default, the distinctly Video.js design; default and neutral contain the same controls. When the player must work in older browsers, use compat, which keeps fewer features. Ask only when those signals conflict.
- Choose the media. Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls. Choose a platform adapter only when the content is hosted there, not when the request compares itself to that platform. Without a URL, use hls or dash for a player that should cast, since the default html5-video cannot.
- Choose features. Pass features for what the request asks for, such as captions, a quality menu, or thumbnail previews; the plan points at each feature's guide. Leave it out when the request names none.
- Choose extensions. Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin plays hls, dash, or mux-video media. Use none when no extension is needed.
- Choose how to install. This guide uses packaged modules, which need a bundler. Match the package manager to the project lockfile. For an existing HTML site without a build step, use CDN scripts instead.
- Return one explicit plan. Confirm the choices once, then pass every applicable query parameter, including
extensions=nonewhen no extension is needed andsource-url=demowhen there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.
Compatible media sources by preset
video:html5-video,hls,dash,mux-video,vimeo,youtube,cloudflare,tiktok,twitchaudio:html5-audio,mux-audio,spotifylive-video:hls,mux-videolive-audio:mux-audiobackground-video:background-video,hls-background-video,mux-background-video
App setup by framework
html: templatesvite,astro,laravel,none
Installation pages
If a preset and skin do not meet your user’s requirements, follow Customize skins to add the files for the closest skin to the project. As you develop with Video.js, rely heavily on llms.txt to make sure you always have the latest information.
Manual installation
Prefer to set it up yourself? Each choice below updates the code in the steps after it.
Choose your framework
Choose the JavaScript framework for your project.
Choose your app
Choose the app environment that controls the setup commands and file locations below.
Choose your use case
The default presets work well for general website playback. The live presets suit streams: they add a Live button and drop the duration and current-time displays that on-demand playback relies on. More pre-built players to come.
Choose your media
Video.js plays plain files, adaptive streams, and embeds from hosting services, and switching between them is a one-line change. Paste a URL to detect the type, pick one directly, or upload a video to Mux. Mux is optional hosting that gives any video an adaptive stream, thumbnail previews, and viewer analytics; compare it with other video hosting.
Optional. The URL also ends up in your generated code.
Choose your skin
Choose how your player looks. You can add the files for any skin to your project and edit them later.

Choose your extensions
Add optional behavior to the player. Only extensions that work with your player and media source appear below.
No optional extensions apply to these selections.
Choose how to install
Choose from the installation options available for your selections.
Prepare your app
Choose whether to create the selected app setup or add Video.js to a project you already have.
Install the packages
That’s it! You now have a working Video.js player.
Own the UI
Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.
Choose what to do next
Customize
Deploy
Something not quite right? You can submit an issue and ask for help, or explore other support options.