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 entry (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 necessary, 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 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 reasonable (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 policy

How to create it:

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 not load until the user clicks “Play”
• Displays an overlay with a privacy notice
• No tracking before the user gives 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 begins in the SoundCloud widget’s iframe (visual waveform user interface). This is the default, resource-efficient method. Developers can optionally switch to VidPly’s standard 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 list view   content element, select a detail page and add one or more list view rows (shelf or grid, manual or category-based selection). Optional: Enable client-side pagination and specify the number of 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 shown again for other tracks).
• Hide keyboard shortcut help: Hides the help button (.vidply-help) in the control bar for this media track. The behaviour is the same as for the speed control: single track or per track in the playlist. The keyboard shortcut ‘?’ will still open the keyboard shortcuts dialogue if keyboard control is enabled for the content element.
• Allow download: Displays a download button in the control bar for this media element. Works automatically if a progressive file (MP4, WebM, MP3, OGG) is attached. For HLS/DASH-only entries, add a progressive fallback file so that the player can resolve a downloadable URL (manifests themselves are not downloadable).
• ‘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 during playback). Applies only to players with individual titles, 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 & 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 subtitle 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. Set 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 has been successfully completed

Multiple languages: Add multiple 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 audio description
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 script (extended audio description, no described video)

If you do not have a video file with audio description:

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 speech’, 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 the described 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 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.

Playlists

Automatic playlist

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

• A list of thumbnails is displayed next to the player
• Click on any item to play it
• ‘Auto-Advance’ plays the next track
• The ‘Repeat’ option plays all tracks in succession

Best practices

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

Player controls

Visual controls

 

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

 

Keyboard shortcuts

Help on keyboard shortcuts

If the keyboard is enabled for the content element, users can press the keyboard shortcut ‘?’ or click the Help button in the control bar to open a focused 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 thumbnail and the play button are displayed
2. Privacy policy: Explains that data is sent to an external service
3. The user clicks ‘Play’: The video is loaded 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 before 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 content
• Provide audio descriptions for visual content
• Use descriptive titles
• Add alt text to poster images

Performance

• Compress videos before uploading
• Use an appropriate resolution (not always 4K)
• For long-form content, consider embedding HLS or DASH streaming sources
• 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 directory.