FrameworkJavaScript

Audio block: an inline audio player

A music-player style audio block. It renders an uploaded or linked audio file with a custom control bar. The bar has play/pause, a waveform scrubber, volume, playback speed and loop.

The block also takes optional cover art and title/artist metadata. An optional caption is switched on from the block settings menu (captionVisible). Waveform peaks and duration are decoded once and cached in the saved data, so playback renders instantly on reload.

Audio is sent through a consumer-supplied uploader. When none is provided, the tool falls back to a local blob URL (uploadByFile) or the pasted URL (uploadByUrl).

Share links from Dropbox, GitHub, GitLab, Hugging Face, Google Cloud Storage, and the Internet Archive are rewritten to their direct-content form automatically. Google Drive and OneDrive links also need an uploadByUrl backend, because those hosts block anonymous browser hotlinking.

An optional MIME allowlist and max size gate what is accepted.

Import

TypeScript

import { Audio } from '@bloklabs/core/tools';

Configuration

Option	Type	Default	Description
`uploader`	`AudioUploader`	`undefined`	Consumer-supplied uploader with optional `uploadByFile(file, ctx)` (resolving to `{ url, fileName? }`) and `uploadByUrl(url, ctx)` (resolving to `{ url }`) methods. The `ctx.onProgress(percent)` callback reports upload progress. When omitted, audio falls back to a blob URL or the pasted URL.
`types`	`string[]`	`['audio/*']`	Accepted MIME allowlist. Entries may be exact (`audio/mpeg`) or family wildcards (`audio/*`). Defaults to any audio type.
`maxSize`	`MaxSizeConfig`	`30 MiB`	Max upload size. A number caps every type (bytes). An object caps each MIME type, with `'*'` as the fallback.
`onUploadError`	`UploadErrorHandler`	`undefined`	Called when an upload fails. It receives `{ code, tool, message, file?, url?, size?, maxSize?, cause }`. Return nothing: the block shows its own message. Return a string: the block shows it instead. Return `false`: the block goes back to its empty state with no error, so you can show a toast. A rejection from your own uploader arrives as `UPLOAD_FAILED`. The original error is in `cause`.
`sources`	`'upload' \| 'url' \| 'both'`	`'both'`	Restrict how the media may be added: file upload only, URL only, or both.
`captionPlaceholder`	`string`	`"Write a caption…"`	Placeholder text shown in the caption field.

Save Data

TypeScript

interface AudioData {
  url: string;             // Audio source URL — http(s) or blob:
  caption?: string;        // Plain-text caption
  captionVisible?: boolean; // Caption is opt-in — switch it on in block settings
  title?: string;          // Track title (from file metadata or edited)
  artist?: string;         // Track artist
  coverUrl?: string;       // Cover art image URL
  loop?: boolean;          // Loop playback
  width?: number;          // Pass-through width value; not currently surfaced in the audio UI
  alignment?: 'left' | 'center' | 'right';
  fileName?: string;       // Original filename, when known
  mimeType?: string;       // MIME type
  duration?: number;       // Decoded duration in seconds (cached)
  peaks?: number[];        // Cached waveform peaks for the scrubber
}

JSON

{
  "id": "aud001",
  "type": "audio",
  "data": {
    "url": "https://example.com/media/track.mp3",
    "fileName": "track.mp3",
    "mimeType": "audio/mpeg",
    "title": "My Song",
    "artist": "The Artist",
    "alignment": "center"
  }
}

Usage Example

TypeScript

import { Blok } from '@bloklabs/core';
import { Audio } from '@bloklabs/core/tools';

const editor = new Blok({
  holder: 'editor',
  tools: {
    audio: {
      class: Audio,
      config: {
        uploader: {
          async uploadByFile(file) {
            const url = await myUpload(file);
            return { url, fileName: file.name };
          },
        },
      },
    },
  },
});