Audio5

Summary: HTML5 Audio Support for PmWiki
Version: 2022-10-30
Prerequisites: PmWiki 2.2.x, php >= 5.2, a recent browser
Status: Stable
License: GPL2+
Maintainer: TomG
Categories: Audio, Media, Markup, HTML5, PHP74, PHP80, PHP82
Users: +2 (view / edit)
Discussion: Audio5-Talk

Questions answered by this recipe

How can I use the (not so) new HTML5 <audio> element?
How can I add audio files to my page in the same easy way as if they were images?

Description

This recipe provides the HTML5 <audio> tag for PmWiki.
The audio files can (but don't have to) be standard pmwiki uploads.

Installation

  • Get audio5.phpΔ and copy it to your cookbook directory
  • Add the following line to config.php: include_once("$FarmD/cookbook/audio5.php");

Audio5 Markup extensions

This recipe adds the (:audio:) markup to PmWiki.

Usage

Basic usage

Example

(:audio myaudio:)

This example will embedd the audio file myaudio on your page.
Please note, you do not have to include the audio file extension, e.g. (:audio myaudio.mp3:). However, no harm will be done if you do so anyway.

You'll then have to upload the audio files to PmWiki as you would do it with any upload.

  • The file(s) need to be named myaudio.mp3, myaudio.ogg or myaudio.wav.
  • If you want to show subtitles also upload a corresponding WebVTT or SRT file. This file has to be named myaudio.vtt or myaudio.srt respectively.

There are three supported audio formats for the <audio> element: MP3, Wav, and Ogg. Not every browser supports all formats. It is therefore recommended that you upload your audio in at least two formats:

  • MP3 (myaudio.mp3)
    • Supported by every major browser except Firefox
  • and either Ogg (myaudio.ogg) or Wav (myaudio.wav) (or both of them)
    • Supported by for every major browser except Internet Explorer

More on audio format browser support: http://en.wikipedia.org/wiki/HTML5_audio#Supported_audio_codecs

Update 2015: MP3 seems to be the best supported codec today. If you want to upload just one file use mp3.

Advanced usage

Advanced example

Audio5 supports all attributes of the HTML <audio> Tag. Here is an example where all possible options are being used:

(:audio myaudio autoplay=0 controls=1 loop=0 preload=auto:)

In this example all options are set to their default values.

The detailed effect of the options is described on various websites, e.g. http://www.w3schools.com/tags/tag_audio.asp.

You can change the default values in your config.php by setting any of these variables before including audio5.php:

$AudioPreload = 'auto';   // (auto|metadata|none)
$AudioAutoplay = 0;
$AudioControls = 1;
$AudioLoop = 0;

Default audio order

By default Audio5 loads video files in the following order: mp3, ogg, wav

You can change this behaviour in your config.php before including audio5.php:

$AudioExtensions = array('mp3','ogg','wav');

PmWiki setting EnableDirectDownload

Audio5 respects the the setting of $EnableDirectDownload.
However, please note that audio playback does not work with most browsers if $EnableDirectDownload=0 is set.

Storage matters

Maybe you don't have enough storage to store audio files in the same place as other PmWiki attachments. If so, you can configure the source URL to point to your audio storage.

An example setting for config.php (note the trailing slash):

$AudioUrl = 'http://server.example.com/path/to/audiofolder/';

You'll now need to upload your audio files to this place.

Unsupported browsers

Users of old browsers will see a message, showing the lack of HTML <audio> support. You can change this message in config.php:

$AudioNotSupportedText = 'Sorry, your browser does not support HTML5 audio.';

Notes

Change log / Release notes

  • 20121101
    • Initial Release
  • 20131023
    • added support for the track element (subtitles)
    • removed necessity to use the (:audio file:) markup without file extensions
    • audio format order is now configurable
    • audio5 now shows upload links if no video files are found
    • documentation update
  • 20131203
    • added support for attachments on other groups/pages (:audio group/page/file:)
  • 20151005
    • added support for PHP 5.5 (replaced Markup with Markup_e, thanks RandyB for the hint)
  • 20221030
    • added support for PHP 8 (thanks Petko for the change in Video5)

See also

Contributors

Comments

See discussion at Audio5-Talk

User notes +2: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.