@libs-ui/components-audio

Component phát âm thanh với đầy đủ chức năng điều khiển cho Angular.

Giới thiệu

LibsUiComponentsAudioComponent là một standalone Angular component cung cấp giao diện phát audio với các tính năng:

• ✅ Phát/tạm dừng âm thanh với giao diện trực quan
• ✅ Điều chỉnh âm lượng với thanh trượt ẩn/hiện
• ✅ Hiển thị thời gian theo định dạng HH:MM:SS
• ✅ Thanh tiến độ với chức năng tua nhanh/tua lại
• ✅ Tải xuống audio với kiểm soát quyền
• ✅ Function Control API cho phép điều khiển từ bên ngoài
• ✅ Hỗ trợ OnPush Change Detection cho hiệu năng cao
• ✅ Sử dụng Angular Signals cho state management

Cài đặt

# npm
npm install @libs-ui/components-audio

# yarn
yarn add @libs-ui/components-audio

Sử dụng

Import Component

import { Component } from '@angular/core';
import { LibsUiComponentsAudioComponent, IAudioFunctionControlEvent } from '@libs-ui/components-audio';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [LibsUiComponentsAudioComponent],
  template: `
    <libs_ui-components-audio
      [fileAudio]="audioUrl"
      [checkPermissionDownloadAudio]="checkPermission"
      (outFunctionsControl)="onFunctionsControl($event)"
      (outPlay)="onPlayChange($event)"
      (outVolumeControl)="onVolumeChange($event)"
      (outTimeUpdate)="onTimeUpdate($event)"
      (outMute)="onMuteChange($event)"
      (outEnded)="onEnded()"></libs_ui-components-audio>
  `,
})
export class ExampleComponent {
  audioUrl = 'https://example.com/audio.mp3';
  controls: IAudioFunctionControlEvent | null = null;

  checkPermission = (): Promise<boolean> => Promise.resolve(true);

  onFunctionsControl(event: IAudioFunctionControlEvent) {
    this.controls = event;
  }

  onPlayChange(isPlaying: boolean) {
    console.log('Đang phát:', isPlaying);
  }

  onVolumeChange(volume: number) {
    console.log('Âm lượng:', volume);
  }

  onTimeUpdate(time: { currentTime: string; duration: string }) {
    console.log('Thời gian:', time.currentTime, '/', time.duration);
  }

  onMuteChange(isMuted: boolean) {
    console.log('Tắt tiếng:', isMuted);
  }

  onEnded() {
    console.log('Audio đã phát xong');
  }
}

Điều khiển từ bên ngoài

Sử dụng outFunctionsControl để lấy reference các hàm điều khiển:

// Phát/Tạm dừng
this.controls.playPause();

// Bật/Tắt tiếng
this.controls.toggleMute();

// Set âm lượng (0-100)
this.controls.setVolume(50);

// Tua đến vị trí (0-100%)
this.controls.seekTo(25);

// Download audio
this.controls.download();

// Kiểm tra trạng thái
const isPlaying = this.controls.isPlaying();
const isMuted = this.controls.isMuted();

API Reference

Inputs

| Tên | Kiểu | Mặc định | Mô tả | | ------------------------------ | ------------------------ | ---------- | --------------------------------------------------------------------- | | fileAudio | string | required | URL của file audio cần phát. Hỗ trợ MP3, WAV, OGG. | | checkPermissionDownloadAudio | () => Promise<boolean> | required | Callback kiểm tra quyền download. Trả về Promise với kết quả boolean. |

Outputs

| Tên | Kiểu | Mô tả | | --------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | outFunctionsControl | IAudioFunctionControlEvent | Emit object chứa các hàm điều khiển: playPause, toggleMute, seekTo, setVolume, download, isPlaying, isMuted. | | outVolumeControl | number | Emit giá trị âm lượng hiện tại từ 0-100. | | outTimeUpdate | { currentTime: string, duration: string } | Emit thông tin thời gian theo định dạng HH:MM:SS. | | outEnded | void | Emit khi audio phát xong. | | outMute | boolean | Emit trạng thái tắt/bật tiếng. | | outPlay | boolean | Emit trạng thái đang phát/tạm dừng. |

Interface: IAudioFunctionControlEvent

interface IAudioFunctionControlEvent {
  /**
   * Bắt đầu hoặc tạm dừng phát audio
   */
  playPause: (event?: Event) => void;

  /**
   * Bật hoặc tắt âm thanh
   */
  toggleMute: (event?: Event) => void;

  /**
   * Điều chỉnh âm lượng (0-100)
   */
  setVolume: (value: number) => void;

  /**
   * Di chuyển đến vị trí cụ thể (0-100%)
   */
  seekTo: (value: number) => void;

  /**
   * Tải xuống file audio
   */
  download: (event?: Event) => void;

  /**
   * Kiểm tra trạng thái đang phát
   */
  isPlaying: () => boolean;

  /**
   * Kiểm tra trạng thái tắt tiếng
   */
  isMuted: () => boolean;
}

Công nghệ sử dụng

• Angular 18+ - Standalone Components
• Angular Signals - Reactive state management
• RxJS - Event handling với takeUntilDestroyed
• TailwindCSS - Styling

Demo

Demo có sẵn trong ứng dụng core-ui:

npx nx serve core-ui

File demo: apps/core-ui/src/app/components/audio/audio.component.ts

Truy cập: http://localhost:4500/audio

Tính năng Demo

• 🎮 Basic Example: Cách sử dụng cơ bản
• 🎛️ External Controls: Điều khiển audio từ component cha
• 📊 Real-time Status: Hiển thị trạng thái play, mute, time, volume

Unit Tests

# Chạy tests
npx nx test components-audio

# Chạy tests với coverage
npx nx test components-audio --coverage

# Watch mode
npx nx test components-audio --watch

License

MIT