Here you can find how to embed audio and video players in your wiki pages, either uploaded to the wiki, or on external websites.
The functions are based on the recipe Cookbook:Ape but are somewhat simpler to use and there are differences in the wiki markup.
Media embedding is available since PmWiki 2.5.10, and can be enabled by adding this line to local/config.php:
$PmMedia['EnableEmbed'] = 1;
Embedding media players is similar to embedding images in wiki pages, with the Attach: link or the bare remote URL, without brackets.
To embed a media file into a page, upload the file using the "Attach:" markup, or enter the address (url) of the file into the markup text.
Embedded locally attached file:Attach:video.webm
Embedded remote file:https://example.com/video.mp4
Embedded file on the same server, outside of the uploads directory structure:Path:/some/directory/video.mp4
[[Attach:video.webm]], [[Attach:video.webm|link text]] [[https://example.com/video.mp4]] [[Path:/some/place/video.mp4]]
The following file extensions are expected to be media files that can be embedded:
mp3, opus, weba, m4a, ogg, flac, wav
mp4, webm, m4v, ogv, mov
Media support varies between different browsers and devices.
If the link is an external URL, Path:, or InterMap, PmWiki will just embed this file.
If uploads are enabled and this is an Attach: link to a locally uploaded file, PmWiki will scan the uploads directory for alternative files in other formats, and present all to the browser.
For example, if you link to Attach:My-Trip-2026.webm, PmWiki will embed this file. It will also check for files with the same basename and another media extension: My-Trip-2026.mp4, My-Trip-2026.m4v, My-Trip-2026.ogv, My-Trip-2026.mov (in this order) and will include them as alternative formats to the player.
The browser will play the first format it supports; if it supports none of the available formats, it should show direct links to the files so the visitors can download them.
If you can upload only one file, for maximum compatibility, prefer MP4 (H.264/AAC) for video and MP3 for audio.
For best quality with lower file size, prefer WebM (VP9) for video and Opus/Ogg/WebA for audio. These should work in recent browsers.
For best user experience, upload media files in the 2 formats above if you can, and link to the best quality formats (the others should be detected and available in the player).
To do.
For locally uploaded files, PmWiki will also search for related pictures and subtitles/captions/chapters, that is the same basename and a different extension, and will include them in the player.
webp, jpg, jpeg, png
vtt
For example, if you link to Attach:My-Trip-2026.webm, if there is an image file My-Trip-2026.jpg, it should appear as the video poster (cover) picture shown before the video starts playing.
If this is an audio file, and there is a related poster file, the player should create a <video> element with the poster as background.
Only for video file formats, the following track files will be automatically added to the player if they are in the uploads directory, and a video file basename.webm is embedded:
basename.vtt
basename.en.vtt, basename.en-US.vtt : with a language code defined
.captions" part between the basename and the extension:
basename.captions.vtt
basename.en.captions.vtt, basename.en-US.captions.vtt : with a language code defined
.chapters" part between the basename and the extension:
basename.chapters.vtt
basename.en.chapters.vtt, basename.en-US.chapters.vtt : with a language code defined
You can have more than one related VTT file, all will be added to the player and a user can enable one of these at a time.
Player options can be set in a hash fragment after the URL. Different player options should be separated by semicolons:
Attach:video.mp4#800x450;loop;t=1:20,5:33
The following options are supported, after the hash sign, separated by semicolons:
audio - Play a video in an audio player (only the sound will play without the moving pictures; note that the browser will still download the full file).
controls=0 - Show the player with no controls or seek bar; the right-click menu may allow for the user to control the player.
muted - The player will be muted initially; the user may be able to unmute it.
loop - After reaching the end of the file, the player will start over.
preload=none - Do not preload the metadata for the video until the user plays it.
loading=lazy - Do not start to load the media file until the player is close to the viewport on the screen.
800x450 - The pixel dimensions WIDTHxHEIGHT of the player element (no 'px', no percents); recommended if preload=none or loading=lazy
1280x - only define the width, x720 - only define the height (the browser should set other dimension proportionally).
1.25x, 0.8x - Change the playback speed of the video (e.g., 2x = twice as fast); the user may be able to change the speed from the ellipsis or right-click menu. Value must be between 0.5 and 3.0.
autoplay - The playing should start as soon as the page is loaded; note that some browsers require for "muted" to also be enabled, and they may ask the users to confirm if they allow media autoplay for the website.
id=video_id - Add an identifier name (a unique one); can be used as an anchor for links to the player like Page#video_id and for styling.
class=vertical - Add a CSS class name (a single one).
t=start,end - Configure start and end timestamps
t=01:00,07:53 - in the format (HH:)MM:SS(.000)
t=130,187 - in the format start-second,end-second
t=10 - only start time, the end time is optional
20.907 with a decimal point.
lang=fr - Set a default language for subtitles/captions in the video player; this would activate a subtitle file video.fr.vtt if it exists, without the user having to select it.
Other options exist, see developer.mozilla.org: <video> (except for poster and src).
The following can be enabled in local configuration:
$PmMedia['EnableEmbed'] = 1; Include media functions (default disabled; required for all functionality).
$PmMedia['EnableUploadEmbed'] = 1; Enable embedding of Attach: bare URLs to media files (default enabled, set to 0 to disable).
$PmMedia['EnableRemoteEmbed'] = 1; Enable embedding of remote bare URLs to media files (default enabled, set to 0 to disable).
$PmMedia['AudioExts'] = 'opus|weba|m4a|ogg|mp3|flac|wav'; Supported audio extensions, in the order of preference.
$PmMedia['VideoExts'] = 'webm|mp4|m4v|ogv|mov'; Supported video extensions, in the order of preference.
$PmMedia['PosterExts'] = 'webp|jpg|jpeg|png'; Supported poster extensions, in the order of preference (not a regular expression).
$PmMedia['DefaultAttrs']['attribute'] = 'value'; Default attribute values, see Player options:
$PmMedia['DefaultAttrs']['controls'] = false; Hide the controls by default, use #controls in the fragment to enable per player.
$PmMedia['DefaultAttrs']['loading'] = 'lazy'; Lazy loading for all media files.
For subtitles and captions, when a language code is detected, the language name is shown as label in the player. Some language codes and labels are included. You can define other language codes and labels this way:
$PmMedia['Langs']['fr-CA'] = 'Français (Canada)'; Show this label for a subtitles file named video.fr-CA.vtt.
Timestamps like 0:19 or 1:01:34 written in plain text after the player are converted to links starting the playback at these points:
Attach:video.mp4 The first song starts at 0:19, the end credits at 12:58. * 0:00 start/intro * 0:19 first song * 6:55 second song * ... * 12:58 end credits |
Another media player, or a page heading of level 1, 2, or 3 like !!! Next Heading will halt the search for timestamps for the current media file.
Ape is a popular PmWiki recipe that allows embedding HTML5 video and audio players. This core PmWiki function is based on Ape but is simplified for wiki writers, with less markup to write.
The main differences between PmMedia and Ape are:
%embed%...%% wikistyles; bare URLs are converted to <audio> and <video> HTML5 tags.
>>embed<< or >>mediajump<<, and are only detected after the video player.
The plan is for PmMedia to some day embed videos from YouTube and Vimeo, like Ape, but with better GDPR compliance.
If you're currently using Ape for audio/video file embedding, PmMedia is not a drop-in replacement - the goal was to have less markup/clutter and improve the writer experience. If you enable PmMedia, you also need to check your existing pages and if needed update the wiki markup (remove link brackets, use hash options instead of wikistyles) and possibly rename any alternative/related attached files.
The web server must send the correct Content-Type headers for all media file formats discussed above.
To do.