@radio-cloud/audio-player

Reusable audio player widget for React with waveform visualization, real-time level meters, and synced lyrics.

Install

npm install @radio-cloud/audio-player

Peer dependencies (must be installed in your app):

npm install react react-dom @radix-ui/react-dialog

Quick Start

import { useState } from 'react'
import { AudioPlayerDialog } from '@radio-cloud/audio-player'

function App() {
  const [open, setOpen] = useState(false)

  return (
    <>
      <button onClick={() => setOpen(true)}>Play</button>

      <AudioPlayerDialog
        src="https://example.com/track.mp3"
        title="Seventeen"
        artist="Alessia Cara"
        enableTranscript={false}
        open={open}
        onOpenChange={setOpen}
      />
    </>
  )
}

No CSS import needed — styles are embedded in the JavaScript bundle.

Components

AudioPlayerDialog

Full-featured audio player rendered as a popup/overlay dialog.

<AudioPlayerDialog
  src="https://example.com/track.mp3"
  title="Seventeen"
  artist="Alessia Cara"
  enableTranscript={true}
  open={isOpen}
  onOpenChange={setIsOpen}
/>

| Prop | Type | Required | Description | |------|------|----------|-------------| | src | string | ✅ | Audio file URL | | title | string | ✅ | Track title | | artist | string | ✅ | Artist name | | enableTranscript | boolean | ✅ | Enable lyrics/transcription panel | | open | boolean | ✅ | Dialog open state | | onOpenChange | (open: boolean) => void | ✅ | Callback when dialog opens/closes | | album | string | ❌ | Album name (improves lyrics search accuracy) | | transcription | string \| TranscriptionLine[] | ❌ | Manual transcription (overrides auto-fetch) | | onDownload | () => void | ❌ | Custom download handler |

AudioPlayerInline

Same player without the dialog overlay — renders inline in your layout.

import { AudioPlayerInline } from '@radio-cloud/audio-player'

<AudioPlayerInline
  src="https://example.com/track.mp3"
  title="Seventeen"
  artist="Alessia Cara"
  enableTranscript={false}
/>

Same props as AudioPlayerDialog except open and onOpenChange.

Lyrics / Transcription

Auto-fetch from LRCLIB

Set enableTranscript={true} without providing transcription — lyrics are fetched automatically from LRCLIB using the artist + title props.

<AudioPlayerDialog
  src="https://example.com/track.mp3"
  title="Apa Kabar Sayang"
  artist="Armada"
  enableTranscript={true}
  open={isOpen}
  onOpenChange={setIsOpen}
/>

If synced lyrics are available, they display karaoke-style with the active line highlighted and auto-scrolling. If only plain lyrics are found, they display as static text.

Manual transcription (plain text)

<AudioPlayerDialog
  src="https://example.com/news.mp3"
  title="Nachrichten"
  artist="Moderator"
  enableTranscript={true}
  transcription={`Erste Zeile der Transkription.
Zweite Zeile.
Dritte Zeile.`}
  open={isOpen}
  onOpenChange={setIsOpen}
/>

Manual transcription (synced / karaoke)

<AudioPlayerDialog
  src="https://example.com/news.mp3"
  title="Nachrichten"
  artist="Moderator"
  enableTranscript={true}
  transcription={[
    { time: 0, text: 'Erste Zeile beginnt bei Sekunde 0.' },
    { time: 4, text: 'Zweite Zeile beginnt bei Sekunde 4.' },
    { time: 8, text: 'Dritte Zeile beginnt bei Sekunde 8.' },
  ]}
  open={isOpen}
  onOpenChange={setIsOpen}
/>

Each line highlights when currentTime reaches its time value. Click a line to seek to that position.

Hooks

useAudioPlayer(src: string)

Low-level hook for building custom player UIs.

import { useAudioPlayer } from '@radio-cloud/audio-player'

const {
  audioRef,       // Ref for <audio> element
  canvasRef,      // Ref for waveform <canvas>
  analyserLeft,   // Web Audio AnalyserNode (L channel)
  analyserRight,  // Web Audio AnalyserNode (R channel)
  isPlaying,
  duration,
  currentTime,
  volume,
  playbackRate,
  waveformReady,
  togglePlay,
  seek,
  rewind10,
  forward10,
  setVolume,
  cyclePlaybackRate,
  skipForward,
} = useAudioPlayer('https://example.com/track.mp3')

useLyrics(options)

Fetch lyrics from LRCLIB.

import { useLyrics } from '@radio-cloud/audio-player'

const { syncedLines, plainLyrics, loading, error, instrumental } = useLyrics({
  trackName: 'Seventeen',
  artistName: 'Alessia Cara',
  enabled: true,
})

useAudioMetadata(src: string)

Read ID3 metadata (title, artist, album) from an audio file URL.

import { useAudioMetadata } from '@radio-cloud/audio-player'

const { metadata, loading } = useAudioMetadata('https://example.com/track.mp3')
// metadata.title, metadata.artist, metadata.album

Utilities

parseLRC(lrc: string): TranscriptionLine[]

Parse an LRC format string into timed lines.

import { parseLRC } from '@radio-cloud/audio-player'

const lines = parseLRC(`[00:05.00]First line
[00:10.00]Second line`)
// [{ time: 5, text: 'First line' }, { time: 10, text: 'Second line' }]

Features

• Waveform visualization (decoded from audio via Web Audio API)
• Real-time L/R level meters with peak hold
• Transport controls: play/pause, rewind 10s, forward 10s, fast forward, skip, download
• Volume control with popup slider
• Playback rate cycling (1x → 1.25x → 1.5x → 2x → 0.5x → 0.75x)
• Timeline ticks
• Synced lyrics with auto-scroll and click-to-seek
• Auto-fetch lyrics from LRCLIB API
• ID3 metadata reader (title, artist, album from MP3 files)
• Dark theme with teal/green accent
• Zero CSS dependencies — all styles inline

Types

import type {
  AudioPlayerDialogProps,
  AudioPlayerProps,
  TranscriptionLine,
  Transcription,
  UseLyricsOptions,
  UseLyricsReturn,
  AudioMetadata,
  UseAudioPlayerReturn,
} from '@radio-cloud/audio-player'

License

MIT