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](https://joldibaev.github.io/ngx-audio-wave/)** - Try the interactive demo ![Audio Wave Demo](https://github.com/joldibaev/ngx-audio-wave/raw/master/public/demo3.png) ## Quick Start ### Installation ```bash npm install ngx-audio-wave ``` ### Angular 20+ (Standalone Components) ```ts 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 ```html <ngx-audio-wave ariaLabel="My podcast episode" audioSrc="https://example.com/audio.mp3" > </ngx-audio-wave> ``` ### With Progress Information ```html <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 ```html <ngx-audio-wave [gap]="3" [height]="50" [rounded]="false" audioSrc="assets/audio.mp3" color="#ff6b6b" > </ngx-audio-wave> ``` ### With Custom Accessibility Labels ```html <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 ```html <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 ```html <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 ```html <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 ```html <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>  <ngx-audio-wave [loop]="true" audioSrc="assets/background-music.mp3" ariaLabel="Background music with auto-loop"> </ngx-audio-wave> ``` ### Different Heights and Gaps ```html  <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>  <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](LICENSE) file for details. ## Support - 📧 Email: nurlan@joldibaev.uz - 🐛 Issues: [GitHub Issues](https://github.com/joldibaev/ngx-audio-wave/issues) - 💬 Discussions: [GitHub Discussions](https://github.com/joldibaev/ngx-audio-wave/discussions) --- **Made with ❤️ by [Joldibaev Nurlan](https://github.com/joldibaev)**