
Schnellstart
1. Einfache Audio-Wiedergabeliste (30 Sekunden)
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="vidply.css">
</head>
<body>
<div id="player"></div>
<script type="module">
import { Player, PlaylistManager } from 'vidply';
// 1. Create player
const player = new Player('#player');
// 2. Create playlist
const playlist = new PlaylistManager(player, {
autoAdvance: true,
showPanel: true
});
// 3. Load tracks
playlist.loadPlaylist([
{ src: 'song1.mp3', type: 'audio/mp3', title: 'Song 1', artist: 'Artist 1' },
{ src: 'song2.mp3', type: 'audio/mp3', title: 'Song 2', artist: 'Artist 2' },
{ src: 'song3.mp3', type: 'audio/mp3', title: 'Song 3', artist: 'Artist 3' }
]);
</script>
</body>
</html>
2. Vollständiges Minimalbeispiel
import { Player, PlaylistManager } from 'vidply';
const player = new Player('#player');
const playlist = new PlaylistManager(player);
playlist.loadPlaylist([
{ src: 'a.mp3', type: 'audio/mp3', title: 'Track A' },
{ src: 'b.mp3', type: 'audio/mp3', title: 'Track B' }
]);
Das war’s schon!
Funktionen
- Navigation zum vorherigen/nächsten Titel – Mit speziellen Tasten zwischen den Titeln wechseln
- Automatischer Weiterlauf – Der nächste Titel wird automatisch abgespielt, sobald ein Titel zu Ende ist
- Loop-Modus – Nach dem letzten Titel wird wieder beim ersten Titel angesetzt
- Anzeige der Titelinformationen – Zeigt die aktuelle Titelnummer, den Titel und den Interpreten an
- Visuelles Wiedergabelisten-Fenster – Interaktive Liste aller Titel mit Miniaturansichten und Umschaltknopf
- Hervorhebung des aktiven Titels – Visuelle Anzeige für den aktuell wiedergegebenen Titel
- Unterstützung gemischter Medien – Kombinieren Sie Audio- und Videodateien in einer einzigen Wiedergabeliste
- Lazy Loading – Mediendateien werden erst beim Abspielen geladen (konfigurierbar)
- Erweiterte Tastaturnavigation – Vollständige Tastaturunterstützung mit Pfeiltasten, Bild auf/ab, Pos1/Ende
- Unterstützung für Screenreader – ARIA-Labels, Live-Regionen und Ansagen von Begrenzungen
- WCAG-konform – Erfüllt die Barrierefreiheitsrichtlinien für Tastaturnavigation und Screenreader
- Benutzerdefinierte Spuren – Unterstützung für Untertitel, Kapitel und andere Textspuren pro Wiedergabelistenelement
Installation
Das PlaylistManager ist im VidPly-Paket enthalten:
import { Player, PlaylistManager } from 'vidply';
Konfigurationsoptionen
PlaylistManager-Optionen
{
autoAdvance: true, // Automatically play next track when current ends
autoPlayFirst: true, // Auto-play first track on load (if false: load/select first track, but do not start playback)
loop: false, // Loop back to first track after last
showPanel: true, // Show visual playlist panel
panelPosition: 'below' // 'below' (default) or 'right' — desktop side-by-side layout from 75rem; mobile always stacks below
}
Struktur des Track-Objekts
{
src: 'path/to/media.mp3', // Required: Media URL
type: 'audio/mp3', // Required: MIME type
title: 'Track Title', // Optional: Track title
artist: 'Artist Name', // Optional: Artist name
duration: 180, // Optional: Duration in seconds
poster: 'path/to/thumbnail.jpg', // Optional: Thumbnail image
downloadUrl: 'path/to/media.mp3', // Optional: File the download button offers for this track
downloadFormat: 'MP3', // Optional: Format for the download label (else inferred)
downloadFileSize: 7340032, // Optional: Size in bytes (else fetched via HEAD)
tracks: [ // Optional: Text tracks (captions, chapters)
{
src: 'captions.vtt',
kind: 'captions',
srclang: 'en',
label: 'English'
}
]
}
Downloads pro Titel
Die Download-Schaltfläche folgt der Wiedergabeliste: Sie wird downloadUrl bei den Titeln, die
heruntergeladen werden können, und die Schaltfläche bietet die Datei des ausgewählten Titels an, zeigt
das Format und die Größe dieser Datei an und verschwindet bei Titeln, für die keine
downloadUrl. Dies erfordert downloadButton: true in den Player-Optionen aktiviert werden – die
URL pro Titel entscheidet nur darüber, welche Datei angeboten wird, nicht darüber, ob die Schaltfläche
überhaupt vorhanden ist.
const player = new Player('#audio', { downloadButton: true });
player.playlistManager.loadPlaylist([
{
src: 'episode-1.m3u8',
type: 'application/x-mpegURL',
title: 'Episode 1',
// Streams are not downloadable — offer the progressive file instead
downloadUrl: 'episode-1.mp3',
downloadFileSize: 7340032
},
{ src: 'episode-2.mp3', type: 'audio/mpeg', title: 'Episode 2' } // no download
]);
Playlists, die downloadUrl bei keinem Titel aktiv ist, behalten das playerweite Ziel
(downloadUrl Option oder data-vidply-download-url) für jeden Titel bei.
API-Methoden
loadPlaylist(items)
Lädt ein Array von Titelelementen in die Wiedergabeliste.
- Wenn
autoPlayFirst: true(Standard): Der erste Titel wird abgespielt. - Wenn
autoPlayFirst: false: Der erste Titel wird ausgewählt und geladen (damit Poster/Benutzeroberfläche/Funktionen initialisiert werden können), die Wiedergabe wird jedoch nicht gestartet.
playlist.loadPlaylist([
{ src: 'track1.mp3', type: 'audio/mp3', title: 'Track 1' },
{ src: 'track2.mp3', type: 'audio/mp3', title: 'Track 2' }
]);
Parameter:
items(Array): Array von Titelobjekten (siehe „Struktur eines Titelobjekts“ oben)
addItem(item)
Fügt einen einzelnen Titel zur Wiedergabeliste hinzu.
playlist.addItem({
src: 'track3.mp3',
type: 'audio/mp3',
title: 'Track 3'
});
Parameter:
item(Objekt): Titelobjekt (siehe „Struktur eines Titelobjekts“ oben)
play(index)
Einen bestimmten Titel anhand seines Index (ab 0) abspielen.
playlist.play(2); // Play third track (0-based index)
Parameter:
index(Zahl): Null-basierter Index des abzuspielenden Tracks
next()
Den nächsten Titel abspielen.
playlist.next();
previous()
Den vorherigen Titel abspielen.
playlist.previous();
hasNext()
Prüft, ob ein nächster Titel vorhanden ist.
if (playlist.hasNext()) {
playlist.next();
}
hasPrevious()
Prüft, ob es einen vorherigen Titel gibt.
if (playlist.hasPrevious()) {
playlist.previous();
}
getCurrentTrack()
Ruft das Objekt des aktuellen Titels ab.
const track = playlist.getCurrentTrack();
console.log(track.title);
togglePanel()
Blendet das Wiedergabelisten-Panel ein oder aus.
playlist.togglePanel();
Beispiele für die programmatische Steuerung
// Navigate
playlist.next(); // Go to next track
playlist.previous(); // Go to previous track
playlist.play(2); // Play track at index 2
// Check state
if (playlist.hasNext()) {
console.log('Has next track');
}
// Get current
const track = playlist.getCurrentTrack();
console.log(track.title);
// Listen to changes
player.on('playlisttrackchange', (e) => {
console.log('Now playing:', e.item.title);
});
Ereignisse
Abhören von Playlist-Ereignissen über den Player:
// Track change event
player.on('playlisttrackchange', (e) => {
console.log('Now playing:', e.item.title);
console.log('Track index:', e.index);
});
Beispiele
Wiedergabeliste mit Untertiteln
const tracks = [
{
src: 'song.mp3',
type: 'audio/mp3',
title: 'My Song',
artist: 'My Artist',
tracks: [
{ src: 'captions-en.vtt', kind: 'captions', srclang: 'en', label: 'English' },
{ src: 'captions-es.vtt', kind: 'captions', srclang: 'es', label: 'Español' }
]
}
];
playlist.loadPlaylist(tracks);
Dynamische Wiedergabeliste
// Start with empty playlist
const playlist = new PlaylistManager(player);
// Add tracks dynamically
playlist.addItem({
src: 'new-song.mp3',
type: 'audio/mp3',
title: 'New Song'
});
// Or reload entire playlist
playlist.loadPlaylist(newTracksArray);
Video-Playlist
// Create video player (note: mediaType: 'video')
const player = new Player('#video-player', {
mediaType: 'video'
});
const playlist = new PlaylistManager(player, {
autoAdvance: true,
showPanel: true
});
const videoTracks = [
{
src: 'video1.mp4',
type: 'video/mp4',
title: 'Episode 1',
poster: 'thumbnail1.jpg',
tracks: [
{ src: 'video1-captions.vtt', kind: 'captions', srclang: 'en', label: 'English' },
{ src: 'video1-chapters.vtt', kind: 'chapters', srclang: 'en', label: 'Chapters' }
]
},
{
src: 'video2.mp4',
type: 'video/mp4',
title: 'Episode 2',
poster: 'thumbnail2.jpg'
}
];
playlist.loadPlaylist(videoTracks);
Playlist-Fenster ausblenden
// Create without panel
const playlist = new PlaylistManager(player, {
showPanel: false
});
// Or toggle it
playlist.togglePanel();
Vollständiges Beispiel mit allen Funktionen
import { Player, PlaylistManager } from 'vidply';
// Create player
const player = new Player('#audio-player', {
autoplay: false,
controls: true,
preload: 'metadata'
});
// Create playlist
const playlist = new PlaylistManager(player, {
autoAdvance: true,
loop: false,
showPanel: true
});
// Load tracks with captions and chapters
const tracks = [
{
src: 'media/song1.mp3',
type: 'audio/mp3',
title: 'Summer Vibes',
artist: 'The Acoustic Project',
duration: 245,
poster: 'media/album-art-1.jpg',
tracks: [
{
src: 'media/song1-captions-en.vtt',
kind: 'captions',
srclang: 'en',
label: 'English'
},
{
src: 'media/song1-chapters.vtt',
kind: 'chapters',
srclang: 'en',
label: 'Chapters'
}
]
},
{
src: 'media/song2.mp3',
type: 'audio/mp3',
title: 'Midnight Jazz',
artist: 'Blue Note Ensemble',
duration: 198,
poster: 'media/album-art-2.jpg'
}
];
playlist.loadPlaylist(tracks);
// Listen for track changes
player.on('playlisttrackchange', (e) => {
console.log(`Now playing: ${e.item.title} by ${e.item.artist}`);
// Optional: Update document title
document.title = `${e.item.title} - ${e.item.artist}`;
// Optional: Update media session API
if ('mediaSession' in navigator) {
navigator.mediaSession.metadata = new MediaMetadata({
title: e.item.title,
artist: e.item.artist,
artwork: [{ src: e.item.poster }]
});
}
});
// Optional: Add keyboard shortcuts
document.addEventListener('keydown', (e) => {
if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') {
return; // Don't interfere with form inputs
}
switch(e.key) {
case 'ArrowLeft':
if (e.shiftKey) {
playlist.previous();
e.preventDefault();
}
break;
case 'ArrowRight':
if (e.shiftKey) {
playlist.next();
e.preventDefault();
}
break;
case 'p':
playlist.togglePanel();
break;
}
});
Verhalten im Vollbildmodus
Im Vollbildmodus verwandelt sich die Wiedergabeliste in ein horizontales, wischbares Karussell (ähnlich wie bei YouTube):
- Automatisches Ein- und Ausblenden: Wird angezeigt, wenn die Wiedergabe angehalten oder noch nicht gestartet wurde; wird während der Wiedergabe ausgeblendet
- Horizontales Layout: Karten werden nebeneinander mit Scroll-Snap-Navigation angezeigt
- Responsive: Auf dem Desktop werden vollständige Karten (280px) mit Miniaturansicht, Titel und Interpret angezeigt
- Mobil: Kompakte Ansicht mit reinen Miniaturansichten im Hochformat (<768px), Text wird angezeigt, wenn keine Miniaturansicht vorhanden ist
- Touch-freundlich: Wischbar mit flüssigem horizontalen Scrollen
- Position: Liegt über den Steuerelementen mit halbtransparentem Hintergrund
- Barrierefreiheit: Menüs werden dynamisch auf die Containerebene verschoben, sodass sie über der Wiedergabeliste erscheinen
Alle Menüs (Kapitel, Qualität, Untertitel usw.) bleiben im Vollbildmodus durch dynamische DOM-Neupositionierung zugänglich, wodurch die WCAG-Konformität gewahrt bleibt.
UI-Komponenten
Anzeige der Titelinformationen
Wird über den Steuerelementen angezeigt und enthält:
- Titelnummer (z. B. „3 / 10“)
- Titel des Titels
- Name des Interpreten (falls angegeben)
Wiedergabelistenbereich
Eine scrollbare Liste, in der alle Titel angezeigt werden. Standardmäßig befindet sich das Feld unterhalb des Players; mit panelPosition: 'right' (oder data-playlist-panel-position="right") befinden sich der Player und die Steuerelemente in der linken Spalte, während die Wiedergabeliste ab einer Viewport-Breite von 75rem die rechte Spalte einnimmt. Bei schmaleren Viewports wird die Liste immer unterhalb des Players gestapelt.
Jedes Feld zeigt Folgendes an:
- Miniaturansichten der Titel (sofern vorhanden)
- Titelnummern
- Titelnamen und Interpreten
- Titel-Dauer (sofern vorhanden)
- Anzeige des aktuellen Titels
Navigationsschaltflächen
Wenn eine Wiedergabeliste aktiv ist:
- Zurück-Taste – Ersetzt die Rückspultaste
- Schaltfläche „Weiter“ – Ersetzt die Schaltfläche „Vorwärts“
- Die Schaltflächen sind an den Grenzen der Wiedergabeliste deaktiviert (es sei denn, die Wiederholungsfunktion ist aktiviert)
Gestaltung
Passen Sie das Erscheinungsbild der Wiedergabeliste mit CSS an:
/* Track info display */
.vidply-track-info {
background: your-gradient;
padding: 20px;
}
.vidply-track-title {
font-size: 18px;
color: #fff;
}
.vidply-track-artist {
color: rgba(255, 255, 255, 0.8);
}
/* Playlist panel */
.vidply-playlist-panel {
background: rgba(20, 20, 30, 0.95);
max-height: 400px;
}
.vidply-playlist-item-active {
background: rgba(59, 130, 246, 0.2);
border-left-color: #3b82f6;
}
/* Custom hover effects */
.vidply-playlist-item:hover {
background: rgba(255, 255, 255, 0.1);
}
/* Active playlist item */
.vidply-playlist-item-active {
background: linear-gradient(90deg, #667eea, #764ba2);
border-left-color: #fff;
}
Tastaturnavigation und Barrierefreiheit
Integrierte Wiedergabelisten-Navigation
Das Wiedergabelisten-Fenster bietet umfassende Unterstützung für die Tastaturnavigation:
- ↑ Pfeil nach oben – Zum vorherigen Titel in der Liste springen
- ↓ Pfeil nach unten – Zum nächsten Titel in der Liste springen
- Bild auf – 5 Titel nach oben springen
- Bild nach unten – 5 Titel nach unten springen
- Home – Zum ersten Titel springen
- Ende – Zum letzten Titel springen
- Enter / Leertaste – Den ausgewählten Titel abspielen
- Tab – Zum Wiedergabelistenbereich navigieren und zwischen Titeln wechseln (roving Tabindex-Muster)
Schaltfläche zum Ein- und Ausschalten der Wiedergabeliste
Wenn PlaylistManager aktiv ist, blendet eine Umschaltfläche in der rechten Steuerleiste (mit Beschriftungen, Einstellungen, Vollbild) den Wiedergabelistenbereich ein oder aus. Bei schmalen Ansichtsfenstern wird die Umschaltfläche möglicherweise in das Überlaufmenü verschoben, während die Steuerelemente für die Wiedergabe sichtbar bleiben.
Die Schaltfläche unterstützt die Tastaturbedienung (Tab, Enter) und stellt aria-expanded, aria-pressedsowie aria-controls für Screenreader bereit.
Unterstützung für Bildschirmleseprogramme
Die Wiedergabeliste bietet umfassende Unterstützung für Bildschirmleseprogramme:
- Ansagen zum aktuellen Bereich während der Navigation (z. B. „Ende der Wiedergabeliste. 5 von 5.“)
- Ansagen zu Begrenzungen (Anfang/Ende der Wiedergabeliste)
- Ansagen zur Titelposition (z. B. „Titel 3 von 10“)
- Statusansagen (wird gerade abgespielt, wird nicht abgespielt)
- Beschreibende Bezeichnungen für alle interaktiven Elemente
Globale Tastaturkürzel (optional)
Sie können globale Tastaturkürzel für die Navigation in der Wiedergabeliste hinzufügen:
document.addEventListener('keydown', (e) => {
// Don't interfere with form inputs
if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') {
return;
}
if (e.key === 'ArrowRight' && e.shiftKey) {
playlist.next();
e.preventDefault();
}
if (e.key === 'ArrowLeft' && e.shiftKey) {
playlist.previous();
e.preventDefault();
}
});
Methoden zur Barrierefreiheit
// Toggle playlist panel visibility
playlist.togglePanel();
// Show playlist panel
playlist.showPanel();
// Hide playlist panel
playlist.hidePanel();
// Check if panel is visible
const isVisible = playlist.isPanelVisible;
Häufige Anwendungsfälle
Musik-Player
const musicPlayer = new PlaylistManager(player, {
autoAdvance: true,
loop: true,
showPanel: true
});
Ideal für:
- Albumwiedergabe
- Diskografie eines Künstlers
- Musikkompilationen
Podcast-Playlist
const podcast = new PlaylistManager(player, {
autoAdvance: false, // Manual navigation
loop: false,
showPanel: true
});
Ideal für:
- Podcast-Reihen
- Episodensammlungen
- Interview-Playlists
Videoserien (im Netflix-Stil)
const series = new PlaylistManager(player, {
autoAdvance: true, // Binge watching
loop: false,
showPanel: true
});
Ideal für:
- Episoden von Fernsehserien
- Videokurse
- Tutorial-Reihen
- Konferenzvorträge
Streaming-Playlist (HLS & DASH)
playlist.loadPlaylist([
{ src: 'https://example.com/video1/manifest.mpd', title: 'DASH Stream' },
{ src: 'https://example.com/video2/master.m3u8', title: 'HLS Stream' },
{ src: 'fallback.mp4', type: 'video/mp4', title: 'MP4 Fallback' }
]);
VidPly erkennt den Renderer für jedes Element der Wiedergabeliste automatisch anhand der Dateiendung der Quell-URL (.mpd bei DASH, .m3u8 für HLS usw.).
Mixed-Media-Wiedergabeliste
const mixedPlaylist = new PlaylistManager(player, {
autoAdvance: true,
showPanel: true
});
mixedPlaylist.loadPlaylist([
{ src: 'intro.mp4', type: 'video/mp4', title: 'Introduction Video' },
{ src: 'episode1.mp3', type: 'audio/mp3', title: 'Episode 1 Audio' },
{ src: 'episode2.mp4', type: 'video/mp4', title: 'Episode 2 Video' },
{ src: 'bonus.mp3', type: 'audio/mp3', title: 'Bonus Content' }
]);
Ideal für:
- Kurse mit gemischten Inhalten (Videovorträge + Audio-Ergänzungen)
- Multimedia-Präsentationen
- Inhalte mit Video- und Audio-Episoden
- Bildungsinhalte, die verschiedene Medienarten kombinieren
Hörbuchkapitel
const audiobook = new PlaylistManager(player, {
autoAdvance: true,
loop: false,
showPanel: true
});
Ideal für:
- Kapitelnavigation
- Mehrteilige Geschichten
- Lerninhalte im Audioformat
Bewährte Vorgehensweisen
- Vermeiden Sie vorzeitiges Laden von Netzwerkdaten: Verwenden Sie
deferLoad: true(und optionalpreload: 'none'), um zu verhindern, dass Downloads bereits während der Initialisierung gestartet werden - Metadaten vorab laden: Setze
preload: 'metadata'ein, um die Titellängen zu laden, ohne die vollständigen Dateien herunterzuladen - Miniaturansichten bereitstellen: Fügen Sie Posterbilder für eine bessere visuelle Darstellung hinzu
- Dauer einbeziehen: Berechne die Laufzeiten im Voraus für eine bessere Benutzererfahrung
- Konsistente Benennung verwenden: Halten Sie die Eigenschaften der Titelobjekte in Ihrer gesamten Wiedergabeliste konsistent
- Ladezustände verarbeiten: Auf
loadstartundcanplayEreignisse für Ladeanzeigen abhören - Barrierefreiheit: Stellen Sie sicher, dass Titelnamen und Interpretenangaben für Screenreader aussagekräftig sind
Fehlerbehebung
Titel werden nicht automatisch weitergeschaltet
Stellen Sie sicher, autoAdvance: true in den Wiedergabelistenoptionen gesetzt ist und das Medienelement das ended Ereignis auslöst.
Schaltflächen „Zurück“/„Weiter“ werden nicht angezeigt
Die Schaltflächen werden nur angezeigt, wenn eine PlaylistManager Instanz an den Player angehängt ist. Stellen Sie sicher, dass Sie den Wiedergabelisten-Manager erstellen, bevor die Steuerelemente gerendert werden, oder rufen Sie player.renderControls() erst nach dem Erstellen des Wiedergabelisten-Managers auf.
Playlist-Panel nicht sichtbar
Überprüfen Sie, ob showPanel: true in den Wiedergabelistenoptionen eingestellt ist. Das Panel wird im DOM hinter dem Player-Element eingefügt.
Untertitel wechseln nicht zwischen den Titeln
Stellen Sie sicher, dass das tracks Array in jedem Wiedergabelistenelement enthalten ist, das Untertitel enthält. Die Titel werden beim Wechseln zwischen den Wiedergabelistenelementen neu geladen.
Browser-Unterstützung
Die Wiedergabelistenfunktion funktioniert in allen modernen Browsern, die Folgendes unterstützen:
- ES6-Module
- HTML5-Medienelemente
- WebVTT (für Untertitel/Kapitel)
Getestet in:
- Chrome/Edge 90+
- Firefox 88+
- Safari 14+
- Opera 76+
Demos
Sehen Sie sich die vollständigen Demos an:
- Audio-Playlist: demo/playlist-audio.html
- Video-Playlist: demo/playlist-video.html
- Mixed-Media-Playlist: demo/playlist-mixed.html
Implementierungsdetails
Hinzugefügte Dateien
src/features/PlaylistManager.js- Kernfunktionalität der Wiedergabelistedemo/playlist-audio.html- Funktionierende Audio-Playlist-Demo mit 5 Titelndemo/playlist-video.html- Funktionierende Demo einer Video-Playlist mit 3 Videos
Geänderte Dateien
src/controls/ControlBar.js- Schaltflächen „Zurück“ und „Weiter“ hinzugefügtsrc/styles/vidply.css- Playlist-Stile hinzugefügtsrc/index.js- PlaylistManager exportiertdemo/demo.html- Links zu den Playlist-Demos hinzugefügt
Erstellt mit Vanilla JavaScript