A single playlist can mix both kinds of video:

You can place as many players on a page as you like. Every player has its own id (a short name such as player_1), its own playlist, and its own settings. Nothing leaks from one player to another: a video you add to player_1 never shows up in player_2. Internally each player is a separate instance of the module, created through a factory function — exactly the same idea Video.js uses. This is explained in Notes on Implementation.

Settings come from three files that are merged together in order. Later files win, so you only have to write down what you want to change.

These live at the top of the settings and control the module as a whole.

The playlist: block controls the playlist panel that sits under each player.

The videoJS: block controls the video engine itself: how a video starts, how fast it can play, and how poster (preview) images are made.

The players.native block sets the behaviour for self-hosted videos. The most useful keys are shown below.

Video.js gains extra buttons through small plugins. J1 VideoPlayer ships a handful, switched on and off under videoJS.plugins:.

The videoPlayer_control.yml file is where you actually create players. It holds a list of players, and each entry describes one player. Keys you do not set fall back to the global settings and then the defaults.

A minimal control file with one player looks like this:

Every player has a slim header bar with three slots:

Below the header is the video itself. Before anything is loaded, a friendly placeholder (the VideoJS logo) is shown in its place.

When opened, the playlist panel shows:

Which of these appear depends on the matching options in the playlist: block described above.

The edit panel is where content is managed. It offers:

Ready-made playlist files are ordinary .json files kept in the folder set by playlist_url_base. To have a player load one (or several) on page load, list the file names under that player’s playlist.preload key:

Preloading is safe to repeat. On every page load the module merges the file into the player’s playlist: it adds any videos that are not there yet and leaves everything else — including the viewer’s own additions, ratings, and watch positions — untouched. Nothing is ever duplicated or overwritten. Preloading only fills the list; it does not start playing on its own.

videoPlayer(id, options) is the main entry point. It creates the player for id the first time you call it and returns the existing one on later calls (this is called "create-or-get"). Options given for a player that already exists are ignored.

The object returned by the factory represents one player. It carries a few accessors and, most importantly, its playlistManager.

The playlist is managed by vp.playlistManager. Its methods are grouped below by what they do. Anywhere you see videoId, it is the videoId field of a playlist item.

The module is built the same way as Video.js. Calling videoPlayer(id) returns a separate instance for each id, kept in a shared registry. Each instance owns its own state, its own playlist manager, and its own event handlers. There is no hidden "default" player that everything shares — that older design caused several players to fight over one set of settings, so it was removed.

Because every player keeps its playlist in the browser’s local storage, the module gives each player its own storage name by adding the player id to it (for example playlist_player_1). This is why a video added to one player never appears in another. The same scoping applies to the small UI preferences, such as whether the playlist was last shown as a list or as cards.

Both native and YouTube videos play through the same Video.js player. The module looks at the item’s link to decide which one it is: a YouTube link is recognised and played through YouTube; anything else is treated as a native file and loaded from its src. Posters follow the same rule — YouTube posters come from YouTube, native posters are generated from the video.

Preloading always merges. It never overwrites the viewer’s existing list, and running it again on the next reload never creates duplicates. This is why it is safe to keep a preload list in your configuration permanently.

This is the simplest useful setup: a single player that loads a ready-made playlist file on page load and shows it as a grid of cards, four per row.

Tiny Desk Concerts is a popular, award-winning video series featuring live music performances at an actual office desk, hosted by NPR Music. Started in 2008 by radio host Bob Boilen and producer Stephen Thompson. The show has grown from a small platform for folk and indie artists into a worldwide pop-culture hit.

Each player has its own id, its own preloaded playlist, and its own card layout. They do not share anything.

A playlist file that mixes one YouTube video and one native video. Save it in your playlist_url_base folder and reference it from a preload list.

For a custom button, you can add and play a video yourself. First get the player, then use its playlist manager.