FrameworkJavaScript

Audio block: an inline audio player

A music-player style audio block. Renders an uploaded or linked audio file with a custom control bar (play/pause, a waveform scrubber, volume, playback speed, loop), optional cover art, title/artist metadata, and a caption. 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, OneDrive, GitHub, GitLab, Hugging Face, Google Cloud Storage, and the Internet Archive are rewritten to their direct-content form automatically; Google Drive links additionally require an `uploadByUrl` backend because Drive blocks 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 per MIME type with `'*'` as the fallback.
`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 visible in the rendered state
  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 };
          },
        },
      },
    },
  },
});