README

An extended audio player block for Kirby CMS. Displays an audio file with a poster image, title, subtitle, rich-text description, and configurable background/text colors — in the Panel and on the front end.

Registered as the block type audio-player, so it will not conflict with any site or plugin block named audio.

Features

Audio file (mp3, m4a, aac, wav, ogg, flac, aif, aiff) with poster image (jpg, jpeg, png, webp, svg)
Title, subtitle, and inline writer description (bold/italic)
Background and text color pickers
Settings tab: show controls, autoplay
Live Panel preview with inline editing (double-click to edit text in place)

Accepted filetypes ; mp3, m4a, aac, wav, ogg, flac, aif, aiff.

Installation

Manual

Copy this folder to site/plugins/ianhobbs-audio-block.

Git submodule

git submodule add https://github.com/ianhobbs/kirby-audio-block.git site/plugins/ianhobbs-audio-block

Composer

composer require ianhobbs/audio-block

Usage

Add the block type to a blocks or layout field in your blueprint:

fields:
  text:
    type: blocks
    fieldsets:
      - audio-player
      - text
      - image

Render blocks in your template as usual:

<?= $page->text()->toBlocks() ?>

Front-end styles

The plugin ships a stylesheet at assets/audio-player.css and loads it automatically — no template change required. It is injected before </head> only on pages whose rendered HTML contains the block (.audio-wrapper), and skipped if the stylesheet is already linked in the page.

Control this with the ianhobbs.audio-block.css option in site/config/config.php:

return [
  // true (default) – load the shipped stylesheet automatically
  // false          – load nothing, style the block yourself
  // string         – URL of your own stylesheet to load instead
  'ianhobbs.audio-block.css' => true,
];

To include the shipped stylesheet manually instead, turn the option off and link the published asset in your <head> snippet:

<?= css($kirby->plugin('ianhobbs/audio-block')->asset('audio-player.css')->url()) ?>

Use the plugin asset URL rather than a hardcoded media/plugins/... path — Kirby 5 publishes plugin assets under a cache-busting hash, and the un-hashed path is deprecated.

You can also skip the shipped stylesheet entirely ('ianhobbs.audio-block.css' => false) and style the block classes (audio-wrapper, audio-poster, audio-info, audio-title, audio-subtitle, audio-description, audio-playbar) yourself, or adapt the snippet at snippets/blocks/audio-player.php.

If your site uses Kirby's page cache, flush it after updating the plugin — the asset URL carries a hash of the stylesheet's modification time, and cached pages keep the old one.

Note: auto-injection detects the block by the audio-wrapper class. If you override the snippet in site/snippets/blocks/audio-player.php and drop that class, set the option to false and load your CSS yourself.

Customisation with design tokens

Every spacing, text-size, and colour value in the shipped stylesheet reads a --ap-* CSS custom property (design token) with a built-in fallback. No configuration is required — without any tokens defined, the block renders with the defaults listed below.

To customise, define the tokens in your site's CSS — in a plain stylesheet, or generated by your CSS build step (Sass/PostCSS/Tailwind theme, etc.). Any scope that contains the block works; :root is simplest:

:root {
  /* colours */
  --ap-color-bg: #1a1a2e;
  --ap-color-text: #f4f4f4;

  /* spacing — plain values, or your own scale */
  --ap-radius: var(--spacing-4-m);
  --ap-gap: 1rem;
  --ap-pad: 0.75rem;
  --ap-pad-md: 1.5rem;
  --ap-poster-size: 10rem;
  --ap-playbar-gap: var(--spacing-2);
  --ap-playbar-height: var(--spacing-5-l);
  --ap-playbar-radius: 0.5rem;

  /* playbar */
  --ap-playbar-bg: #1a1a2e;
  --ap-playbar-scheme: dark;

  /* text */
  --ap-title-size: 1.75rem;
  --ap-subtitle-size: 1.25rem;
  --ap-description-size: 1rem;
}

Token reference

Token	Default	Controls
`--ap-color-bg`	`#333`	Block background colour
`--ap-color-text`	`#fff`	Text colour
`--ap-shadow`	`0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)`	Drop shadow
`--ap-radius`	`var(--spacing-4-m, 1.75rem)`	Corner radius
`--ap-poster-size`	`12rem`	Poster width and height
`--ap-gap`	`0.5rem`	Gap between poster and text area
`--ap-pad`	`0.5rem`	Text-area padding (small screens)
`--ap-pad-md`	`1rem`	Text-area padding (≥ 768px)
`--ap-title-size`	`1.5rem`	Title font size
`--ap-title-weight`	`400`	Title font weight
`--ap-subtitle-size`	`var(--ap-title-size)`	Subtitle font size
`--ap-subtitle-gap`	`1rem`	Space below subtitle
`--ap-subtitle-opacity`	`0.6`	Subtitle opacity
`--ap-description-size`	`1rem`	Description font size
`--ap-line-height`	`1.5`	Description line height
`--ap-playbar-gap`	`var(--spacing-2, 2rem)`	Space above the audio player
`--ap-playbar-height`	`var(--spacing-5-l, 2rem)`	Audio player height
`--ap-playbar-radius`	`0.5rem`	Playbar corner radius
`--ap-playbar-bg`	`Field`	Playbar background colour
`--ap-playbar-scheme`	`normal`	`color-scheme` of the playbar (`dark` for light icons)

Three of the spacing tokens resolve through a site spacing scale before falling back to a literal: --ap-radius → --spacing-4-m → 1.75rem, --ap-playbar-gap → --spacing-2 → 2rem, --ap-playbar-height → --spacing-5-l → 2rem. Sites with a --spacing-* scale pick it up automatically; sites without one get the literal.

Styling the playbar

The playbar is the browser's own <audio> control, and its interface lives in a user-agent shadow DOM. That sets hard limits on what any stylesheet can reach:

Corner radius (--ap-playbar-radius) applies to the element box, and is passed into the control via ::-webkit-media-controls-enclosure.
Background (--ap-playbar-bg) is honoured on the control panel in Chromium and Safari. Firefox exposes no pseudo-elements for the control, so it keeps its own bar colour there.
Icon, scrubber, and timestamp colours are not stylable in any browser. The one lever is color-scheme: set --ap-playbar-scheme: dark to get the light-icon variant of the control, which is what you want alongside a dark --ap-playbar-bg. Without it, a dark bar gets dark icons.

The --ap-playbar-bg default is the CSS system colour Field — the standard input-surface colour, light or dark according to the effective color-scheme. That keeps the out-of-the-box appearance close to the unstyled control while still being overridable.

Colour precedence

Per-block Panel colour picker — if the editor picks a background or text colour on a block, that wins (emitted as inline --colBG / --colTX).
Site tokens — --ap-color-bg / --ap-color-text from your CSS.
Built-in defaults — #333 background, #fff text.

The Panel colour fields have no preset value, so freshly added blocks follow your site tokens until an editor explicitly picks a colour.

Development

The Panel bundle (index.js, index.css) is built with kirbyup and committed to the repository — no build step is needed to use the plugin.

To modify the Panel preview:

npm run dev    # watch mode
npm run build  # production build

Requirements

Kirby 5
PHP 8.2+

Publishing statement

This plugin is published as free, open-source software under the MIT License. It is provided "as is", without warranty of any kind, express or implied. You are free to use, copy, modify, merge, publish, and distribute it in personal and commercial projects. If you find it useful in a commercial context, please consider supporting Kirby by purchasing a license at getkirby.com/buy — this plugin is not affiliated with or endorsed by the Kirby team.

ianhobbs / audio-block

Package info

Security

Statistics