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) 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)

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. Include it in your template <head>:

<?= css('media/plugins/ianhobbs/audio-block/audio-player.css') ?>

You can also skip the shipped stylesheet and style the block classes (audio-wrapper, audio-poster, audio-info, audio-title, audio-subtitle, audio-description, audio-element) yourself, or adapt the snippet at snippets/blocks/audio-player.php.

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 */
  --ap-radius: 1rem;
  --ap-gap: 1rem;
  --ap-pad: 0.75rem;
  --ap-pad-md: 1.5rem;
  --ap-poster-size: 10rem;

  /* 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`	`0.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-element-gap`	`2rem`	Space above the audio player
`--ap-element-height`	`2rem`	Audio player height

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

Maintainers

Package info

Statistics

Security