Before diving into the settings, it helps to know the five pieces that make up a J1 MultiPlayer. You never touch most of them directly, but knowing they exist makes every later section easier to follow.

A single playlist can mix all three kinds of media. The module decides what to do by looking at the item itself — you never set a "mode" anywhere.

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. A media item 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 VideoJS uses for its own players. This is explained in One instance per player.

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: block and control the module as a whole.

The ui_elements: block controls which parts of a player are shown at all. Each key stands for one visible element and takes true (show it) or false (hide it).

All keys follow the normal chain: set them in the defaults for everyone, in your global multiPlayer.yml for all players of your site, or inside one player’s entry in multiPlayer_control.yml for that player only. The most specific setting wins.

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

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

VideoJS gains extra buttons through small plugins. MultiPlayer ships a handful, switched on and off under videoJS.plugins:. What each plugin does in detail is described in the VideoJS manual.

The multiPlayer_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 to the defaults.

A control file with one fully customised player looks like this:

A player is placed on a content page with the AsciiDoc block macro multiPlayer::, followed by the id of the player you configured:

The macro writes an empty placeholder into the page; the adapter loads the player’s HTML into it and starts the module.

When you write a playlist file by hand, or read one that was exported, this is the shape of each item. Only videoId is truly required; every other field has a sensible default and can be left out.

Ready-made playlist files are ordinary .json files kept in the folder set by playlist_url_base (by default /assets/data/apps/multiPlayer/playlists). A single item looks like this:

A playlist file mixing one YouTube video, one native video and one audio track:

To have a player load one or several playlist files on page load, list the file names under that player’s playlist.preload key:

How a name is resolved:

Preloading only fills the list; it does not start playing on its own. On a first visit the module loads the first item into the player in the paused state as soon as the preload has arrived, so the viewer sees a poster instead of an empty box. On later visits the first stored item is loaded the same way.

The search box above the playlist filters the list as you type. The search runs over an index the module builds from the playlist, so it is fast even for long lists.

These fields are searched, in order of importance:

The index is rebuilt automatically whenever the playlist changes — after an import, an edit, a delete, or a preload.

The sort control offers the following orders:

The module also picks a sensible starting order for you. When every item of a list belongs to a series, the list is sorted by episode automatically; otherwise the most recently watched item comes first. As soon as the viewer picks an order by hand, that choice wins.

Some YouTube items are worth listening to but not worth watching — a concert recording, a podcast, an audio book. Audio only plays such an item without showing the video: the poster image stays on screen, the control bar keeps working, and YouTube is asked for the lowest video quality so far less data is loaded.

The feature applies to YouTube items only. Native mp3 and mp4 items are never touched — an mp3 has no video to hide anyway.

Three settings work together:

Sometimes only a part of a media item is interesting — the song inside a long concert recording, or a chapter of a podcast. startAt and endAt define a playback window: playback begins at startAt and stops at endAt.

Both values accept several shapes, so you can write whatever is convenient:

Where the values may be set, most specific first:

Resuming still wins where it makes sense: when the viewer stopped inside the window last time, playback continues from there instead of jumping back to startAt. A stop position outside the window is discarded.

When the item is part of a playlist and endAt is reached, the player stops. With loop mode or the autoadvance option of the playlist plugin switched on, the next item takes over from there.

audioFadeIn ramps the sound up from silence to the player’s volume when an item starts, instead of starting at full volume. It works for all kinds of media — YouTube, mp3 and mp4.

As with the playback window, a value set on the media item wins over the YAML setting, and off on an item is a deliberate opt-out.

Some media is only licensed for a limited period. The optional expiryDate field of a media item states the day access ends. An empty value — the default for every item — means unlimited.

The module colours the Expiry Date field of the edit dialog like a traffic light and blocks playback once the date is reached:

A viewer can save plain media files to the download folder — one item at a time with the download button on the item, or the whole list at once with the Download button in the playlist title bar.

What can be downloaded is decided by the file extension:

The buttons are self-hiding: a YouTube-only playlist shows no download UI at all. They can also be switched off per player with ui_elements.playlist_download_button and ui_elements.playlist_download_all_button.

Every export shows a small toast notification: when it starts, for each file of a batch, and for the final result.

A poster is the still image shown before an item plays. MultiPlayer fills it in for you:

Every player has a slim header bar with three slots:

Below the header is the player itself. Before anything is loaded, a friendly placeholder image is shown in its place. As soon as an item is loaded, the poster appears; playback starts either automatically (videoJS.autoStart) or when the viewer presses play.

For audio items and for YouTube items played in audio only mode, the poster stays visible for the whole playback — there is no video to show.

When opened, the playlist panel shows a title bar with the controls, and below it the items themselves.

The title bar can hold:

All of these hide themselves while the playlist is empty, and some hide themselves when they would have nothing to do — see the note in UI elements.

The edit panel is where content is managed. It opens over the media area and offers:

Whether an import adds to or replaces the current list is decided by the merge switch in the playlist panel.

The Edit button of an item opens a dialog with every field the viewer may change.

Two kinds of message can appear:

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 — exactly as in VideoJS.

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

Two small helper objects are also exposed on every player:

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

Adding an item from a custom button and playing it:

Adding a local audio track instead:

The adapter is a small piece of J1 JavaScript located at ~/assets/theme/j1/adapter/js/multiPlayer.js. It is loaded on every page and does the following work for you:

You normally never call the adapter yourself. It is started automatically by the J1 core at page load.

The module is built the same way as VideoJS. 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. An earlier design had one, and it caused several players on a page to fight over one set of settings — so it was removed.

Whenever a player needs one of its 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 start 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 an item added to one player never appears in another.

The same scoping applies to the small display preferences — whether the playlist was last shown as a list or as cards, the merge switch, the loop switch, the audio-only switch, and the last search mode are all remembered per player.

Audio, native video and YouTube all play through the same VideoJS player. The module looks at the item to decide which one it is: a YouTube link is 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 or taken from the item. The settings, however, come from two different blocks: videoJS.players.youtube for YouTube and videoJS.players.native for native audio and video.

The cards layout of the playlist is rendered by a small, modern web component (built with Lit). It draws each item as a card and updates only the card that changed — rating one item 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.

player.css defines its colours as CSS variables on :root. To adapt them to your site, overwrite the variables in your own stylesheet — there is no need to modify the module file:

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.

Place it on a page with:

A player for a series of mp3 episodes. The list starts in list layout, loops through the series, and fades the sound in on every episode.

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

The viewer can watch and browse the preloaded playlist, but nothing can be changed: the Manage Playlists button is hidden and the item action buttons are switched off.

Every item of this player starts twelve seconds in and stops after four minutes and forty-five seconds — useful for a preview player. Individual items can override the window in their own record.

Switch cross-page synchronization on in your global multiPlayer.yml so it applies to every player of your site: