Audio

A Mantine-native audio player for React with waveform visualisation and a live spectrum analyser, built on the Web Audio API. Three layers in one package: a polished default <Audio />, a composable compound API, and a fully headless useAudio hook for 100% custom UIs.

Installation

yarn add @gfazioli/mantine-audio

Overview

Mantine Audio wraps the native HTML <audio> element with three layers of abstraction, layered from “drop-in” to “fully custom”:

• <Audio /> — factory component with four built-in variants (overlay, minimal, floating, bordered), five sizes (xs–xl), full Mantine theme integration, and a sensible default control bar
• Compound API — ten sub-components (Audio.Controls, Audio.PlayButton, Audio.SkipButton, Audio.Timeline, Audio.TimeDisplay, Audio.MuteButton, Audio.VolumeSlider, Audio.SpeedControl, Audio.Waveform, Audio.Spectrum) you can reorder and re-style
• useAudio headless hook — 16 state values plus 12 actions, plus the decoded peaks, the AnalyserNode, and currentSrc, to drive a fully custom UI on top of a plain <audio> element

Other highlights:

• Waveform visualisation — peaks decoded via Web Audio API + click/drag to seek, 60fps playhead tracking via RAF, mirror with mirrorGap, configurable bar radius
• Live spectrum analyser — AnalyserNode-driven, solid or gradient bars, optional mirror, configurable bar count / gap / smoothing
• Multiple sources — sources prop renders one <source> child per entry for codec / format / media-query fallbacks; fallbackSrc for runtime errors
• scrubSound — keep the audio playing during a seek-drag and hear snippets (Audacity / Adobe Audition style), works even from paused state
• asBackground preset — turns the same player into an ambient hero / section background in one prop
• Keyboard shortcuts (Space/K, J/L, ←/→, ↑/↓, M, > / <)
• Full Mantine Styles API (classNames, styles, vars, unstyled) on every part — theme-aware out of the box

Targets Mantine 9 and React 19. TypeScript-first.