@libs-ui/components-audio 0.2.189 → 0.2.191

package/README.md

@@ -1,3 +1,352 @@
-# audio
+# Audio Component
 
-This library was generated with [Nx](https://nx.dev).
+## 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:
+
+```bash
+npm install @libs-ui/components-audio
+```
+
+hoặc
+
+```bash
+yarn add @libs-ui/components-audio
+```
+
+## Sử dụng
+
+### Import module
+
+```typescript
+import { LibsUiComponentsAudioComponent } from '@libs-ui/components-audio';
+
+@NgModule({
+  declarations: [
+    AppComponent
+  ],
+  imports: [
+    BrowserModule,
+    LibsUiComponentsAudioComponent
+  ],
+  bootstrap: [AppComponent]
+})
+export class AppModule { }
+```
+
+Hoặc trong component standalone:
+
+```typescript
+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
+
+| Input                          | Type                | Description                                          |
+|--------------------------------|---------------------|------------------------------------------------------|
+| fileAudio                      | string              | URL của file audio cần phát                          |
+| checkPermissionDownloadAudio   | () => Promise<boolean> | Function trả về promise với kết quả boolean cho biết nếu được phép download |
+
+### Outputs
+
+| Output              | Type                        | Description                                      |
+|---------------------|----------------------------|--------------------------------------------------|
+| 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                |
+
+### Methods (Available through outFunctionsControl)
+
+| Method            | Parameters    | Return Type | Description                                         |
+|-------------------|---------------|-------------|-----------------------------------------------------|
+| 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 (từ 0 đến 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
+
+```typescript
+// 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:
+
+```css
+/* Đị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:
+
+```html
+<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
+
+```typescript
+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:
+
+```typescript
+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);
+  }
+}
+```

package/audio.component.d.ts

@@ -1,4 +1,5 @@
 import { AfterViewInit, ElementRef, OnDestroy } from '@angular/core';
+import { IAudioFunctionControlEvent } from './interfaces/function-control-event.interface';
 import * as i0 from "@angular/core";
 export declare class LibsUiComponentsAudioComponent implements AfterViewInit, OnDestroy {
     protected audioRatioValue: import("@angular/core").WritableSignal<number>;
@@ -12,22 +13,32 @@ export declare class LibsUiComponentsAudioComponent implements AfterViewInit, On
     protected showFullControlVolume: import("@angular/core").WritableSignal<boolean>;
     private onDestroy;
     readonly fileAudio: import("@angular/core").InputSignal<string>;
-    checkPermissionDownloadAudio?: () => Promise<boolean>;
+    readonly checkPermissionDownloadAudio: import("@angular/core").InputSignal<() => Promise<boolean>>;
     readonly audioRef: import("@angular/core").Signal<ElementRef<any>>;
     readonly volumeControlRef: import("@angular/core").Signal<ElementRef<any>>;
+    readonly outFunctionsControl: import("@angular/core").OutputEmitterRef<IAudioFunctionControlEvent>;
+    readonly outVolumeControl: import("@angular/core").OutputEmitterRef<number>;
+    readonly outTimeUpdate: import("@angular/core").OutputEmitterRef<{
+        currentTime: string;
+        duration: string;
+    }>;
+    readonly outEnded: import("@angular/core").OutputEmitterRef<void>;
+    readonly outMute: import("@angular/core").OutputEmitterRef<boolean>;
+    readonly outPlay: import("@angular/core").OutputEmitterRef<boolean>;
+    constructor();
     ngAfterViewInit(): void;
     private initObservable;
     protected handlerKeyPressAudio(): Promise<void>;
-    protected handlerAudioMuteMuted(event: Event): Promise<void>;
-    protected handlerAudioPausePlay(event: Event): Promise<void>;
+    protected handlerAudioMuteMuted(event?: Event): Promise<void>;
+    protected handlerAudioPausePlay(event?: Event): Promise<void>;
     protected handlerLoadedData(event: Event): Promise<void>;
-    protected handlerTimeUpdate(event: Event): Promise<void>;
+    protected handlerTimeUpdate(event?: Event): Promise<void>;
     private toHHMMSS;
     protected handlerChangeAudio(value: number): Promise<void>;
     protected handlerChangeVolume(value: number): Promise<void>;
     protected handlerEnded(event: Event): Promise<void>;
-    protected handlerDownload(e: Event): Promise<void>;
+    protected handlerDownload(e?: Event): Promise<void>;
     ngOnDestroy(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiComponentsAudioComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioComponent, "libs_ui-components-audio", never, { "fileAudio": { "alias": "fileAudio"; "required": true; "isSignal": true; }; "checkPermissionDownloadAudio": { "alias": "checkPermissionDownloadAudio"; "required": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioComponent, "libs_ui-components-audio", never, { "fileAudio": { "alias": "fileAudio"; "required": true; "isSignal": true; }; "checkPermissionDownloadAudio": { "alias": "checkPermissionDownloadAudio"; "required": true; "isSignal": true; }; }, { "outFunctionsControl": "outFunctionsControl"; "outVolumeControl": "outVolumeControl"; "outTimeUpdate": "outTimeUpdate"; "outEnded": "outEnded"; "outMute": "outMute"; "outPlay": "outPlay"; }, never, never, true, never>;
 }

package/demo/audio-demo.component.d.ts

@@ -0,0 +1,112 @@
+import { LibsUiComponentsAudioComponent } from '../audio.component';
+import { IAudioFunctionControlEvent } from '../interfaces/function-control-event.interface';
+import * as i0 from "@angular/core";
+export declare class LibsUiComponentsAudioDemoComponent {
+    audioPlayer: LibsUiComponentsAudioComponent;
+    isPlaying: import("@angular/core").WritableSignal<boolean>;
+    isMuted: import("@angular/core").WritableSignal<boolean>;
+    volume: import("@angular/core").WritableSignal<number>;
+    currentTime: import("@angular/core").WritableSignal<string>;
+    duration: import("@angular/core").WritableSignal<string>;
+    progress: import("@angular/core").WritableSignal<number>;
+    volumePercent: import("@angular/core").Signal<number>;
+    selectedAudio: import("@angular/core").WritableSignal<number>;
+    currentAudioSource: import("@angular/core").WritableSignal<string>;
+    functionControls: IAudioFunctionControlEvent | null;
+    audioSamples: import("@angular/core").WritableSignal<{
+        id: number;
+        name: string;
+        src: string;
+        duration: string;
+    }[]>;
+    inputsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        type: string;
+        default: string;
+        description: string;
+    }[]>;
+    outputsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        type: string;
+        description: string;
+    }[]>;
+    interfacesDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        description: string;
+        properties: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+    }[]>;
+    methodsDoc: import("@angular/core").WritableSignal<{
+        name: string;
+        params: string;
+        returnType: string;
+        description: string;
+    }[]>;
+    features: import("@angular/core").WritableSignal<{
+        id: number;
+        icon: string;
+        title: string;
+        description: string;
+    }[]>;
+    codeExamples: import("@angular/core").WritableSignal<{
+        id: number;
+        title: string;
+        code: string;
+    }[]>;
+    playAudio(): void;
+    toggleMute(): void;
+    changeVolume(event: Event): void;
+    downloadAudio(): void;
+    /**
+     * Format thời gian từ giây sang chuỗi HH:MM:SS
+     */
+    formatTime(timeInSeconds: number): string;
+    /**
+     * Sao chép text vào clipboard
+     */
+    copyToClipboard(text: string): void;
+    /**
+     * Đăng ký các function control từ component
+     */
+    registerFunctions(event: IAudioFunctionControlEvent): void;
+    /**
+     * Xử lý sự kiện thay đổi thời gian
+     */
+    handleTimeUpdate(timeInfo: {
+        currentTime: string;
+        duration: string;
+    }): void;
+    /**
+     * Xử lý sự kiện thay đổi âm lượng
+     */
+    handleVolumeChange(volume: number): void;
+    /**
+     * Xử lý sự kiện thay đổi trạng thái phát
+     */
+    handlePlayChange(isPlaying: boolean): void;
+    /**
+     * Xử lý sự kiện thay đổi trạng thái tắt tiếng
+     */
+    handleMuteChange(isMuted: boolean): void;
+    /**
+     * Xử lý sự kiện kết thúc phát
+     */
+    handleEnded(): void;
+    /**
+     * Chọn mẫu âm thanh
+     */
+    selectAudio(id: number): void;
+    /**
+     * Kiểm tra quyền tải xuống
+     */
+    checkDownloadPermission: () => Promise<boolean>;
+    /**
+     * Thay đổi vị trí phát bằng cách click trực tiếp vào thanh tiến độ
+     */
+    seekAudioByClick(event: MouseEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LibsUiComponentsAudioDemoComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<LibsUiComponentsAudioDemoComponent, "lib-audio-demo", never, {}, {}, never, never, true, never>;
+}