dlp-player

DJ tracklist widget that displays a synchronized track listing alongside any media player. DJs export their playlist as JSON from the DJ Live Playlist app, then embed this widget on their page so viewers can see which track is playing at every moment of the video or audio.

Live demo · Documentation

Features

• Zero dependencies — lightweight, pure JavaScript
• Works with <video>, <audio>, and YouTube iframes
• Two display modes — side-by-side list & bottom overlay
• Auto-syncs tracks to media playback time in real-time
• Fully customizable via CSS variables
• TypeScript support — type definitions included
• Dual format — ESM and UMD bundles

Installation

Via npm

npm install dlp-player

import 'dlp-player/style.css'
import 'dlp-player'

Via <script>

<link rel="stylesheet" href="https://unpkg.com/dlp-player/dist/dlp-player.css">
<script src="https://unpkg.com/dlp-player/dist/dlp-player.umd.js"></script>

Usage

Add the dlp class and a data-dlp-src attribute (URL to the playlist JSON) to your media element:

<!-- Video -->
<video class="dlp" data-dlp-src="/playlists/mix.json" src="video.mp4" controls></video>

<!-- Audio -->
<audio class="dlp" data-dlp-src="/playlists/mix.json" src="mix.mp3" controls></audio>

<!-- YouTube -->
<iframe class="dlp" data-dlp-src="/playlists/mix.json"
        src="https://www.youtube.com/embed/VIDEO_ID"
        allowfullscreen></iframe>

The widget automatically detects .dlp[data-dlp-src] elements on page load and displays the synchronized tracklist.

Display modes

List mode (default)

The tracklist is displayed next to the player. The current track is highlighted and the list auto-scrolls.

<video class="dlp" data-dlp-src="/playlist.json" src="video.mp4" controls></video>

Overlay mode

The tracklist overlays the bottom of the player with enter/exit animations.

<video class="dlp" data-dlp-src="/playlist.json" data-dlp-mode="overlay" src="video.mp4" controls></video>

Attributes

| Attribute | Required | Description | |-----------|----------|-------------| | data-dlp-src | Yes | URL to the playlist JSON file (exported from DLP) | | data-dlp-mode | No | Display mode: list (default) or overlay |

Playlist JSON format

The JSON file is exported from the DJ Live Playlist app. Structure:

{
  "id": "uuid",
  "name": "Mix name",
  "recordingStartTime": 1717272000000,
  "recordingEndTime": 1717275600000,
  "tracks": [
    {
      "id": "uuid",
      "title": "Track title",
      "artist": "Artist",
      "imageUrl": "https://...",
      "trackUrl": "https://open.spotify.com/...",
      "order": 1,
      "playHistory": [
        {
          "startedAt": "2024-06-01T20:00:00Z",
          "endedAt": "2024-06-01T20:05:00Z"
        }
      ]
    }
  ]
}

Key fields for synchronization:

• recordingStartTime — timestamp (ms) of the recording start. Used as the time reference.
• playHistory[].startedAt / endedAt — ISO 8601 timestamps for each track appearance.

The widget computes each track's offset relative to recordingStartTime and maps it to the media player's currentTime.

Supported elements

| Element | Support | |---------|---------| | <video> | Native via timeupdate | | <audio> | Native via timeupdate | | <iframe> YouTube | Via YouTube IFrame Player API (loaded automatically) |

YouTube note: the enablejsapi=1 parameter is automatically added to the iframe URL if missing.

JavaScript API

For advanced usage, the widget exposes a programmatic API:

Global (UMD)

// Re-scan the DOM (useful for dynamically loaded content)
DLP.init()

// Access active instances
DLP.instances // DlpInstance[]

ESM

import { DlpInstance, SyncEngine, loadPlaylist } from 'dlp-player'

// Load and validate a playlist manually
const playlist = await loadPlaylist('/playlist.json')

// Create a sync engine
const sync = new SyncEngine(playlist)
const activeTrackIds = sync.getActiveTrackIds(currentTimeInSeconds)

CSS customization

Styles use the dlp- prefix and CSS custom properties for theming:

.dlp-wrapper {
  --dlp-bg: rgba(0, 0, 0, 0.85);
  --dlp-text-color: #ffffff;
  --dlp-title-size: 15px;
  --dlp-artist-size: 13px;
  --dlp-active-bg: rgba(59, 130, 246, 0.15);
  --dlp-active-border: #3b82f6;
  --dlp-image-size: 48px;
  --dlp-animation-duration: 500ms;
}

License

MIT