Demo:

This song is “ Heyamoli” by Tutarchela

Usage:

{{< audio "https://archive.org/download/foo/bar.mp3" >}}

Features:

  • clean, responsive and accessible
  • available in multiple languages
  • supports WAV, FLAC, OGG, MP3, M4A
  • allows to download the audio file
  • fully customizable with CSS variables
  • fallback to default HTML player if no JS is available
  • provides keyboard navigation
  • lightweight: 180 Ko

Installation

Shortcode files are available in this repo and can be installed with this Shortcode collection I maintain.
This collection provides a selection of Shortcodes to enhance Hugo.

1. Add the Shortcode collection

Install as Git submodule:

git submodule add https://gitlab.com/Roneo/hugo-shortcode-roneo-collection.git themes/hugo-shortcode-roneo-collection

Then call this module from config.yml:

theme:
  - hugo-shortcode-roneo-collection
  - YourCurrentTheme

OR from config.toml

theme = ["hugo-shortcode-roneo-collection", "YourCurrentTheme"]

2. Add Plyr to your theme

Download plyr.css and plyr.polyfilled.js to static/.

Make sure to download the “polyfilled” version of the JS file, to be able to include multiple players on the same page.

3. Load the player

Last step, we need to call the player from our theme.

I’m using the theme Hugo Papermod and I pasted the following code in /layouts/_default/single.html, inside the block {{- define "main" }}


{{/*  Load plyr.io  */}}

{{ if or ( .HasShortcode "audio" ) ( .HasShortcode "video" )  ( .HasShortcode "archive-audio" ) }}

    <link rel="stylesheet" href="/css/plyr.css">

    <script src="/js/plyr.polyfilled.js" crossorigin="anonymous"></script>
    <script>
      (function() {
        const players = Array.from(document.querySelectorAll('.player')).map(
            p => new Plyr(p, {
                controls: ['play', 'progress', 'current-time', 'mute', 'volume', 'download', 'fullscreen'],
                {{/*  autoplay: true,  */}}
                {{/*  settings: ['speed']  */}}
            })
        );
        {{/*  Stop other players when starting  */}}
        players.forEach(function(p){
            p.on('play', event => {
                const instance = event.detail.plyr;
                console.log('Stop others players');
                players.forEach(function(p){ if(p != instance) p.stop()});
            })
        });
    })();
    </script>

{{ end }}

See the documentation of Plyr.io for details.

Source code

FAQ

Which theme file should I use to load the player?

To improve performance, we load the player only when the Shortcode is used in the current page, with .HasShortcode.

It seems like loading the player from template files may not work in such situation.

In my situation, with the theme Papermod, I pasted the following code inside the block {{- define "main" }} in the file /layouts/_default/single.html:

Plyr is not loaded, and the default HTML player is displayed

Fist of all, check the file paths.

Plyr assets must be located in the following files:

  • JS: /static/js/plyr.polyfilled.js
  • CSS: /static/css/plyr.css

When running locally, your web browser should be able to display these files at

  • http://localhost:1313/js/plyr.polyfilled.js
  • http://localhost:1313/css/plyr.css