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 das Script-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-Steuerelemente von VidPly für Wiedergabe, Pause, Spulsuche und Lautstärke integrieren.

Bei der 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 1.6.16 wird bei Bedarf geladen, wenn .m3u8 URLs erkannt werden (CDN-Fallback, falls noch nicht auf der Seite vorhanden). 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 5.2.0 (modernes UMD) wird bei Bedarf geladen, sobald .mpd URLs erkannt werden. DASH-Streams unterstützen:

• Auswahl der Qualität mit adaptiver 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 aktivierte Untertitel

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

Kapitel

Kapitelnavigation mit einer Kapitel-Spur 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
});

Übersicht über alle 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 per Tastatur erreichbar, 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 schwebenden Player („eigenes PiP“), der in einer konfigurierbaren Ecke des Ansichtsbereichs erscheint, gezogen und in der Größe angepasst werden kann und die VidPly-eigene Untertitelanzeige, die Steuerelemente sowie den Vollbildmodus innerhalb der schwebenden Hülle beibehält.

Solange floating aktiviert ist, wird die native Picture-in-Picture-API des Browsers automatisch unterdrückt (disablepictureinpicture + disableremoteplayback) , sodass der Nutzer browserübergreifend ein einheitliches Erlebnis erhält.

Verhalten

• Automatisches Anzeigen beim Herausscrollen – Wenn der ursprüngliche Player aus dem Ansichtsbereich herausgescrollt wird, erscheint das Video in der schwebenden Hülle. Wenn er wieder hineingescrollt wird, wird das Video wieder an seinen ursprünglichen Container angedockt.
• Manuelles Anheften/Lösen – Über die PiP-Schaltfläche in der Steuerleiste lässt sich die schwebende Hülle manuell anheften. Das manuelle Anheften/Lösen hat Vorrang vor dem scrollbasierten automatischen Anheften, bis die nächste vom Benutzer ausgelöste 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 unterbindet das automatische Schweben für den Rest der Wiedergabesitzung.
• Ziehen und Größe ändern – Die schwebende Einblendung kann an der Kopfzeile gezogen und über die Eck- bzw. Randgriffe in der Größe angepasst werden. Die Geometrie wird pro Player über den lokalen Speicher beibehalten.
• Reduzierte Steuerleiste – Innerhalb des schwebenden Fensters werden nur die wesentlichen Steuerelemente angezeigt: Wiedergabe/Pause, Zurückspulen, Vorspulen, Lautstärke, Untertitel, PiP und Vollbild. Tooltips werden über den Schaltflächen angezeigt; die Größe der Untertitel wird 90% und auf 95% Breite begrenzt.
• Audioplayer werden übersprungen – Die Floating-Funktion gilt nur für <video> Player.
• Standardmäßig nur auf dem Desktop – Unterhalb von floatingMinViewportWidth (Standard 768 px) ist die Funktion deaktiviert und die PiP-Schaltfläche zum Schweben wird in der Hauptsteuerleiste ausgeblendet (sie gelangt niemals in das Überlaufmenü).

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

Die Floating-Optionen werden über den data-vidply-options JSON-Blob (derselbe Kanal, den 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 Schaltfläche ü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

Während des Pufferns der Medien (waiting / seeking / anfängliche 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 Ladevorgangs eine .vidply-buffering Klasse, die Sie zum Stylen oder zum Einbinden von Hooks nutzen können:

.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

VidPly unterstützt gesprochene Audiobeschreibungen auf zwei Arten:

1. Beschriebenes Video (für die Produktion empfohlen) – Laden Sie eine vorab gemischte MP4-/WebM-Datei hoch oder verlinken Sie diese, in der der Kommentar bereits in die Audiospur eingebettet ist. VidPly ersetzt die gesamte Videoquelle, wenn der Nutzer die Audiobeschreibung ein- oder ausschaltet.

2. VTT-Sprache (erweiterter Fallback für Audiobeschreibung) – wenn kein beschriebenes Video verfügbar ist, kann eine kind="descriptions" WebVTT-Spur die Text-to-Speech-Funktion des Browsers steuern: Der Player hält an jedem Cue an, spricht die Beschreibung vor und setzt dann die Wiedergabe fort. Die Qualität hängt von der Browser-Stimme ab; verwenden Sie beschriebene Videos, wenn eine Erzählung in Sendequalität erforderlich ist.

Textbeschreibungsmarkierungen stehen im Transkript-Fenster stets zum Lesen zur Verfügung, unabhängig davon, welcher Sprachpfad aktiv ist. Legen Sie audioDescriptionSpeech: false , um reine Textbeschreibungen (ohne TTS) zu verwenden.

Modus (audioDescriptionMode, Standard auto):

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

Benutzer schalten die Untertitel über die AD-Schaltfläche um. Demo: `demo/single-player-vtt-speech.html`.

Gebärdensprache

Overlay für 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 gezogen und in der Größe angepasst werden

Tastaturkürzel

VidPly bietet umfassende Tastatursteuerung:

Benutzerdefinierte Tastenkombinationen

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;
}

Benutzerdefinierter Fortschrittsbalken

.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 Vorgehensweisen

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

• ✅ Stets Untertitel bereitstellen
• ✅ Verwenden Sie aussagekräftige Titel für die Tonspuren
• ✅ Testen Sie die Bedienung ausschließlich mit der Tastatur
• ✅ Mit Bildschirmleseprogrammen 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? Sehen Sie in der API-Dokumentation nach oder erstellen Sie ein Ticket auf GitHub.