VidPly Benutzerhandbuch

Ein ausführliches Benutzerhandbuch zum Video- und AudioPlayer

Erste Schritte

1. Fügen Sie das CSS ein

<link rel="stylesheet" href="src/styles/vidply.css">

2. Fügen Sie Ihr Medienelement hinzu

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

<!-- Audio -->
<audio data-vidply>
  <source src="your-audio.mp3" type="audio/mpeg">
</audio>

3. Importieren Sie den Player

Für Produktions-Builds:

<script type="module">
  import Player from './dist/prod/vidply.esm.min.js';
  // Player auto-initializes elements with data-vidply attribute
</script>

Für die Entwicklung mit rohen TypeScript-Quellen (z. B. über vite oder tsx):

import Player from './src/index';

const player = new Player('#video');

Häufige Anwendungsfälle

Automatische Wiedergabe mit stummgeschaltetem Ton

const player = new Player('#video', {
  autoplay: true,
  muted: true
});

Start zu einer bestimmten Zeit

const player = new Player('#video', {
  startTime: 30  // Start at 30 seconds
});

Benutzerdefinierte Tastaturkürzel

const player = new Player('#video', {
  keyboardShortcuts: {
    'play-pause': ['Space', 'Enter'],
    'seek-forward': ['d'],
    'seek-backward': ['a']
  }
});

Video wiederholen

const player = new Player('#video', {
  loop: true
});

Sprache ändern

Integrierte Sprachen

const player = new Player('#video', {
  language: 'es'  // Spanish (available: en, es, fr, de, ja)
});

Benutzerdefinierte Sprachdateien laden

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

Datenattribute verwenden

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

Automatische Erkennung aus HTML

Der Player erkennt die Sprache automatisch anhand des HTML-Attributs lang :

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

Benutzerdefinierte Gestaltung von Untertiteln

const player = new Player('#video', {
  captionsFontSize: '120%',
  captionsFontFamily: 'Arial',
  captionsColor: '#FFFF00',
  captionsBackgroundColor: '#000000',
  captionsOpacity: 0.9
});

Ereignisbehandlung

const player = new Player('#video');

player.on('play', () => {
  console.log('Video started playing');
});

player.on('timeupdate', (currentTime) => {
  console.log('Current time:', currentTime);
});

player.on('ended', () => {
  console.log('Video ended');
  // Redirect or show related content
});

player.on('error', (error) => {
  console.error('Player error:', error);
});

Programmgesteuerte Steuerung

const player = new Player('#video');

// Play/Pause
document.getElementById('playBtn').addEventListener('click', () => {
  player.play();
});

document.getElementById('pauseBtn').addEventListener('click', () => {
  player.pause();
});

// Seek
document.getElementById('seek30').addEventListener('click', () => {
  player.seek(30);
});

// Volume
document.getElementById('volumeSlider').addEventListener('input', (e) => {
  player.setVolume(e.target.value / 100);
});

// Speed
document.getElementById('speedSelect').addEventListener('change', (e) => {
  player.setPlaybackSpeed(parseFloat(e.target.value));
});

YouTube/Vimeo/SoundCloud-Integration

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

<!-- Vimeo -->
<video data-vidply src="https://vimeo.com/76979871"></video>

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

<!-- These will automatically use the appropriate renderer -->

HLS-Streaming

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

// Access HLS-specific features
const player = new Player('#video');

// Listen for quality levels (hls.js path)
player.on('hlsmanifestparsed', (data) => {
  console.log('Available qualities:', data.levels);
});

// Listen for live cue updates (works for both hls.js and native iOS HLS)
player.on('textcuesupdate', () => {
  console.log('New subtitle cues available');
});

// Switch quality manually (if using HLS renderer)
if (player.renderer.switchQuality) {
  player.renderer.switchQuality(2); // Switch to quality level 2
}

Auf iOS/iPadOS, wo MSE nicht verfügbar ist, nutzt VidPly die native HLS-Unterstützung des Browsers, zeigt Untertitel und Qualität jedoch weiterhin über dieselbe VidPly-Benutzeroberfläche mittels der nativen TextTrack API-Brücke an.

DASH-Streaming (MPEG-DASH)

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

// Access DASH-specific features
const player = new Player('#video');

// Listen for quality changes
player.on('dashqualitychanged', (data) => {
  console.log('Quality changed:', data);
});

// Get available qualities
if (player.renderer.getQualities) {
  const qualities = player.renderer.getQualities();
  console.log('Available qualities:', qualities);
}

// Switch quality manually
if (player.renderer.switchQuality) {
  player.renderer.switchQuality(2); // Switch to quality level 2
}

DASH-Untertitelverarbeitung:

TTML/stpp-Untertitel – werden nativ von dash.js gerendert; die Gestaltung der Untertitel erfolgt durch den Stream selbst. Das interaktive Transkript ist für TTML-Spuren nicht verfügbar.
WebVTT-Untertitel – Werden vom VidPly-Untertitel-System verarbeitet, mit vollständiger Unterstützung für Untertitel-Styling und interaktive Transkripte.

DASH + HLS + MP4-Fallback

Um maximale Kompatibilität über Geräte und Browser hinweg zu gewährleisten, stellen Sie alle drei Formate bereit:

<video data-vidply width="800" height="450" poster="preview.jpg">
  <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="vtt/subtitles.de.vtt" srclang="de" label="Deutsch">
  <track kind="subtitles" src="vtt/subtitles.en.vtt" srclang="en" label="English">
</video>

VidPly wählt automatisch den besten Renderer basierend auf der Dateiendung der Quelldatei aus.

Download-Button

Zeigen Sie in der Steuerleiste eine Download-Schaltfläche an, damit Besucher die Mediendatei speichern können:

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

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

Bei Streaming-Quellen (.mpd, .m3u8) wird dringend empfohlen, einen expliziten downloadUrl , der auf eine einzelne MP4-/MP3-/WebM-Datei verweist – Manifestdateien können nicht direkt heruntergeladen werden.

Benutzerdefinierter schwebender Player (Miniplayer)

Aktivieren Sie den seiteninternen Floating-Player („eigenes PiP“). Wenn das Originalvideo aus dem Sichtbereich scrollt, öffnet VidPly eine verschiebbare und in der Größe anpassbare Floating-Hülle in der gewählten Ecke; wenn das Original wieder in den Sichtbereich scrollt, wird es erneut angedockt. Die PiP-Schaltfläche schaltet das manuelle Anheften/Lösen um. Das native PiP des Browsers wird automatisch unterdrückt, solange das Floating aktiviert ist, sodass Benutzer ein einheitliches Erlebnis erhalten.

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

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

Hinweise:

Reine Audio-Player ignorieren floating.
Das Schließen der schwebenden Hülle pausiert die Wiedergabe und verhindert ein erneutes automatisches Schweben, bis der Benutzer das nächste Mal play.
Die schwebende Shell zeigt eine reduzierte Steuerleiste an (Wiedergabe/Pause, Zurückspulen, Vorspulen, Lautstärke, Untertitel, PiP, Vollbild) und behält ihre Größe und Position pro Player bei.
Unten floatingMinViewportWidth (Standard 768) ist die Funktion deaktiviert und die schwebende PiP-Schaltfläche ausgeblendet – sie erscheint auch nie im Überlaufmenü.

Ladeanzeige

Ein zentrierter Ladespinner erscheint automatisch, während der Player puffert (waiting, seeking, initial loadstart) und verschwindet bei canplay / playing. Er ist für HTML5-, HLS- und DASH-Renderer aktiviert 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;
}

Der Container stellt während des Ladevorgangs eine .vidply-buffering Klasse; du kannst diese über CSS nutzen:

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

Auswahl der Untertitelspur

Wenn mehrere Untertitelspuren vorhanden sind, wird durch Klicken auf die CC-Schaltfläche ein Menü zur Auswahl der Sprache angezeigt:

<video data-vidply src="video.mp4">
  <track kind="captions" src="en.vtt" srclang="en" label="English">
  <track kind="captions" src="es.vtt" srclang="es" label="Español">
  <track kind="captions" src="fr.vtt" srclang="fr" label="Français">
  <track kind="captions" src="de.vtt" srclang="de" label="Deutsch">
</video>

Spuren programmgesteuert wechseln:

const player = new Player('#video');

// Get available tracks
const tracks = player.captionManager.getAvailableTracks();
console.log(tracks);
// [{index: 0, language: 'en', label: 'English', kind: 'captions'}, ...]

// Switch to specific track
player.captionManager.switchTrack(1);  // Switch to Spanish

// Or by finding the track you want
const frenchTrack = tracks.find(t => t.language === 'fr');
if (frenchTrack) {
  player.captionManager.switchTrack(frenchTrack.index);
}

Interaktives Transkript

Zeigen Sie neben Ihrem Video ein anklickbares, scrollbares Transkript mit Drag-and-Drop- und Größenänderungsfunktionen an:

<video 
  data-vidply
  data-transcript="true"
  data-transcript-button="true"
  src="video.mp4"
>
  <track kind="captions" src="captions.vtt" srclang="en" label="English">
</video>

const player = new Player('#video', {
  transcript: true,
  transcriptButton: true
});

// Show/Hide Transcript
player.transcriptManager.showTranscript();
player.transcriptManager.hideTranscript();
player.transcriptManager.toggleTranscript();

// Drag & Resize Modes (Desktop only, screen width >= 768px)
player.transcriptManager.toggleKeyboardDragMode();   // Toggle drag mode (D key)
player.transcriptManager.togglePointerResizeMode();  // Toggle resize mode (R key)

// Check State
if (player.transcriptManager.isVisible) {
  console.log('Transcript is showing');
}

Tastaturkürzel:

T – Transkriptfenster ein-/ausblenden
D – Ziehmodus umschalten (mit Pfeiltasten verschieben)
R – Größenänderungsmodus umschalten (Größe mit den Pfeiltasten ändern)
Home – Position auf Mitte zurücksetzen
Esc – Zieh-/Größenänderungsmodus beenden

Einstellungsmenü: Das Transkriptfenster enthält ein Einstellungsmenü (⚙️-Symbol) mit folgenden Optionen:

Ziehmodus aktivieren/deaktivieren
Größenänderungsmodus aktivieren/deaktivieren
Das Transkriptfenster schließen

Die vollständige Dokumentation finden Sie unter TRANSCRIPT.md.

Video-Overlay für Gebärdensprache

Einblenden eines Videos mit Gebärdensprachdolmetscher, synchronisiert mit dem Hauptvideo:

Einzelnes Gebärdensprachvideo

<video 
  data-vidply
  src="main-video.mp4"
  data-sign-language-src="sign-language-video.mp4"
  data-sign-language-position="bottom-right"
>
</video>

const player = new Player('#video', {
  signLanguageSrc: 'path/to/sign-language-video.mp4',
  signLanguageButton: true,
  signLanguagePosition: 'bottom-right' // Options: 'bottom-right', 'bottom-left', 'top-right', 'top-left'
});

// Control programmatically
player.enableSignLanguage();   // Show sign language video
player.disableSignLanguage();  // Hide sign language video
player.toggleSignLanguage();   // Toggle visibility

// Check state
if (player.state.signLanguageEnabled) {
  console.log('Sign language is enabled');
}

Mehrere Gebärdensprachvideos (Sprachumschaltung)

Sie können mehrere Gebärdensprachvideos für verschiedene Sprachen bereitstellen. Der Player zeigt automatisch eine Sprachauswahl an, wenn mehrere Quellen verfügbar sind:

<video 
  data-vidply
  src="main-video.mp4"
  data-sign-language-src-en="sign-language-en.mp4"
  data-sign-language-src-de="sign-language-de.mp4"
  data-sign-language-src-es="sign-language-es.mp4"
  data-sign-language-position="bottom-right"
>
</video>

const player = new Player('#video', {
  signLanguageSources: {
    en: 'path/to/sign-language-en.mp4',
    de: 'path/to/sign-language-de.mp4',
    es: 'path/to/sign-language-es.mp4'
  },
  signLanguageButton: true,
  signLanguagePosition: 'bottom-right'
});

// Switch sign language programmatically
player.switchSignLanguage('de'); // Switch to German sign language

Wenn mehrere Gebärdensprachquellen verfügbar sind:

Eine Sprachauswahl erscheint in der Kopfzeile des Gebärdensprachvideos
Das Gebärdensprachvideo wechselt automatisch, wenn sich die Untertitel ändern (sofern die Sprachcodes übereinstimmen)
Benutzer können die Sprache manuell über die Auswahl umschalten

Menü „Gebärdensprach-Einstellungen“

Das Gebärdensprachvideo enthält ein Einstellungsmenü (⚙️-Symbol) mit den folgenden Optionen:

Ziehmodus aktivieren/deaktivieren – Ziehmodus über die Tastatur umschalten (Tastenkürzel: Taste D)
Größenänderungsmodus aktivieren/deaktivieren – Umschalten des Größenänderungsmodus zum Anpassen der Videogröße (Tastenkombination: R-Taste)
Sprachauswahl – Wechseln Sie zwischen den verfügbaren Gebärdensprachvideos (falls mehrere vorhanden)
Menü schließen – Schließt das Einstellungsmenü

Funktionen der Gebärdensprache:

Synchronisiert sich automatisch mit der Wiedergabe des Hauptvideos
Passt die Wiedergabegeschwindigkeit an das Hauptvideo an
Standardmäßig stummgeschaltet (es wird der Ton des Hauptvideos verwendet)
Wird als Overlay über dem Hauptvideo angezeigt
Kann verschoben und in der Größe angepasst werden (nur Desktop, >= 768px)
Unterstützt Tastaturnavigation:
- D – Ziehmodus umschalten (mit Pfeiltasten verschieben)
- R – Größenänderungsmodus umschalten (Größe mit den Pfeiltasten ändern)
- Home – Position zurücksetzen
- Esc – Zieh-/Größenänderungsmodus beenden
Enthält ein Einstellungsmenü für Drag, Größenänderung, Sprachumschaltung und Schließoptionen
Wechselt automatisch die Sprache, wenn sich die Untertitelsprache ändert (sofern eine passende Gebärdensprache verfügbar ist)

Audiodeskription

Wechseln Sie zu einer Version Ihres Videos mit Audiodeskription:

<video 
  data-vidply
  src="regular-version.mp4"
  data-audio-description-src="described-version.mp4"
  data-audio-description-button="true"
>
</video>

const player = new Player('#video', {
  audioDescriptionSrc: 'path/to/described-version.mp4',
  audioDescriptionButton: true
});

// Control programmatically
await player.enableAudioDescription();   // Switch to described version
await player.disableAudioDescription();  // Switch back to original
await player.toggleAudioDescription();   // Toggle between versions

// Check state
if (player.state.audioDescriptionEnabled) {
  console.log('Audio description is active');
}

// Listen for events
player.on('audiodescriptionenabled', () => {
  console.log('Switched to described version');
});

player.on('audiodescriptiondisabled', () => {
  console.log('Switched back to original');
});

Hinweis: Die Wiedergabeposition bleibt beim Wechsel zwischen den Versionen erhalten.

Kapitelnavigation

Springe zu Videokapiteln, wenn Kapitelspuren verfügbar sind:

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

Kapitel im VTT-Format:

WEBVTT

00:00:00.000 --> 00:01:30.000
Introduction

00:01:30.000 --> 00:05:00.000
Getting Started

00:05:00.000 --> 00:10:00.000
Advanced Features

00:10:00.000 --> 00:15:00.000
Conclusion

Die Schaltfläche „Kapitel“ wird automatisch in der Steuerleiste angezeigt, wenn Kapitel-Tracks erkannt werden. Nutzer können darauf klicken, um ein Menü anzuzeigen und zu einem beliebigen Kapitel zu springen.

Untertitel-Gestaltung

VidPly verfügt über ZWEI Schaltflächen für Untertitel:

CC-Schaltfläche – Sprache/Spur der Untertitel auswählen
Aa-Schaltfläche – Darstellung der Untertitel anpassen (Schriftart, Größe, Farbe)

const player = new Player('#video', {
  captions: true,
  captionsButton: true,      // Shows CC button for track selection
  captionStyleButton: true   // Shows Aa button for styling
});

// Programmatically set caption styles
player.captionManager.setCaptionStyle('fontSize', '120%');
player.captionManager.setCaptionStyle('fontFamily', 'serif');
player.captionManager.setCaptionStyle('color', '#FFFF00');
player.captionManager.setCaptionStyle('backgroundColor', '#000000');
player.captionManager.setCaptionStyle('opacity', 0.9);

Mehrere Player auf derselben Seite

<video id="player1" data-vidply src="video1.mp4"></video>
<video id="player2" data-vidply src="video2.mp4"></video>
<video id="player3" data-vidply src="video3.mp4"></video>

// All will auto-initialize
// By default, playing one will pause the others

// To allow multiple simultaneous playback:
const player1 = new Player('#player1', {
  pauseOthersOnPlay: false
});

Responsiver Player

const player = new Player('#video', {
  responsive: true,
  fillContainer: false
});

Bestimmte Steuerelemente deaktivieren

const player = new Player('#video', {
  controls: true,
  playPauseButton: true,
  progressBar: true,
  volumeControl: false,     // Hide volume
  speedButton: false,        // Hide speed
  captionsButton: true,
  fullscreenButton: true,
  pipButton: false           // Hide PiP
});

Benutzerdefinierte Callbacks

const player = new Player('#video', {
  onReady: function() {
    console.log('Player ready!');
    console.log('Duration:', this.getDuration());
  },
  
  onPlay: function() {
    console.log('Started playing');
    // Track analytics
    gtag('event', 'video_play', { video_title: 'My Video' });
  },
  
  onPause: function() {
    console.log('Paused at:', this.getCurrentTime());
  },
  
  onEnded: function() {
    console.log('Video finished');
    // Show "Watch Next" overlay
  }
});

Bereinigung

const player = new Player('#video');

// Later, when done:
player.destroy();

Bewährte Verfahren für Barrierefreiheit

1. Immer Untertitel bereitstellen

<video data-vidply>
  <source src="video.mp4" type="video/mp4">
  <track kind="subtitles" src="en.vtt" srclang="en" label="English">
  <track kind="subtitles" src="es.vtt" srclang="es" label="Español">
</video>

2. Tastaturnavigation aktivieren

const player = new Player('#video', {
  keyboard: true,
  screenReaderAnnouncements: true
});

3. Beschreibende Beschriftungen bereitstellen

const player = new Player('#video', {
  ariaLabels: {
    play: 'Start video playback',
    pause: 'Pause video playback',
    // ... custom labels
  }
});

4. Unterstützung für hohen Kontrast

Der Player passt sich automatisch an den Hochkontrastmodus an. Testen Sie dies mit:

Windows: Einstellungen > Barrierefreiheit > Kontrastthemen
CSS: @media (prefers-contrast: high)

5. Reduzierte Bewegung

Der Player berücksichtigt prefers-reduced-motion Einstellungen automatisch.

Leistungstipps

1. Vorladestrategie

// Don't preload (better for mobile)
const player = new Player('#video', {
  preload: 'none'
});

// Preload metadata only
const player = new Player('#video', {
  preload: 'metadata'
});

// Preload entire video
const player = new Player('#video', {
  preload: 'auto'
});

2. Lazy Loading

VidPly kann ein vorzeitiges Laden über das Netzwerk vermeiden (nützlich, wenn Sie viele Player auf einer Seite haben):

<video
  data-vidply
  preload="none"
  data-vidply-options='{"deferLoad": true, "preload": "none"}'
  src="video.mp4"
></video>