Bedienungsanleitung

Für Produktionsversionen:

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

<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-Quelldateien (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 einem bestimmten Zeitpunkt

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

Verwendung von Datenattributen

<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- lang :

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

Benutzerdefinierte Gestaltung der Untertitel

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 Bildqualitä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 die Gestaltung der Untertitel und interaktive Transkripte.

DASH + HLS + MP4-Fallback

Um maximale Kompatibilität über verschiedene 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-Schaltfläche

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 – Manifeste können nicht direkt heruntergeladen werden.

Benutzerdefinierter schwebender Player (Miniplayer)

Aktivieren Sie den seiteninternen schwebenden Player („eigenes PiP“). Wenn das Originalvideo aus dem Sichtbereich herausgescrollt wird, blendet VidPly eine verschiebbare und in der Größe anpassbare schwebende Hülle in der gewählten Ecke ein; wenn das Original wieder in den Sichtbereich zurückgescrollt wird, wird sie wieder angedockt. Die PiP- Schaltfläche schaltet das manuelle Fixieren/Lösen um. Das native PiP des Browsers wird automatisch unterdrückt, solange der schwebende Player aktiviert ist, sodass Nutzer 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 des schwebenden Fensters pausiert die Wiedergabe und verhindert ein erneutes automatisches Schweben bis zum nächsten vom Nutzer ausgelösten play.
Die schwebende Einblendung 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ü.

Puffer-Ladeanzeige

Ein zentrierter Ladeindikator erscheint automatisch, während der Player Daten puffert (waiting, seeking, beim Start 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; Sie können 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ößenanpassungsfunktionen 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 ein-/ausschalten (mit Pfeiltasten verschieben)
R – Größenänderungsmodus ein-/ausschalten (Größe mit den Pfeiltasten anpassen)
Home – Position auf die 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 Interaktive Transkriptfunktion.

Video-Overlay mit Gebärdensprache

Ein Video eines Gebärdensprachdolmetschers synchron zum Hauptvideo einblenden:

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:

Erscheint eine Sprachauswahl im Kopfbereich 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

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

Ziehmodus aktivieren/deaktivieren – Den Ziehmodus über die Tastatur ein- und ausschalten (Tastenkürzel: Taste „D“)
Größenänderungsmodus aktivieren/deaktivieren – Schalten Sie den Größenänderungsmodus ein oder aus, um die Videogröße anzupassen (Tastenkürzel: Taste „R“)
Sprachauswahl – Wechseln Sie zwischen den verfügbaren Gebärdensprachvideos (falls mehrere vorhanden sind)
Menü schließen – Das Einstellungsmenü schließen

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 die Navigation per Tastatur:
- 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 Ziehen, Größenänderung, Sprachumschaltung und Schließoptionen
Wechselt automatisch die Sprache, wenn sich die Sprache der Untertitel ändert (sofern eine passende Gebärdensprache verfügbar ist)

Audiodeskription

VidPly unterstützt drei sich ergänzende Audiodeskriptionskanäle:

Kanal	Anwendung	Verhalten
Beschriebenes Video wird ausgetauscht	`audioDescriptionSrc` oder `<source data-desc-src>`	Ersetzt das Video durch eine vorab gemischte, beschriebene MP4-/WebM-Datei; die Wiedergabeposition bleibt erhalten
VTT-Sprachausgabe (erweiterte Untertitel)	`kind="descriptions"` Spur, kein beschriftetes Video	Pausiert das Video, liest den Cue-Text über `speechSynthesis`, setzt die Wiedergabe fort, sobald die Sprachausgabe endet
Textbeschreibungen	Beschreibungen: VTT immer verfügbar	Werden im Transkript-Fenster angezeigt; Umschaltung über den Track-Modus, wenn TTS deaktiviert ist

Modusauflösung (audioDescriptionMode, Standard auto):

auto — Wechsel zu beschreibendem Video, falls konfiguriert; andernfalls VTT-Sprache, sofern eine Beschreibungsspur vorhanden ist
swap — nur beschreibendes Video
vtt_speech — nur VTT-Sprache (URL des beschrifteten Videos wird ignoriert)

Wechsel zu beschriftetem Video

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

Oder mit <source> Elementen:

<source src="regular.mp4" type="video/mp4"
        data-desc-src="described.mp4" data-orig-src="regular.mp4">

VTT-Sprachausgabe (erweiterte AD)

Keine beschriebene Videodatei – nur eine WebVTT-Spur mit Beschreibungen:

<video
  data-vidply
  data-audio-description-mode="vtt_speech"
  data-audio-description-button="true"
>
  <source src="video.mp4" type="video/mp4">
  <track kind="descriptions" src="descriptions-en.vtt" srclang="en" label="Descriptions">
</video>

Siehe auch: `demo/single-player-vtt-speech.html`.

JavaScript-API

const player = new Player('#video', {
  audioDescriptionSrc: 'path/to/described-version.mp4', // optional
  audioDescriptionButton: true,
  audioDescriptionMode: 'auto',       // 'auto' | 'swap' | 'vtt_speech'
  audioDescriptionSpeech: true,       // false = text-only (transcript / track toggle)
  audioDescriptionExtended: true      // resume after TTS ends, not at cue.endTime
});

// Control programmatically
await player.enableAudioDescription();
await player.disableAudioDescription();
await player.toggleAudioDescription();

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

// Events — swap mode
player.on('audiodescriptionenabled', () => {
  console.log('Audio description enabled');
});

player.on('audiodescriptiondisabled', () => {
  console.log('Audio description disabled');
});

// Events — VTT speech mode (per cue)
player.on('audiodescriptioncuestart', ({ time, text, cue }) => {
  console.log('Speaking description at', time, text);
});

player.on('audiodescriptioncueend', ({ time, text }) => {
  console.log('Finished description at', time);
});

HTML-Datenattribute (CamelCase in data-vidply-*):

data-audio-description-src
data-audio-description-button
data-audio-description-mode — auto, swapoder vtt_speech
data-audio-description-speech — true / false
data-audio-description-extended — true / false

Hinweis: Die Wiedergabeposition bleibt beim Wechseln der beschrifteten Videoquellen erhalten. Für VTT-Sprache ist ein Browser mit speechSynthesis Unterstützung; andernfalls werden die Beschreibungen auf reinen Text zurückgesetzt (track.mode = 'showing').

Zu Videokapiteln springen, 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, sobald Kapitel-Tracks erkannt werden. Nutzer können darauf klicken, um ein Menü aufzurufen und zu einem beliebigen Kapitel zu springen.

Gestaltung der Untertitel

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>

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.

Tipps zur Leistung

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>