Audio Component

Giới thiệu

audio là một component mạnh mẽ dùng để phát âm thanh trong ứng dụng Angular. Component này cung cấp giao diện đơn giản để phát, tạm dừng và điều khiển các tệp âm thanh với nhiều tính năng.

Tính năng

• Phát/tạm dừng âm thanh
• Điều chỉnh âm lượng với chức năng tắt/bật tiếng
• 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
• Thiết kế responsive
• Source audio có thể cấu hình

Cài đặt

Để cài đặt component audio, sử dụng npm hoặc yarn:

npm install @libs-ui/components-audio

hoặc

yarn add @libs-ui/components-audio

Sử dụng

Import module

import { LibsUiComponentsAudioComponent } from '@libs-ui/components-audio';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, LibsUiComponentsAudioComponent],
  bootstrap: [AppComponent],
})
export class AppModule {}

Hoặc trong component standalone:

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

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [CommonModule, LibsUiComponentsAudioComponent],
  template: `
    <libs_ui-components-audio
      [fileAudio]="audioSource"
      [checkPermissionDownloadAudio]="checkDownloadPermission"
      (outFunctionsControl)="registerFunctions($event)"></libs_ui-components-audio>

    <div class="controls">
      <button (click)="playAudio()">Phát/Tạm dừng</button>
      <button (click)="toggleMute()">Bật/Tắt tiếng</button>
    </div>
  `,
})
export class ExampleComponent {
  audioSource = 'path/to/audio/file.mp3';
  functionControls: IAudioFunctionControlEvent | null = null;

  checkDownloadPermission(): Promise<boolean> {
    // Kiểm tra quyền download
    return Promise.resolve(true);
  }

  registerFunctions(event: IAudioFunctionControlEvent) {
    this.functionControls = event;
  }

  playAudio() {
    if (this.functionControls) {
      this.functionControls.playPause();
    }
  }

  toggleMute() {
    if (this.functionControls) {
      this.functionControls.toggleMute();
    }
  }
}

API Reference

Inputs

| Tên | Kiểu | Mặc định | Mô tả | | ---------------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------- | | fileAudio | string | required | URL của file audio cần phát. | | checkPermissionDownloadAudio | () => Promise<boolean> | required | Function trả về promise với kết quả boolean cho biết nếu được phép download. |

Outputs

| Tên | Kiểu | Mô tả | | ------------------- | ------------------------------------------- | ------------------------------------------------------- | | outFunctionsControl | IAudioFunctionControlEvent | Event chứa các hàm điều khiển của audio component. | | outVolumeControl | number | Phát ra giá trị âm lượng hiện tại (0-100). | | outTimeUpdate | { currentTime: string, duration: string } | Phát ra thông tin thời gian hiện tại và tổng thời gian. | | outEnded | void | Phát ra khi audio kết thúc phát. | | outMute | boolean | Phát ra trạng thái tắt/bật tiếng. | | outPlay | boolean | Phát ra trạng thái phát/tạm dừng. |

Các phương thức (qua outFunctionsControl)

| Tên phương thức | Tham số | Kiểu trả về | Mô tả | | --------------- | --------------- | ----------- | ------------------------------------------------ | | playPause | event?: Event | void | Bắt đầu/tạm dừng phát audio. | | toggleMute | event?: Event | void | Bật/tắt âm thanh. | | setVolume | value: number | void | Điều chỉnh âm lượng (0-100). | | seekTo | value: number | void | Di chuyển đến vị trí cụ thể trong audio (0-100). | | download | event?: Event | void | Tải xuống file audio. | | isPlaying | - | boolean | Kiểm tra trạng thái đang phát audio. | | isMuted | - | boolean | Kiểm tra trạng thái tắt tiếng. |

Interfaces

// Audio Function Control Event
interface IAudioFunctionControlEvent {
  playPause: (event?: Event) => void;
  toggleMute: (event?: Event) => void;
  setVolume: (value: number) => void;
  seekTo: (value: number) => void;
  download: (event?: Event) => void;
  isPlaying: () => boolean;
  isMuted: () => boolean;
}

Styling Volume Slider

Để tạo hiệu ứng thanh trượt âm lượng có màu nền thay đổi theo giá trị, bạn có thể sử dụng CSS variables:

/* Định nghĩa thanh trượt âm lượng */
input[type='range'].volume-slider {
  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
}

/* Track styling cho WebKit browsers */
input[type='range'].volume-slider::-webkit-slider-runnable-track {
  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
}

/* Track styling cho Firefox */
input[type='range'].volume-slider::-moz-range-track {
  background: linear-gradient(to right, #3b82f6 var(--volume-percent, 50%), #e5e7eb var(--volume-percent, 50%));
}

Và trong template:

<input
  type="range"
  min="0"
  max="100"
  [value]="volumePercent()"
  (input)="changeVolume($event)"
  class="volume-slider"
  [style.--volume-percent.%]="volumePercent()" />

Ví dụ

Sử dụng Function Control

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

@Component({
  selector: 'app-example',
  template: `
    <libs_ui-components-audio
      [fileAudio]="audioSource()"
      [checkPermissionDownloadAudio]="checkDownloadPermission"
      (outFunctionsControl)="registerFunctions($event)"></libs_ui-components-audio>

    <div class="audio-controls">
      <button (click)="playPauseAudio()">{{ isPlaying() ? 'Tạm dừng' : 'Phát' }}</button>
      <button (click)="toggleMuteAudio()">{{ isMuted() ? 'Bật tiếng' : 'Tắt tiếng' }}</button>
      <div class="volume-control">
        <span>Âm lượng:</span>
        <input
          type="range"
          min="0"
          max="100"
          [value]="volumePercent()"
          (input)="changeVolume($event)"
          class="volume-slider"
          [style.--volume-percent.%]="volumePercent()" />
        <span>{{ volumePercent() }}%</span>
      </div>
      <div class="progress-control">
        <span>Tiến độ:</span>
        <input
          type="range"
          min="0"
          max="100"
          [value]="progress()"
          (input)="changeProgress($event)" />
        <span>{{ progress() }}%</span>
      </div>
      <button (click)="downloadAudio()">Tải xuống</button>
    </div>
  `,
})
export class ExampleComponent {
  audioSource = signal('path/to/audio.mp3');
  functionControls: IAudioFunctionControlEvent | null = null;
  isPlaying = signal(false);
  isMuted = signal(false);
  volume = signal(80);
  progress = signal(0);

  // Computed properties
  volumePercent = computed(() => Math.round(this.volume()));

  checkDownloadPermission = (): Promise<boolean> => {
    return Promise.resolve(true);
  };

  registerFunctions(event: IAudioFunctionControlEvent) {
    this.functionControls = event;

    // Initialize state
    if (this.functionControls) {
      this.isPlaying.set(this.functionControls.isPlaying());
      this.isMuted.set(this.functionControls.isMuted());
    }
  }

  playPauseAudio() {
    if (this.functionControls) {
      this.functionControls.playPause();
      this.isPlaying.set(this.functionControls.isPlaying());
    }
  }

  toggleMuteAudio() {
    if (this.functionControls) {
      this.functionControls.toggleMute();
      this.isMuted.set(this.functionControls.isMuted());
    }
  }

  changeVolume(event: Event) {
    if (this.functionControls && event.target) {
      const value = parseInt((event.target as HTMLInputElement).value);
      this.volume.set(value);
      this.functionControls.setVolume(value / 100); // Convert to 0-1 range
    }
  }

  changeProgress(event: Event) {
    if (this.functionControls && event.target) {
      const value = parseInt((event.target as HTMLInputElement).value);
      this.progress.set(value);
      this.functionControls.seekTo(value);
    }
  }

  downloadAudio() {
    if (this.functionControls) {
      this.functionControls.download();
    }
  }
}

Sử dụng Events

Sử dụng các events để phản ứng với thay đổi từ audio player:

import { Component, signal } from '@angular/core';

@Component({
  selector: 'app-example',
  template: `
    <libs_ui-components-audio
      [fileAudio]="audioSource()"
      [checkPermissionDownloadAudio]="checkPermission"
      (outTimeUpdate)="handleTimeUpdate($event)"
      (outVolumeControl)="handleVolumeChange($event)"
      (outPlay)="handlePlayChange($event)"
      (outMute)="handleMuteChange($event)"
      (outEnded)="handleEnded()"></libs_ui-components-audio>

    <div class="audio-info">
      <p>Trạng thái: {{ isPlaying() ? 'Đang phát' : 'Tạm dừng' }}</p>
      <p>Thời gian hiện tại: {{ currentTime() }}</p>
      <p>Tổng thời gian: {{ duration() }}</p>
      <p>Âm lượng: {{ volumeLevel() }}%</p>
    </div>
  `,
})
export class ExampleComponent {
  audioSource = signal('path/to/audio.mp3');
  isPlaying = signal(false);
  isMuted = signal(false);
  currentTime = signal('00:00:00');
  duration = signal('00:00:00');
  volumeLevel = signal(100);

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

  handleTimeUpdate(timeInfo: { currentTime: string; duration: string }) {
    this.currentTime.set(timeInfo.currentTime);
    this.duration.set(timeInfo.duration);
  }

  handleVolumeChange(volume: number) {
    this.volumeLevel.set(volume);
  }

  handlePlayChange(isPlaying: boolean) {
    this.isPlaying.set(isPlaying);
  }

  handleMuteChange(isMuted: boolean) {
    this.isMuted.set(isMuted);
  }

  handleEnded() {
    this.isPlaying.set(false);
  }
}