Benutzerhandbuch: VidPly Player

Kurzer Überblick

VidPly ist ein universeller, barrierefreier Mediaplayer, der Folgendes unterstützt:

Installation

1. Erstellen Sie den Player

npm install
npm run build

Dadurch werden Dateien im dist/:

• prod/vidply.esm.min.js - ES-Modul (empfohlen)
• legacy/vidply.min.js - IIFE für Skript-Tag (global VidPly)
• vidply.min.css - Styles

2. In Ihre Seite einbinden

ES-Modul (empfohlen):

<link rel="stylesheet" href="dist/vidply.min.css">
<script type="module">
  import Player from './dist/prod/vidply.esm.min.js';
</script>

Herkömmliches Script-Tag:

<link rel="stylesheet" href="dist/vidply.min.css">
<script src="dist/legacy/vidply.min.js"></script>

Grundlegende Verwendung

Videoplayer

<video data-vidply width="800" height="450">
  <source src="video.mp4" type="video/mp4">
  <source src="video.webm" type="video/webm">
</video>

Das data-vidply Attribut initialisiert den Player automatisch.

Audio-Player

<audio data-vidply>
  <source src="audio.mp3" type="audio/mpeg">
  <source src="audio.ogg" type="audio/ogg">
</audio>

Mit Posterbild

<video data-vidply poster="thumbnail.jpg" width="800" height="450">
  <source src="video.mp4" type="video/mp4">
</video>

Externe Dienste

YouTube

<video data-vidply src="https://www.youtube.com/watch?v=VIDEO_ID"></video>

Oder mit vollständiger URL:

<video data-vidply src="https://youtu.be/VIDEO_ID"></video>

Vimeo

<video data-vidply src="https://vimeo.com/VIDEO_ID"></video>

SoundCloud

<audio data-vidply src="https://soundcloud.com/artist/track-name"></audio>

Die SoundCloud-Widget-API wird automatisch für jede URL erkannt, die soundcloud.com. Das Widget wird bei Bedarf geladen und lässt sich in die Standard-VidPly-Steuerelemente für Wiedergabe, Pause, Suche und Lautstärke integrieren.

Bei Verwendung mpc-vidply in TYPO3 zeigt die Datenschutzebene ein DSGVO-Einwilligungs-Overlay an, bevor der SoundCloud-Iframe geladen wird – Besucher müssen zunächst dem Laden externer Inhalte zustimmen.

HLS-Streaming

<video data-vidply src="https://example.com/stream.m3u8"></video>

hls.js wird automatisch vom CDN geladen, sobald .m3u8 URLs erkannt werden. Verhalten je nach Plattform:

 

Selbst auf iOS, wo hls.js nicht ausgeführt werden kann (kein MSE), bindet VidPly das Untertitelmenü, das interaktive Transkript und das Qualitätsmenü dennoch in die nativen HLS-Textspuren des Browsers ein – Sie verlieren keine UI-Steuerelemente.

 

DASH-Streaming

<video data-vidply src="https://example.com/manifest.mpd"></video>

dash.js wird automatisch vom CDN geladen, sobald .mpd URLs erkannt werden. DASH-Streams unterstützen:

• Auswahl der adaptiven Bitrate
• TTML-Untertitel (nativ von dash.js gerendert)
• WebVTT-Untertitel (verarbeitet durch das Untertitel-System von VidPly mit Transkript-Unterstützung)

DASH + HLS + MP4-Fallback

<video data-vidply width="800" height="450">
  <source src="dash/manifest.mpd" type="application/dash+xml">
  <source src="hls/master.m3u8" type="application/x-mpegURL">
  <source src="fallback.mp4" type="video/mp4">
  <track kind="subtitles" src="subtitles.en.vtt" srclang="en" label="English">
</video>

Hinzufügen von Untertiteln

Einfache Untertitel

<video data-vidply width="800" height="450">
  <source src="video.mp4" type="video/mp4">
  <track kind="subtitles" src="captions-en.vtt" srclang="en" label="English">
  <track kind="subtitles" src="captions-de.vtt" srclang="de" label="Deutsch">
</video>

Spurtypen

Standardmäßig Untertitel ein

<track kind="subtitles" src="captions.vtt" srclang="en" label="English" default>

Kapitel

Kapitelnavigation mit einer Kapitelspur hinzufügen:

<video data-vidply>
  <source src="video.mp4" type="video/mp4">
  <track kind="chapters" src="chapters.vtt" srclang="en">
</video>

chapters.vtt:

WEBVTT

00:00:00.000 --> 00:02:30.000
Introduction

00:02:30.000 --> 00:08:00.000
Main Topic

00:08:00.000 --> 00:12:00.000
Examples

00:12:00.000 --> 00:15:00.000
Conclusion

Konfigurationsoptionen

Über Datenattribute

<video 
  data-vidply
  data-vidply-autoplay="false"
  data-vidply-loop="false"
  data-vidply-muted="false"
  data-vidply-volume="0.8"
  data-vidply-language="en"
  data-vidply-keyboard="true"
  data-vidply-responsive="true"
  src="video.mp4">
</video>

Über JavaScript

const player = new Player('#my-video', {
  // Display
  width: 800,
  height: 450,
  poster: 'poster.jpg',
  responsive: true,
  
  // Playback
  autoplay: false,
  loop: false,
  muted: false,
  volume: 0.8,
  playbackSpeed: 1.0,
  
  // Controls
  controls: true,
  hideControlsDelay: 3000,
  
  // Buttons (show/hide individual controls)
  playPauseButton: true,
  progressBar: true,
  volumeControl: true,
  speedButton: true,
  captionsButton: true,
  fullscreenButton: true,
  pipButton: true,
  downloadButton: false,        // Show a download button in the control bar
  downloadUrl: null,            // Optional explicit download URL (defaults to current src)

  // Custom Floating Player (in-page miniplayer / "own PiP")
  floating: false,                          // Enable the custom floating player; also disables native browser PiP
  floatingPosition: 'bottom-right',         // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  floatingMinViewportWidth: 768,            // Floating feature is hidden below this viewport width (px)

  // Language
  language: 'en',
  
  // Keyboard
  keyboard: true,
  
  // Accessibility
  screenReaderAnnouncements: true,
  focusHighlight: true
});

Referenz aller Optionen

Download-Schaltfläche

Zeigt eine optionale Download-Schaltfläche in der Steuerleiste an:

<video
  data-vidply
  data-vidply-download-button="true"
  data-vidply-download-url="/files/lecture.mp4"
  src="/streams/lecture/manifest.mpd">
</video>

const player = new Player('#video', {
  downloadButton: true,
  downloadUrl: '/files/lecture.mp4' // optional; falls back to current src
});

Die Schaltfläche ist über die Tastatur bedienbar, vollständig internationalisiert (player.download Übersetzungsschlüssel) und verwendet aria-label , sodass Screenreader ihn korrekt ansagen.

 

Hinweis für Streaming-Quellen: downloadUrl ist normalerweise die URL eines MP4/MP3-Fallbacks, da Nutzer in der Regel keine .mpd oder .m3u8 Manifest nicht als einzelne Datei herunterladen können.

 

Benutzerdefinierter schwebender Player (Miniplayer)

VidPly enthält einen optionalen, seiteninternen Floating-Player („eigenes PiP“), der in einer konfigurierbaren Ecke des Ansichtsbereichs erscheint, verschoben und in der Größe angepasst werden kann und VidPlys eigene Untertitelanzeige, Transportsteuerung und Vollbildfunktion innerhalb der Floating-Shell beibehält.

Solange floating aktiviert ist, wird die native Picture-in-Picture-API des Browsers automatisch unterdrückt (disablepictureinpicture + disableremoteplayback), sodass der Benutzer eine einheitliche Benutzererfahrung über alle Browser hinweg erhält.

Verhalten

• Automatisches Anzeigen beim Herausscrollen – Wenn der ursprüngliche Player aus dem Viewport herausgescrollt wird, erscheint das Video in der schwebenden Hülle. Wenn er wieder hineingescrollt wird, dockt das Video wieder an seinen ursprünglichen Container an.
• Manuelles Anheften/Lösen – Die PiP-Schaltfläche in der Steuerleiste heftet die schwebende Hülle manuell an. Das manuelle Anheften/Lösen überschreibt das scrollbasierte automatische Schweben bis zum nächsten vom Benutzer ausgelösten play.
• Schließen-Schaltfläche – Die X-Schaltfläche in der schwebenden Hülle pausiert das Video, kehrt es in seinen ursprünglichen Container zurück und unterdrückt das automatische Schweben für den Rest der Wiedergabesitzung.
• Ziehen & Größe ändern – Die schwebende Hülle kann an der Kopfzeile gezogen und über die Eck-/Randgriffe in der Größe angepasst werden. Die Geometrie wird pro Player über den lokalen Speicher beibehalten.
• Reduzierte Steuerleiste – Innerhalb der schwebenden Hülle werden nur die wesentlichen Steuerelemente angezeigt: Wiedergabe/Pause, Zurückspulen, Vorspulen, Lautstärke, Untertitel, PiP und Vollbild. Tooltips öffnen sich über den Schaltflächen; die Größe der Untertitel ist 90% und auf 95% Breite begrenzt.
• Audio-Player werden übersprungen – Die Floating-Funktion gilt nur für <video> Player.
• Standardmäßig nur auf dem Desktop – Unterhalb floatingMinViewportWidth (Standard 768 px) ist die Funktion deaktiviert und die schwebende PiP-Schaltfläche wird in der Hauptsteuerleiste ausgeblendet (sie gelangt nie in das Überlaufmenü).

Aktivierung über HTML (data-vidply-options JSON)

Die Floating-Optionen werden über den data-vidply-options JSON-Blob (die gleichen Kanäle wie TYPO3 / mpc_vidply verwendet):

<video
  data-vidply
  data-vidply-options='{"floating": true, "floatingPosition": "bottom-right", "floatingMinViewportWidth": 768}'
  src="video.mp4"
  width="800" height="450">
  <track kind="subtitles" src="captions.vtt" srclang="en" label="English">
</video>

Aktivierung über JavaScript

const player = new Player('#video', {
  floating: true,
  floatingPosition: 'bottom-right', // or 'bottom-left' | 'top-right' | 'top-left'
  floatingMinViewportWidth: 768
});

Barrierefreiheit

• Die schwebende Shell wird als role="dialog" mit einem übersetzten aria-label (player.floatingPlayerDialog).
• Der PiP-Schalter verwendet aria-pressed , um den angehefteten Status anzuzeigen.
• Der Fokus kehrt zur ursprünglichen Schaltfläche zurück, wenn die schwebende Schale über die Tastatur geschlossen wird.
• Alle integrierten Sprachen (en, de, es, fr, ja) enthalten Übersetzungen für player.floatingPlayer, player.floatingPlayerClose, player.floatingPlayerEnter, player.floatingPlayerExit und player.floatingPlayerDialog.

Pufferungs-Spinner

Ein zentrierter Ladespinner erscheint automatisch, während die Medien gepuffert werden (waiting / seeking / initial loadstart) und verschwindet bei canplay / playing. Er funktioniert für HTML5-, HLS- und DASH-Renderer und berücksichtigt prefers-reduced-motion.

Sie können das Design über CSS-Variablen anpassen:

.vidply-player {
  --vidply-spinner-color: #ffffff;
  --vidply-spinner-size: 56px;
  --vidply-z-buffering: 1; /* sits below the play overlay */
}

Der Container stellt während des Ladens eine .vidply-buffering Klasse, die du zum Stylen oder Einbinden nutzen kannst:

.vidply-player.vidply-buffering .my-skin-overlay {
  opacity: 0.3;
}

Wiedergabelisten

Audio-Wiedergabeliste

<div id="audio-player"></div>

<script type="module">
  import { Player, PlaylistManager } from './dist/prod/vidply.esm.min.js';
  
  // When you pass a non-media element, VidPly will create the media element for you.
  const player = new Player('#audio-player', { mediaType: 'audio' });
  const playlist = new PlaylistManager(player, {
    autoAdvance: true,
    loop: false,
    showPanel: true
  });
  
  playlist.loadPlaylist([
    {
      src: 'track1.mp3',
      title: 'Track 1',
      artist: 'Artist Name',
      poster: 'cover1.jpg'
    },
    {
      src: 'track2.mp3',
      title: 'Track 2',
      artist: 'Artist Name',
      poster: 'cover2.jpg'
    }
  ]);
</script>

Video-Playlist

<div id="video-player"></div>

<script type="module">
  import { Player, PlaylistManager } from './dist/prod/vidply.esm.min.js';
  
  const player = new Player('#video-player');
  const playlist = new PlaylistManager(player, {
    autoAdvance: true,
    showPanel: true
  });
  
  playlist.loadPlaylist([
    {
      src: 'video1.mp4',
      title: 'Video 1',
      poster: 'thumb1.jpg',
      tracks: [
        { src: 'captions1.vtt', kind: 'captions', srclang: 'en', label: 'English' }
      ]
    },
    {
      src: 'video2.mp4',
      title: 'Video 2',
      poster: 'thumb2.jpg'
    }
  ]);
</script>

Wiedergabelisten-Optionen

Wiedergabelisten-Steuerelemente

playlist.next()           // Next track
playlist.previous()       // Previous track
playlist.goToTrack(2)     // Jump to track index
playlist.hasNext()        // Check if next exists
playlist.hasPrevious()    // Check if previous exists

Barrierefreiheitsfunktionen

Audiodeskription

Stellen Sie ein alternatives Video mit Audiobeschreibungen bereit:

const player = new Player('#my-video', {
  audioDescription: true,
  audioDescriptionSrc: 'video-with-description.mp4'
});

Benutzer können über die AD-Schaltfläche umschalten.

Gebärdensprache

Überlagerung mit Gebärdensprachdolmetschung hinzufügen:

const player = new Player('#my-video', {
  signLanguage: true,
  signLanguageSrc: 'sign-language.mp4',
  signLanguagePosition: 'bottom-right'
});

Positionierungsoptionen: bottom-right, bottom-left, top-right, top-left

Interaktive Transkripte

const player = new Player('#my-video', {
  transcript: true,
  transcriptPosition: 'external',
  transcriptContainer: '#transcript-panel'
});

Funktionen:

• Klicken Sie auf eine beliebige Zeile, um zu dieser Stelle zu springen
• Automatischer Bildlauf während der Wiedergabe
• Durchsuchbarer Text
• Fenster kann verschoben und in der Größe angepasst werden

Tastaturkürzel

VidPly bietet umfassende Tastatursteuerung:

Benutzerdefinierte Tastaturkürzel

const player = new Player('#my-video', {
  keyboardShortcuts: {
    'play-pause': [' ', 'p', 'k'],
    'seek-forward': ['ArrowRight', 'l'],
    'seek-backward': ['ArrowLeft', 'j'],
    'volume-up': ['ArrowUp'],
    'volume-down': ['ArrowDown'],
    'mute': ['m'],
    'fullscreen': ['f'],
    'captions': ['c']
  }
});

Gestaltung & Themen

CSS-Variablen

.vidply-player {
  /* Colors */
  --vidply-primary-color: #3b82f6;
  --vidply-background: rgba(0, 0, 0, 0.8);
  --vidply-text-color: #ffffff;
  
  /* Sizing */
  --vidply-button-size: 40px;
  --vidply-icon-size: 20px;
  
  /* Spacing */
  --vidply-gap-sm: 4px;
  --vidply-gap-md: 8px;
  --vidply-gap-lg: 12px;
  
  /* Border radius */
  --vidply-radius-sm: 4px;
  --vidply-radius-md: 8px;
  --vidply-radius-lg: 12px;
  
  /* Transitions */
  --vidply-transition-fast: 150ms;
  --vidply-transition-normal: 300ms;
}

Benutzerdefinierte Fortschrittsanzeige

.vidply-progress-played {
  background: linear-gradient(90deg, #667eea, #764ba2);
}

Benutzerdefinierte Schaltflächen

.vidply-button:hover {
  background: rgba(59, 130, 246, 0.2);
}

.vidply-button:focus {
  outline: 2px solid var(--vidply-primary-color);
  outline-offset: 2px;
}

Internationalisierung

Integrierte Sprachen

• Englisch (en)
• Spanisch (es) – Español
• Französisch (fr) – Français
• Deutsch (de) - Deutsch
• Japanisch (ja) – 日本語

Sprache einstellen

const player = new Player('#my-video', {
  language: 'de'  // German
});

Automatisch aus HTML erkennen

<html lang="de">
  <!-- Player auto-detects German -->
</html>

Benutzerdefinierte Sprache laden

Über Datenattribut:

<video 
  data-vidply 
  data-vidply-language-files='{"pt": "languages/pt.json"}'
  src="video.mp4">
</video>

Über JavaScript (Optionen):

import Player from './dist/prod/vidply.esm.min.js';

const player = new Player('#my-video', {
  language: 'pt',
  languageFiles: { pt: 'languages/pt.json' }
});

Sprachdateiformat

languages/pt.json:

{
  "player": {
    "play": "Reproduzir",
    "pause": "Pausar",
    "mute": "Silenciar",
    "unmute": "Ativar som",
    "fullscreen": "Tela cheia",
    "captions": "Legendas",
    "settings": "Configurações"
  },
  "time": {
    "currentTime": "Tempo atual",
    "duration": "Duração"
  }
}

API-Referenz

Wiedergabe

player.play()              // Start playback
player.pause()             // Pause playback
player.stop()              // Stop and reset
player.toggle()            // Toggle play/pause
player.seek(30)            // Seek to 30 seconds
player.seekForward(10)     // Skip forward 10s
player.seekBackward(10)    // Skip backward 10s

Lautstärke

player.setVolume(0.5)      // Set volume (0-1)
player.getVolume()         // Get volume
player.mute()              // Mute
player.unmute()            // Unmute
player.toggleMute()        // Toggle mute

Geschwindigkeit

player.setPlaybackSpeed(1.5)   // Set speed (0.25-2.0)
player.getPlaybackSpeed()      // Get speed

Vollbild

player.enterFullscreen()   // Enter fullscreen
player.exitFullscreen()    // Exit fullscreen
player.toggleFullscreen()  // Toggle fullscreen

Untertitel

player.enableCaptions()    // Enable captions
player.disableCaptions()   // Disable captions
player.toggleCaptions()    // Toggle captions

Status

player.getCurrentTime()    // Current time in seconds
player.getDuration()       // Total duration
player.isPlaying()         // Is playing?
player.isPaused()          // Is paused?
player.isEnded()           // Has ended?
player.isMuted()           // Is muted?
player.isFullscreen()      // Is fullscreen?

Ereignisse

player.on('ready', () => {})
player.on('play', () => {})
player.on('pause', () => {})
player.on('ended', () => {})
player.on('timeupdate', (time) => {})
player.on('volumechange', (volume) => {})
player.on('fullscreenchange', (isFullscreen) => {})
player.on('captionsenabled', (track) => {})
player.on('error', (error) => {})

Bereinigung

player.destroy()           // Remove player

Browser-Unterstützung

Fehlerbehebung

Video wird nicht abgespielt

Untertitel werden nicht angezeigt

YouTube/Vimeo funktioniert nicht

HLS wird nicht abgespielt

DASH wird nicht abgespielt

Bewährte Verfahren

Leistung

• ✅ Verwenden Sie responsive: true für flüssige Layouts
• ✅ Stellen Sie Posterbilder bereit
• ✅ Verwenden Sie geeignete Videoauflösungen
• ✅ Videos für die Bereitstellung im Web komprimieren

Barrierefreiheit

• ✅ Immer Untertitel bereitstellen
• ✅ Verwenden Sie aussagekräftige Titel
• ✅ Nur mit der Tastatur testen
• ✅ Mit Screenreadern testen

Browserübergreifend

• ✅ Stellen Sie MP4- und WebM-Quellen bereit
• ✅ Auf Mobilgeräten testen
• ✅ Unterschiede im Vollbildmodus unter iOS berücksichtigen

Live-Demos

Probieren Sie VidPly in Aktion aus:

• Hauptdemo
• Audio-Playlist
• Video-Playlist
• Mixed-Media-Playlist
• HLS-Streaming
• DASH-Streaming

Benötigen Sie Hilfe? Schauen Sie in der API-Dokumentation nach oder erstellen Sie ein Ticket auf GitHub.