Schnellstart für Entwickler

Installation

composer require mpc/mpc-vidply

Anschließend:

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

Voraussetzungen: Nur TYPO3-Core, Fluid und Extbase — fluid_styled_content ist nicht erforderlich. Die Erweiterung verfügt über einen eigenen lib.mpcVidplyContentElement Renderer und ein Standard-Layout (Frame-Wrapper + tt_content Kopfzeile/Unterkopfzeile).

Optionale Anpassung: Wenn Ihr Site-Paket oder fluid_styled_content benutzerdefinierte Frame-/Header-Partials enthält, können Sie VidPly darauf verweisen:

lib.mpcVidplyContentElement.layoutRootPaths.10 = {$styles.templates.layoutRootPath}
lib.mpcVidplyContentElement.partialRootPaths.10 = {$styles.templates.partialRootPath}

Verzeichnisstruktur

mpc_vidply/
├── Classes/
│   ├── Backend/
│   │   ├── Controller/           # MediaImportAjaxController (URL import)
│   │   ├── Form/Element/           # MediaUrlImportElement
│   │   └── Preview/              # VidPlyPreviewRenderer
│   ├── Form/FormDataProvider/    # MediaUrlImportFormDataProvider
│   ├── Service/                  # MediaFromUrlService, MediaUrlNormalizer
│   └── 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/
│   │   └── Helper/ContentElement.typoscript  # lib.mpcVidplyContentElement
│   ├── ContentSecurityPolicies.php
│   ├── Icons.php
│   ├── JavaScriptModules.php
│   └── Services.yaml
├── Resources/
│   ├── Private/
│   │   ├── Language/             # XLF translations (en, de)
│   │   ├── Partials/VidPly/      # Modular template partials
│   │   ├── Layouts/              # Default content element layout
│   │   └── 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/
    ├── README.md                 # Documentation index (start here)
    ├── AssetLoading.md
    ├── Editors-Guide.md
    ├── HLS-Implementation.md
    ├── Integrations.md           # Vue/Swiper, CSP, mp-core JSON-LD
    ├── Listview.md
    ├── Partials.md
    ├── PrivacyLayer.md
    └── SettingsArchitecture.md

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

Einträge in der Medienbibliothek mit folgenden Typen: video, audio, youtube, vimeo, soundcloud

Schlüsselspalten:

Audiodeskription – Zuordnung der Player-Optionen

VidPlyProcessor Ordnet Medienfelder VidPly zu data-vidply-options:

Fallback-Hierarchie, wenn audioDescriptionMode ist auto:

1. Beschreibung des Video-Wechsels, wenn audio_description eingestellt ist
2. Andernfalls VTT-Sprache, falls eine VTT-Spur mit Untertiteln vorhanden ist
3. Andernfalls wird die AD-Schaltfläche ausgeblendet (keine gesprochene AD)

Die AD-Schaltfläche ist aktiviert, wenn entweder ein beschriftetes Video oder eine VTT-Spur mit Beschreibungen vorhanden ist.

SRT → WebVTT-Konvertierung

Für die Wiedergabe und Transkripte von VidPly ist WebVTT erforderlich. Die Erweiterung akzeptiert SubRip-Uploads (.srt) für Untertitel, Kapitel und alternative Audiodeskriptionsspuren (tx_desc_src_file).

Implementierung: SrtToVttConverter, SrtCaptionMigrationService, SrtCaptionConversionHook, ConvertSrtCaptionsUpgradeWizard.

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:

Erweiterungskonfiguration

Globale UI- und Sicherheitsstandards: Admin → Einstellungen → Erweiterungskonfiguration → mpc_vidply (ext_conf_template.txt).

Vollständige Referenz: SettingsArchitecture.md → Erweiterungskonfiguration.

Dynamische Inhalte und Integrationen

Vue, Swiper, CSP, mp-core JSON-LD-Zusammenführung, Theme-API: Integrationen.

Schnell-API nach PlaylistInit.js dem Laden:

window.VidPlyInit.scan(rootElement);
window.VidPlyInit.pauseOutside(activeSlide);
document.dispatchEvent(new CustomEvent('mpc:dynamic-content:ready', { detail: { root } }));

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

Listenansicht & Detailansicht (CE im Mediathek-Stil)

• 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 / Teilvorlagen: Templates/Listview.html, Partials/Listview/*.

Vorlagenstruktur

Hauptvorlage

Resources/Private/Templates/VidPly.html

Partials

Anpassung

Vorlagen in Ihrem Sitepackage überschreiben:

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 JavaScript, das für die aktuellen Medientypen benötigt wird:

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

Dateien

Initialisierung des Players

// 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 ein Einwilligungs-Overlay an:

1. PrivacySettingsService Ruft Einstellungen ab von tx_mpcvidply_privacy_settings Tabelle
2. Die Vorlage rendert das Poster und die Wiedergabetaste (kein Iframe) mit den Einstellungen aus der Datenbank
3. PrivacyLayer.js / PlaylistInit.js verarbeitet den Klick
4. Bei Einwilligung: 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']

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

Datenschutzerklärung anpassen

Empfohlen: Über das Backend konfigurieren (Listenmodul → Einstellungen für die 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 Dateiendung)
2. Bindet hls.min.js (nur bei Bedarf) – das VidPly-Bundle nutzt es in Chrome, Firefox, Edge und der Desktop-Version von Safari, um die volle Funktionsparität zu gewährleisten
3. In Safari unter iOS / iPadOS (wo MSE nicht verfügbar ist) greift VidPly automatisch auf natives HLS zurück und bindet die TextTrack API 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, wenn neue Untertitel-Fragmente für lange bzw. Live-Streams geladen werden

DASH:

1. Erkennt .mpd Quelle in Medien-Dateiverweisen (nach MIME-Typ oder Dateiendung)
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. Standardmäßig werden eingebettete Untertitel aus dem DASH-Manifest verwendet; lokale VTT-Dateien haben Vorrang

Priorität der Quellen: DASH → HLS → progressiv (MP4/WebM/MP3/OGG)

CSP-Konfiguration

Configuration/ContentSecurityPolicies.php Fügt Streaming-Domains und die von diesen verwendeten Schemata zur Whitelist hinzu 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 festlegen. data: ist erforderlich, da einige HLS-Varianten Init-Segmente / Untertitel inline als Daten-URIs einbetten.

 

Erweiterung von VidPly

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 den DataProcessor, um den neuen Typ zu verarbeiten

3. Erstellen eines Partials 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;

Strukturierte Daten (JSON-LD)

VidPly generiert schema.org strukturierte Daten für seine Medien aus, sodass Seiten für Google-Rich-Results für Video/Audio in Frage kommen. Die Ausgabe wird in der Seite <head>, nicht in der Vorlage für das „content“-Element.

• Was ausgegeben wird

  • Detailansichten und Einzelmedienseiten: ein VideoObject (oder AudioObject für audio/soundcloud).
  • Galerieseiten mit mehreren unterschiedlichen Medien: ein ItemList der eingebetteten VideoObject/AudioObject Knoten. Inline- mpc_vidply Player (einschließlich Wiedergabelisten) und mpc_vidply_listview Regale werden beide berücksichtigt und anhand ihrer Medien-UID in der Standardsprache dedupliziert.
  • Felder aus dem Mediendatensatz: name, description, duration (ISO 8601), thumbnailUrl, uploadDate, sowie contentUrl/embedUrl je nach Medientyp aufgelöst.

• contentUrl und adaptives Streaming: HLS/DASH-Manifeste sind keine progressiven Dateien, daher wird contentUrl für reine HLS-/DASH-Quellen ausgegeben (der embedUrl verweist weiterhin auf die Wiedergabeseite). Progressive MP4-/WebM-/MP3-/OGG-Quellen werden verwendet, sofern verfügbar.

• Auflösung der Wiedergabe-URL (in der Reihenfolge der Priorität): die auf einer Listenansicht (tx_mpcvidply_detail_page), ein mpc_vidply_detail Element auf derselben Seite, dann die siteweite erste Detailseite; andernfalls ein #media-<uid> Fragment auf der aktuellen Seite.

• Mit und ohne mp-core

  • Standalone: Ein eigenes <script type="application/ld+json"> wird gerendert, page.headerData unter Verwendung eines CSP-Nonce gerendert.
  • Bei mp_core geladen: Der Knoten wird in den mp-core @graph und über WebPage.mainEntityverknüpft, sodass nur ein einziges JSON-LD-Skript ausgegeben wird. Wenn mp-core kein brauchbares @grapherzeugt, greift VidPly auf ein eigenständiges Dokument zurück.

• Deaktivieren: Setzen Sie die Website-Einstellung structuredDataEnabled auf false , um das gesamte VidPly-JSON-LD für diese Website zu unterdrücken (standardmäßig aktiviert). Fügen Sie dies zu config/sites/<site>/config.yaml hin, falls Ihr Site-Set dies nicht definiert.

• Mit mp-core: Wenn mp-core JSON-LD ausgibt, fügt VidPly es in sein @graph. mp-core benötigt möglicherweise außerdem seo.schema.enabled — beide Schalter müssen auf „true“ gesetzt sein, damit der globale Pfad für strukturierte Daten von mp-core verwendet wird. Siehe Integrations.md → Strukturierte Daten.

Automatisierte Tests

Die Erweiterung enthält eine PHPUnit-Suite, die auf typo3/testing-framework:

• Unit-Tests (Tests/Unit/, Konfiguration phpunit.xml.dist) – schnell, ohne Datenbank.
• Funktionstests (Tests/Functional/, Konfiguration Build/FunctionalTests.xml) – testen den Datenbank-/FAL-Code (Repository, Services, Prozessoren) anhand einer echten Datenbank.

Einrichtung (einmalig)

Installieren Sie die entwicklungsspezifischen Abhängigkeiten der Erweiterung in einem eigenständigen .Build/ Verzeichnisbaum (ausgehend vom Stammverzeichnis der Erweiterung – dem Verzeichnis, das die composer.json):

composer install --working-dir=vendor/mpc/mpc-vidply
# or, in a path-repo checkout:
composer install --working-dir=mpcore/packages/mpc-vidply

Funktionstests benötigen die Berechtigung, temporäre db_* zu erstellen. Erteilen Sie diese Berechtigung einmalig dem Benutzer „DDEV“ db :

ddev exec 'mysql -uroot -proot -e "GRANT ALL ON \`db_%\`.* TO \`db\`@\`%\`; FLUSH PRIVILEGES;"'

Führen Sie

# Unit tests (replace EXT_ROOT with your checkout path)
ddev exec 'cd mpcore/packages/mpc-vidply && .Build/bin/phpunit -c phpunit.xml.dist'

# Functional tests (point typo3Database* at the DDEV `db` service)
ddev exec 'cd mpcore/packages/mpc-vidply && \
  typo3DatabaseDriver=mysqli typo3DatabaseHost=db typo3DatabaseName=db \
  typo3DatabaseUsername=db typo3DatabasePassword=db \
  .Build/bin/phpunit -c Build/FunctionalTests.xml'

Es sind auch Composer-Shortcuts definiert: composer test:unit und composer test:functional (der funktionale benötigt noch die typo3Database* Umgebungsvariablen vorangestellt werden).

Abdeckung

Aktivieren Sie einen Coverage-Treiber (ddev xdebug onoder pcov installieren) und fügen Sie ein Coverage-Flag hinzu:

ddev exec 'cd mpcore/packages/mpc-vidply && XDEBUG_MODE=coverage .Build/bin/phpunit -c phpunit.xml.dist --coverage-text --coverage-html .Build/coverage'

Weiterführende Informationen

Zielgruppenbasierte Navigation und die vollständige Dokumentenliste: Übersicht.

Externe Ressourcen

• TYPO3-Dokumentation
• HLS.js
• dash.js
• WebVTT-Validator
• WCAG 2.2-Richtlinien für Medien

Schnellübersicht

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.2.17 | TYPO3: 13.4+ / 14.x | PHP: ≥8.2