Media›Audio

media

Audio

Audio player with optional waveform and chapter markers

Install

  1. Add the package: npm install @refrakt-md/media
  2. Add it to the plugins array in refrakt.config.json: "plugins": ["@refrakt-md/media"]

About the plugin and its runes

Source

import Markdoc from '@markdoc/markdoc';
const { Tag } = Markdoc;
import {
	createContentModelSchema,
	createComponentRenderable,
	renderNodes,
} from '@refrakt-md/runes';
import { parseDuration } from '../duration.js';

export const audioSections = { description: 'description' } as const;

export const audio = createContentModelSchema({
	sections: audioSections,
	attributes: {
		src: { type: String, required: false, description: 'URL of the audio file to play.' },
		playlist: {
			type: String,
			required: false,
			description: 'ID of a playlist rune to load tracks from.',
		},
		title: {
			type: String,
			required: false,
			description: 'Track title shown in the player interface.',
		},
		artist: {
			type: String,
			required: false,
			description: 'Artist name displayed alongside the track title.',
		},
		waveform: {
			type: Boolean,
			required: false,
			description: 'Enable/disable waveform visualization in the player.',
		},
		chapters: {
			type: String,
			required: false,
			description: 'URL of an external chapters file (WebVTT or JSON).',
		},
	},
	contentModel: {
		type: 'sequence',
		fields: [
			{ name: 'description', match: 'paragraph', optional: true, greedy: true },
			{
				name: 'chapterList',
				match: 'list',
				optional: true,
				description: 'Inline chapter markers',
				itemModel: {
					fields: [
						{ name: 'label', match: 'strong', optional: true },
						{ name: 'time', match: 'text', optional: true, pattern: /\((\d+:\d+(?::\d+)?)\)/ },
						{ name: 'text', match: 'text', pattern: 'remainder', optional: false },
					],
				},
			},
		],
	},
	transform(resolved, attrs, config) {
		const src = (attrs.src as string) ?? '';
		const playlistId = (attrs.playlist as string) ?? '';
		const title = (attrs.title as string) ?? '';
		const artist = (attrs.artist as string) ?? '';
		const waveform = (attrs.waveform as boolean) ?? false;
		const chaptersUrl = (attrs.chapters as string) ?? '';

		const playerData: Record<string, any> = {};
		if (src) playerData.src = src;
		if (title) playerData.name = title;
		if (artist) playerData.artist = artist;
		if (playlistId) playerData.playlist = playlistId;

		const chapterData = (resolved.chapterListData as Record<string, unknown>[] | undefined) ?? [];
		if (chapterData.length > 0) {
			playerData.chapters = chapterData.map((ch) => ({
				name: (ch.label as string) || (ch.text as string) || '',
				time: ch.time ? parseDuration(ch.time as string) : 0,
			}));
		}

		const descNodes = renderNodes(resolved.description, config);

		const waveformMeta = waveform ? new Tag('meta', { content: 'true' }) : null;

		const children: any[] = [];

		const audioEl = new Tag(
			'rf-audio',
			{
				waveform: String(waveform),
				...(playlistId ? { playlist: playlistId } : {}),
				...(chaptersUrl ? { chapters: chaptersUrl } : {}),
			},
			[new Tag('script', { type: 'application/json' }, [JSON.stringify(src ? [playerData] : [])])],
		);

		children.push(audioEl);

		if (descNodes.count() > 0) {
			children.push(descNodes.wrap('div', { 'data-name': 'description' }).next());
		}

		return createComponentRenderable({
			rune: 'audio',
			tag: 'div',
			properties: {
				waveform: waveformMeta,
			},
			children,
		});
	},
});

View plugins/media/src/tags/audio.ts on GitHub

An audio player, with an optional waveform, chapter markers, and a link to a playlist it plays from. To list tracks rather than play one, use playlist or track.

Basic usage

A simple audio player with a source file.

{% audio src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%209%20no.%202%20in%20E%20flat%20major.mp3" title="Nocturne Op. 9 No. 2 in E-flat major" artist="Frederic Chopin" /%}
<div data-rune="audio">
  <rf-audio waveform="false">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Nocturne%20Op.%209%20no.%202%20in%20E%20flat%20major.mp3&quot;,&quot;name&quot;:&quot;Nocturne Op. 9 No. 2 in E-flat major&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;}]</script>
  </rf-audio>
</div>
<div class="rf-audio rf-audio--false" data-waveform="false" data-rune="audio" data-density="compact">
  <rf-audio waveform="false">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Nocturne%20Op.%209%20no.%202%20in%20E%20flat%20major.mp3&quot;,&quot;name&quot;:&quot;Nocturne Op. 9 No. 2 in E-flat major&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;}]</script>
  </rf-audio>
</div>

How Markdown is read

You writeIt becomes
A paragraphThe recording's description
A listChapter markers: bold text is a chapter's label, (0:45) its start time

With waveform

Enable waveform visualisation with the waveform attribute.

{% audio src="https://archive.org/download/musopen-chopin/Mazurka%20Op.%207%20no.%204%20in%20A%20flat%20major.mp3" title="Mazurka Op. 7 No. 4 in A-flat major" artist="Frederic Chopin" waveform=true /%}
<div data-rune="audio" data-rune-fields="{&quot;waveform&quot;:&quot;true&quot;}">
  <rf-audio waveform="true">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Mazurka%20Op.%207%20no.%204%20in%20A%20flat%20major.mp3&quot;,&quot;name&quot;:&quot;Mazurka Op. 7 No. 4 in A-flat major&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;}]</script>
  </rf-audio>
</div>
<div class="rf-audio rf-audio--true" data-waveform="true" data-rune="audio" data-density="compact">
  <rf-audio waveform="true">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Mazurka%20Op.%207%20no.%204%20in%20A%20flat%20major.mp3&quot;,&quot;name&quot;:&quot;Mazurka Op. 7 No. 4 in A-flat major&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;}]</script>
  </rf-audio>
</div>

With inline chapters

Add a list inside the rune to define chapter markers. Bold text is the chapter label and parenthetical text is the timestamp.

{% audio src="https://archive.org/download/musopen-chopin/Ballade%20no.%201%20-%20Op.%2023.mp3" title="Ballade No. 1 in G minor, Op. 23" artist="Frederic Chopin" %}

A sweeping narrative arc from brooding introduction through lyrical themes to a fiery conclusion.

1. **Introduction** (0:00) Largo opening over a Neapolitan chord
2. **First Theme** (0:45) Principal theme in G minor
3. **Second Theme** (2:50) Lyrical melody in E-flat major
4. **Development** (4:30) Thematic transformation and modulation
5. **Recapitulation** (7:00) Themes return in reverse order
6. **Coda** (8:30) Presto con fuoco to the dramatic finish
{% /audio %}
<div data-rune="audio">
  <rf-audio waveform="false">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Ballade%20no.%201%20-%20Op.%2023.mp3&quot;,&quot;name&quot;:&quot;Ballade No. 1 in G minor, Op. 23&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;chapters&quot;:[{&quot;name&quot;:&quot;Introduction&quot;,&quot;time&quot;:0},{&quot;name&quot;:&quot;First Theme&quot;,&quot;time&quot;:45},{&quot;name&quot;:&quot;Second Theme&quot;,&quot;time&quot;:170},{&quot;name&quot;:&quot;Development&quot;,&quot;time&quot;:270},{&quot;name&quot;:&quot;Recapitulation&quot;,&quot;time&quot;:420},{&quot;name&quot;:&quot;Coda&quot;,&quot;time&quot;:510}]}]</script>
  </rf-audio>
  <div data-name="description">
    <p>A sweeping narrative arc from brooding introduction through lyrical themes to a fiery conclusion.</p>
  </div>
</div>

A sweeping narrative arc from brooding introduction through lyrical themes to a fiery conclusion.

<div class="rf-audio rf-audio--false" data-waveform="false" data-rune="audio" data-density="compact">
  <rf-audio waveform="false">
    <script type="application/json">[{&quot;src&quot;:&quot;https://archive.org/download/musopen-chopin/Ballade%20no.%201%20-%20Op.%2023.mp3&quot;,&quot;name&quot;:&quot;Ballade No. 1 in G minor, Op. 23&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;chapters&quot;:[{&quot;name&quot;:&quot;Introduction&quot;,&quot;time&quot;:0},{&quot;name&quot;:&quot;First Theme&quot;,&quot;time&quot;:45},{&quot;name&quot;:&quot;Second Theme&quot;,&quot;time&quot;:170},{&quot;name&quot;:&quot;Development&quot;,&quot;time&quot;:270},{&quot;name&quot;:&quot;Recapitulation&quot;,&quot;time&quot;:420},{&quot;name&quot;:&quot;Coda&quot;,&quot;time&quot;:510}]}]</script>
  </rf-audio>
  <div data-name="description" class="rf-audio__description" data-section="description">
    <p>A sweeping narrative arc from brooding introduction through lyrical themes to a fiery conclusion.</p>
  </div>
</div>

Connected to a playlist

Use the playlist attribute to connect the player to a named playlist rune via its id.

{% playlist type="album" artist="Frederic Chopin" id="nocturnes" %}
# Chopin Nocturnes

- **Nocturne Op. 15 No. 1 in F major** [play](https://archive.org/download/musopen-chopin/Nocturne%20Op.%2015%20no.%201%20In%20F%20major.mp3) (5:06)
- **Nocturne Op. 27 No. 1 in C-sharp minor** [play](https://archive.org/download/musopen-chopin/Nocturne%20Op.%2027%20no.%201%20in%20C%20sharp%20minor.mp3) (5:52)
- **Nocturne Op. 32 No. 1 in B major** [play](https://archive.org/download/musopen-chopin/Nocturne%20Op.%2032%20no.%201%20in%20B%20major.mp3) (5:01)
{% /playlist %}

{% audio playlist="nocturnes" /%}
<section data-rune="playlist" data-rune-fields="{&quot;type&quot;:&quot;album&quot;,&quot;media-position&quot;:&quot;top&quot;,&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;id&quot;:&quot;nocturnes&quot;}" typeof="MusicAlbum" data-schema-lists="[&quot;track&quot;]">
  <h1 id="chopin-nocturnes" data-name="headline" property="name">Chopin Nocturnes</h1>
  <ol data-name="tracks">
    <li data-rune="track" data-rune-fields="{&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;duration&quot;:&quot;PT306S&quot;}" elevation="flush" data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2015%20no.%201%20In%20F%20major.mp3" data-field="track" typeof="MusicRecording" property="track">
      <span data-name="track-name" property="name">Nocturne Op. 15 No. 1 in F major</span>
      <meta data-name="artist" content="Frederic Chopin" property="byArtist">
      <meta data-name="duration" content="PT306S" property="duration">
    </li>
    <li data-rune="track" data-rune-fields="{&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;duration&quot;:&quot;PT352S&quot;}" elevation="flush" data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2027%20no.%201%20in%20C%20sharp%20minor.mp3" data-field="track" typeof="MusicRecording" property="track">
      <span data-name="track-name" property="name">Nocturne Op. 27 No. 1 in C-sharp minor</span>
      <meta data-name="artist" content="Frederic Chopin" property="byArtist">
      <meta data-name="duration" content="PT352S" property="duration">
    </li>
    <li data-rune="track" data-rune-fields="{&quot;artist&quot;:&quot;Frederic Chopin&quot;,&quot;duration&quot;:&quot;PT301S&quot;}" elevation="flush" data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2032%20no.%201%20in%20B%20major.mp3" data-field="track" typeof="MusicRecording" property="track">
      <span data-name="track-name" property="name">Nocturne Op. 32 No. 1 in B major</span>
      <meta data-name="artist" content="Frederic Chopin" property="byArtist">
      <meta data-name="duration" content="PT301S" property="duration">
    </li>
  </ol>
  <meta property="byArtist" content="Frederic Chopin">
</section>
<div data-rune="audio">
  <rf-audio waveform="false" playlist="nocturnes">
    <script type="application/json">[]</script>
  </rf-audio>
</div>
album

Chopin Nocturnes

  1. 1Nocturne Op. 15 No. 1 in F major
    Frederic Chopin5:06
  2. 2Nocturne Op. 27 No. 1 in C-sharp minor
    Frederic Chopin5:52
  3. 3Nocturne Op. 32 No. 1 in B major
    Frederic Chopin5:01
<section class="rf-playlist rf-playlist--album" typeof="MusicAlbum" data-schema-lists="[&quot;track&quot;]" data-type="album" data-media-position="top" data-artist="Frederic Chopin" data-id="nocturnes" data-elevation="flat" data-rune="playlist" data-density="full">
  <div data-name="content" class="rf-playlist__content">
    <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" class="rf-playlist__eyebrow">
      <span data-meta-type="category" data-field="type">album</span>
    </div>
    <header data-name="preamble" class="rf-playlist__preamble" data-section="preamble">
      <h1 id="chopin-nocturnes" data-name="headline" property="name" class="rf-playlist__headline" data-section="title">Chopin Nocturnes</h1>
    </header>
    <ol data-name="tracks" data-sequence="numbered" class="rf-playlist__tracks">
      <li data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2015%20no.%201%20In%20F%20major.mp3" data-field="track" typeof="MusicRecording" property="track" data-meta="row" data-artist="Frederic Chopin" data-duration="PT306S" data-elevation="flush" class="rf-track" data-rune="track" data-density="full">
        <span data-name="ordinal" data-meta-type="quantity" class="rf-track__ordinal">1</span>
        <span data-name="track-name" property="name" class="rf-track__track-name">Nocturne Op. 15 No. 1 in F major</span>
        <div data-name="details" data-zone="details" data-zone-layout="bar" class="rf-track__details">
          <span data-field="artist">Frederic Chopin</span>
          <span data-meta-type="quantity" data-align="end" data-field="duration">5:06</span>
        </div>
        <meta data-name="artist" content="Frederic Chopin" property="byArtist" class="rf-track__artist" />
        <meta data-name="duration" content="PT306S" property="duration" class="rf-track__duration" />
      </li>
      <li data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2027%20no.%201%20in%20C%20sharp%20minor.mp3" data-field="track" typeof="MusicRecording" property="track" data-meta="row" data-artist="Frederic Chopin" data-duration="PT352S" data-elevation="flush" class="rf-track" data-rune="track" data-density="full">
        <span data-name="ordinal" data-meta-type="quantity" class="rf-track__ordinal">2</span>
        <span data-name="track-name" property="name" class="rf-track__track-name">Nocturne Op. 27 No. 1 in C-sharp minor</span>
        <div data-name="details" data-zone="details" data-zone-layout="bar" class="rf-track__details">
          <span data-field="artist">Frederic Chopin</span>
          <span data-meta-type="quantity" data-align="end" data-field="duration">5:52</span>
        </div>
        <meta data-name="artist" content="Frederic Chopin" property="byArtist" class="rf-track__artist" />
        <meta data-name="duration" content="PT352S" property="duration" class="rf-track__duration" />
      </li>
      <li data-src="https://archive.org/download/musopen-chopin/Nocturne%20Op.%2032%20no.%201%20in%20B%20major.mp3" data-field="track" typeof="MusicRecording" property="track" data-meta="row" data-artist="Frederic Chopin" data-duration="PT301S" data-elevation="flush" class="rf-track" data-rune="track" data-density="full">
        <span data-name="ordinal" data-meta-type="quantity" class="rf-track__ordinal">3</span>
        <span data-name="track-name" property="name" class="rf-track__track-name">Nocturne Op. 32 No. 1 in B major</span>
        <div data-name="details" data-zone="details" data-zone-layout="bar" class="rf-track__details">
          <span data-field="artist">Frederic Chopin</span>
          <span data-meta-type="quantity" data-align="end" data-field="duration">5:01</span>
        </div>
        <meta data-name="artist" content="Frederic Chopin" property="byArtist" class="rf-track__artist" />
        <meta data-name="duration" content="PT301S" property="duration" class="rf-track__duration" />
      </li>
    </ol>
  </div>
  <meta property="byArtist" content="Frederic Chopin" />
</section>
<div class="rf-audio rf-audio--false" data-waveform="false" data-rune="audio" data-density="compact">
  <rf-audio waveform="false" playlist="nocturnes">
    <script type="application/json">[]</script>
  </rf-audio>
</div>

Attributes

AttributeTypeRequiredDescription
srcstring—URL of the audio file to play.
playliststring—ID of a playlist rune to load tracks from.
titlestring—Track title shown in the player interface.
artiststring—Artist name displayed alongside the track title.
waveformboolean—Enable/disable waveform visualization in the player.
chaptersstring—URL of an external chapters file (WebVTT or JSON).

Universal attributes

bg

The background layer: image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—Gradient start colour — a semantic token name (→ var(--rf-color-*))
bg-gradient"to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl"—Gradient direction (bounded named set)
bg-gradient-type"linear" | "radial" | "conic"—Gradient type
bg-tostring—Gradient end colour — a semantic token name
bg-viastring—Optional middle gradient stop — a semantic token name
scrim"top" | "bottom" | "left" | "right" | "none"—Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim
scrim-blur"none" | "sm" | "md" | "lg"—Frost scrim blur amount
scrim-strength"sm" | "md" | "lg"—Gradient scrim strength
scrim-tone"dark" | "light"—Whether the scrim darkens (for light text) or lightens (for dark text)
scrim-type"gradient" | "frost"—Scrim treatment: gradient (default) or frost (backdrop blur)
elevation

How far the rune sits off the page, from sunken to overlay. The theme decides what each step looks like.

AttributeTypeRequiredDescription
elevation"sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg"—Surface depth, from sunken to overlay. Deprecated: none, sm, md and lg (read as flat, raised, raised and floating)
inset

Internal padding override.

AttributeTypeRequiredDescription
inset"flush" | "tight" | "default" | "loose" | "breathe"—Inner padding of this block
motion

Scroll-reveal entrance. You choose its character; the theme decides how it moves.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—Cascade this block's items in as it reveals (no-op on single-child runes)
prominence

Header emphasis. Scales a rune's header, or its featured quotation; the theme decides the type size for each step.

AttributeTypeRequiredDescription
prominence"quiet" | "normal" | "prominent" | "display" | "marquee"—Emphasis of a page-section header or a featured quotation (only on runes that have one)
spacing

Block-level rhythm override.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills behind the content, drawn by the theme.

AttributeTypeRequiredDescription
substrate"dots" | "grid" | "lines" | "cross" | "checker" | "none"—Generated surface pattern
substrate-fill"inherit" | "inset"—Surface fill the pattern sits on (full colour stays with tint)
substrate-opacity"sm" | "md" | "lg"—Pattern ink strength
substrate-size"sm" | "md" | "lg"—Pattern cell size
substrate-target"self" | "media"—Which surface the pattern fills (overrides the rune/theme default)
tint

Per-rune colour override: a named tint from the theme registry, with inline per-token overrides layered on top.

AttributeTypeRequiredDescription
tintstring—Color tint preset applied to this block
tint-mode"auto" | "dark" | "light"—Whether the tint adapts to auto, dark, or light mode
width

The track a block rune occupies.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
dropcap, readingthis rune declares no prose body
framethis rune declares neither a `frameTarget` nor a media section