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, and a setting you change for one player never changes another. 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 ui_elements: block controls which controls (buttons and switches) of a player are shown at all. Each key stands for one visible element and takes true (show it) or false (hide it).

The two header buttons can be switched on and off per player: set the key in the defaults for everyone, in your global videoPlayer.yml for all players of your site, or inside one player’s entry in videoPlayer_control.yml for that player only. As everywhere else, the most specific setting wins.

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 of the player itself. Despite its name it is used for both video kinds — native files and YouTube videos play through the same settings. 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 control file with one fully customised player looks like this:

Every player has a slim header bar with three slots:

Either button can be hidden per player through the ui_elements keys show_playlist_button and edit_playlist_button (see UI Elements). The header keeps its three-slot layout even when a button is hidden, so the title always stays centred.

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 ui_elements: block, and the controls hide themselves while the playlist is empty.

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.

Whenever a player needs one of its videoJS settings, it looks in a fixed order: first the options handed to its own factory call (that is, the merged per-player configuration), then the page-global options, and only then an internal fallback. In short: the setting closest to the player wins. This is why two players on one page can autostart differently, offer different speed menus, or run different plugins.

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 — whether the playlist was last shown as a list or as cards, the merge switch, the loop switch, and the last search mode are all remembered per player.

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. The player settings for both kinds come from the players.native block.

The cards layout of the playlist is rendered by a small, modern web component (built with Lit). It draws each video as a card and updates only the card that changed — rating one video or deleting one entry never redraws the whole grid. It renders into the normal page (light DOM), so all existing styles and click handling keep working. You never interact with it directly; the mode switch and playlist.type control it for you.

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 "read-only" player: the viewer can watch and browse the preloaded playlist, but the Manage Playlists button is hidden, so the playlist cannot be changed from the page. The player also gets its own, shorter speed menu.

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.