npm package: @libs-ui/components-audio
Description: > Component phát âm thanh với đầy đủ chức năng điều khiển cho Angular.
Latest version: 0.2.356-23

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

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

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

## Sử dụng

### Import Component

```typescript
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:

```typescript
// 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

```typescript
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`:

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

```bash
# 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