@jackuait/blok 0.17.0 → 0.19.0

package/src/tools/audio/index.ts

@@ -0,0 +1,482 @@
+import type {
+  API,
+  BlockAPI,
+  BlockTool,
+  BlockToolConstructorOptions,
+  FilePasteEvent,
+  PasteConfig,
+  PasteEvent,
+  PatternPasteEvent,
+  ToolboxConfig,
+} from '../../../types';
+import type { MenuConfig } from '../../../types/tools/menu-config';
+import type { AudioAlignment, AudioConfig, AudioData } from '../../../types/tools/audio';
+import {
+  IconAlignCenter,
+  IconAlignLeft,
+  IconAlignRight,
+  IconCaption,
+  IconCopy,
+  IconDownload,
+  IconMusic,
+  IconPlayerLoop,
+  IconReplace,
+} from '../../components/icons';
+import { renderUploadingState, type UploadingStateElement } from '../image/uploading-state';
+import { DEFAULT_CAPTION_PLACEHOLDER, URL_PATTERN } from './constants';
+import { renderEmptyState, type EmptyStateElement } from './empty-state';
+import { tr } from './i18n';
+import { renderCaptionRow, renderNowPlaying } from './ui';
+import { attachControls, type ControlsHandle } from './controls';
+import { attachWaveform, decodePeaks, type WaveformHandle } from './waveform';
+import { readTrackMetadata, resolveCover } from './metadata';
+import { Uploader, AudioUploadError, type UploadResult } from './uploader';
+import { uploadErrorMessage } from '../../components/utils/upload-error-message';
+import { pickDisplayMaxSize } from '../../components/utils/max-size';
+
+type ToolState = 'EMPTY' | 'LOADING' | 'RENDERED' | 'ERROR';
+
+export class AudioTool implements BlockTool {
+  private readonly api: API;
+  private readonly block: BlockAPI;
+  private readonly config: AudioConfig;
+  private readonly uploader: Uploader;
+  private data: AudioData;
+  private readOnly: boolean;
+  private root: HTMLElement | null = null;
+  private state: ToolState;
+  private uploadingEl: UploadingStateElement | null = null;
+  private lastFileName: string | null = null;
+  private errorMessage: string | null = null;
+  private lastSource: { kind: 'file'; file: File } | { kind: 'url'; url: string } | null = null;
+  private controlsHandle: ControlsHandle | null = null;
+  private waveformHandle: WaveformHandle | null = null;
+  private destroyed = false;
+
+  constructor(options: BlockToolConstructorOptions<AudioData, AudioConfig>) {
+    this.api = options.api;
+    this.block = options.block;
+    this.config = options.config ?? {};
+    this.readOnly = options.readOnly;
+    this.data = { ...options.data, url: options.data?.url ?? '' };
+    this.state = this.data.url ? 'RENDERED' : 'EMPTY';
+    this.uploader = new Uploader(this.config);
+  }
+
+  public render(): HTMLElement {
+    const root = document.createElement('div');
+    root.setAttribute('data-blok-tool', 'audio');
+    this.root = root;
+    this.renderState();
+    return root;
+  }
+
+  public save(_block?: HTMLElement): AudioData {
+    const out: AudioData = { url: this.data.url };
+    if (this.data.caption !== undefined) out.caption = this.data.caption;
+    if (this.data.captionVisible !== undefined) out.captionVisible = this.data.captionVisible;
+    if (this.data.title !== undefined) out.title = this.data.title;
+    if (this.data.artist !== undefined) out.artist = this.data.artist;
+    if (this.data.coverUrl !== undefined) out.coverUrl = this.data.coverUrl;
+    if (this.data.loop) out.loop = true;
+    if (this.data.width !== undefined) out.width = this.data.width;
+    if (this.data.alignment !== undefined) out.alignment = this.data.alignment;
+    if (this.data.fileName !== undefined) out.fileName = this.data.fileName;
+    if (this.data.mimeType !== undefined) out.mimeType = this.data.mimeType;
+    if (this.data.duration !== undefined) out.duration = this.data.duration;
+    if (this.data.peaks !== undefined) out.peaks = this.data.peaks;
+    return out;
+  }
+
+  public validate(data: AudioData): boolean {
+    return typeof data.url === 'string' && data.url.length > 0;
+  }
+
+  public static get toolbox(): ToolboxConfig {
+    return {
+      icon: IconMusic,
+      titleKey: 'audio',
+      searchTerms: ['audio', 'music', 'sound', 'song', 'mp3', 'track', 'media'],
+    };
+  }
+
+  public static get isReadOnlySupported(): boolean {
+    return true;
+  }
+
+  public static get pasteConfig(): PasteConfig {
+    return {
+      patterns: { audio: URL_PATTERN },
+      files: { mimeTypes: ['audio/*'] },
+    };
+  }
+
+  public onPaste(event: PasteEvent): void {
+    if (event.type === 'pattern') {
+      this.applyResult({ url: (event as PatternPasteEvent).detail.data });
+      return;
+    }
+    if (event.type === 'file') {
+      this.startUpload((event as FilePasteEvent).detail.file);
+    }
+  }
+
+  public getToolbarAnchorElement(): HTMLElement | undefined {
+    return this.root?.querySelector<HTMLElement>('[data-role="audio-figure"]') ?? undefined;
+  }
+
+  public setReadOnly(state: boolean): void {
+    this.readOnly = state;
+    this.renderState();
+  }
+
+  public renderSettings(): MenuConfig {
+    const i18n = this.api.i18n;
+    const current: AudioAlignment = this.data.alignment ?? 'center';
+    const captionVisible = this.data.captionVisible !== false;
+    const alignments: { value: AudioAlignment; title: string; icon: string }[] = [
+      { value: 'left', title: tr(i18n, 'tools.audio.alignmentLeft', 'Align left'), icon: IconAlignLeft },
+      { value: 'center', title: tr(i18n, 'tools.audio.alignmentCenter', 'Align center'), icon: IconAlignCenter },
+      { value: 'right', title: tr(i18n, 'tools.audio.alignmentRight', 'Align right'), icon: IconAlignRight },
+    ];
+    const alignIcon = alignments.find((a) => a.value === current)?.icon ?? alignments[1].icon;
+
+    return [
+      {
+        icon: alignIcon,
+        title: tr(i18n, 'tools.audio.alignment', 'Alignment'),
+        name: 'audio-alignment',
+        children: {
+          items: alignments.map((a) => ({
+            icon: a.icon,
+            title: a.title,
+            name: `audio-alignment-${a.value}`,
+            isActive: current === a.value,
+            closeOnActivate: true,
+            onActivate: (): void => this.setAlignment(a.value),
+          })),
+        },
+      },
+      {
+        icon: IconCaption,
+        title: tr(i18n, 'tools.audio.caption', 'Caption'),
+        name: 'audio-caption',
+        isActive: captionVisible,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleCaption(),
+      },
+      {
+        icon: IconPlayerLoop,
+        title: tr(i18n, 'tools.audio.loop', 'Loop'),
+        name: 'audio-loop',
+        isActive: this.data.loop === true,
+        closeOnActivate: true,
+        onActivate: (): void => this.toggleLoop(),
+      },
+      {
+        icon: IconReplace,
+        title: tr(i18n, 'tools.audio.replace', 'Replace audio'),
+        name: 'audio-replace',
+        closeOnActivate: true,
+        onActivate: (): void => this.transitionToEmpty(),
+      },
+      {
+        icon: IconDownload,
+        title: tr(i18n, 'tools.audio.download', 'Download'),
+        name: 'audio-download',
+        closeOnActivate: true,
+        onActivate: (): void => this.download(),
+      },
+      {
+        icon: IconCopy,
+        title: tr(i18n, 'tools.audio.copyUrl', 'Copy URL'),
+        name: 'audio-copy-url',
+        closeOnActivate: true,
+        onActivate: (): void => this.copyUrl(),
+      },
+    ];
+  }
+
+  public removed(): void {
+    this.destroyed = true;
+    this.controlsHandle?.destroy();
+    this.controlsHandle = null;
+    this.waveformHandle?.destroy();
+    this.waveformHandle = null;
+    if (this.data.url.startsWith('blob:')) {
+      URL.revokeObjectURL(this.data.url);
+    }
+  }
+
+  private startUpload(file: File): void {
+    this.lastFileName = file.name;
+    this.lastSource = { kind: 'file', file };
+    this.state = 'LOADING';
+    this.renderState();
+    void this.uploader
+      .handleFile(file, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
+      .then((result) => this.applyResult(result, file))
+      .catch((err) => this.applyError(err));
+  }
+
+  private startUrl(url: string): void {
+    this.lastFileName = null;
+    this.lastSource = { kind: 'url', url };
+    this.state = 'LOADING';
+    this.renderState();
+    void this.uploader
+      .handleUrl(url, { onProgress: (p) => this.uploadingEl?.setProgress(p) })
+      .then((result) => this.applyResult(result))
+      .catch((err) => this.applyError(err));
+  }
+
+  private applyResult(result: UploadResult, file?: File): void {
+    this.data = {
+      ...this.data,
+      url: result.url,
+      fileName: result.fileName ?? this.lastFileName ?? this.data.fileName,
+      mimeType: file?.type || this.data.mimeType,
+    };
+    this.errorMessage = null;
+    this.state = 'RENDERED';
+    this.renderState();
+    this.block.dispatchChange();
+
+    // Asynchronous enrichment from a real File upload (not URL paste).
+    if (file) {
+      // Metadata: title, artist, cover
+      void readTrackMetadata(file)
+        .then(async (meta) => {
+          if (this.destroyed) return;
+          const dirty = { value: false };
+          if (meta.title) { this.data.title = meta.title; dirty.value = true; }
+          if (meta.artist) { this.data.artist = meta.artist; dirty.value = true; }
+          if (meta.cover) {
+            const coverUrl = await resolveCover(meta.cover, this.config.uploader).catch(() => undefined);
+            if (coverUrl) { this.data.coverUrl = coverUrl; dirty.value = true; }
+          }
+          if (this.destroyed) return;
+          if (dirty.value) {
+            this.renderState();
+            this.block.dispatchChange();
+          }
+        })
+        .catch(() => { /* leave player working without metadata */ });
+
+      // Waveform peaks + duration
+      void decodePeaks(file)
+        .then((decoded) => {
+          if (this.destroyed) return;
+          if (decoded && decoded.peaks.length) {
+            this.data.peaks = decoded.peaks;
+            this.data.duration = decoded.duration;
+            this.renderState();
+            this.block.dispatchChange();
+          }
+        })
+        .catch(() => { /* leave player working without waveform */ });
+    }
+  }
+
+  private applyError(err?: unknown): void {
+    this.errorMessage = err instanceof AudioUploadError
+      ? uploadErrorMessage(err, (key) => this.api.i18n.t(key), {
+        tooLarge: 'tools.audio.errorFileTooLarge',
+        generic: 'tools.audio.errorUploadFailed',
+      })
+      : null;
+    this.state = 'ERROR';
+    this.renderState();
+  }
+
+  private syncRootAttributes(): void {
+    if (!this.root) return;
+    const r = this.root;
+    r.setAttribute('data-state', this.state.toLowerCase());
+    r.setAttribute('data-align', this.data.alignment ?? 'center');
+    r.setAttribute('data-caption', this.data.captionVisible === false ? 'off' : 'on');
+  }
+
+  private renderState(): void {
+    if (!this.root) return;
+    this.controlsHandle?.destroy();
+    this.controlsHandle = null;
+    this.waveformHandle?.destroy();
+    this.waveformHandle = null;
+    this.root.replaceChildren();
+    this.uploadingEl = null;
+    this.syncRootAttributes();
+
+    if (this.state === 'EMPTY') {
+      this.renderEmpty();
+      return;
+    }
+    if (this.state === 'LOADING') {
+      this.renderLoading();
+      return;
+    }
+    if (this.state === 'ERROR') {
+      this.renderError();
+      return;
+    }
+    this.renderRendered();
+  }
+
+  private renderEmpty(): void {
+    if (!this.root) return;
+    const el: EmptyStateElement = renderEmptyState({
+      onFile: (file) => this.startUpload(file),
+      onUrl: (url) => this.startUrl(url),
+      acceptTypes: this.config.types,
+      maxSize: pickDisplayMaxSize(this.config.maxSize),
+      i18n: this.api.i18n,
+    });
+    this.root.appendChild(el);
+  }
+
+  private renderLoading(): void {
+    if (!this.root) return;
+    this.uploadingEl = renderUploadingState({
+      fileName: this.lastFileName ?? tr(this.api.i18n, 'tools.audio.uploading', 'Uploading…'),
+      onCancel: () => this.transitionToEmpty(),
+      i18n: this.api.i18n,
+    });
+    this.root.appendChild(this.uploadingEl);
+  }
+
+  private renderError(): void {
+    if (!this.root) return;
+    const wrap = document.createElement('div');
+    wrap.className = 'blok-audio-error-state';
+    wrap.setAttribute('data-role', 'audio-error');
+
+    const message = document.createElement('span');
+    message.textContent = this.errorMessage ?? tr(this.api.i18n, 'tools.audio.errorUploadFailed', 'Upload failed');
+
+    const retry = document.createElement('button');
+    retry.type = 'button';
+    retry.className = 'blok-audio-retry';
+    retry.setAttribute('data-action', 'replace');
+    retry.textContent = tr(this.api.i18n, 'tools.audio.errorReplace', 'Replace');
+    retry.addEventListener('click', () => this.transitionToEmpty());
+
+    wrap.append(message, retry);
+    this.root.appendChild(wrap);
+  }
+
+  private renderRendered(): void {
+    if (!this.root) return;
+    const titlePlaceholder = tr(this.api.i18n, 'tools.audio.titlePlaceholder', 'Track title');
+    const artistPlaceholder = tr(this.api.i18n, 'tools.audio.artistPlaceholder', 'Artist');
+
+    const { figure, audio, waveformMount, title, artist, body } = renderNowPlaying(this.data, {
+      editable: !this.readOnly,
+      titlePlaceholder,
+      artistPlaceholder,
+    });
+
+    // Waveform (if peaks are available)
+    if (this.data.peaks?.length) {
+      this.waveformHandle = attachWaveform({ mount: waveformMount, media: audio, peaks: this.data.peaks });
+    }
+
+    // Transport controls — appended into the right-column body (under waveform)
+    this.controlsHandle = attachControls({
+      media: audio,
+      figure,
+      data: this.data,
+      onLoopChange: (loop) => {
+        this.data.loop = loop || undefined;
+        this.block.dispatchChange();
+      },
+    });
+    body.appendChild(this.controlsHandle.element);
+
+    // Caption row — outside body, below the card
+    const placeholder = this.config.captionPlaceholder ?? DEFAULT_CAPTION_PLACEHOLDER;
+    const captionVisible = this.data.captionVisible !== false;
+    if (captionVisible || !this.readOnly) {
+      figure.appendChild(renderCaptionRow({
+        value: this.data.caption ?? '',
+        placeholder,
+        editable: !this.readOnly,
+      }));
+    }
+
+    // Wire title/artist blur handlers
+    title.addEventListener('blur', () => {
+      const next = title.textContent ?? '';
+      if (next !== this.data.title) {
+        this.data.title = next || undefined;
+        this.block.dispatchChange();
+      }
+    });
+    artist.addEventListener('blur', () => {
+      const next = artist.textContent ?? '';
+      if (next !== this.data.artist) {
+        this.data.artist = next || undefined;
+        this.block.dispatchChange();
+      }
+    });
+
+    // Wire caption blur handler
+    const captionEl = figure.querySelector<HTMLElement>('[data-role="audio-caption"]');
+    if (captionEl) {
+      captionEl.addEventListener('blur', () => {
+        const next = captionEl.textContent ?? '';
+        if (next !== this.data.caption) {
+          this.data.caption = next || undefined;
+          this.block.dispatchChange();
+        }
+      });
+    }
+
+    this.root.appendChild(figure);
+  }
+
+  private setAlignment(next: AudioAlignment): void {
+    if (this.data.alignment === next) return;
+    this.data.alignment = next;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleCaption(): void {
+    this.data.captionVisible = this.data.captionVisible === false;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private toggleLoop(): void {
+    this.data.loop = this.data.loop !== true ? true : undefined;
+    this.block.dispatchChange();
+    this.renderState();
+  }
+
+  private transitionToEmpty(): void {
+    this.data = { ...this.data, url: '' };
+    this.state = 'EMPTY';
+    this.lastSource = null;
+    this.lastFileName = null;
+    this.renderState();
+    this.block.dispatchChange();
+  }
+
+  private download(): void {
+    const a = document.createElement('a');
+    a.href = this.data.url;
+    a.download = this.data.fileName ?? '';
+    a.target = '_blank';
+    a.rel = 'noopener';
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+  }
+
+  private copyUrl(): void {
+    const clip = navigator.clipboard;
+    if (clip && typeof clip.writeText === 'function') {
+      void clip.writeText(this.data.url);
+    }
+  }
+}

package/src/tools/audio/liveliness.ts

@@ -0,0 +1,136 @@
+/**
+ * Waveform "now playing" liveliness math.
+ *
+ * The cached peaks are static — there's no real-time FFT — so the sense of a
+ * live visualizer is composed from two layers:
+ *
+ *   1. A focal **comet** at the playhead: a bright head spike, a tight leading
+ *      edge, and a longer decaying wake trailing into the already-played bars.
+ *      It travels left→right as playback advances.
+ *   2. A global **ambient** ripple that flows across the entire field so no bar
+ *      sits frozen. It's biased stronger on the played side (a shimmering wake
+ *      of music) and faint on the not-yet-played preview ahead.
+ *
+ * All functions are pure so the behaviour is unit-testable; the canvas in
+ * waveform.ts just samples them per bar, per frame.
+ */
+
+/** Bars ahead of the playhead (not yet played) that still react. */
+export const REACH_AHEAD = 4;
+/** Bars behind the playhead (already played) that keep a decaying wake. */
+export const REACH_BEHIND = 9;
+
+/**
+ * Asymmetric "comet" falloff around the playhead. `distance` is the bar index
+ * minus the fractional playhead index: negative = behind (already-played wake),
+ * positive = ahead (not yet played). The wake reaches further than the leading
+ * edge so the energy reads as travelling with momentum. 1 at the playhead,
+ * easing to 0 at the respective reach.
+ */
+export function cometEnvelope(distance: number, reachAhead = REACH_AHEAD, reachBehind = REACH_BEHIND): number {
+  const reach = distance < 0 ? reachBehind : reachAhead;
+  const d = Math.abs(distance);
+  if (d >= reach) return 0;
+  const t = 1 - d / reach;
+  return t * t;
+}
+
+/**
+ * Tight symmetric spike centred on the playhead so the bar under it stands
+ * clearly proud of its neighbours — the bright head of the comet. Falls off
+ * faster (cubed) than the comet body.
+ */
+export function headFocus(distance: number, reach = 3): number {
+  const d = Math.abs(distance);
+  if (d >= reach) return 0;
+  const t = 1 - d / reach;
+  return t * t * t;
+}
+
+/**
+ * Deterministic per-bar wobble in [-1, 1]. Two out-of-phase sines keyed to the
+ * bar index so neighbouring bars rise and fall independently — the cluster
+ * reads as a dancing equalizer rather than one uniform swell.
+ */
+export function barWobble(index: number, timeSeconds: number): number {
+  const a = Math.sin(timeSeconds * 8.5 + index * 0.7);
+  const b = Math.sin(timeSeconds * 5.3 + index * 1.9);
+  return a * 0.6 + b * 0.4;
+}
+
+/**
+ * Slow travelling undulation across the whole bar field, in [-1, 1]. Two waves
+ * propagate in opposite directions (the `-index`/`+index` phase terms) so the
+ * field gently churns rather than sliding uniformly. Kept low-frequency so the
+ * motion is graceful, not busy.
+ */
+export function ambientWave(index: number, timeSeconds: number): number {
+  const a = Math.sin(timeSeconds * 2.1 - index * 0.35);
+  const b = Math.sin(timeSeconds * 1.3 + index * 0.21);
+  return a * 0.6 + b * 0.4;
+}
+
+/** Ambient swing applied to every bar (the faint preview-side breath). */
+const AMBIENT_BASE = 0.035;
+/** Extra ambient swing layered onto the played side (the shimmering wake). */
+const AMBIENT_PLAYED = 0.06;
+/** Bars ahead of the playhead over which the played-side shimmer fades out. */
+const AMBIENT_AHEAD_FADE = 26;
+
+/**
+ * Ease-out cubic for the head-colour entrance ramp: 0→1 with most of the travel
+ * up front, so the colour blooms in quickly then settles. Clamped to [0, 1].
+ */
+export function entranceEase(progress: number): number {
+  const t = Math.min(1, Math.max(0, progress));
+  return 1 - (1 - t) ** 3;
+}
+
+/**
+ * 0..1 tint strength for a bar's comet-head colour overlay. Peaks at the
+ * playhead (via {@link headFocus}) and scales with both the live `energy` (so it
+ * fades out on the pause settle) and the `entrance` ramp (so it animates in when
+ * playback starts).
+ */
+export function headColorBlend(opts: { distance: number; energy: number; entrance: number }): number {
+  return headFocus(opts.distance) * opts.energy * opts.entrance;
+}
+
+interface LiveAmplitudeOptions {
+  basePeak: number;
+  index: number;
+  /** Fractional bar position of the playhead (played * peaks.length). */
+  playheadIndex: number;
+  timeSeconds: number;
+  reduced: boolean;
+  /** 0..1 multiplier on the live boost — 1 while playing, ramps to 0 on the pause settle. */
+  energy?: number;
+}
+
+/**
+ * Final 0..1 bar amplitude, blending the static peak with two live layers: the
+ * playhead-localized comet (body swell + bright head spike + bidirectional
+ * dance) and a global ambient ripple biased toward the played side. The
+ * combined boost is scaled by `energy` (for the pause settle) and zeroed under
+ * `reduced` (prefers-reduced-motion).
+ */
+export function liveAmplitude(opts: LiveAmplitudeOptions): number {
+  const { basePeak, index, playheadIndex, timeSeconds, reduced, energy = 1 } = opts;
+  if (reduced || energy <= 0) return basePeak;
+
+  const distance = index - playheadIndex;
+
+  // Layer 1 — focal comet near the playhead.
+  const env = cometEnvelope(distance);
+  const head = headFocus(distance);
+  const comet = env * 0.15 + head * 0.2 + env * 0.28 * barWobble(index, timeSeconds);
+
+  // Layer 2 — global ambient ripple. Full strength behind the playhead (the
+  // played wake), fading across AMBIENT_AHEAD_FADE bars into the preview ahead.
+  const playedBias = distance <= 0 ? 1 : Math.max(0, 1 - distance / AMBIENT_AHEAD_FADE);
+  const ambient = ambientWave(index, timeSeconds) * (AMBIENT_BASE + AMBIENT_PLAYED * playedBias);
+
+  const amp = basePeak + (comet + ambient) * energy;
+
+  return Math.min(1, Math.max(0, amp));
+}

package/src/tools/audio/metadata.ts

@@ -0,0 +1,56 @@
+import type { AudioUploader } from '../../../types/tools/audio';
+import { COVER_DATA_URL_CAP_BYTES } from './constants';
+
+export interface RawPicture {
+  data: Uint8Array;
+  format?: string;
+}
+export interface RawTags {
+  common?: { title?: string; artist?: string; picture?: RawPicture[] };
+}
+export interface TrackMeta {
+  title?: string;
+  artist?: string;
+  cover?: { data: Uint8Array; mimeType: string };
+}
+
+export function mapMetadata(raw: RawTags): TrackMeta {
+  const common = raw.common ?? {};
+  const meta: TrackMeta = {};
+  if (common.title) meta.title = common.title;
+  if (common.artist) meta.artist = common.artist;
+  const pic = common.picture?.[0];
+  if (pic) meta.cover = { data: pic.data, mimeType: pic.format ?? 'image/jpeg' };
+  return meta;
+}
+
+function toBase64(bytes: Uint8Array): string {
+  return btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(''));
+}
+
+export async function resolveCover(
+  cover: { data: Uint8Array; mimeType: string },
+  uploader?: AudioUploader,
+): Promise<string | undefined> {
+  if (uploader?.uploadByFile) {
+    const file = new File([new Uint8Array(cover.data)], 'cover', { type: cover.mimeType });
+    const res = await uploader.uploadByFile(file);
+    return res.url;
+  }
+  if (cover.data.byteLength <= COVER_DATA_URL_CAP_BYTES) {
+    return `data:${cover.mimeType};base64,${toBase64(cover.data)}`;
+  }
+  return undefined;
+}
+
+export async function readTrackMetadata(file: File): Promise<TrackMeta> {
+  try {
+    const mm = await import('music-metadata');
+    const buf = new Uint8Array(await file.arrayBuffer());
+    // parseBuffer(uint8Array, fileInfo?: IFileInfo | string) — passing mimeType string is valid
+    const parsed = await mm.parseBuffer(buf, file.type);
+    return mapMetadata(parsed as RawTags);
+  } catch {
+    return {};
+  }
+}