Zum Inhalt springen

Erste Schritte mit VidPly

Willkommen! Diese Anleitung hilft Ihnen dabei, VidPly in 5 Minuten einzurichten.

VidPly Logo

Voraussetzungen

  • Node.js 20+ installiert
  • 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 Ausgabe
  • clean-css - CSS-Minifier
  • vitest + @playwright/test - Unit- und End-to-End-Tests

3. Erstellen des Players

 
npm run build
 

Dadurch werden produktionsfertige 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 Nutzer
  • vidply.min.css - Minimierte Styles (~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 Sie die Quelldateien direkt verwenden möchten, 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 Floating-Player

Aktivieren Sie den seiteninternen Floating-Player („eigenes PiP“). Wenn das Original aus dem Sichtbereich herausgescrollt wird, blendet VidPly das Video in einer verschiebbaren, in der Größe anpassbaren Floating-Shell in der gewählten Ecke ein; wenn es wieder in den Sichtbereich zurückgescrollt wird, dockt der Player wieder an. Die PiP- Schaltfläche in der Steuerleiste fixiert die Floating-Shell manuell oder löst sie wieder. Das native Browser-PiP wird automatisch unterdrückt, solange das Floating 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>
 

Audio-Player ignorieren floating. Die Funktion ist unter floatingMinViewportWidth (Standard 768px) und die Schaltfläche für den schwebenden PiP-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 du volle Typsicherheit bei PlayerOptions, bei Ereignissen und bei Renderer-APIs.

 

Konfiguration

Über Datenattribut

 
<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 CC-Schaltfläche, um das Untertitelmenü zu öffnen
  • Wähle deine bevorzugte Sprache
  • Oder drücken Sie 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 im Fokus 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 Untertitelstile öffnen
  • < / > – Geschwindigkeit verringern/erhöhen
  • S – Geschwindigkeitsmenü öffnen
  • Q – Qualitätsmenü öffnen
  • J – Kapitelmenü öffnen
  • T – Transkript ein-/ausschalten
  • D – Drag-Modus umschalten (Transkript/Gebärdensprache)
  • R – Umschalten zwischen Größenänderungsmodus (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 Button-Hover

 
.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 , 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 (Zukunft)

 
<!-- 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 mit einem mobilen Breakpoint bei 768px. Für beste Ergebnisse:

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

Und verwenden Sie den Responsive-Modus:

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

Mobilgerätespezifisches Verhalten (< 768px Breakpoint):

  • Das Transkriptfenster erscheint unterhalb des Videos (nicht verschiebbar/in der Größe veränderbar)
  • Das Gebärdensprachvideo ist nicht verschiebbar/in der Größe veränderbar
  • Optimierte Steuerleiste mit Überlaufmenü für zahlreiche Schaltflächen
  • Touch-freundliche Oberflä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 Screenreadern
  • Modus für hohen Kontrast
  • 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 CC-Schaltfläche
  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 Produktion 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 in Chrome / Firefox / Edge / Desktop-Safari (automatisch vom CDN geladen). Auf iOS / iPadOS wird die native <video> HLS-Unterstützung verwendet und über die TextTrack API eingebunden.
  • DASH (.mpd) – Verwendet dash.js, automatisch vom CDN geladen.
  • 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 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 auch 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 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 hinzufügen
  • Optionen konfigurieren
  • die Wiedergabe steuern
  • Stile anpassen

Viel Spaß beim Programmieren!

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

Seite teilen