version=pmwiki-2.5.9 ordered=1 urlencoded=1
author=Petko
charset=UTF-8
csum= (+149)
ctime=1777109481
name=PmWiki.Media
rev=69
targets=Cookbook.Ape,PmWiki.UploadVariables,PmWiki.Images,PmWiki.Uploads,PmWiki.InterMap
text=(:Summary:Embedding audio and video players in pages:)%0aHere you can find how to embed audio and video players in your wiki pages, either uploaded to the wiki, or on external websites.%0a%0aThe functions are based on the recipe Cookbook:Ape but are somewhat simpler to use and there are [[#diffape|differences]] in the wiki markup.%0a%0a!!#enable Enabling the media functions%0a%0aMedia embedding is available since PmWiki 2.5.10, and can be enabled by adding this line to local/config.php:%0a%0a%25hlt php%25@@$PmMedia['EnableEmbed'] = 1;@@%25%25%0a%0a%0a!!#basic Basic usage%0a%0aEmbedding media players is similar to embedding [[images]] in wiki pages, with the Attach: link or the bare remote URL, '''without brackets'''.%0a%0aTo embed a media file into a page, [[PmWiki.Uploads|upload]] the file using the "%25pmhlt%25[@Attach:@]" markup, or enter the address (url) of the file into the markup text.  %0a%0a'''Embedded locally attached file:'''\\%0a%25pmhlt%25[@Attach:video.webm@]%25%25%0a%0a'''Embedded remote file:'''\\%0a%25pmhlt%25[@https://example.com/video.mp4@]%25%25%0a%0a'''Embedded file on the same server, outside of the uploads directory structure:'''\\%0a%25pmhlt%25[@Path:/some/directory/video.mp4@]%25%25%0a%0a'''Links only (not embedded, note the brackets)''':\\%0a%25pmhlt%25[@[[Attach:video.webm]], [[Attach:video.webm|link text]]%0a[[https://example.com/video.mp4]]%0a[[Path:/some/place/video.mp4]]%0a@]%25%25%0a%0aThe following file extensions are expected to be media files that can be embedded:%0a* Audio files: @@mp3, opus, weba, m4a, ogg, flac, wav@@%0a* Video files: @@mp4, webm, m4v, ogv, mov@@%0a%0a!!#files Locally attached file formats, related files, poster, subtitles%0a%0aMedia support varies between different browsers and devices.%0a%0aIf the link is an external URL, Path:, or [[InterMap]], PmWiki will just embed this file.%0a%0aIf [[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.%0a%0aFor example, if you link to %25pmhlt%25[@Attach:My-Trip-2026.webm@]%25%25, 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. %0a%0aThe 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.%0a%0aIf you can upload only one file, for maximum compatibility, prefer '''MP4''' (H.264/AAC) for video and '''MP3''' for audio.%0a%0aFor best quality with lower file size, prefer '''WebM''' (VP9) for video and '''Opus/Ogg/WebA''' for audio. These should work in recent browsers.%0a%0aFor 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).%0a%0a(:details summary="Video encoding optimized for web":)%0aTo do.%0a(:detailsend:)%0a%0aFor 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.%0a* Poster (cover) pictures: @@webp, jpg, jpeg, png@@%0a* Tracks (subtitles, captions, chapters): @@vtt@@%0a%0aFor example, if you link to %25pmhlt%25[@Attach:My-Trip-2026.webm@]%25%25, 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.%0a%0aIf this is an audio file, and there is a related poster file, the player should create a %3cvideo> element with the poster as background.%0a%0aOnly 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:%0a* Subtitles:%0a** @@basename'''.vtt'''@@ %0a** @@basename'''.en.vtt'''@@, @@basename'''.en-US.vtt'''@@ : with a language code defined%0a* Captions, has a "@@.captions@@" part between the basename and the extension:%0a** @@basename'''.captions.vtt'''@@ %0a** @@basename'''.en.captions.vtt'''@@, @@basename'''.en-US.captions.vtt'''@@ : with a language code defined%0a* Chapters, has a "@@.chapters@@" part between the basename and the extension:%0a** @@basename'''.chapters.vtt'''@@ %0a** @@basename'''.en.chapters.vtt'''@@, @@basename'''.en-US.chapters.vtt'''@@ : with a language code defined%0a%0aYou 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.%0a%0a%0a!!#player Player options%0a%0aPlayer options can be set in a hash fragment after the URL. Different player options should be separated by semicolons:%0a%0a%25pmhlt%25@@[=Attach:video.mp4#800x450;loop;t=1:20,5:33=]@@%25%25%0a%0aThe following options are supported, after the hash sign, separated by semicolons:%0a* @@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).%0a* @@controls=0@@ - Show the player with no controls or seek bar; the right-click menu may allow for the user to control the player.%0a* @@muted@@ - The player will be muted initially; the user may be able to unmute it.%0a* @@loop@@ - After reaching the end of the file, the player will start over.%0a* @@preload=none@@ - Do not preload the metadata for the video until the user plays it.%0a* @@loading=lazy@@ - Do not start to load the media file until the player is close to the viewport on the screen.%0a* @@%25green%25800%25%25x%25red%25450%25%25@@ - The pixel dimensions %25green%25WIDTH%25%25x%25red%25HEIGHT%25%25 of the player element (no 'px', no percents); recommended if @@preload=none@@ or @@loading=lazy@@%0a** @@%25green%251280%25%25x@@ - only define the %25green%25width%25%25, @@x%25red%25720%25%25@@ - only define the %25red%25height%25%25 (the browser should set other dimension proportionally).%0a* @@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.%0a* @@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.%0a* @@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.%0a* @@class=vertical@@ - Add a CSS class name (a single one).%0a* @@t=%25green%25start%25%25,%25red%25end%25%25@@ - Configure '''start''' and '''end''' timestamps%0a** @@t=%25green%2501:00%25%25,%25red%2507:53%25%25@@ - in the format (HH:)MM:SS(.000)%0a** @@t=%25green%25130%25%25,%25red%25187%25%25@@ - in the format %25green%25start-second%25%25,%25red%25end-second%25%25%0a** @@t=%25green%2510%25%25@@ - only %25green%25start time%25%25, the end time is optional%0a** the seconds can be a decimal number like @@20.907@@ with a decimal point.%0a* @@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.%0a%0aOther options exist, see [[https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video|developer.mozilla.org: %3cvideo>]] (except for @@poster@@ and @@src@@).%0a%0a!!#config Configuration variables%0a%0aThe following can be enabled in local configuration:%0a%0a* %25list hlt php%25[@$PmMedia['EnableEmbed'] = 1;@] Include media functions (default disabled; required for all functionality).%0a* [@$PmMedia['EnableUploadEmbed'] = 1;@] Enable embedding of Attach: bare URLs to media files (default enabled, set to @@0@@ to disable).%0a* [@$PmMedia['EnableRemoteEmbed'] = 1;@] Enable embedding of remote bare URLs to media files (default enabled, set to @@0@@ to disable).%0a* [@$PmMedia['AudioExts'] = 'opus|weba|m4a|ogg|mp3|flac|wav';@] Supported audio extensions, in the order of preference.%0a* [@$PmMedia['VideoExts'] = 'webm|mp4|m4v|ogv|mov';@] Supported video extensions, in the order of preference.%0a* [@$PmMedia['PosterExts'] = 'webp|jpg|jpeg|png';@] Supported poster extensions, in the order of preference (not a regular expression).%0a* [@$PmMedia['DefaultAttrs']['attribute'] = 'value';@] Default attribute values, see [[#player|Player options]]:%0a** [@$PmMedia['DefaultAttrs']['controls'] = false;@] Hide the controls by default, use @@#@@@@controls@@ in the fragment to enable per player.%0a** [@$PmMedia['DefaultAttrs']['loading'] = 'lazy';@] Lazy loading for all media files.%0a%0aFor 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:%0a%0a* %25hlt php%25[@$PmMedia['Langs']['fr-CA'] = 'Français (Canada)';@]%25%25 Show this label for a subtitles file named @@video.'''fr-CA'''.vtt@@.%0a%0a!!#mjump Links to timestamps / chapters%0a%0aTimestamps like @@0:19@@ or @@1:01:34@@ written in plain text '''after the player''' are converted to links starting the playback at these points:%0a%0a(:markup class=norender:)%0aAttach:video.mp4%0aThe first song starts at 0:19, the end credits at 12:58.%0a* 0:00 start/intro%0a* 0:19 first song%0a* 6:55 second song%0a* ...%0a* 12:58 end credits%0a(:markupend:)%0a%0aAnother media player, or a page heading of level 1, 2, or 3 like %25pmhlt%25[@!!! Next Heading@]%25%25 will halt the search for timestamps for the current media file.%0a%0a!!#diffape Differences with Cookbook:Ape%0a%0a[[Cookbook:Ape|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.%0a%0aThe main differences between PmMedia and Ape are:%0a# No need for %25pmhlt%25[@%25embed%25...%25%25@]%25%25 wikistyles; bare URLs are converted to %25hlt html%25[@%3caudio>@] and [@%3cvideo>@]%25%25 HTML5 tags.%0a# Only bare URLs are embedded, like for [[images]]; Ape allows for links in brackets to be embedded.%0a# Player options are written in the hash fragment rather than wikistyles.%0a# Automatic detection within local uploads of alternative media formats, poster images and subtitles/captions, no need to link to them. %0a** PmMedia has conventions for file name patterns, while Ape allows linking to any file names.%0a# Automatic labeling of many languages for the subtitles/captions.%0a# Video player for audio file + poster.%0a# Links to timestamps do not need to be wrapped in %25pmhlt%25[@>>embed%3c%3c@] or [@>>mediajump%3c%3c@]%25%25, and are only detected after the video player.%0a# Unlike Ape, PmMedia does not require JavaScript to be enabled (except for the links to timestamps).%0a# Unlike Ape, PmMedia players can be embedded in an Ape map.%0a%0aThe plan is for PmMedia to some day embed videos from YouTube and Vimeo, like Ape, but with better GDPR compliance.%0a%0aIf you're currently using [[Cookbook:Ape|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.%0a%0a!!#notes Notes%0a%0aThe web server must send the correct @@Content-Type@@ headers for all media file formats discussed above.%0a%0a(:details summary="Apache configuration":)%0aTo do.%0a(:detailsend:)%0a%0a
time=1778561436