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

!Audio Wave Demo

Quick Start

$3

``bash
npm install ngx-audio-wave
`

$3

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

@Component({
selector: 'app-root',
standalone: true,
imports: [NgxAudioWave],
template:
ariaLabel="My audio player"
audioSrc="path/to/your/audio.mp3"
>

,
})
export class AppComponent {}
`

Basic Usage

`html
ariaLabel="My podcast episode"
audioSrc="https://example.com/audio.mp3"
>

`

$3

`html



`

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

Examples

$3

`html
[gap]="3"
[height]="50"
[rounded]="false"
audioSrc="assets/audio.mp3"
color="#ff6b6b"
>

`

$3

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

`

$3

`html



▶️ Play
⏸️ Pause
⏹️ Stop
`

$3

`html


Current volume: {{ player.currentVolume() | percent }}


`

$3

`html


Current speed: {{ player.currentPlaybackRate() }}x


`

$3

`html


Looping: {{ player.isLooping() ? 'Enabled' : 'Disabled' }}


[loop]="true"
audioSrc="assets/background-music.mp3"
ariaLabel="Background music with auto-loop">

`

$3

`html









`

Accessibility Features

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

$3

| 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 |

$3

- 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

$3

The component has been tested with:

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

API Reference

$3

| 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 |

$3

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

$3

| 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: nurlan@joldibaev.uz
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions

---

Made with ❤️ by Joldibaev Nurlan