• View
• Edit
• History
• Print
• Backlinks

Media

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.

Enabling the media functions

Media embedding is available since PmWiki 2.5.10, and can be enabled by adding this line to local/config.php:

$PmMedia['EnableEmbed'] = 1;

Basic usage

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:

• Audio files: mp3, opus, weba, m4a, ogg, flac, wav
• Video files: mp4, webm, m4v, ogv, mov

Locally attached file formats, related files, poster, subtitles

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:mytrip2026.webm, PmWiki will embed this file. It will also check for files with the same basename and another media extension: mytrip2026.mp4, mytrip2026.m4v, mytrip2026.ogv, mytrip2026.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).

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.

• Poster (cover) pictures: webp, jpg, jpeg, png
• Tracks (subtitles, captions, chapters): vtt

For example, if you link to Attach:mytrip2026.webm, if there is an image file mytrip2026.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:

• Subtitles:
  • basename.vtt
  • basename.en.vtt, basename.en-US.vtt : with a language code defined
• Captions, has a .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, has a .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

Player options can be set in a hash fragment after the URL. Different player options should be separated by semicolons:

Attach:video.mp4#loop;t=1:20,5:33;width=800

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 by default; 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
• width=800 and/or height=450 - the pixel dimensions of the player element (no 'px', no percents); recommended if preload=none or loading=lazy
• autoplay - the player should start playing as soon as the page is loaded; note that some browsers require for "muted" to also be enabled, or they may ask the users to confirm if they allow media autoplay for the website
• 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
  • the seconds can be a decimal number like 20.907 with a decimal point.
• lang=fr - set a default language for subtitles/captions; this would enable a subtitle file video.fr.vtt if it exists, without the user having to enable it

Other options exist, see developer.mozilla.org: <video> (except for poster and src).

Configuration variables

The following can be enabled in local configuration:

• $PmMedia['EnableEmbed'] = 1; Enable media embed for bare URLs to media files.
• $PmMedia['EnableUploadEmbed'] = 0; Disable embedding of Attach: bare URLs to media files.
• $PmMedia['EnableRemoteEmbed'] = 0; Disable embedding of remote bare URLs to media files.
• $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
• $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.

Links to timestamps

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.

Differences with Cookbook:Ape

Ape is a popular PmWiki recipe that allows to embed HTML5 video and audio players. This core PmWiki function is based on Ape, but is somewhat simplified for wiki writers, with less markup to write.

The main differences between PmMedia and Ape are:

1. No need for %embed%...%% wikistyles; bare URLs are converted to <audio> and <video> HTML5 tags.
2. Only bare URLs are embedded, like for images; Ape allows for links in brackets to be embedded.
3. Player options are written in the hash fragment rather than wikistyles.
4. Automatic detection within local uploads of alternative media formats, poster images and subtitles/captions, no need to link to them. OTOH there are conventions for file name patterns.
5. Automatic labeling of many languages for the subtitles/captions.
6. Video player for audio file + poster.
7. Links to timestamps do not need to be wrapped in >>embed<< or >>mediajump<<, and are only detected after the video player.
8. Unlike Ape, PmMedia does not require JavaScript to be enabled (except for the links to timestamps).

The plan is for PmMedia to some day embed videos from YouTube and Vimeo, like Ape, but with better GDPR compliance.

Notes

The web server must send the correct Content-Type headers for all media file formats discussed above.