{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "audio-player", "title": "Audio Player", "author": "Ballmac ", "description": "A podcast-style audio player: play and pause, skip back and forward, a scrubber with chapter ticks, a named current chapter and a speed control. Works with a real file or as a silent demo.", "dependencies": [ "lucide-react" ], "registryDependencies": [ "utils", "https://ui.ballmac.com/r/slider.json", "https://ui.ballmac.com/r/i18n.json" ], "files": [ { "path": "registry/ballmac/components/audio-player.tsx", "content": "// Ballmac UI: Audio Player. https://ui.ballmac.com/components/audio-player\n\"use client\"\n\nimport * as React from \"react\"\nimport { Pause, Play, RotateCcw, RotateCw } from \"lucide-react\"\n\nimport { Slider } from \"@/components/ballmac/slider\"\nimport { cn } from \"@/lib/utils\"\nimport { useMessages } from \"@/lib/ballmac/i18n\"\n\ntype AudioChapter = {\n /** Start time in seconds. */\n start: number\n /** Chapter title. */\n title: string\n}\n\ntype AudioPlayerProps = Omit, \"title\" | \"onTimeUpdate\"> & {\n /** Audio file URL. Leave it out for a silent demo that advances a clock, so you can design the page before the audio exists. */\n src?: string\n /** Episode or track title. */\n title: string\n /** Show or artist, shown under the title. */\n subtitle?: string\n /** Length in seconds. Used before the file's metadata loads, and as the length of a silent demo. */\n duration?: number\n /** Chapters. Drawn as ticks on the scrubber, and the current one is named under the title. */\n chapters?: AudioChapter[]\n /** Artwork shown on the left. */\n artwork?: React.ReactNode\n /** Playback speeds the speed button cycles through. */\n rates?: number[]\n /** Seconds the back and forward buttons skip. */\n skip?: { back: number; forward: number }\n /** Controlled position in seconds. */\n time?: number\n /** Called when the position changes (playback, seeking or skipping). */\n onTimeChange?: (seconds: number) => void\n /** Called when play or pause is chosen. */\n onPlayingChange?: (playing: boolean) => void\n /** \"compact\" is a single row, for a sticky mini player. */\n variant?: \"default\" | \"compact\"\n}\n\n/** m:ss, or h:mm:ss for long audio. */\nfunction formatTime(s: number) {\n const t = Math.max(0, Math.floor(s))\n const h = Math.floor(t / 3600)\n const m = Math.floor((t % 3600) / 60)\n const sec = String(t % 60).padStart(2, \"0\")\n return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${sec}` : `${m}:${sec}`\n}\n\n/** An audio player with play and pause, skip back and forward, a scrubber, chapters and a speed control. Works with a real file or as a silent demo. */\nfunction AudioPlayer({\n src,\n title,\n subtitle,\n duration: durationProp = 0,\n chapters = [],\n artwork,\n rates = [1, 1.25, 1.5, 2, 0.75],\n skip = { back: 15, forward: 30 },\n time: timeProp,\n onTimeChange,\n onPlayingChange,\n variant = \"default\",\n className,\n ...props\n}: AudioPlayerProps) {\n const msg = useMessages()\n const audio = React.useRef(null)\n const [inner, setInner] = React.useState(0)\n const [length, setLength] = React.useState(durationProp)\n const [playing, setPlaying] = React.useState(false)\n const [rateIndex, setRateIndex] = React.useState(0)\n const time = timeProp ?? inner\n const rate = rates[rateIndex] ?? 1\n const total = length || durationProp\n\n // Latest values for the timer and the change callback, kept in refs so they never restart the interval.\n const timeRef = React.useRef(time)\n const onTimeRef = React.useRef(onTimeChange)\n React.useEffect(() => {\n timeRef.current = time\n onTimeRef.current = onTimeChange\n })\n\n // Report every change of position once, whether it came from playback, the scrubber or a skip.\n const first = React.useRef(true)\n React.useEffect(() => {\n if (first.current) {\n first.current = false\n return\n }\n onTimeRef.current?.(inner)\n }, [inner])\n\n // A silent demo (no src) advances its own clock.\n React.useEffect(() => {\n if (src || !playing) return\n const id = setInterval(() => {\n const next = Math.min(total, timeRef.current + 0.25 * rate)\n timeRef.current = next\n setInner(next)\n if (next >= total) {\n setPlaying(false)\n onPlayingChange?.(false)\n }\n }, 250)\n return () => clearInterval(id)\n }, [src, playing, rate, total, onPlayingChange])\n\n // Keep a real element in step with what the controls say.\n React.useEffect(() => {\n const el = audio.current\n if (!el) return\n el.playbackRate = rate\n }, [rate])\n React.useEffect(() => {\n const el = audio.current\n if (!el || timeProp === undefined) return\n if (Math.abs(el.currentTime - timeProp) > 1) el.currentTime = timeProp\n }, [timeProp])\n\n function toggle() {\n const next = !playing\n const el = audio.current\n if (el) {\n if (next) el.play().catch(() => setPlaying(false))\n else el.pause()\n } else if (next && total && time >= total) {\n setInner(0)\n }\n setPlaying(next)\n onPlayingChange?.(next)\n }\n function seek(to: number) {\n const clamped = Math.min(Math.max(0, to), total || to)\n setInner(clamped)\n if (audio.current) audio.current.currentTime = clamped\n }\n\n const chapter = [...chapters].reverse().find((c) => time >= c.start)\n const label = `${formatTime(time)} of ${formatTime(total)}`\n const btn = \"text-foreground hover:bg-accent focus-visible:ring-ring/50 inline-flex shrink-0 items-center justify-center rounded-full outline-none transition-colors focus-visible:ring-[3px]\"\n\n const controls = (\n
\n \n \n \n
\n )\n\n const scrubber = (\n
\n
\n seek(v[0] ?? 0)}\n formatValue={(v) => label.replace(formatTime(time), formatTime(v))}\n />\n {chapters.length > 1 && total > 0 && (\n
\n {chapters.slice(1).map((c) => )}\n
\n )}\n
\n
\n {formatTime(time)}\n −{formatTime(Math.max(0, total - time))}\n
\n
\n )\n\n const speed = (\n \n )\n\n return (\n
\n {src &&
\n )\n}\n\nexport { AudioPlayer, formatTime, type AudioChapter, type AudioPlayerProps }\n", "type": "registry:ui", "target": "@components/ballmac/audio-player.tsx" } ], "meta": { "schema": 1, "tier": "free", "tags": [ "audio", "player", "podcast", "music", "media", "chapters", "speed" ], "version": "1.0.0", "updated": "2026-10-01", "ai": { "summary": "Pass src (omit it for a silent demo), title, duration and optional chapters=[{ start, title }]. Control the position with time and onTimeChange to sync a transcript. variant='compact' is a one-row mini player.", "whenToUse": [ "Podcast episodes, audio articles, voice notes and music previews", "Syncing a transcript or chapter list to playback" ], "whenNotToUse": [ "Video (use the native video element or video-dialog)" ], "composesWith": [ "slider", "segmented-control", "scroll-area" ], "a11y": [ { "keys": "Space / Enter on Play", "action": "Plays or pauses; the name switches between Play and Pause" }, { "keys": "Arrow keys on the scrubber", "action": "Seeks one second; Page Up / Down seeks more; the value reads as 'm:ss of m:ss'" }, { "keys": "Skip buttons", "action": "Jump back or forward by the configured seconds" } ], "customization": [ "rates: the speeds the speed button cycles through", "skip: { back, forward } seconds", "artwork: any node", "variant: default or compact" ] }, "examples": [ "audio-player-demo", "audio-player-compact" ], "url": "https://ui.ballmac.com/components/audio-player" }, "categories": [ "data-display" ], "type": "registry:ui" }