Schnellstart für Entwickler

🚀 Installation

composer require mpc/mpc-vidply

Dann:

1. Datenbankaktualisierung → Admin-Tools → Wartung → Datenbankstruktur analysieren
2. Site-Set hinzufügen → Site-Verwaltung → Sites → Ihre Site → Sets → Hinzufügen mpc/mpc-vidply
3. Caches leeren

📁 Verzeichnisstruktur

mpc_vidply/
├── Classes/
│   ├── Backend/
│   │   ├── Form/FieldWizard/     # MediaTypeFilterWizard
│   │   └── Preview/              # VidPlyPreviewRenderer
│   └── DataProcessing/           # VidPly, Listview, Detail processors
├── Configuration/
│   ├── Sets/mpc-vidply/          # Site Set (TYPO3 13.4+)
│   ├── TCA/
│   │   ├── tx_mpcvidply_media.php # Media record TCA
│   │   └── Overrides/
│   │       └── tt_content.php    # Content element TCA
│   ├── TypoScript/
│   ├── ContentSecurityPolicies.php
│   ├── Icons.php
│   ├── JavaScriptModules.php
│   └── Services.yaml
├── Resources/
│   ├── Private/
│   │   ├── Language/             # XLF translations (en, de)
│   │   ├── Partials/VidPly/      # Modular template partials
│   │   └── Templates/            # Main VidPly.html template
│   └── Public/
│       ├── Css/vidply.min.css
│       ├── Icons/
│       └── JavaScript/
│           ├── hls.min.js        # HLS streaming (loaded only when needed)
│           ├── dash.all.min.js   # DASH streaming (loaded only when needed)
│           ├── PlaylistInit.js   # Playlist logic
│           ├── PrivacyLayer.js   # GDPR consent (YouTube/Vimeo/SoundCloud)
│           └── vidply/           # Core player (compiled from TypeScript, ESM, code-split)
└── Documentation/
    ├── AssetLoading.md
    ├── HLS-Implementation.md
    ├── Partials.md
    ├── PrivacyLayer.md
    └── SettingsArchitecture.md

⚡ Site-Set

Aktivieren in config/sites/<site>/config.yaml:

dependencies:
  - mpc/mpc-vidply

Oder über das Backend: Website-Verwaltung → Websites → Sets → VidPly hinzufügen.

📦 Datenbanktabellen

tx_mpcvidply_media

Medienbibliotheksdatensätze mit folgenden Typen: video, audio, youtube, vimeo, soundcloud

Schlüsselspalten:

tx_mpcvidply_content_media_mm

MM-Beziehung zwischen tt_content und tx_mpcvidply_media.

tx_mpcvidply_privacy_settings

Siteweite Konfiguration der Datenschutzebene für externe Dienste (YouTube, Vimeo, SoundCloud).

Schlüsselspalten:

🎬 Inhaltselement

CType: mpc_vidply

TCA-Felder:

Optionen-Bitmaske

const AUTOPLAY        = 1;    // Auto-start playback
const LOOP            = 2;    // Loop content
const MUTED           = 4;    // Start muted
const CONTROLS        = 8;    // Show controls
const CAPTIONS_DEFAULT = 16;  // Captions on by default
const KEYBOARD        = 64;   // Enable keyboard shortcuts
const AUTO_ADVANCE    = 256;  // Auto-play next in playlist

// Default: 328 = CONTROLS + KEYBOARD + AUTO_ADVANCE

Hinweise:

• Die adaptive Größenanpassung ist immer aktiviert (kein Umschaltknopf).
• Die Transkription wird pro Mediendatensatz gesteuert (tx_mpcvidply_media.enable_transcript).

Option in Fluid aktivieren:

<f:if condition="{data.tx_mpcvidply_options} % 16 >= 8">
    <!-- Controls enabled -->
</f:if>

🔧 Datenverarbeitung

VidPlyProcessor

Verarbeitet Medienelemente für die Frontend-Darstellung.

TypoScript:

tt_content.mpc_vidply =< lib.contentElement
tt_content.mpc_vidply {
    templateName = VidPly
    dataProcessing {
        10 = Mpc\MpcVidply\DataProcessing\VidPlyProcessor
    }
}

Verfügbar in der Vorlage:

{mediaItems}           <!-- Array of processed media -->
{isPlaylist}           <!-- true if 2+ items -->
{hasLocalMedia}        <!-- Has video/audio (including HLS/DASH sources) -->
{hasExternalService}   <!-- Has YouTube/Vimeo/SoundCloud -->
{playerOptions}        <!-- Decoded options array -->
{privacySettings}      <!-- Privacy layer settings per service -->

Listview & Detail (Mediathek-artige CEs)

• ListviewProcessor — mpc_vidply_listview; erstellt listview.rows mit Karten, Paginierungsflags, Sortiervorgaben usw. Siehe Documentation/Listview.md (Routing, i18n, Editorfelder).
• DetailProcessor — mpc_vidply_detail; erstellt detail.* und Player- Daten für die Detailseite. Vorlage: Detail.html + Listview CSS, wenn gemeinsam genutzt. Das zugehörige Regal wird nur geladen, wenn tt_content.tx_mpcvidply_show_related aktiviert ist (Standard 1); bei Deaktivierung detail.related ist es leer.

Vorlagen / Partials: Templates/Listview.html, Partials/Listview/*.

🎨 Vorlagenstruktur

Hauptvorlage

Resources/Private/Templates/VidPly.html

Partials

Anpassung

Überschreiben Sie Vorlagen in Ihrem Sitepackage:

tt_content.mpc_vidply {
    templateRootPaths.20 = EXT:my_sitepackage/Resources/Private/Templates/
    partialRootPaths.20 = EXT:my_sitepackage/Resources/Private/Partials/
}

📜 JavaScript-Architektur

Bedingtes Laden

VidPly lädt nur das für die aktuellen Medientypen benötigte JavaScript:

Bis zu 97 % Reduzierung bei ausschließlich externen Inhalten.

Dateien

Player-Initialisierung

// This is roughly what `PlaylistInit.js` does internally:
import { Player, PlaylistManager } from './vidply/vidply.esm.min.js';

const player = new Player('#my-player', {
    controls: true,
    keyboard: true,
    responsive: true,
});

// Optional: attach a playlist
const playlist = new PlaylistManager(player, { autoAdvance: true });

🔒 Datenschutzebene

Implementierung

Externe Dienste (YouTube, Vimeo, SoundCloud) zeigen Einwilligungs-Overlay an:

1. PrivacySettingsService Ruft Einstellungen ab von tx_mpcvidply_privacy_settings Tabelle
2. Vorlage rendert Poster + Wiedergabetaste (kein Iframe) mit Datenbankeinstellungen
3. PrivacyLayer.js / PlaylistInit.js verarbeitet Klick
4. Bei Zustimmung: Erstellt Iframe, lädt den Player des Dienstes
5. Kein Tracking, bis der Nutzer explizit auf „Wiedergabe“ klickt

Datenschutzeinstellungen-Dienst

Classes/Service/PrivacySettingsService.php bietet:

$privacySettings = $privacySettingsService->getSettingsForService('youtube', $languageId);
// Returns: ['headline', 'intro_text', 'outro_text', 'policy_link', 'link_text', 'button_label']

Einstellungen greifen auf Übersetzungen aus der Sprachdatei zurück, wenn Datenbankfelder leer sind.

Datenschutzerklärung anpassen

Empfohlen: Über das Backend konfigurieren (List-Modul → Einstellungen für Datenschutzebene)

Oder Vorlage überschreiben: Partials/VidPly/PrivacyLayer.html

<div class="vidply-privacy-layer" 
     data-service="{service}" 
     data-embed-url="{embedUrl}">
    <f:if condition="{privacySettings.headline}">
        <h3>{privacySettings.headline}</h3>
    </f:if>
    <img src="{poster}" alt="{title}" />
    <button class="vidply-privacy-play">
        {privacySettings.button_label}
    </button>
    <p class="vidply-privacy-notice">
        {privacySettings.intro_text}
        <a href="{privacySettings.policy_link}">{privacySettings.link_text}</a>
        {privacySettings.outro_text}
    </p>
</div>

🌐 HLS- und DASH-Streaming

HLS und DASH sind keine separaten Medientypen. Streaming-Quellen (.m3u8 / .mpd) werden als Dateien innerhalb des Medientyps „Video“ oder „Audio“ zusammen mit progressiven Fallbacks hinzugefügt.

So funktioniert es

HLS:

1. Erkennt .m3u8 Quelle in Medien-Dateiverweisen (nach MIME-Typ oder Erweiterung)
2. Bindet hls.min.js (nur bei Bedarf) – das VidPly-Bundle nutzt dies in Chrome / Firefox / Edge / Desktop-Safari für vollständige Funktionsparität
3. Auf iOS / iPadOS Safari (wo MSE nicht verfügbar ist) greift VidPly automatisch auf natives HLS zurück und bindet die TextTrack in die VidPly-Menüs für Untertitel, Transkripte und Qualität ein – es ist kein separater Codepfad erforderlich
4. Bietet eine Benutzeroberfläche zum Wechseln der Qualität
5. Eingebettete Untertitel aus dem HLS-Manifest werden standardmäßig verwendet; lokale VTT-Dateien haben Vorrang
6. Der HLS-Renderer reagiert zudem auf Hls.Events.SUBTITLE_FRAG_PROCESSED, sodass das interaktive Transkript synchron bleibt, während neue Untertitel-Fragmente für lange / Live-Streams geladen werden

DASH:

1. Erkennt .mpd Quelle in Medien-Dateiverweisen (nach MIME-Typ oder Erweiterung)
2. Bezieht dash.all.min.js (nur bei Bedarf)
3. Initialisiert dash.js für Video-/Audio-Elemente
4. Bietet Unterstützung für adaptive Qualität sowie TTML- und WebVTT-Untertitel
5. Eingebettete Untertitel aus dem DASH-Manifest werden standardmäßig verwendet; lokale VTT-Dateien haben Vorrang

Quellenpriorität: DASH → HLS → progressiv (MP4/WebM/MP3/OGG)

CSP-Konfiguration

Configuration/ContentSecurityPolicies.php Setzt Streaming-Domains und die von hls.js / dash.js.

Benutzerdefinierte Domänen hinzufügen:

return [
    'default-src' => ["'self'"],
    'media-src' => ["'self'", 'blob:', 'data:', 'https://your-cdn.com'],
    'connect-src' => ["'self'", 'https://your-cdn.com'],
];

 

blob: ist erforderlich, da hls.js / dash.js ein blob: URL während <video>.src während der Wiedergabe. data: ist erforderlich, da einige HLS-Varianten Init-Segmente / Untertitel inline als Daten-URIs einbetten.

 

🛠️ VidPly erweitern

Benutzerdefinierten Medientyp hinzufügen

1. TCA erweitern (Configuration/TCA/Overrides/tx_mpcvidply_media.php):

$GLOBALS['TCA']['tx_mpcvidply_media']['columns']['media_type']['config']['items'][] = [
    'label' => 'My Service',
    'value' => 'myservice',
];

$GLOBALS['TCA']['tx_mpcvidply_media']['types']['myservice'] = [
    'showitem' => '...',
];

2. Aktualisieren Sie DataProcessor, um den neuen Typ zu verarbeiten

3. Erstellen Sie ein Partial für die Darstellung

Benutzerdefinierte Player-Optionen

Hinzufügen zu tt_content.php:

$GLOBALS['TCA']['tt_content']['columns']['tx_mpcvidply_options']['config']['items'][] = [
    'label' => 'My Option',
    'value' => 512,  // Next power of 2
];

🐛 Debugging

Häufige Probleme

Nützliche Abfragen

-- Check media records
SELECT uid, title, media_type, hidden FROM tx_mpcvidply_media;

-- Check MM relations
SELECT * FROM tx_mpcvidply_content_media_mm WHERE uid_local = [tt_content.uid];

-- Check file references
SELECT * FROM sys_file_reference WHERE tablenames = 'tx_mpcvidply_media';

Debug-Modus

Aktivieren Sie den TYPO3-Debug-Modus, um detaillierte Fehler anzuzeigen:

$GLOBALS['TYPO3_CONF_VARS']['BE']['debug'] = true;
$GLOBALS['TYPO3_CONF_VARS']['FE']['debug'] = true;

📚 Dokumentationsindex

🔗 Externe Ressourcen

• TYPO3-Dokumentation
• HLS.js
• dash.js
• WebVTT-Validator
• WCAG 2.2 Medienrichtlinien

Schnellreferenz

Installieren

composer require mpc/mpc-vidply
# → Database update → Include Site Set → Clear caches

Wichtige Dateien

Datenbank

-- Tables
tx_mpcvidply_media          -- Media library
tx_mpcvidply_content_media_mm -- Content-to-media relation
tx_mpcvidply_privacy_settings -- Privacy layer configuration

Version: 1.1.3 | TYPO3: 13.4+ / 14.x | PHP: ≥8.2