Dokumentation

Universeller, barrierefreier Video- und Audio-Player

Ein moderner, funktionsreicher Mediaplayer, der vollständig in TypeScript programmiert und als ES-Modul ohne Abhängigkeiten bereitgestellt wird. Er vereint die besten Barrierefreiheitsfunktionen von AblePlayer mit den Streaming-Fähigkeiten von MediaElement.js. Vollständig internationalisiert mit Unterstützung für 5 Sprachen und vollständiger WCAG 2.2 AA-Konformität.

Live-Demos

Probieren Sie VidPly in Aktion aus:

Hauptdemo – Präsentation des Videoplayers mit vollem Funktionsumfang
Audio-Playlist – Audio-Player mit Unterstützung für Playlists
Video-Playlist – Video-Playlist mit Miniaturansichten
Gemischte Wiedergabeliste – Kombinierte Audio- und Video- Wiedergabeliste
HLS-Streaming – Demo für Streaming mit adaptiver Bitrate
DASH-Streaming – MPEG-DASH-Streaming-Demo

Warum VidPly?

Keine Abhängigkeiten – Reines Vanilla-JavaScript/TypeScript, keine Frameworks erforderlich
TypeScript-nativ – In strengem TypeScript mit integrierten Typdeklarationen erstellt (dist/types/index.d.ts)
Barrierefreiheit an erster Stelle – WCAG 2.2 AA-konform mit vollständiger Unterstützung für Tastatur und Screenreader
Mehrsprachig – Integrierte Übersetzungen für 5 Sprachen mit einfacher Erweiterbarkeit
Vollständig anpassbar – CSS-Variablen und umfassende API
Moderne Build-Struktur – ES-Module mit Tree-Shaking, Code-Splitting und Source Maps
Produktionsreif – Gründlich getestet mit realen Medieninhalten

Funktionen

Kernunterstützung für Medien

Audio- und Videowiedergabe – Native HTML5-Unterstützung für beide Medientypen
Mehrere Formate – MP3, OGG, WAV (Audio) / MP4, WebM (Video)
YouTube-Integration – Einbetten von YouTube-Videos mit einheitlichen Steuerelementen
Vimeo-Integration – Nahtlose Integration des Vimeo-Players
SoundCloud-Integration – Wiedergabe von SoundCloud-Titeln und -Sets über die Widget-API mit einheitlichen Steuerelementen
HLS-Streaming – Adaptives Bitrate-Streaming mit Qualitätsauswahl und dynamischer Untertitelerkennung
- Verwendet hls.js 1.6.16 in Chrome / Firefox / Edge / Desktop-Safari für vollständige Funktionsparität (Qualitätsmenü, Untertitel, Transkript)
- Wechselt auf iOS / iPadOS, wo MSE nicht verfügbar ist, auf natives HLS zurück; native Text-Spuren werden weiterhin über die VidPly-Benutzeroberfläche für Untertitel und Transkripte angezeigt
DASH-Streaming – MPEG-DASH-Unterstützung über dash.js 5.2.0 (modernes UMD) mit adaptiver Qualität, TTML- und WebVTT-Untertiteln
Puffer-Spinner – Zentrierter Lade-Spinner, der automatisch angezeigt wird, während Medien gepuffert werden (HTML5, HLS, DASH)
Download-Schaltfläche – Optionale Download-Steuerung mit Unterstützung für benutzerdefinierte URLs (downloadButton + downloadUrl)
Vorschau-Miniaturansichten – Video-Vorschau-Miniaturansichten beim Bewegen des Mauszeigers über den Fortschrittsbalken
OS-Mediensteuerung – Integration der Media Session API: Metadaten zum aktuell wiedergegebenen Titel (Titel/Interpret/Album/Cover) sowie Steuerelemente für den Sperrbildschirm, Benachrichtigungen und Kopfhörer, einschließlich „Vorheriger/Nächster Titel“ für Wiedergabelisten
Wiedergabelisten – Vollständige Unterstützung von Wiedergabelisten mit automatischem Weiterlauf und Navigation
- Audio-Wiedergabelisten mit Titelinformationen
- Video-Wiedergabelisten mit Miniaturansichten
- Gemischte Wiedergabelisten – Kombination von Audio und Video in einer einzigen Wiedergabeliste
- Steuerelemente für „Vorheriger/Nächster Titel“
- Visuelles Wiedergabelisten-Fenster
- Vollbildmodus: Horizontales Karussell im YouTube-Stil
  - Automatisches Ein- und Ausblenden je nach Wiedergabestatus
  - Wischbare Touch-Oberfläche
  - Responsives Kartenlayout

Barrierefreiheitsfunktionen (konform mit WCAG 2.2 AA)

Vollständige Tastaturnavigation – Alle Funktionen sind über die Tastatur, benutzerdefinierte Tastenkombinationen und die Menünavigation mit den Pfeiltasten zugänglich (nicht interaktive/deaktivierte Menüpunkte werden vom wandernden Fokus ausgeschlossen)
Unterstützung für Screenreader – Vollständige ARIA-Bezeichnungen (aria-controls, aria-expanded, aria-haspopup), Live-Regionen; Menüs mit Einzelauswahl (Geschwindigkeit/Qualität/Untertitel) verwenden role="menuitemradio" + aria-checked, und sowohl mit der Maus als auch über die Tastatur gesteuerte Wiedergabe/Pause, Untertitel- und Lautstärkeregelungen werden angesagt
Interaktive Transkripte – Klicken zum Springen und automatisches Scrollen mit korrektem semantischem HTML und einer Fokusfalle, solange das Transkript geöffnet ist
Gebärdensprache-Overlay – Bild-in-Bild mit Ziehen/Größenänderung, über die Tastatur bedienbar
Audiodeskription – Alternative Audiospur mit Beschreibungen der visuellen Inhalte
Gestaltung der Untertitel – Vollständig anpassbar (Schriftart, Größe, Farbe, Deckkraft, Randstil)
Hochkontrastmodus – Unterstützung des Windows-Hochkontrastmodus, farbunabhängiges Design
Reduzierte Bewegung – Sanftes Scrollen und Animationen entsprechen prefers-reduced-motion (SC 2.3.3)
Zoom & Neuanordnung – Pinch-Zoom bleibt auch im (Pseudo-)Vollbildmodus erhalten; keine feste maximum-scale Sperre (SC 1.4.4 / 1.4.10)
Fokusverwaltung – Logische Fokusreihenfolge, programmatische Fokusverwaltung, sichtbare Indikatoren, Fokusfallen im Transkriptfenster und im Einstellungsdialog
Touch-Barrierefreiheit – Schaltflächen, Größenänderungsgriffe und Schieberegler-Schieber mit einer Größe von mindestens 24×24 CSS-Pixel gemäß WCAG 2.2 AA (SC 2.5.8); wischbare Oberflächen

Bildunterschriften & Untertitel

WebVTT-Unterstützung – Standard-Untertitelformat
Mehrere Sprachen – Unterstützung mehrerer Tonspuren
Untertitelauswahl – Einfaches Umschalten zwischen Spuren mit der CC-Schaltfläche
Gestaltung der Untertitel – Spezieller Gestaltungsdialog (Schriftart, Größe, Farbe, Deckkraft)
Kapitelnavigation – Zu Videokapiteln springen
Interaktive Transkripte – Transkriptfenster mit Klick-und-Suchen-Funktion (die Suchfunktion des Browsers „Auf dieser Seite suchen“ funktioniert zum Suchen)

Wiedergabefunktionen

Einstellbare Wiedergabegeschwindigkeit – 0,25-fache bis 2-fache Wiedergabe
Navigationssteuerung – Vorwärts-/Rückwärtsnavigation
Lautstärkeregelung – 0–100 % mit Stummschaltung
Wiederholung – Einzelne Datei oder gesamte Wiedergabeliste
Vollbildmodus – Native Vollbild-API mit intelligenter Playlist-Einblendung
Bild-in-Bild – Native PiP-Unterstützung im Browser (über die Standard-PiP-Schaltfläche aktivierbar)
Benutzerdefinierter schwebender Player (Miniplayer) – Optionales, auf der Seite schwebendes Fenster, das
- automatisch schwebt, wenn der ursprüngliche Player aus dem Sichtbereich gescrollt wird, und wieder andockt, wenn er wieder in den Sichtbereich gescrollt wird
- manuell über die PiP-Schaltfläche fixiert oder gelöst werden kann (manuelles Fixieren hat Vorrang vor dem Scroll-Verhalten)
- vollständig verschiebbar und in der Größe anpassbar ist, wobei die Geometrie pro Player beibehalten wird
- sorgt dafür, dass VidPly-Untertitel, Steuerelemente und Vollbildmodus innerhalb der schwebenden Hülle weiterhin funktionieren
- unterdrückt automatisch das native PiP des Browsers, solange es aktiviert ist
- ist nur auf dem Desktop verfügbar (standardmäßig deaktiviert bei einer Ansichtsbereichsbreite unter 768 px)

Internationalisierung

Integrierte Unterstützung für 5 Sprachen:

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

Alle Elemente der Benutzeroberfläche sind vollständig übersetzt, darunter:

Steuerungsschaltflächen und Menüs
Zeitanzeige und Formatierung der Dauer
Tastaturkürzel
Fehlermeldungen und Benachrichtigungen
ARIA-Bezeichnungen für Bildschirmleseprogramme

Benutzerdefinierte Übersetzungen: Fügen Sie ganz einfach eigene Sprachen hinzu, indem Sie JSON- oder YAML-Übersetzungsdateien über Datenattribute oder JavaScript-Optionen laden. Der Player erkennt automatisch das HTML-Attribut lang Attribut und lädt die passenden Übersetzungen.

Installation

Aus dem Quellcode kompilieren

Erstellen Sie zunächst den Player:

# Install dependencies
npm install

# Build production files
npm run build

Dadurch werden minimierte Dateien im dist/ Ordner.

Option 1: Verwendung der kompilierten Dateien (für die Produktion empfohlen)

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="dist/vidply.min.css">
</head>
<body>
  <video data-vidply src="video.mp4" width="800" height="450">
    <track kind="subtitles" src="captions.vtt" srclang="en" label="English">
  </video>

  <script type="module">
    import Player from './dist/prod/vidply.esm.min.js';
    // Auto-initialized via data-vidply attribute
  </script>
</body>
</html>

Option 2: Herkömmliches Script-Tag (IIFE)

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

<video id="my-video" src="video.mp4"></video>

<script>
  const player = new VidPly.Player('#my-video', {
    controls: true,
    autoplay: false,
    volume: 0.8,
    language: 'en'
  });
</script>

Option 3: Entwicklung (TypeScript-Quelldateien)

import Player from './src/index';

const player = new Player('#my-video', {
  controls: true,
  autoplay: false,
  volume: 0.8,
  language: 'en'
});

Die Bibliothek ist in strengem TypeScript geschrieben. Typdeklarationen werden an dist/types/index.d.ts , sodass Nutzer, die tsc oder vite erhalten vollständigen IntelliSense ohne zusätzliche @types Paket.

Schnellstart

1. Erstellen Sie den Player

npm install
npm run build

2. Fügen Sie ihn Ihrer Seite hinzu

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

3. Erstellen Sie einen Videoplayer

<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-es.vtt" srclang="es" label="Español">
</video>

Das war’s schon! Der Player wird automatisch initialisiert.

YouTube-Player

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

Vimeo-Player

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

Audio-Player

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

HLS-Streaming

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

DASH-Streaming

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

SoundCloud

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

Download-Schaltfläche

Aktivieren Sie die Download-Schaltfläche und geben Sie (optional) eine benutzerdefinierte URL 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('#my-video', {
  downloadButton: true,
  downloadUrl: '/files/lecture.mp4' // optional, falls back to current src
});

Benutzerdefinierter schwebender Player (Miniplayer)

Aktivieren Sie den schwebenden Player auf der Seite („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. Benutzer können den Floating-Player außerdem manuell über die PiP-Schaltfläche in der Steuerleiste anheften oder lösen. Die native Picture-in-Picture-API des Browsers wird automatisch unterdrückt, solange der Floating-Modus aktiviert ist, sodass Benutzer ein einheitliches Erlebnis erhalten.

Aktivieren über den data-vidply-options JSON-Blob:

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

Oder programmgesteuert:

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

Hinweise:

Reine Audio-Player (<audio>) ignorieren die Option „floating“.
Das Schließen des schwebenden Fensters pausiert die Wiedergabe und verhindert ein erneutes automatisches Schweben bis zur nächsten vom Benutzer ausgelösten play.
Das schwebende Fenster speichert seine Größe und Position pro Player im lokalen Speicher.
Unterhalb floatingMinViewportWidth (Standard: 768 px) ist die PiP-Schaltfläche ausgeblendet und die Floating-Funktion deaktiviert.

DASH + HLS + MP4-Fallback

Um eine maximale Gerätekompatibilität zu gewährleisten, stellen Sie alle drei Formate bereit:

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

VidPly erkennt den Quelltyp automatisch anhand der Dateiendung (.mpd / .m3u8 / .mp4) und wählt den passenden Renderer aus.

Konfigurationsoptionen

const player = new Player('#video', {
  // Display
  width: 800,
  height: 450,
  poster: 'poster.jpg',
  responsive: true,

  // Media metadata + OS media controls (Media Session API)
  title: null,                  // Now-playing title (lock-screen / notification)
  artist: null,                 // Now-playing artist/author
  album: null,                  // Now-playing album/collection
  mediaSession: true,           // Expose OS media controls + metadata (set false to opt out)

  // Playback
  autoplay: false,
  loop: false,
  muted: false,
  volume: 0.8,
  playbackSpeed: 1.0,
  startTime: 0,
  
  // Controls
  controls: true,
  hideControlsDelay: 3000,
  playPauseButton: true,
  progressBar: true,
  currentTime: true,
  duration: true,
  volumeControl: true,
  muteButton: true,
  chaptersButton: true,
  qualityButton: true,
  captionStyleButton: true,
  speedButton: true,
  captionsButton: true,
  transcriptButton: true,
  audioDescriptionButton: true,
  signLanguageButton: true,
  fullscreenButton: true,
  helpButton: true,             // Show a keyboard-shortcuts help button (requires keyboard: true)
  pipButton: false,
  downloadButton: false,        // Show a download button in the control bar
  downloadUrl: null,            // Optional explicit download URL (falls back to current src)
  downloadFormat: null,         // Optional override for the displayed download format (e.g. "MP4")
  downloadFileSize: null,       // Optional override for the displayed file size (bytes)
  downloadFetchSize: true,      // Issue a HEAD request to detect file size when not provided

  // 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)

  // Seeking
  seekInterval: 10,
  seekIntervalLarge: 30,

  // Captions
  captions: true,
  captionsDefault: false,
  captionsFontSize: '100%',
  captionsFontFamily: 'sans-serif',
  captionsColor: '#FFFFFF',
  captionsBackgroundColor: '#000000',
  captionsOpacity: 0.8,

  // Audio Description
  audioDescription: true,
  audioDescriptionSrc: null, // URL to audio-described version

  // Sign Language
  signLanguage: true,
  signLanguageSrc: null, // URL to sign language video
  signLanguagePosition: 'bottom-right', // 'bottom-right', 'bottom-left', 'top-right', 'top-left'
  signLanguageDisplayMode: 'both',      // 'pip' (overlay) | 'main' (source swap) | 'both'
  signLanguageSources: undefined,       // { en: '/sl/en.mp4', de: '/sl/de.mp4', ... }

  // Transcripts
  transcript: false,
  transcriptPosition: 'external',
  transcriptContainer: null,
  
  // Keyboard (defaults; do not assign the same key to two actions)
  keyboard: true,
  keyboardShortcuts: {
    'play-pause': [' ', 'p', 'k'],
    'seek-forward': ['ArrowRight'],
    'seek-backward': ['ArrowLeft'],
    'volume-up': ['ArrowUp'],
    'volume-down': ['ArrowDown'],
    'mute': ['m'],
    'fullscreen': ['f'],
    'captions': ['c'],
    'caption-style-menu': ['a'],
    'speed-up': ['>'],
    'speed-down': ['<'],
    'speed-menu': ['s'],
    'quality-menu': ['q'],
    'chapters-menu': ['j'],
    'transcript-toggle': ['t'],
    'help': ['?']
  },
  
  // Accessibility
  screenReaderAnnouncements: true,
  focusHighlight: true,
  highContrast: false,
  ariaLabels: {},                 // Override individual ARIA labels by i18n key
  metadataAlerts: {},             // Map of metadata-cue keys to alert handlers (opt-in)
  metadataHashtags: {},           // Map of metadata-cue hashtags to handler config (opt-in)

  // Internationalization
  language: 'en',
  languages: ['en'],
  languageFiles: undefined,       // { pt: '/i18n/pt.json', it: '/i18n/it.json' }
  languageFile: undefined,        // Single language code to load
  languageFileUrl: undefined,     // URL for the single language file

  // Resume Playback
  resumePlayback: true,           // Save and offer to resume playback position
  resumeThreshold: 10,            // Seconds; do not offer resume if less than this was watched
  resumePrompt: true,             // false = silently auto-resume

  // Thumbnail Preview
  thumbnailPreview: true,
  thumbnailCacheSize: 50,
  thumbnailPregenerate: true,
  thumbnailInterval: 10,
  thumbnailWidth: 160,
  thumbnailHeight: 90,
  thumbnailQuality: 0.8,

  // Lazy Loading
  lazyInit: true,
  lazyMargin: '200px',

  // Theming
  theme: 'dark',                  // 'dark' | 'light' | 'minimal' | 'high-contrast'
  themeVariables: {},             // Custom --vidply-* CSS variable overrides

  // Callbacks
  onReady: () => console.log('Ready!'),
  onPlay: () => console.log('Playing!'),
  onPause: () => console.log('Paused!'),
  onEnded: () => console.log('Ended!'),
  onTimeUpdate: (t) => {},
  onVolumeChange: (v) => {},
  onError: (err) => console.error(err),

  // Streaming
  hideSpeedForHls: false,         // Hide speed control for ALL HLS streams
  hideSpeedForHlsVideo: false,    // Hide speed control only for HLS video (e.g. live streams)
  hideSpeedForDash: false,        // Hide speed control for ALL DASH streams
  hideSpeedForDashVideo: false,   // Hide speed control only for DASH video

  // Advanced
  debug: false,
  pauseOthersOnPlay: true,
  classPrefix: 'vidply',          // CSS class prefix and event/storage namespace
  iconType: 'svg',
  initialDuration: 0,             // Optional duration shown before metadata is loaded
  requirePlaybackForAccessibilityToggles: false, // If true, AD/SL toggles before play show a notice instead of starting playback
  fillContainer: false,
  playsInline: true,              // Inline playback on iOS

  // Performance
  preload: 'metadata',            // 'none', 'metadata', or 'auto'
  deferLoad: false                // Delay loading until user plays (good for many players)
});

Tastaturkürzel

Taste	Aktion
`Leertaste` / `P` / `K`	Abspielen/Pause
`F`	Vollbild umschalten
`M`	Stummschalten/Stummschaltung aufheben
`↑` / `↓`	Lautstärke erhöhen/verringern
`←` / `→`	Springen: -10 s / +10 s
`C`	Untertitel ein-/ausschalten (oder Menü öffnen, falls mehrere vorhanden)
`A`	Menü für Untertitelstil öffnen
`<` / `>`	Geschwindigkeit verringern/erhöhen
`S`	Geschwindigkeitsmenü öffnen
`Q`	Menü „Qualität“ öffnen
`J`	Kapitel-Menü öffnen
`T`	Untertitel ein-/ausblenden
`?`	Hilfe zu Tastaturkürzeln anzeigen
`D`	Zugriffsmodus umschalten (Transkript/Gebärdensprache)
`R`	Größenänderungsmodus umschalten (Transkript/Gebärdensprache)
`Esc`	Zieh-/Größenänderungsmodus beenden oder Menüs schließen
`Home`	Position von Untertiteln/Gebärdensprache zurücksetzen

API-Referenz

Wiedergabesteuerung

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 10 seconds
player.seekBackward(10) // Skip backward 10 seconds

Lautstärkeregelung

player.setVolume(0.5)   // Set volume (0.0-1.0)
player.getVolume()      // Get current volume
player.mute()           // Mute audio
player.unmute()         // Unmute audio
player.toggleMute()     // Toggle mute state

Hinweis zu Mobilgeräten: Auf Touch-Geräten (iOS, Android, Tablets) wird anstelle des Lautstärkereglers nur eine Schaltfläche zum Stummschalten/Entstummschalten angezeigt. Mobile Browser regeln die Lautstärke von HTML5-Videos über die Lautstärketasten des Geräts – dies ist ein Standardverhalten, das aus Sicherheitsgründen von Web-Apps nicht außer Kraft gesetzt werden kann. Die Stummschalttaste dient zum schnellen Stummschalten , während die Hardware-Tasten die tatsächliche Lautstärke regeln.

Wiedergabegeschwindigkeit

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

Vollbild

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

Hinweis zu iOS/Mobile Safari: Da iOS die Vollbild-API für Container-Elemente nicht unterstützt, wechselt VidPly automatisch in einen „Pseudo-Vollbild“-Modus, bei dem der Player mithilfe von CSS so positioniert wird, dass er den gesamten Darstellungsbereich ausfüllt. Dies sorgt auf iOS-Geräten für ein vollbildähnliches Erlebnis, wobei alle Funktionen des Players erhalten bleiben.

Untertitel

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

// Switch between caption tracks
player.captionManager.switchTrack(0)  // Switch to first track
player.captionManager.getAvailableTracks()  // Get all tracks

Transkript

// Show/Hide Transcript
player.transcriptManager.showTranscript()     // Show transcript window
player.transcriptManager.hideTranscript()     // Hide transcript window
player.transcriptManager.toggleTranscript()   // Toggle transcript visibility

// Drag & Resize Modes (Desktop only, mobile breakpoint: 768px)
player.transcriptManager.toggleKeyboardDragMode()   // Toggle drag mode (D key)
player.transcriptManager.toggleResizeMode()         // Toggle resize mode (R key)

// Settings Menu
player.transcriptManager.showSettingsMenu()    // Show settings dropdown
player.transcriptManager.hideSettingsMenu()    // Hide settings dropdown

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

Audiodeskription

player.enableAudioDescription()   // Switch to described version
player.disableAudioDescription()  // Switch back to original
player.toggleAudioDescription()   // Toggle audio description

Gebärdensprache

// Show/Hide Sign Language Video
player.enableSignLanguage()   // Show sign language overlay
player.disableSignLanguage()  // Hide sign language overlay
player.toggleSignLanguage()   // Toggle sign language

// Multi-Language Support
player.switchSignLanguage('de')  // Switch to German sign language

// Drag & Resize (available via settings menu or keyboard)
// D key - Toggle drag mode with arrow keys
// R key - Toggle resize mode (shows resize handles)
// Home key - Reset position
// Escape - Exit drag/resize mode

Wiedergabelisten

import { Player, PlaylistManager } from './dist/prod/vidply.esm.min.js';

// Create player
const player = new Player('#my-player');

// Create playlist manager
const playlist = new PlaylistManager(player, {
  autoAdvance: true,   // Auto-play next track
  loop: false,         // Loop back to start
  showPanel: true      // Show playlist UI
});

// Load tracks
playlist.loadPlaylist([
  {
    src: 'track1.mp3',
    title: 'Track 1',
    artist: 'Artist Name',
    poster: 'thumb1.jpg'
  },
  {
    src: 'track2.mp3',
    title: 'Track 2',
    artist: 'Artist Name',
    tracks: [
      { src: 'captions.vtt', kind: 'captions', srclang: 'en' }
    ]
  }
]);

// Control playlist
playlist.next()         // Go to next track
playlist.previous()     // Go to previous track
playlist.goToTrack(2)   // Jump to specific track
playlist.hasNext()      // Check if next track exists
playlist.hasPrevious()  // Check if previous track exists

// Listen for track changes
player.on('playlisttrackchange', (e) => {
  // e: { index: number, item: PlaylistTrack, total: number, previousIndex?: number }
  console.log(`Now playing track ${e.index + 1} / ${e.total}:`, e.item.title);
});

Einstellungen

player.showSettings()  // Open settings dialog
player.hideSettings()  // Close settings dialog

Tastaturkürzel-Hilfe

player.toggleKeyboardHelp()  // Toggle the keyboard-shortcuts help dialog
player.showKeyboardHelp()    // Open the help dialog
player.hideKeyboardHelp()    // Close the help dialog

Der Dialog wird aus den aktuellen keyboardShortcuts Tastenbelegungen (einschließlich etwaiger Überschreibungen) und ist außerdem über die Hilfe-Schaltfläche in der Steuerleiste sowie über den Tastenkürzel „?“ erreichbar. Es werden nur Tastenkombinationen aufgelistet, die für den jeweiligen Player relevant sind: Tastenkombinationen für Funktionen (Untertitel, Untertitel-Stil, Wiedergabegeschwindigkeit, Qualität, Kapitel, Transkript, Vollbild) werden nur angezeigt, wenn die jeweilige Funktion tatsächlich verfügbar ist; daher werden bei einem reinen Audio-Player oder einem Video ohne Untertitel keine Tastenkombinationen angezeigt, die nicht ausgeführt werden können. Die Liste wird bei jedem Öffnen des Dialogfelds neu erstellt, sodass Funktionen, die später geladen werden (z. B. HLS-Untertitel oder Qualitätsstufen), erscheinen, sobald sie bereit sind.

Statusinformationen

player.getCurrentTime()  // Get current time
player.getDuration()     // Get duration
player.isPlaying()       // Check if playing
player.isPaused()        // Check if paused
player.isEnded()         // Check if ended
player.isMuted()         // Check if muted
player.isFullscreen()    // Check if fullscreen

Ereignis-Listener

player.on('ready', () => {})
player.on('play', () => {})
player.on('pause', () => {})
player.on('ended', () => {})
player.on('timeupdate', (time) => {})
player.on('volumechange', (volume) => {})
player.on('playbackspeedchange', (speed) => {})
player.on('fullscreenchange', (isFullscreen) => {})
player.on('hlsmanifestparsed', (data) => {})
player.on('dashqualitychanged', (data) => {})
player.on('textcuesupdate', () => {})
player.on('captionsenabled', (track) => {})
player.on('captionsdisabled', () => {})
player.on('error', (error) => {})

Bereinigung

player.destroy()  // Remove player and cleanup

Anpassung

Individuelles Styling

VidPly bietet umfangreiche CSS-Variablen für eine einfache Anpassung:

/* Override default colors and sizing */
.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;
}

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

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

Benutzerdefinierte Sprache hinzufügen

Option 1: Von URL laden (empfohlen)

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

Option 2: JavaScript-API

import { i18n } from './src/i18n/i18n';

// Load language file from URL
await i18n.loadLanguageFromUrl('pt', 'languages/pt.json');

// Or load multiple languages
await i18n.loadLanguagesFromUrls({
  'pt': 'languages/pt.json',
  'it': 'languages/it.json'
});

// Set the language
i18n.setLanguage('pt');

Option 3: Übersetzungen programmgesteuert hinzufügen

import { i18n } from './src/i18n/i18n';

i18n.addTranslation('pt', {
  player: {
    play: 'Reproduzir',
    pause: 'Pausar',
    mute: 'Silenciar',
    unmute: 'Ativar som'
  }
});

i18n.setLanguage('pt');

Format der Sprachdatei

Erstellen languages/pt.json:

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

Der Player unterstützt sowohl das JSON- als auch das YAML-Format für Sprachdateien.

Build-Prozess

VidPly verwendet ein modernes Build-System mit esbuild für das TypeScript-Bundling, den TypeScript-Compiler für .d.ts Deklarationen sowie „clean-css“ für CSS.

Verfügbare Skripte

npm run build        # Build everything (JS + types + CSS)
npm run build:js     # Bundle TypeScript with esbuild (ESM + IIFE)
npm run build:types  # Emit type declarations to dist/types/
npm run build:css    # Build CSS only
npm run typecheck    # Run tsc --noEmit
npm run watch        # Watch mode for development
npm run clean        # Clean dist directory
npm run dev          # Start dev server
npm run test         # Run unit tests (Vitest)
npm run test:e2e     # Run end-to-end tests (Playwright)
npm run test:all     # Run all tests

Ausgabedateien

dist/dev/vidply.esm.js - ES-Modul (Entwicklung)
dist/prod/vidply.esm.min.js - ES-Modul (Produktion)
dist/legacy/vidply.js - IIFE (Entwicklung)
dist/legacy/vidply.min.js - IIFE (Produktionsumgebung)
dist/types/index.d.ts - TypeScript-Deklarationen
dist/vidply.css - Stile (unminifiziert)
dist/vidply.min.css - Stile (minifiziert)

Ausführliche Informationen zur Build-Dokumentation finden Sie in der Datei „BUILD.md“.

Browser-Unterstützung

Die Bibliothek wird in zwei Bundles bereitgestellt. Wählen Sie dasjenige aus, das zu Ihrer Zielgruppe passt:

Modernes ESM-Bundle (dist/prod/vidply.esm.min.js) – empfohlen.

Chrome 100+
Firefox 100+
Safari 15+
Edge 100+
iOS Safari 15+
Android Chrome 100+

Legacy-IIFE-Paket (dist/legacy/vidply.min.js) – zur Unterstützung älterer Browser.

Chrome 80+
Firefox 78+
Safari 14+
Edge 88+

Die TypeScript-Deklarationen sind auf ES2022 ausgerichtet; beide Bundles werden mit esbuild + Terser erstellt. Die genauen Ziele finden Sie in der Datei Build-Anleitung.

Lizenz

GNU General Public License v2.0 oder höher

Dieses Programm ist freie Software; Sie können es weitergeben und/oder verändern unter den Bedingungen der GNU General Public License, wie sie von der Free Software Foundation veröffentlicht wurde; entweder Version 2 der Lizenz oder (nach Ihrer Wahl) jede spätere Version.

Den vollständigen Lizenztext finden Sie in der Datei LICENSE.

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.

Dokumentation

Anleitungen

Benutzerhandbuch – Umfassende Integrationsanleitung für Webentwickler
Schnellstart für Entwickler – Kurzreferenz für Mitwirkende

Referenz

Einführungshandbuch – Grundlegende Einrichtung und Verwendung
Anwendungshandbuch – Detaillierte Anwendungsbeispiele
Anleitung zu Wiedergabelisten – Audio-/Video-Wiedergabelisten mit Vollbildunterstützung
Leitfaden zu Transkripten – Interaktive Transkripte
Tastaturkürzel – Vollständige Tastaturreferenz
Anleitung zum Erstellen – Build-System und Entwicklung
Änderungsprotokoll – Versionshistorie und Updates

Danksagungen

Inspiriert von:

AblePlayer – Barrierefreiheitsfunktionen
MediaElement.js – Streaming-Unterstützung

Erstellt mit Vanilla JavaScript von Matthias Peltzer

Dokumentation

Live-Demos

Warum VidPly?

Funktionen

Kernunterstützung für Medien

Barrierefreiheitsfunktionen (konform mit WCAG 2.2 AA)

Bildunterschriften & Untertitel

Wiedergabefunktionen

Internationalisierung

Installation

Aus dem Quellcode kompilieren

Option 1: Verwendung der kompilierten Dateien (für die Produktion empfohlen)

Option 2: Herkömmliches Script-Tag (IIFE)

Option 3: Entwicklung (TypeScript-Quelldateien)

Schnellstart

1. Erstellen Sie den Player

2. Fügen Sie ihn Ihrer Seite hinzu

3. Erstellen Sie einen Videoplayer

YouTube-Player

Vimeo-Player

Audio-Player

HLS-Streaming

DASH-Streaming

SoundCloud

Download-Schaltfläche

Benutzerdefinierter schwebender Player (Miniplayer)

DASH + HLS + MP4-Fallback

Konfigurationsoptionen

Tastaturkürzel

API-Referenz

Wiedergabesteuerung

Lautstärkeregelung

Wiedergabegeschwindigkeit

Vollbild

Untertitel

Transkript

Audiodeskription

Gebärdensprache

Wiedergabelisten

Einstellungen

Tastaturkürzel-Hilfe

Statusinformationen

Ereignis-Listener

Bereinigung

Anpassung

Individuelles Styling

Benutzerdefinierte Sprache hinzufügen

Option 1: Von URL laden (empfohlen)

Option 2: JavaScript-API

Option 3: Übersetzungen programmgesteuert hinzufügen

Format der Sprachdatei

Build-Prozess

Verfügbare Skripte

Ausgabedateien

Browser-Unterstützung

Lizenz

Mitwirken

Dokumentation

Anleitungen

Referenz

Danksagungen

Seite teilen