Guidelines for Editors: VidPly Player

Brief overview

VidPly is a universal, accessible media player that supports various sources:

Two-stage workflow

Step 1: Create media assets

First, create reusable media assets in the VidPly media library.

Step 2: Add a player to the page

Next, add a VidPly player content element and select your media.

Step 1: Create media entries

How to find it

Web → List module → Select storage folder → Click ‘+’ → VidPly Media

Or use the ‘Create new record’ button in the VidPly player element.

The quickest way: Import via URL

For YouTube, Vimeo, SoundCloud, streaming URLs (.m3u8 / .mpd) and approved external MP4/MP3 links:

1. Create a new VidPly media record (or open an existing one)
2. Select ‘Import from URL’ at the top of the form
3. Paste the full media URL and click ‘Import’
4. VidPly recognises the media type, adds the online media file and automatically fills in the title, artist and poster, provided the provider supplies this information
5. Check the fields, add subtitles if required, and then click “Save”

You no longer need to select the media type before pasting the URL. The manual ‘Media type’ drop-down menu and the ‘Add media via URL’ option in the file field remain available to advanced users.

For existing records with a linked online media file, use ‘Update metadata’ to retrieve oEmbed data again without overwriting the fields you have already filled in manually.

Explanation of media types

Video

Usage: Self-hosted video files, HLS/DASH streaming with optional progressive fallbacks

Supported formats: MP4, WebM, HLS (.m3u8), DASH (.mpd)

To create an entry:

1. Select media type: Video
2. Click on ‘Add media file’ and upload your video or add a streaming URL (.m3u8 / .mpd)
3. Optionally, add further files as fallbacks (e.g. DASH + HLS + MP4)
4. Add a title (required)
5. Add a poster image (thumbnail displayed before playback) – supported formats: JPG / JPEG, PNG, WebP, SVG

Tips:

• Upload multiple formats to ensure browser compatibility and provide fallbacks (DASH → HLS → MP4/WebM)
• Recommended: MP4 with H.264 codec as a progressive fallback
• HLS/DASH sources use embedded subtitles by default; local VTT files can override these
• HLS streams play hls.js in Chrome / Firefox / Edge / Desktop Safari, as well as via native HLS on iOS / iPadOS – subtitles, transcripts and quality control work on all platforms
• Keep file sizes within reasonable limits (compress for the web)

Audio

Used for: podcasts, music, audio content, audio streaming

Supported formats: MP3, OGG, HLS (.m3u8), DASH (.mpd)

How to create them:

1. Select media type: Audio
2. Click on ‘Add media file’ and upload your audio file or add a streaming URL (.m3u8 / .mpd)
3. Optionally, add further files as fallbacks (e.g. DASH + HLS + MP3)
4. Add a title (required)
5. Optionally, add a poster image (album cover) – supported formats: JPG / JPEG, PNG, WebP, SVG

YouTube

Usage: YouTube videos with a GDPR-compliant privacy layer

How to create an entry:

1. Select media type: YouTube
2. Click on ‘Add media file’ → ‘Add external video’
3. Paste the YouTube URL (e.g. www.youtube.com/watch.)
4. Add a title (required)
5. Add a poster image (displayed before consent is given) – supported formats: JPG / JPEG, PNG, WebP, SVG

Privacy behaviour:

• The video will only load once the user clicks ‘Play’
• Displays an overlay with a privacy notice
• No tracking takes place before the user gives their consent
• Complies with the requirements of the GDPR

Vimeo

Used for: Vimeo videos with a privacy overlay

How to create it:

1. Select media type: Vimeo
2. Click on ‘Add media file’ → ‘Add external video’
3. Paste the Vimeo URL (e.g. vimeo.com/123456789)
4. Add a title (required)
5. Add a cover image – supported formats: JPG / JPEG, PNG, WebP, SVG

SoundCloud

Usage: SoundCloud tracks or playlists with privacy settings

To create the element:

1. Select media type: SoundCloud
2. Enter the media URL (track or set URL)
3. Add a title (required)
4. Add a poster image (optional) – supported formats: JPG / JPEG, PNG, WebP, SVG

 

Once the user has accepted the privacy policy, playback takes place within the SoundCloud widget iframe (visual waveform user interface). This is the default, resource-efficient method. Developers can optionally switch to VidPly’s standardised control bar via a template/processor override – see PrivacyLayer.md → Switch SoundCloud to renderer mode.

 

Add metadata

Every media record has a metadata palette:

VidPly List View & Detail Page (Overview)

To create a media library-style overview: Add a VidPly Listview   content element, select a detail page and add one or more Listview rows (shelf or grid, manual or category-based selection). Optional: Enable client-side pagination and specify thenumberof items per page and per row; use the sorting control in the browser on the public website; and retain the shelf definitions in the default language when the website is translated. See List View and Detail Page for step-by-step setup instructions, URLs and notes for administrators .

VidPly Detail (the content element on the media details page) has a ‘Related content’ option under ‘Settings’ (enabled by default). Disable this if you do not wish to display the ‘You might also like’ row below the player.

Player user interface options (per media record)

• Hide speed button: Hides the playback speed control for this media item.
  • Single item: The speed control is hidden.
  • Playlist: The speed control is hidden only whilst this item is the active track (it can be displayed again for other tracks).
• Hide keyboard shortcuts help: Hides the help button (.vidply-help) in the control bar for this media track. The behaviour is the same as for the speed button: single track or per track in the playlist. The keyboard shortcut ‘?’ will still open the dialogue box with the keyboard shortcuts if keyboard control is enabled for the content element.
• Allow download: Makes the media file available for download. Works automatically if a progressive file (MP4, WebM, MP3, OGG) is attached. For HLS/DASH-only records, add a progressive fallback file so that a download URL can be resolved (manifests themselves cannot be downloaded).
  • Single item: A download button appears in the control bar.
  • Multiple media files: The button in the control bar follows the selected track – it offers the file of the track currently being played and disappears for tracks where this setting is not enabled.
  • Episode list layout: Each episode is listed so that the download link appears directly in the episode description and can be used without having to select the track first.
• Enable floating player (custom PiP): Replaces the browser’s native Picture-in-Picture with VidPly’s movable and resizable floating window (this is also triggered if the video scrolls out of view whilst playing). Applies only to players with individual elements, not to playlists. This differs from the standard PiP button in the toolbar, which uses the browser’s native mini-player.
• Buffer loading indicator: A centred loading indicator is automatically displayed whilst the player is buffering – no configuration required. Works for local files as well as HLS and DASH streams.

Accessibility features

VidPly supports accessibility in accordance with WCAG 2.2 AA.

Image captions and subtitles

Tab: Subtitles

WebVTT (.vtt) or SubRip (.srt) for viewers who require subtitles (including many deaf and hard-of-hearing users):

1. Click on ‘Add caption file’
2. Upload your .vtt or .srt file
3. Select the track type: subtitles or captions
4. Specify the language name: e.g. ‘English’, ‘German’
5. Enter the language code: e.g. ‘en’, ‘de’
6. Save the media entry – SRT files are automatically converted to WebVTT; you will receive a notification in the backend as soon as the conversion is complete

Multiple languages: Add several subtitle files for each language.

SRT uploads: SubRip (.srt) is accepted for the sake of simplicity. VidPly stores WebVTT internally, as this is required by browsers and the transcription feature. The original SRT file is replaced upon saving.

Older SRT files already present in the file storage: Ask a website administrator to run the one-off upgrade wizard: Admin Tools → Upgrade → Upgrade Wizards → VidPly: Convert SRT subtitle files to WebVTT (no command line required).

VTT example:

WEBVTT

00:00:00.000 --> 00:00:03.000
Welcome to our video tutorial.

00:00:03.000 --> 00:00:07.000
Today we'll learn about VidPly.

Chapter

Tab: Subtitles → Chapters

Add chapter markers for easy navigation:

1. Click on ‘Add chapter file’
2. Upload your chapters .vtt or .srt Upload file (SRT will be converted to WebVTT when the media record is saved)
3. Set track type: Chapter
4. Specify the language information

Example of VTT chapters:

WEBVTT

00:00:00.000 --> 00:02:30.000
Introduction

00:02:30.000 --> 00:08:00.000
Main Content

00:08:00.000 --> 00:10:00.000
Conclusion

Audio description

Tab: Accessibility → Audio description

VidPly supports two workflows for spoken audio descriptions and text descriptions in the transcript.

Option A – Described video (recommended)

For blind and visually impaired users, add a video in which the descriptions are already mixed into the audio:

1. Click on ‘Add audio description’
2. Upload an alternative MP4 or WebM file with embedded voice-over
3. Users can switch between the standard video and the described video using the AD button

Optionally, set the duration of the audio description if the described version is longer than the original.

Option B – VTT voice-over (advanced AD, no described video)

If you do not have a described video file:

1. Under ‘Subtitles’, upload a WebVTT file and set the track type to ‘Descriptions’
2. Leave the ‘Audio description’ field blank (or specify the mode explicitly – see below)
3. If the audio description mode is set to “Automatic” or “Descriptions (VTT language)”, VidPly pauses the video at each description cue, reads out the text using the browser’s text-to-speech function, and then resumes playback

Text description notes remain visible in the transcript window for users who prefer to read. This method requires browser support speechSynthesis ; speech quality varies depending on the browser.

‘Audio Description’ mode

Tab: Accessibility → Audio Description Mode

Alternative subtitle/chapter files for captioned video

When using the switch to captioned video, you can attach a VTT file with audio description for each subtitle or chapter file reference (tx_desc_src_file). These alternative files are loaded when AD mode is active.

Sign language

Tab: Accessibility → Sign language

Add a sign language interpretation overlay:

1. Click on ‘Add video with sign language’
2. Upload a video with a sign language interpreter
3. Displayed as a picture-in-picture overlay

Transcripts

Tab: Subtitles → Enable transcript

Create a searchable text transcript from subtitles:

1. Enable ‘Show transcript window’
2. Subtitles are displayed as clickable, searchable text
3. Users can click on any line to jump to that point

Step 2: Add the player to the page

Insert content element

Page module → Add content → VidPly player

Select media elements

‘Media’ tab:

• Click in the ‘Media items’ field
• Search for your media records and select them
• Add multiple items to a playlist (2 or more items)

Configure player options

‘Settings’ tab:

Playback settings:

• Volume: Default volume (0.0 – 1.0)
• Playback speed: Default speed (0.25 – 2.0)
• Language: Force a specific UI language

Transcript (per media item):

• Enable transcript per media file: Media file → ‘Subtitles’ tab → ‘Enable transcript’
• The transcript window is displayed if the transcript is enabled for at least one selected entry.

Episode card layout (podcasts)

The ‘Layout’ field controls how the element is displayed:

The card is populated with the data from the first selected media record. The release date and episode number are taken from this record’s metadata palette, and the cover is its poster – therefore, for podcast episodes, use a square poster to achieve the best result. The card is reformatted into a single column if the content column is narrow, so that it also works in sidebars and modal windows.

Order of the episode list and pages

For the episode card with an episode list, three additional fields appear on the ‘Settings’ tab:

Visitors can reorder the list themselves using the drop-down menu next to the ‘Episodes (n)’ heading. Sorting and pagination only affect the list: Playback always follows the order of your media items, so that ‘Next/Previous’ and the automatic fast-forward remain predictable – and when playback switches to an episode on a different page, the list jumps to that page.

Episodes without a publication date are listed last in both date-based sort orders; therefore, please specify the publication date if you are relying on sorting by this criterion.

View notes on the card and in the list

As soon as a media entry contains a ‘Detailed description’, the ‘Show description’ button appears on the map and in the list row, which opens the rich text directly in place. There is no need to activate anything separately – if you fill in the field, the button appears; if you leave it blank, the map looks as it did before. Visitors who want to see everything at a glance can still access the details page, where the same text is displayed in full.

Make sure to structure the detailed description well (paragraphs, lists, links). It is displayed unchanged directly below the episode, so very long texts will push the next episode far down the page, even if they are initially hidden.

The same text can also be accessed via the list view: cards in a grid row have a small button in the bottom right-hand corner that opens the description in an overlay. Cards in a shelf row do not have this button – a shelf scrolls sideways and does not have room for it, so the card’s link to the details page remains there instead.

Playlists

Automatic playlist

Select two or more media items to automatically create a playlist:

• The thumbnail list appears next to or below the player (see ‘Position of the playlist’)
• Click on any item to play it
• Selecting ‘Automatically next’ plays the next track
• The ‘Repeat’ option plays all tracks in succession

Playlist position (the ‘Settings’ tab, visible when there are two or more media items):

The playlist toggle is located in the right-hand control bar (next to subtitles, settings and full screen). On very narrow screens, it may be moved to the overflow menu, whilst ‘Back’, ‘Play/Pause’, ‘Next’ and the volume controls remain visible.

Live streams

HLS and DASH live sources (e.g. TV streams available at .m3u8) are automatically detected. The player then does the following:

• displays a ‘LIVE’ icon instead of the total duration
• hides the controls for restarting and adjusting playback speed
• displays the ‘Go Live’ and ‘Skip Forward’ buttons only if the viewer falls behind the live progress
• Keeps subtitles and the interactive transcript synchronised as soon as new subtitle segments arrive

Import .m3u8 of URLs into a video media record (not audio) if the stream contains video – VidPly takes the media type of the record into account even if the URL matches both the audio and video allowlists.

Best practices

• Use consistent poster images (same dimensions)
• Add titles to all elements
• Consider grouping related content
• Arrange the elements logically (reorder by dragging)

Player controls

Visual controls

 

Note: Enabling the floating player for a media recording uses VidPly’s custom, page-internal floating window instead of (and in addition to) the native PiP behaviour. See ‘Player UI options’ above.

Keyboard shortcuts

Help on keyboard shortcuts

If keyboard navigation is enabled for the content element, users can press the ‘?’ shortcut or click the Help button in the control bar to open a focus-bound dialogue box listing all active keyboard shortcuts. Hide the button for each media record using ‘Hide Keyboard Shortcuts Help’ (the ? keyboard shortcut will still work, provided that keyboard navigation for the content element is not disabled).

Data Protection (GDPR)

For YouTube, Vimeo and SoundCloud:

How it works

1. Before consent is given: Only the featured image and the play button are displayed
2. Privacy policy: Explains that data is transferred to an external service
3. The user clicks ‘Play’: The video loads and plays immediately
4. No cookies until the user gives their explicit consent

Configure settings for the privacy layer

‘List’ module → Privacy layer settings

Customise the content of the privacy layer for all external services:

1. Create a new privacy settings record
2. Configure the settings for each service (YouTube, Vimeo, SoundCloud):
   • Heading (optional) – Displayed above the privacy policy text
   • Introductory text – Text preceding the link to the privacy policy
   • Closing text – Text following the link to the privacy policy
   • Link to the privacy policy – URL to the page containing the privacy policy
   • Link text – Text for the link to the privacy policy
   • Button label (optional) – Accessible label for the play button
3. For multilingual websites: Create translated versions of the data set

These settings apply to both individual tracks and playlists. If any fields are left blank, the default translations will be used automatically.

What users see

┌─────────────────────────────────┐
│                                 │
│      [Poster Image]             │
│                                 │
│         Play                    │
│                                 │
│  [Optional Headline]            │
│  Privacy Notice: Clicking play  │
│  will load content from YouTube │
│  and send data to Google.       │
│  [Privacy Policy Link] applies. │
└─────────────────────────────────┘

Tips and best practices

Video quality

• Resolution: 1080p or 720p for the web
• Bitrate: 5–8 Mbit/s for HD
• Codec: H.264 for MP4
• Always provide a thumbnail

Audio quality

• Bitrate: 128–320 kbps MP3
• Sampling rate: 44.1 or 48 kHz

Accessibility

• Always add subtitles to videos containing spoken text
• Provide audio descriptions for visual content
• Use meaningful titles
• Add alt text to poster images

Performance

• Compress videos before uploading
• Use an appropriate resolution (not always 4K)
• Consider integrating HLS or DASH streaming sources for long-form content
• External services (YouTube/Vimeo) reduce server load

Mobile

• Test on mobile devices
• The player is responsive by default and adapts to the screen or container size
• Touch controls work automatically

Troubleshooting

VTT validation

Ensure that your VTT files:

• begin WEBVTT on the first line
• a blank line after WEBVTT
• Use the following format: HH:MM:SS.mmm --> HH:MM:SS.mmm
• text on the next line(s)

Quick guide

Need help? Contact your website administrator or check the documentation index.