🎧 hugo-audio

A Hugo theme component to embed sounds using the HTML audio element.

Features

This Hugo theme component provides a shortcode audio for embedding sounds using the HTML audio element.

• Languages: English and German (more languages are welcome!)
• Fallback to a localized download notice if the browser doesn't support the HTML audio element
• Supported audio formats:
  • MP3 (extension .mp3)

Installation

The best way to install this component is as a Hugo module:

1. Initialize your existing site as Hugo module:

   hugo mod init github.com/<USERNAME>/<REPO>

2. Add the hugo-audio component as a Hugo module:

   hugo mod get github.com/heinrichreimer/hugo-audio

3. In your site's or theme's configuration file, add a module section and define both hugo-audio and your currently used theme as modules to be imported.

   Here is an example, with a YAML configuration file:

   module:
     imports:
       - path: github.com/heinrichreimer/hugo-audio
       - path: my-theme

   With a TOML configuration file, it should look like this:

   [module]
     [[module.imports]]
       path = "github.com/heinrichreimer/hugo-audio"
     [[module.imports]]
       path = "my-theme"

But it can also be installed as a Git module.

1. Add this repository as a submodule like this:

   git submodule add https://github.com/heinrichreimer/hugo-audio.git themes/hugo-audio

2. Add hugo-audio as the leftmost element of the theme list in your site's or theme's configuration file:

   Here is an example, with a YAML configuration file:

   theme: ["hugo-audio", "my-theme"]

   With a TOML configuration file, it should look like this:

   theme = ["hugo-audio", "my-theme"]

Usage

This shortcode uses Hugo Page Resources.

So first place the audio to be played in the page bundle of the page where you want to use the shortcode.

In the page source file, then use the shortcode like this, indicating the audio filename without its extension:

{{< audio src="my-cool-sound" >}}

This will reference the file my-cool-sound.mp3, for example. ... or with a fixed width:

{{< audio src="my-cool-sound" width="600px" >}}

The shortcode takes one mandatory argument: the filename of the audio file to play without the extension. The component automatically detects if several versions of the file exist in the page bundle and accordingly adds multiple src tags. If no audio file of the given name is found in the supported format (see above), the shortcode intentionally fails with a No valid audio file with filename <filename> found. error.

Defaults

• The web browser's default audio controls are displayed (controls attribute is always included).
• Audio can be preloaded (preload="auto" attribute is always included).
• Audio width is 100% (width="100%" attribute is included). Can be changed by explicitly specifying the width in the shortcode.
• The following other audio attributes can be set: muted="true", autoplay="true" and loop="true".
• Default settings are used for all other audio attributes.

Acknowledgments

• Nicolas Martignoni, for the hugo-video shortcode on which this shortcode is based.
• Tom McKenzie, for implementing muted, autoplay and loop audio attributes support.
• Olaf Haag, Paul Lettington and Christian Mahnke, for raising and fixing some bugs.
• Arsenii Lyashenko, for implementing controls disabling option.

License

All the source code is licensed under GPL 3 or any later version

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.