Integrations

Dynamic content (Vue, Swiper, AJAX)

VidPly will DOMContentLoaded. If your website subsequently inserts player mark-up (Vue v-html, Swiper slide clones, Turbo, etc.), call the public scan API so that new [data-vidply-init] / [data-playlist] elements are detected.

Rescan after HTML integration

PlaylistInit.js and PrivacyLayer.js listen for both:

document.dispatchEvent(new CustomEvent('mpc:dynamic-content:ready', {
  detail: { root: containerElement }  // Element or Document fragment to scan
}));

Or call directly:

window.VidPlyInit.scan(containerElement);

• containerElement — Root of the newly inserted HTML code (a slide, a modal or document for a full rescan).
• Duplicate swiper slides (.swiper-slide-duplicate) are skipped by default so that the cloned DOM does not initialise the players twice.

Pause players on inactive slides

When switching between Swiper slides (or similar), players that are no longer visible are paused:

window.VidPlyInit.pauseOutside(activeSlideElement);

This pauses all initialised players whose <video> / wrapper is located outside the specified container.

Late-loaded scripts

If VidPly assets are loaded after Vue has already rendered the slides, PlaylistInit.js a catch-up process is carried out when the module is executed (catchUpVueContainers). For reliability reasons, however, mpc:dynamic-content:ready after every dynamic update to ensure reliability.

Debug

Ensure window.VIDPLY_DEBUG = true before loading the VidPly scripts so that all VidPly console logs remain visible.

Theme synchronisation (dark / light)

Extension configuration (Admin → Settings → Extension Configuration → mpc_vidply):

If design synchronisation is enabled, the player adapts to the page’s light/dark mode (changes to the body class and custom events).

Programmatic API (after PlaylistInit.js loading):

window.VidPlyTheme.setTheme('dark');   // or 'light'
window.VidPlyTheme.getPlayers();       // alive Player instances
window.VidPlyTheme.detectPageTheme();  // read current page theme

See ‘Settings architecture’ → ‘Extension configuration’.

Content Security Policy (CSP)

VidPly records CSP changes in Configuration/ContentSecurityPolicies.php and extends connect-src via PolicyMutatedEvent for streaming CDNs.

Streaming (HLS / DASH)

Required for adaptive streaming in modern browsers:

• media-src: blob:, data:, https: (as well as 'self')
• worker-src: blob:
• connect-src: blob:, data:, https: (retrieval of segments/manifests)

Details and troubleshooting: Implementation of HLS and DASH streaming.

Included scripts

mpc-vidply provides hls.js and dash.js at Resources/Public/JavaScript/. The TYPO3 extension does not require a CDN script source (since v1.2.6).

mp-core and inline nonces

On websites using mp-core, inline <script> / <style> blocks may contain CSP nonces script-src / style-src. VidPly ensures nonceProxy is preserved, so that script-src-elem / style-src-elem theme bootstrap and structured data blocks are not blocked when VidPly is present (v1.2.7).

If you customise the CSP in your website package, ensure that the streaming directives mentioned above are not overridden without incorporating VidPly’s requirements.

Structured data (JSON-LD) with mp-core

VidPly provides schema.org VideoObject / AudioObject (or ItemList on pages with multiple videos) from page.headerData.2042.

Standalone (mpc-vidply only)

A special <script type="application/ld+json"> is rendered if media is present. Disable via the website setting:

# config/sites/<site>/config.yaml
settings:
  structuredDataEnabled: false

If your website does not contain a site setting that defines this key, add it manually – mpc-vidply reads structuredDataEnabled with default value true.

When mp-core is installed

When mp-core is loaded and a JSON-LD is generated @graph, VidPly inserts its video node into this graph and sets WebPage.mainEntity (a single script tag). If mp-core does not provide a usable graph, VidPly falls back to its standalone output.

On mp-core websites, structured data may also require ‘seo.schema.enabled’ (both switches must be set to ‘true’ for the global mp-core JSON-LD path). The VidPly-specific processor continues to take into account structuredDataEnabled.

Full field mapping and Watch URL resolution: Developer Quick Start → Structured Data.

Media Session API

The integrated VidPly player registers media session handlers (lock screen / headset / notification controls and metadata for the current playback). On pages with multiple players, the API targets the instance that is actually playing at that moment (v1.2.8). No TYPO3 configuration is required.

Progressive Enhancement (without JavaScript)

Local video and audio content elements are rendered semantically <video controls> / <audio controls> using <source> and <track> -elements. Without JavaScript, browsers display native HTML5 controls; VidPly extends this same markup when the scripts load. External services (YouTube/Vimeo/SoundCloud) require JavaScript for consent prompts in order to load embeds.

Overrides to the website package template

Link the VidPly content elements to your frame/header partials:

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

Override partial templates for the player:

tt_content.mpc_vidply {
    partialRootPaths.20 = EXT:your_sitepackage/Resources/Private/Partials/
}

See “Partials.md” for filenames and data-* hooks used by the Listview.js.

SoundCloud Renderer Mode (advanced)

Default behaviour in TYPO3: SoundCloud uses the iframe path from the privacy layer (~7 KB JS). To control SoundCloud via VidPly’s unified control bar, override PrivacyLayer.html and set $needsVidPlay = true for SoundCloud in a custom processor. Step by step: “PrivacyLayer.md” → Switch SoundCloud to renderer mode.