Audio Player
Plays an audio file from a URL with basic transport controls (play, pause, stop) and a live waveform visualization whose pattern and colors are configurable. Its only data source is the audio URL.
At a glance
| Type key | audio-player |
| Default size | 4 × 6 (min 3 × 4) |
| Data source | URL to an audio file |
| Emits | — |
| Receives | — |
| Source | src/widgets/widgets/audio-player/ |
Configuration
| Field | Type | Default | Purpose |
|---|---|---|---|
audioUrl | string | "" | URL of the audio file to play. Empty shows a configure-me placeholder. |
title | string | "" | Optional label shown above the controls. |
loop | boolean | false | Restart the track automatically when it ends. |
waveformStyle | "bars" | "mirror" | "line" | "bars" | Visualization pattern. |
waveColor | string | "#38bdf8" | Wave/bar color (hex). |
backgroundColor | string | "transparent" | Canvas background (hex, or transparent). |
barWidth | number (1–24 px) | 3 | Bar width for the bars/mirror styles. |
barGap | number (0–24 px) | 1 | Gap between bars for the bars/mirror styles. |
lineWidth | number (1–12 px) | 2 | Line thickness for the line style. |
Config panel
- Data — audio file URL, optional title, and a play-once/loop toggle.
- Appearance — waveform pattern (Bars, Mirror, Line), wave and background colors, and the bar width/gap (bars/mirror) or line width (line).
Cross-widget actions
None.
Waveform styles
- Bars — vertical frequency bars rising from the baseline.
- Mirror — frequency bars mirrored around a center line.
- Line — a continuous oscilloscope-style waveform line.
Notable behavior
- The visualization is driven by the Web Audio API: on first play the widget
builds an
AnalyserNodegraph from the audio element and paints its samples to a canvas each animation frame while playing. - The browser can only start audio after a user gesture, so the audio graph is created lazily on the first Play click.
- Reading audio samples for the waveform requires a CORS-enabled source. The
element uses
crossOrigin="anonymous"; a cross-origin file served without CORS headers still plays, but the waveform stays flat. - Where the Web Audio API or a 2D canvas context is unavailable, playback still works and the waveform simply doesn't render.