ngx-audio-wave

ngx-audio-wave

A modern, accessible audio wave visualization component for Angular 20+ with comprehensive keyboard navigation and screen reader support.

Features

• 🎵 Audio Wave Visualization - Beautiful SVG-based audio wave display
• ⌨️ Full Keyboard Support - Complete keyboard navigation (Space, Enter, Arrow keys, Home, End)
• ♿ Accessibility First - WCAG 2.1 compliant with ARIA support
• 🎨 Highly Customizable - Colors, dimensions, gaps, and styling options
• 📱 Responsive Design - Works on all screen sizes
• 🚀 Modern Angular - Built with Angular 20+ signals and standalone components
• 🎯 TypeScript - Full type safety and IntelliSense support

Demo

🎮 Live Demo - Try the interactive demo

Quick Start

Installation

npm install ngx-audio-wave

Angular 20+ (Standalone Components)

import { NgxAudioWave } from 'ngx-audio-wave';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [NgxAudioWave],
  template: `
    <ngx-audio-wave
      ariaLabel="My audio player"
      audioSrc="path/to/your/audio.mp3"
    >
    </ngx-audio-wave>
  `,
})
export class AppComponent {}

Basic Usage

<ngx-audio-wave
  ariaLabel="My podcast episode"
  audioSrc="https://example.com/audio.mp3"
>
</ngx-audio-wave>

With Progress Information

<ngx-audio-wave #player audioSrc="assets/audio.mp3"></ngx-audio-wave>

<div class="audio-info">
  <p>Progress: {{ player.exactPlayedPercent() | number:'1.1-1' }}%</p>
  <p>
    Time: {{ player.exactCurrentTime() | number:'1.1-1' }}s / {{
    player.exactDuration() | number:'1.1-1' }}s
  </p>
  <p>Status: {{ player.statusText() }}</p>
</div>

Note: Use exact* properties instead of deprecated currentTime, duration, and playedPercent for better precision.

Examples

Custom Styling

<ngx-audio-wave
  [gap]="3"
  [height]="50"
  [rounded]="false"
  audioSrc="assets/audio.mp3"
  color="#ff6b6b"
>
</ngx-audio-wave>

With Custom Accessibility Labels

<ngx-audio-wave
  ariaLabel="Weekly Tech Podcast Episode 42"
  audioSrc="assets/podcast.mp3"
  pauseButtonLabel="Pause podcast"
  playButtonLabel="Start podcast"
  progressBarLabel="Podcast progress - use arrow keys to navigate"
>
</ngx-audio-wave>

Hide Default Button

<ngx-audio-wave [hideBtn]="true" #audioPlayer audioSrc="assets/audio.mp3">
</ngx-audio-wave>

<button (click)="audioPlayer.play()">▶️ Play</button>
<button (click)="audioPlayer.pause()">⏸️ Pause</button>
<button (click)="audioPlayer.stop()">⏹️ Stop</button>

Volume Control

<ngx-audio-wave #player audioSrc="assets/audio.mp3"></ngx-audio-wave>

<div class="volume-controls">
  <button (click)="player.mute()">🔇 Mute</button>
  <button (click)="player.unmute()">🔊 Unmute</button>
  <button (click)="player.toggleMute()">🔊/🔇 Toggle</button>
  <button (click)="player.setVolume(0.5)">50% Volume</button>
  <button (click)="player.setVolume(1)">100% Volume</button>
</div>

<p>Current volume: {{ player.currentVolume() | percent }}</p>

Playback Speed Control

<ngx-audio-wave #player audioSrc="assets/audio.mp3"></ngx-audio-wave>

<div class="speed-controls">
  <button (click)="player.decreasePlaybackRate()">⏪ Slower</button>
  <button (click)="player.resetPlaybackRate()">1x Normal</button>
  <button (click)="player.increasePlaybackRate()">⏩ Faster</button>
  <button (click)="player.setPlaybackRate(0.5)">0.5x</button>
  <button (click)="player.setPlaybackRate(1.5)">1.5x</button>
  <button (click)="player.setPlaybackRate(2)">2x</button>
</div>

<p>Current speed: {{ player.currentPlaybackRate() }}x</p>

Loop Control

<ngx-audio-wave #player audioSrc="assets/audio.mp3"></ngx-audio-wave>

<div class="loop-controls">
  <button (click)="player.enableLoop()">🔄 Enable Loop</button>
  <button (click)="player.disableLoop()">⏹️ Disable Loop</button>
  <button (click)="player.toggleLoop()">🔄/⏹️ Toggle Loop</button>
</div>

<p>Looping: {{ player.isLooping() ? 'Enabled' : 'Disabled' }}</p>

<!-- Auto-loop example -->
<ngx-audio-wave 
  [loop]="true" 
  audioSrc="assets/background-music.mp3"
  ariaLabel="Background music with auto-loop">
</ngx-audio-wave>

Different Heights and Gaps

<!-- Different heights -->
<ngx-audio-wave [height]="25" audioSrc="assets/audio.mp3"></ngx-audio-wave>
<ngx-audio-wave [height]="50" audioSrc="assets/audio.mp3"></ngx-audio-wave>
<ngx-audio-wave [height]="100" audioSrc="assets/audio.mp3"></ngx-audio-wave>

<!-- Different gaps -->
<ngx-audio-wave [gap]="1" audioSrc="assets/audio.mp3"></ngx-audio-wave>
<ngx-audio-wave [gap]="5" audioSrc="assets/audio.mp3"></ngx-audio-wave>
<ngx-audio-wave [gap]="10" audioSrc="assets/audio.mp3"></ngx-audio-wave>

Accessibility Features

This component is built with accessibility as a core feature, ensuring it works seamlessly with assistive technologies and keyboard navigation.

Keyboard Navigation

Key	Action
Space or Enter	Play/Pause audio
Arrow Left	Skip backward (configurable with skip)
Arrow Right	Skip forward (configurable with skip)
Home	Jump to beginning
End	Jump to end

Screen Reader Support

• ARIA Labels: All interactive elements have descriptive labels
• Live Regions: Status changes are announced automatically
• Progress Information: Detailed progress text with time and percentage
• Semantic Roles: Proper ARIA roles for all components
• Focus Management: Logical tab order and focus indicators

Testing with Screen Readers

The component has been tested with:

• NVDA (Windows)
• JAWS (Windows)
• VoiceOver (macOS/iOS)
• TalkBack (Android)

API Reference

Input Properties

Property	Type	Default	Description
audioSrc	string | SafeUrl	Required	URL or SafeUrl of the audio file to play
color	string	'#1e90ff'	Color of the audio wave bars
height	number	25	Height of the wave visualization in pixels
gap	number	5	Gap between wave bars in pixels
rounded	boolean	true	Whether to round the corners of wave bars
hideBtn	boolean	false	Hide the play/pause button
skip	number	5	Seconds to skip when using arrow keys
volume	number	1	Initial volume level (0-1)
playbackRate	number	1	Initial playback speed (0.25-4)
loop	boolean	false	Whether to loop the audio
ariaLabel	string	'Audio player'	Main ARIA label for the component
playButtonLabel	string	'Play audio'	ARIA label for the play button
pauseButtonLabel	string	'Pause audio'	ARIA label for the pause button
progressBarLabel	string	'Audio progress bar'	ARIA label for the progress bar

Output Properties (Signals)

Property	Type	Description
isPaused	Signal<boolean>	Whether the audio is currently paused
isLoading	Signal<boolean>	Whether the audio is currently loading
hasError	Signal<boolean>	Whether there was an error loading the audio
currentVolume	Signal<number>	Current volume level (0-1)
currentPlaybackRate	Signal<number>	Current playback speed (0.25-4)
isLooping	Signal<boolean>	Whether the audio is currently looping
exactCurrentTime	Signal<number>	Current playback time in seconds (exact)
exactDuration	Signal<number>	Total duration in seconds (exact)
exactPlayedPercent	Signal<number>	Playback progress as percentage (exact)
currentTime	Signal<number>	Deprecated - Current playback time rounded to seconds
duration	Signal<number>	Deprecated - Total duration rounded to seconds
playedPercent	Signal<number>	Deprecated - Playback progress as percentage (rounded)
progressText	Signal<string>	Human-readable progress text for screen readers
statusText	Signal<string>	Current status text for screen readers

Methods

Method	Parameters	Description
play(time?: number)	time?: number	Play the audio, optionally from a specific time
pause()	-	Pause the audio
stop()	-	Stop the audio and reset to beginning
setVolume(volume)	volume: number	Set volume level (0-1)
mute()	-	Mute the audio
unmute()	-	Unmute the audio
toggleMute()	-	Toggle mute state
setPlaybackRate(rate)	rate: number	Set playback speed (0.25-4)
resetPlaybackRate()	-	Reset playback speed to 1x
increasePlaybackRate()	-	Increase playback speed by 0.25x
decreasePlaybackRate()	-	Decrease playback speed by 0.25x
setLoop(loop)	loop: boolean	Enable or disable audio looping
enableLoop()	-	Enable audio looping
disableLoop()	-	Disable audio looping
toggleLoop()	-	Toggle loop state

Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Made with ❤️ by Joldibaev Nurlan