vimeoplaylist

📼 Vimeo Playlist

A pure JavaScript library to create endless video playlists with the Vimeo Player API. Features playlist UI, controls and customizable template.

Simply define your markup and playlist template, pass an array of Vimeo IDs, profit 💵 💵 💵.

Demo Playlist→

Contents

1. 📌 Features
2. 🎯 Quickstart
3. 🧬 Options
4. 🤖 Commands
5. 🕹️ Usage
6. 📅 Todos

📌 Features

• Builds a playlist of Vimeo Videos from an array of Vimeo IDs
• Uses the Vimeo Player API
• UI consists of Video Player, Playlist items (optional), Playlist controls (optional).
• Super flexible - UI conforms to your structre / markup / selectors.
• Playlist items authored via custom template (default included).
• Supports continuous autoplay.
• Customizable controls for navigation, play/pause, etc. Includes arrow key nav
• Offers Fullscreen API control for Video player.
• Supports Vimeo API options like width, color, player controls, muted, title
• Hybrid NPM module, works with import and require

📦 Dependencies

• @vimeo/player

🎯 Quickstart

1. Install from NPM

npm i vimeoplaylist

2. Define Markup

Create locations for Player, Nav and Playlist

<!-- Player -->
<div class="player">
  <div id="js-vp-player" class="player__vid"></div>
</div>

<!-- Playlist Nav -->
<nav class="playlist-nav">
  <button id="js-vp-prev" class="playlist-nav__prev"><i>←</i> Prev</button>
  <button id="js-vp-next" class="playlist-nav__next">Next <i>→</i></button>
</nav>

<!-- Playlist -->
<div id="js-vp-playlist" class="playlist"></div>

3. Create Playlist Item Template

Playlist items show info about the tracks (Ie: title, thumbnail, duraction, user, etc). Create a custom template literal (probaly as an external file) to display the info you'd like. The data paramater can access all video / user data returned by Vimeo respoinse object.

Full list of available properties here.

/**
 * Playlist Item Template
 * Each is item is wrapped in <article='plist-item'></article>
 * @param {obj} data - response object of video info from vimeo promise
 * @return {string} returns template literal
 */

// import included time formater util
import {formatTime}  from 'vimeoplaylist'

export default function playlistTmpl(data) {
  let timeDuration = formatTime(data.duration)

  return `
    <a class="plist-item__link" data-vimeo-id="${data.id}" tabindex="0">
      <figure class="plist-item__thumb">
          <img class="plist-item__thumb-img" src="${data.thumbnail_large}"/>
      </figure>
      <div class="plist-item__main">
        <span class="plist-item__title">${data.title}</span>
        <span class="plist-item__user">${data.user_name}</span>
        <span class="plist-item__time-dur">${timeDuration}</span>
      </div>
    </a>
  `
}

4. Setup JS

Initizale the plugin on the defined selector, passing in options for our playlist template and playlist ids. (Complete list of Options found here )

import VimeoPlaylist from 'vimeoplaylist'

// Provide custom template for playist items
import playlistTmpl from './plist.tmpl'

// Plugin Options
let options = {
  hasPlaylist: true,
  itemTmpl: playlistTmpl,
  playlist: [
    { "id": "288588748" },
    { "id": "328536852" },
    { "id": "281449879" }
  ]
}

// Create instance on id #js-player
let playlist = new VimeoPlaylist('js-vp-player', options)

// Init
playlist.init()

5. Provide Styles

Style as desired. While the core lib doesn't include styles, see the repo's demo project for styles that you can clone as a starting point.

🧬 Options

The options param supports the following properties:

Option	Type	Description	Default
hasPlaylist	Boolean	Make false if you need endless vids, but not playlist ui	true
playlistOutput	String	id or class to output playlist	#js-vp-playlist
playlistNavPrev	String / Element ID	id of Prev nav element	#js-vp-prev
playlistNavNext	String / Element ID	id of Next element	#js-vp-next
playlist	Array of Objects	playlist as array of objects { "id" : [vimeoID] }	[]
itemTmpl	HTML Template Literal	Template for playlist Items	Template found at plist.tmpl.js
itemName	String	Parent name of playlist Items (becomes parent class name)	plist-item
itemTrigger	String / Element selector	Wrapping Link selector (trigger) of playlist items (matching playlistTemplate)	plist-item__link
supportsKeyNav	Boolean	Enables next/prev key nav	true
width	Number	Video width in px	900
title	Boolean	Show video title	false
muted	Boolean	Mute vids	false
controls	Boolean	Show player controls	true
autoplay	Boolean	Autoplay vids (required for continuous playlist vids)	true
color	String (3 or 6 digit hex value)	Player ui color	#7B8EF9
fullscreenToggle	String / Element ID	id of fullscreen video toggle control	#js-vp-fstoggle
fullscreenToggleKeyCode	String / Element ID	full screen toggle keycode, ie: KeyF for F key	null
debug	Boolean	Outputs helpful logs	false

🤖 Project Commands

Install Project Deps

npm i

Build

npm run build

Builds src with microbundle to the various common js patterns.

Run Dev

npm run dev

Dev has microbundle begin watching / building the files, while also running the demo project via Parcel, which imports from the local src directory.

Run Demo

npm run demo:start

Runs the demo project via Parcel.

Lint

npm run lint

🕹️ Usage

Playlist Content

Playlists are created from Vimeo IDs.

Vimeo IDs can be provided to the playlist option directly, as an Array of objects, or as an external JSON file.

Creating playlist of Vimeo Ids

import VimeoPlaylist form 'vimeoplaylist'

// Plugin Options (with internal data array)
let options = {
  playlist: [
    { "id": "288588748" },
    { "id": "328536852" },
    { "id": "281449879" }
  ]
}

// Create instance
let vplaylist = new VimeoPlaylist('js-player', options)

// Init
vplaylist.init()

Vimeo IDs from JSON file

To use external JSON file, setup you JSON like so:

// playlist.json
[
  {
    "id": "288588748"
  },
  {
    "id": "328536852"
  },
  {
    "id": "281449879"
  }
  ....

Passing IDs as external JSON file (with Babel or Parcel)

import VimeoPlaylist from 'vimeoplaylist'
import data from '../data/playlist.json'

let options = {
  playlist: data,
  ...
}

// Create instance
let vplaylist = new VimeoPlaylist('js-player', options)

// Init
vplaylist.init()

Passing IDs as external JSON file with Request()

import VimeoPlaylist from 'vimeoplaylist'

const data = new Request('assets/data/playlist.json')

fetch(req)
  .then(response => response.json())
  .then(data => {
    let options = {
      hasPlaylist: true,
      playlistOutput: '#js-vp-playlist',
      playlist: data,
      ...
    }
    let vplaylist = new VimeoPlaylist('js-vp-player', options)
    vplaylist.init()
})

Markup / HTML

Construct your markup, adding IDs for the output of the:

• Video player
• Playlist list of items (optional)
• Playlist nav prev and next controls (optional)

<!-- Player (main video embed)-->
<div id="js-vp-player"></div>

<!-- Playlist (list of vids) -->
<div id="js-vp-playlist"></div>

<!-- Playlist Nav -->
<nav class="playlist-nav">
  <button id="js-vp-prev" class="playlist-nav__prev"><i>←</i> Prev</button>
  <button id="js-vp-next" class="playlist-nav__next">Next <i>→</i></button>
</nav>

You can customize the target ids

let options = {
  hasPlaylist: true,
  playlistOutput: '#js-vp-playlist',
  playlistNavPrev: '#js-vp-prev'
  playlistNavNext: '#js-vp-next'
  fullscreenToggle:  '#js-vp-fstoggle',
  fullscreenToggleKeyCode: 'Digit1',
}

Playlist Item Template

Each item in the playlist provides video and user info (ie: id, title, thubnails, url, duration, etc).

You can use the default template or provide your own to customize the layout/markup of each playlist item. Simply create a template literal, perhaps as a seperate file, and pass its reference to the itemTmpl option.

Playlist Template Example

// plist.tmpl

/**
 * Plist Item Template
 * Contents below are wrapped in <article='plist-item'/>
 * @param {obj} data - response object of video info from vimeo promise
 * @return {string} returns template literal
 */
export default function playlistTmpl(data) {
  return `
    <a class="plist-item__link" data-vimeo-id="${data.id}" tabindex="0">
      <figure class="plist-item__thumb">
        <img class="plist-item__thumb-img" src="${data.thumbnail_large}"/>
      </figure>
      <div class="plist-item__main">
        <span class="plist-item__title">${data.title}</span>
        <span class="plist-item__user">${data.user_name}</span>
      </div>
    </a>
  `
}

Pass Playlist template

import playlistTmpl from './plist.tmpl'

let options = {
  hasPlaylist: true,
  itemTmpl: playlistTmpl,
  ...
}

Available Vimeo Response Properties

Your template's data param can use to following properties from Vimeo's reponse object.

Name	Type	Description
description	String	Vid details
duration	number	Vid duration time
embed_privacy	string	Privacy embed location, ie: 'anywhere
height	number	px height of vid
id	number	Vid id
stats_number_of_comments	number	Number of comments
stats_number_of_likes	number	Number of vid's likes
stats_number_of_plays	number	Number of vid's plays
tags	string	Comma seperated tags
thumbnail_large	(string|link)	Large format vid thumb
thumbnail_medium	(string|link)	Med format vid thumb
thumbnail_small	(string|link)	Small format thumb
title	string	Vid title
upload_date	(string|date)	Upload date ie "2019-01-18 10:22:32"
url	(string|link)	Vid URL
user_id	number	User ID
user_name	string	User name
user_portrait_huge	(string|link)	User image 300x300px
user_portrait_large	(string|link)	User image 100x100px
user_portrait_medium	(string|link)	User image 75x75px
user_portrait_small	(string|link)	User image 30x30px
user_url	(string|link)	User url
width	number	Video width in px

Playlist Template Requirements

It's important that your playlist template at least have a wrapping trigger/link element as seen in the above example.

Important:

The itemTrigger option defines the playlist Item wrapping link/trigger used for click events. If you're passing your own itemTmpl, make sure to update the itemTrigger to match your link's selector name. Will refactor out this requirement in the future.

The itemName option is used to define the parent class name of the playlist item block. You might also want to make sure that has some relevance to how you organize item's class names.

Additional Notes:

When a playlist item is playing, it will have an is-playing class to leverage. When a playlist item is paused, it will have an is-paused class.

Playlist Navigation

Playlist navigation contols next / prev buttons. You can use the default selectors or provide your own. Keynav arrows are also supported by default.

Default Nav ids

<!-- Playlist Nav -->
<nav class="playlist__nav">
  <button id="js-vp-prev" class="playlist__prev"><i>←</i> Prev</button>
  <button id="js-vp-next" class="playlist__next">Next <i>→</i></button>
</nav>

Customize Nav Ids

let options = {
  ...
  playlistNavNext: '#js-next',
  playlistNavPrev: '#js-prev',
}

Fullscreen Toggle

Leverage the fullscreen api to launch currently playing vid as fullscreen. Fullscreen mode repains during autoplay.

<!-- Playlist Full Screen Toggle -->
<button id="js-vp-fstoggle" class="playlist__fstoggle">Fullscreen</button>

Customize FS Toggle Ids

Provide a KeyboardEvent.code string for the fullscreenToggleKeyCode option.

let options = {
  ...
  fullscreenToggleKeyCode: 'Digit1',
}

Using Almost Ended (Timeupdate)

The Vimeo Player API seems to have an issue where End Screen overlays the video if the player is scrolled out of view (not visible).

We can seemingly address this by listening until the current video is almost ended, then calling next. This prevents the End Screen from appearing, which seems desireable for a continous playlist.

So, as of v2.6.0, we use Timeupdate instead of ended to call next() when current vid is 0.5s from end.

📅 ToDos

• Option for custom playlist template
• Document availble data options from Vimeo's reponse object for playlist template.
• Make hybrid npm module to support import and require.
• Provide a util method for ellapsed time.
• Address issue with End Screen overlaying player/video.
• Provide better error handling for 404'd items.
• Since autoplay on load only works if muted due to Chrome policy, provide a button to unmute.
• Provide destory method
• Perhaps support for multiple instances per page, with everything scoped to element.