Zum Inhalt springen

Erste Schritte mit VidPly

Willkommen! Diese Anleitung hilft Ihnen dabei, VidPly in 5 Minuten einzurichten und in Betrieb zu nehmen.

VidPly Logo

Voraussetzungen

  • Node.js 18+ muss installiert sein
  • Ein Texteditor
  • Ein moderner Webbrowser

Schnellinstallation

1. Code herunterladen

 
git clone github.com/MatthiasPeltzer/vidply.git
cd vidply
 

2. Abhängigkeiten installieren

 
npm install
 

Dadurch wird Folgendes installiert:

  • esbuild - Schneller TypeScript-/JavaScript-Bundler
  • typescript - Strenge Typprüfung und .d.ts Generierung
  • clean-css - CSS-Minifier
  • vitest + @playwright/test - Unit- und End-to-End-Tests

3. Erstellen des Players

 
npm run build
 

Dadurch werden produktionsreife Dateien erstellt in dist/:

  • prod/vidply.esm.min.js - Minifiziertes ES-Modul (für die Produktion empfohlen)
  • legacy/vidply.min.js - Minifiziertes IIFE-Bundle (globale VidPly)
  • types/index.d.ts - TypeScript-Typdeklarationen für IDE / tsc Anwender
  • vidply.min.css - Minifizierte Stile (~12 KB)

4. Demo ansehen

 
npm run dev
 

Öffnen Sie http://localhost:3000/demo/, um VidPly in Aktion zu sehen!

Ihr erster Videoplayer

Erstellen index.html

 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Video Player</title>
  <link rel="stylesheet" href="dist/vidply.min.css">
</head>
<body>
  <h1>My Video Player</h1>
  
  <video 
    data-vidply 
    width="800" 
    height="450"
    poster="poster.jpg"
  >
    <source src="video.mp4" type="video/mp4">
    <track 
      kind="captions" 
      src="captions.vtt" 
      srclang="en" 
      label="English"
    >
  </video>

  <script type="module">
    import Player from './dist/prod/vidply.esm.min.js';
    // That's it! Player auto-initializes
  </script>
</body>
</html>
 

Testen

 
# Start a local server
npm run dev

# Or use Python
python -m http.server 3000

# Or use PHP
php -S localhost:3000
 

Öffnen Sie http://localhost:3000 in Ihrem Browser.

Schnellstart in 3 Schritten

Wenn du die Quelldateien einfach direkt nutzen möchtest, ohne sie zu kompilieren:

Schritt 1: Fügen Sie das CSS ein

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

Schritt 2: Fügen Sie Ihr Video hinzu

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

Schritt 3: Importieren Sie den Player

 
<script type="module">
  import Player from './src/index.js';
</script>
 

Das war’s schon!

Einfache Beispiele

Beispiel 1: Einfaches Video

 
<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="src/styles/vidply.css">
</head>
<body>
  <video data-vidply src="video.mp4" width="800" height="450"></video>
  
  <script type="module">
    import Player from './src/index.js';
  </script>
</body>
</html>
 

Beispiel 2: Audio-Player

 
<audio data-vidply>
  <source src="music.mp3" type="audio/mpeg">
  <track kind="captions" src="lyrics.vtt" srclang="en" label="Lyrics">
</audio>
 

Beispiel 3: YouTube-Video

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

Beispiel 4: Vimeo-Video

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

Beispiel 5: SoundCloud-Titel

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

Beispiel 6: HLS-Streaming

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

Beispiel 7: DASH-Streaming

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

Beispiel 8: Mit Download-Button

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

Beispiel 9: Mit dem benutzerdefinierten schwebenden Player

Aktivieren Sie den seiteninternen schwebenden Player („eigenes PiP“). Wenn die Originalseite aus dem Ansichtsbereich herausgescrollt wird, blendet VidPly das Video in einer verschiebbaren und in der Größe anpassbaren schwebenden Hülle in der ausgewählten Ecke ein; wenn die Seite wieder in den Ansichtsbereich zurückgescrollt wird, wird der Player wieder angedockt. Über die PiP- Schaltfläche in der Steuerleiste lässt sich die schwebende Hülle manuell anheften bzw. lösen. Die native PiP-Funktion des Browsers wird automatisch unterdrückt, solange der schwebende Modus aktiviert ist.

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

Audioplayer ignorieren floating. Die Funktion ist unterhalb floatingMinViewportWidth (Standard 768px) und die PiP-Schaltfläche für den schwebenden Player erscheint nie im Überlaufmenü.

 

Beispiel 10: Mit Optionen

 
<video 
  data-vidply 
  data-vidply-options='{"autoplay": true, "loop": true, "muted": true}'
  src="video.mp4"
></video>
 

Beispiel 11: Manuelle Initialisierung

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

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

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

  player.on('ready', () => {
    console.log('Player is ready!');
  });
</script>
 

Arbeiten Sie mit TypeScript? Importieren Sie direkt aus dem Quellcode-Verzeichnis (import Player from 'vidply') – VidPly liefert eigene .d.ts Deklarationen mit, sodass Sie volle Typsicherheit bei PlayerOptions, bei Ereignissen und bei den Renderer-APIs.

 

Konfiguration

Über Datenattribute

 
<video 
  data-vidply 
  data-vidply-options='{
    "autoplay": true,
    "loop": true,
    "volume": 0.5,
    "language": "de"
  }'
  src="video.mp4"
></video>
 

Über JavaScript

 
const player = new Player('#my-video', {
  controls: true,
  autoplay: false,
  loop: false,
  volume: 0.8,
  playbackSpeed: 1.0,
  captions: true,
  captionsDefault: true,
  keyboard: true,
  language: 'en',
  responsive: true
});
 

Allgemeine Optionen

 
{
  // Playback
  autoplay: false,      // Auto-start playback
  loop: false,          // Loop video
  muted: false,         // Start muted
  volume: 0.8,          // Volume (0-1)
  playbackSpeed: 1.0,   // Speed (0.25-2.0)
  
  // Display
  responsive: true,     // Responsive sizing
  controls: true,       // Show controls
  
  // Captions
  captions: true,       // Enable captions
  captionsDefault: false, // Show captions by default
  
  // Accessibility
  keyboard: true,       // Keyboard shortcuts
  
  // Language
  language: 'en'        // UI language (en, es, fr, de, ja)
}
 

Mehrsprachige Bildunterschriften

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

So funktioniert es:

  • Klicken Sie auf die Schaltfläche „CC“, um das Untertitelmenü zu öffnen
  • Wählen Sie Ihre bevorzugte Sprache aus
  • Oder drücken Sie die Taste „C“, um das Menü zu öffnen (sofern mehrere Tonspuren verfügbar sind)
  • Die aktive Tonspur ist mit einem Häkchen markiert

Untertitel erstellen (WebVTT)

Erstellen Sie eine Datei mit dem Namen captions.vtt:

 
WEBVTT

00:00:00.000 --> 00:00:05.000
Welcome to my video!

00:00:05.000 --> 00:00:10.000
This is how captions work.

00:00:10.000 --> 00:00:15.000
Pretty easy, right?
 

Steuerung des Players

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

// Playback
player.play();
player.pause();
player.stop();
player.seek(60);  // Jump to 1 minute

// Volume
player.setVolume(0.5);  // 50% volume
player.mute();
player.unmute();

// Speed
player.setPlaybackSpeed(1.5);  // 1.5x speed

// Fullscreen
player.enterFullscreen();
player.exitFullscreen();

// Captions
player.enableCaptions();
player.disableCaptions();

// Events
player.on('play', () => console.log('Playing!'));
player.on('pause', () => console.log('Paused'));
player.on('ended', () => console.log('Finished'));
player.on('timeupdate', (time) => {
  console.log('Current time:', time);
});
 

Tastaturkürzel

Sobald der Player aktiv ist:

  • Leertaste / P / K – Abspielen/Pause
  • F – Vollbild
  • M – Stummschalten/Stummschaltung aufheben
  • ↑ / ↓ – Lautstärke erhöhen/verringern
  • ← / → – 10 Sekunden vor-/zurückspringen
  • C – Untertitel ein-/ausschalten
  • A – Menü für Untertitelstil öffnen
  • < / > – Wiedergabegeschwindigkeit verringern/erhöhen
  • S – Menü „Wiedergabegeschwindigkeit“ öffnen
  • Q – Qualitätsmenü öffnen
  • J – Kapitelmenü öffnen
  • T – Transkript ein-/ausschalten
  • D – Drag-Modus umschalten (Transkript/Gebärdensprache)
  • R – Größenänderungsmodus umschalten (Transkript/Gebärdensprache)
  • Home – Position zurücksetzen (Transkript/Gebärdensprache)
  • Esc – Modus beenden oder Menü schließen

Stile anpassen

CSS-Variablen überschreiben

 
.vidply-player {
  --vidply-primary-color: #ff0000;
  --vidply-background: rgba(0, 0, 0, 0.9);
}
 

Benutzerdefinierter Fortschrittsbalken

 
.vidply-progress-played {
  background: linear-gradient(90deg, #ff0000, #ff00ff);
}
 

Benutzerdefinierter Hover-Effekt für Schaltflächen

 
.vidply-button:hover {
  background: rgba(255, 0, 0, 0.2);
}
 

Sprache ändern

Integrierte Sprachen

VidPly enthält Übersetzungen für 5 Sprachen:

  • en - Englisch
  • es - Spanisch (Español)
  • fr - Französisch (Français)
  • de - Deutsch
  • ja - Japanisch (日本語)
const player = new Player('#video', {
  language: 'de'  // German UI
});
 

Benutzerdefinierte Übersetzungen

Sie können eigene Übersetzungen hinzufügen, indem Sie Sprachdateien über URLs laden. Der Player unterstützt die Formate JSON und YAML.

Verwendung von Datenattributen

Mehrere Sprachdateien laden:

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

Eine einzelne Sprachdatei laden:

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

Oder separate Attribute verwenden:

 
<video 
  data-vidply 
  data-vidply-language-file-code="pt"
  data-vidply-language-file-url="languages/pt.json"
  src="video.mp4"
></video>
 

Verwendung von JavaScript-Optionen

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

Sprachdateiformat (JSON)

Datei erstellen languages/pt.json:

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

Automatische Erkennung aus HTML

Der Player erkennt die Sprache automatisch anhand des HTML-Attributs lang -Attribut, sofern eine passende Übersetzung verfügbar ist:

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

Programmgesteuertes Laden von Übersetzungen

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

// Load a language file
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');
 

Entwicklungsmodus

Debug-Protokollierung aktivieren:

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

Überprüfen Sie die Browserkonsole auf detaillierte Protokolle.

Bereitstellungsoptionen

Option 1: ES-Modul (moderne Browser)

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

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

 
<link rel="stylesheet" href="dist/vidply.min.css">
<script src="dist/legacy/vidply.min.js"></script>
<script>
  const player = new VidPly.Player('#video');
</script>
 

Option 3: CDN (zukünftig)

 
<!-- Will be available after publishing to npm -->
<link rel="stylesheet" href="https://cdn.example.com/vidply@1.0.0/vidply.min.css">
<script type="module">
  import Player from 'https://cdn.example.com/vidply@1.0.0/vidply.esm.min.js';
</script>
 

Optimierung für Mobilgeräte

VidPly ist standardmäßig mobilfreundlich und verwendet einen mobilen Breakpoint bei 768px. Für optimale Ergebnisse:

 
<meta name="viewport" content="width=device-width, initial-scale=1.0">
 

Und nutzen Sie den responsiven Modus:

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

Mobilgerätespezifisches Verhalten (Breakpoint < 768px):

  • Das Transkriptfenster erscheint unterhalb des Videos (nicht verschiebbar/in der Größe veränderbar)
  • Das Gebärdensprachvideo lässt sich nicht verschieben oder in der Größe anpassen
  • Optimierte Steuerleiste mit Überlaufmenü für zahlreiche Schaltflächen
  • Touch-freundliche Benutzeroberfläche mit Touch-Zielen von mindestens 44px
  • Mindestbreite des Transkriptfensters: 300px

Barrierefreiheit

VidPly ist standardmäßig WCAG 2.2 AA-konform:

  • Vollständige Tastaturnavigation
  • Unterstützung von Bildschirmleseprogrammen
  • Hochkontrastmodus
  • Fokusanzeigen
  • ARIA-Labels

Keine zusätzliche Konfiguration erforderlich!

Fehlerbehebung

Video lässt sich nicht abspielen

  1. Überprüfen Sie die Konsole auf Fehler (drücken Sie F12)
  2. Überprüfen Sie, ob die Video-URL korrekt ist
  3. Überprüfen Sie die CORS-Header, wenn das Video von einer anderen Domain geladen wird
  4. Debug-Modus aktivieren: { debug: true }

Untertitel werden nicht angezeigt

  1. Überprüfen Sie, ob das VTT-Dateiformat korrekt ist
  2. Überprüfen Sie den Dateipfad
  3. Untertitel aktivieren: Klicken Sie auf die Schaltfläche „CC“
  4. Oder standardmäßig aktivieren: { captionsDefault: true }

Erstellung fehlgeschlagen

 
# Clean and rebuild
npm run clean
rm -rf node_modules
npm install
npm run build
 

Autoplay funktioniert nicht

Browser blockieren die automatische Wiedergabe mit Ton. Lösung:

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

Verfügbare Build-Skripte

 
npm run build        # Build everything
npm run build:js     # Build JS only
npm run build:css    # Build CSS only
npm run watch        # Watch mode for development
npm run clean        # Clean dist/
npm run dev          # Start dev server (port 3000)
npm start            # Alias for npm run dev
 

Dateistruktur

Nach dem Erstellen erhalten Sie:

 
vidply/
├── dist/
│   ├── dev/
│   │   └── vidply.esm.js       # ES Module (dev)
│   ├── prod/
│   │   └── vidply.esm.min.js   # ES Module (prod)
│   ├── legacy/
│   │   ├── vidply.js           # IIFE (dev)
│   │   └── vidply.min.js       # IIFE (prod)
│   ├── types/
│   │   └── index.d.ts          # TypeScript declarations
│   ├── vidply.css              # Styles (dev)
│   └── vidply.min.css          # Styles (prod)
└── ...
 

Nur in der Produktionsumgebung einbinden:

  • dist/prod/vidply.esm.min.js (oder dist/legacy/vidply.min.js)
  • dist/vidply.min.css

Insgesamt: ~62 KB unkomprimiert, ~18 KB gzipped

Streaming (HLS & DASH)

VidPly erkennt Streaming-Formate automatisch anhand der Dateiendung:

  • HLS (.m3u8) – Verwendet hls.js 1.6.16 in Chrome / Firefox / Edge / Desktop-Safari (CDN-Fallback, wenn nicht vorinstalliert). Unter iOS / iPadOS wird die native <video> HLS-Unterstützung genutzt und über die TextTrack API eingebunden.
  • DASH (.mpd) – Verwendet dash.js 5.2.0 (modernes UMD), das bei Bedarf geladen wird, sofern es nicht bereits auf der Seite vorhanden ist.
  • SoundCloud – Wird automatisch für jede URL erkannt, die soundcloud.com; die SoundCloud-Widget-API wird bei Bedarf geladen.
<!-- HLS -->
<video data-vidply src="https://example.com/stream.m3u8"></video>

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

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

Alle Formate unterstützen eine adaptive Qualitätsauswahl und Untertitel. DASH-Streams mit eingebetteten TTML-Untertiteln werden nativ von dash.js gerendert, während WebVTT-Untertitel vom Untertitelsystem von VidPly verarbeitet werden und zudem das interaktive Transkript unterstützen.

Nächste Schritte

Tipps

  1. Verwenden Sie immer einen lokalen Server – öffnen Sie HTML-Dateien nicht direkt (file://)
  2. Aktivieren Sie standardmäßig Untertitel für eine bessere Barrierefreiheit
  3. Verwenden Sie den responsiven Modus für die Unterstützung mobiler Geräte
  4. Testen Sie Tastaturkürzel, um die Barrierefreiheit sicherzustellen
  5. Überprüfen Sie die Browserkonsole auf hilfreiche Debug-Meldungen

Sie sind bereit!

Das war’s! Sie wissen nun, wie Sie:

  • VidPly installieren und erstellen
  • Video-/Audio-Player erstellen
  • Untertitel hinzuzufügen
  • Optionen konfigurieren
  • die Wiedergabe steuern
  • Stile anpassen

Viel Spaß beim Programmieren!

Brauchst du Hilfe? Schau in die README-Datei oder erstelle ein Issue.

Seite teilen