@hoanghong/speaking-angular 0.4.3 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.6.0
+
+- Versioned overall local pronunciation score (harmonic mean of accuracy and completeness).
+- Explicit score scale, availability, components, exclusions and calibration status.
+- New clients accept older servers without inventing an overall score.
+
+## 0.5.0
+
+- Optional multi-criteria local pronunciation diagnostics with methods, limitations and unavailable scores.
+- Compatible with older service responses.
+
 ## 0.4.3
 
 - Remove service addresses from public integration examples; no runtime changes.

package/README.md

@@ -1,168 +1,228 @@
 # @hoanghong/speaking-angular
 
-Component nhận dạng lời nói online dùng ngay. Chỉ cài package, chọn `serviceType`, ngôn ngữ và nhận callback **text + file audio**. Không khai báo URL, không tạo gateway, không nhập token, không copy worklet. Model chạy tại dịch vụ FSEL, không tải xuống máy người dùng. MIT. Angular 18.x, RxJS 7.8.
+Angular 18 / RxJS 7.8 SDK for realtime transcription, audio upload and US English pronunciation diagnostics. Service connections, sessions and worklet loading are automatic; no service URL or service token is required. Models run on the service. MIT license.
 
-## 1. Cài đặt
+## Install from npm
 
 ```bash
-npm install ./vendor/hoanghong-speaking-core-0.4.3.tgz ./vendor/hoanghong-speaking-angular-0.4.3.tgz
+npm install @hoanghong/speaking-core@0.6.0 @hoanghong/speaking-angular@0.6.0
 ```
 
-Core được cài tự động. Với ứng dụng mới: `npx @angular/cli@18 new speaking-demo --standalone --routing=false --style=css`, rồi `cd speaking-demo` và chạy lệnh trên.
+## 1. Install from the version 0.6.0 release ZIP
 
-Bản 0.4.3 là bộ cài test local: giải nén ZIP và copy hai tarball vào `vendor/` trước.
-Chưa publish 0.4.3 lên registry. Các tính năng nhận dạng cũ vẫn dùng được.
+Copy both npm tarballs into your application's vendor directory:
 
-## Đánh giá phát âm tiếng Anh Mỹ (0.4.3)
+```bash
+npm install ./vendor/hoanghong-speaking-core-0.6.0.tgz ./vendor/hoanghong-speaking-angular-0.6.0.tgz
+```
+
+For a new application, first run npx @angular/cli@18 new speaking-demo --standalone --routing=false --style=css, then cd speaking-demo. These instructions use local archives and do not assume registry publication.
+
+## 2. Configure an application key, if supplied
 
-Thêm `SpeakingService` vào `providers` của component dùng để test, import từ
-`@hoanghong/speaking-angular`, rồi gọi trong class component:
+Use the following src/app/app.config.ts when FSEL has provided a key. Without a key, use an empty providers array for the basic anonymous quota.
 
 ```ts
-constructor(private readonly speaking: SpeakingService) {}
-
-async assessPronunciation(file: File): Promise<void> {
-  const result = await this.speaking.pronunciation.assessAudio(file, {
-    referenceText: 'cat',
-    expectedPhonemes: ['k', 'æ', 't'],
-    filename: file.name,
-  });
-  console.log(result.phoneme_similarity, result.comparisons, result.warnings);
-}
+import { ApplicationConfig } from '@angular/core';
+import { provideSpeakingApp } from '@hoanghong/speaking-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideSpeakingApp({ appKey: 'YOUR_APP_KEY' })],
+};
 ```
 
-Gọi bằng file vừa chọn hoặc `result.audio` trong callback `completed` của component hiện có.
-Có thể dùng câu/đoạn đọc: thay referenceText bằng đúng nội dung cần đọc và bỏ
-expectedPhonemes nếu server đã cài eSpeak; không dùng chuỗi âm của `cat` cho đoạn khác.
-Hỗ trợ audio tối đa 120 giây/25 MiB, reference 4096 ký tự, client chờ tối đa 11 phút.
-Thêm `signal: controller.signal` để hủy request. Hàm reject khi lỗi; UI cần catch và hiển thị.
-`calibrated=false`: similarity chỉ là đối chiếu âm vị, chưa phải điểm phát âm chính thức.
-Kết quả có timestamp, âm thiếu/thừa/thay thế, formant/pitch/intensity/PSD và warnings.
+Use src/main.ts:
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { AppComponent } from './app/app.component';
+import { appConfig } from './app/app.config';
+
+bootstrapApplication(AppComponent, appConfig).catch(console.error);
+```
 
-Dùng `provideSpeakingApp` hiện có nếu có appKey. SDK tự cấp phiên riêng cho mỗi lần đánh giá,
-không nhập service token. Dịch vụ đánh giá phát âm và model phải
-được triển khai trước; 404/503 nghĩa là server chưa sẵn sàng. Bộ cài không triển khai server.
-Không đưa service credential vào ứng dụng.
+Application keys are visible application identifiers, not administrative credentials. Key quotas/status are managed server-side. An invalid/disabled key returns INVALID_APP_KEY rather than falling back to anonymous access. Never embed service credentials.
 
-## 2. Thêm component — ví dụ đầy đủ
+## 3. Complete pronunciation example
 
-Thay `src/app/app.component.ts` bằng:
+Replace src/app/app.component.ts below. The learner reads the displayed passage, selects a recording and clicks Assess pronunciation. Alternatively, record with the existing speaking component; its completed callback supplies the same audio File. Assessment is a separate explicit action.
 
 ```ts
 import { Component, OnDestroy } from '@angular/core';
-import { FselSpeakingComponent, SpeakingResult } from '@hoanghong/speaking-angular';
+import {
+  FselSpeakingComponent, PronunciationAssessment, SpeakingError,
+  SpeakingResult, SpeakingService,
+} from '@hoanghong/speaking-angular';
 
 @Component({
-  selector: 'app-root', standalone: true,
+  selector: 'app-root',
+  standalone: true,
   imports: [FselSpeakingComponent],
+  providers: [SpeakingService],
   template: `
-    <main style="max-width:800px;margin:auto;padding:20px">
-      <h1>Luyện nói</h1>
-      <fsel-speaking serviceType="realtime" initialLanguage="vi"
-        (completed)="onCompleted($event)" (failed)="onFailed($event)" />
-      <p>{{ text }}</p>
+    <main>
+      <h1>US English pronunciation practice</h1>
+      <p>Read this passage: {{ referenceText }}</p>
+      <label for="recording">Choose an audio recording (maximum 120 seconds)</label>
+      <input id="recording" type="file" accept="audio/*"
+        [disabled]="busy" (change)="selectFile($event)" />
+      <p>Or record the passage, then stop before 120 seconds:</p>
+      @if (!busy) {
+        <fsel-speaking serviceType="realtime" initialLanguage="en"
+          (completed)="onCompleted($event)" (failed)="onFailed($event)" />
+      }
       @if (audioUrl) {
         <audio controls [src]="audioUrl"></audio>
-        <p><a [href]="audioUrl" [download]="filename">Tải file bài nói</a></p>
+      }
+      <button type="button" [disabled]="!audio || busy" (click)="assess()">
+        Assess pronunciation
+      </button>
+      <button type="button" [disabled]="!busy" (click)="cancel()">Cancel</button>
+      @if (busy) { <p role="status">Assessing pronunciation...</p> }
+      @if (assessment) {
+        <p>Phoneme similarity: {{ assessment.phoneme_similarity }} (uncalibrated)</p>
+        <p>Phoneme accuracy: {{ accuracy }}</p>
+        <p>Overall local pronunciation score: {{ overall }}</p>
+        @for (warning of assessment.warnings; track $index) { <p>{{ warning }}</p> }
       }
       <p role="alert">{{ error }}</p>
     </main>
   `,
 })
 export class AppComponent implements OnDestroy {
-  text = ''; error = ''; filename = ''; audioUrl = '';
-  onCompleted(result: SpeakingResult): void {
-    if (this.audioUrl) URL.revokeObjectURL(this.audioUrl);
-    this.text = result.text;
-    this.filename = result.audio.name;
-    this.audioUrl = URL.createObjectURL(result.audio);
-    // result.audio là File: có thể đưa vào FormData để lưu ở hệ thống của bạn.
+  readonly referenceText = 'The cat is sitting on the mat.';
+  audio: File | null = null;
+  audioUrl = '';
+  assessment: PronunciationAssessment | null = null;
+  error = '';
+  busy = false;
+  private controller?: AbortController;
+  private destroyed = false;
+
+  constructor(private readonly speaking: SpeakingService) {}
+
+  get overall(): string {
+    const value = this.assessment?.overall;
+    return value?.status === 'estimated' && value.score != null
+      ? value.score.toFixed(1) + ' / ' + value.scale + ' (local estimate)'
+      : value?.reason ?? 'Unavailable: upgrade the server if needed';
   }
-  onFailed(error: Error): void { this.error = error.message; }
-  ngOnDestroy(): void { if (this.audioUrl) URL.revokeObjectURL(this.audioUrl); }
-}
-```
 
-Giữ `src/main.ts` chuẩn Angular CLI; nếu cần tạo lại:
+  get accuracy(): string {
+    const value = this.assessment?.breakdown?.accuracy;
+    return value?.status === 'estimated' && value.score != null
+      ? value.score.toFixed(1) + ' / 100 (estimate)'
+      : 'Unavailable';
+  }
 
-```ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { AppComponent } from './app/app.component';
-bootstrapApplication(AppComponent).catch(console.error);
-```
+  selectFile(event: Event): void {
+    this.setAudio((event.target as HTMLInputElement).files?.[0] ?? null);
+  }
 
-Không cần `provideSpeakingGateway` hoặc chỉnh assets trong `angular.json` khi dùng dịch vụ public. Nếu nâng cấp từ 0.2, bỏ provider gateway cũ để sử dụng dịch vụ public mặc định.
+  onCompleted(result: SpeakingResult): void { this.setAudio(result.audio); }
+  onFailed(error: Error): void { this.error = error.message; }
 
-## Key riêng của ứng dụng (cấu hình một lần)
+  private setAudio(file: File | null): void {
+    if (this.audioUrl) URL.revokeObjectURL(this.audioUrl);
+    this.audio = file;
+    this.audioUrl = file ? URL.createObjectURL(file) : '';
+    this.assessment = null;
+    this.error = '';
+  }
+
+  async assess(): Promise<void> {
+    if (!this.audio || this.busy) return;
+    this.busy = true;
+    this.error = '';
+    this.assessment = null;
+    this.controller = new AbortController();
+    try {
+      const result = await this.speaking.pronunciation.assessAudio(this.audio, {
+        referenceText: this.referenceText,
+        filename: this.audio.name,
+        signal: this.controller.signal,
+      });
+      if (!this.destroyed) this.assessment = result;
+    } catch (error) {
+      if (!this.destroyed) {
+        this.error = error instanceof SpeakingError
+          ? error.code + ': ' + error.message
+          : 'Pronunciation assessment failed.';
+      }
+    } finally {
+      if (!this.destroyed) this.busy = false;
+      this.controller = undefined;
+    }
+  }
 
-Nếu được FSEL cấp key riêng, thêm vào `src/app/app.config.ts`:
+  cancel(): void { this.controller?.abort(); }
 
-```ts
-import { ApplicationConfig } from '@angular/core';
-import { provideSpeakingApp } from '@hoanghong/speaking-angular';
-export const appConfig: ApplicationConfig = {
-  providers: [provideSpeakingApp({ appKey: 'KEY_DUOC_FSEL_CAP' })],
-};
+  ngOnDestroy(): void {
+    this.destroyed = true;
+    this.cancel();
+    if (this.audioUrl) URL.revokeObjectURL(this.audioUrl);
+  }
+}
 ```
 
-Khi có appConfig, `main.ts` cần truyền nó cho bootstrap:
+Run npx ng serve and open the local address printed by Angular. Microphone capture requires HTTPS or localhost and user permission. The SDK does not automatically record on page load. The component currently uses its built-in interface labels; the example's own labels and comments are English.
 
-```ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { AppComponent } from './app/app.component';
-import { appConfig } from './app/app.config';
-bootstrapApplication(AppComponent, appConfig).catch(console.error);
-```
+SpeakingService must be provided at the screen/component level as shown. provideSpeakingApp configures application identity; it does not replace that provider. The fsel-speaking component owns its recording/transcription lifecycle. Assessment consumes an additional session after recording/transcription. For upload-only pronunciation, the file input calls the pronunciation client directly without first creating a transcription job.
 
-Component và callback text/audio không đổi; không cần URL. Đây là key định danh có thể quan sát trong frontend, không phải khóa quản trị. Hạn mức của key được FSEL quản lý phía server, thay đổi không cần build lại ứng dụng. Key sai/bị khóa trả INVALID_APP_KEY; không tự chuyển sang dùng ẩn danh. Bỏ cấu hình key thì dùng hạn mức public cơ bản.
+## 4. Reference text and optional phonemes
 
-## 3. Chạy
+Pronunciation supports en-US only. referenceText is the exact word, sentence or paragraph being read (1–4096 characters). Omit expectedPhonemes for normal passages; server-side text-to-phoneme support must be installed.
 
-```bash
-npx ng serve
-```
+For a specific word, add expectedPhonemes: ['k', 'æ', 't'] and set referenceText: 'cat' in the assessment options. These are complete model vocabulary tokens, not individual IPA characters. Do not include enclosing slashes or reuse this sequence for another passage.
 
-Mở localhost do CLI in ra → chọn ngôn ngữ → Bắt đầu nói → cho phép microphone → chờ “Đang nghe…” → nói → Dừng và lấy kết quả. Callback nhận text và WAV, ví dụ trên cho nghe lại/tải file. Production phải dùng HTTPS. Không ghi âm tự động.
+Audio must be nonempty, at most 120 seconds and 25 MiB. WAV PCM16 mono at 16 kHz is suitable; the service validates duration/formats. Realtime transcription itself permits 300 seconds, so stop within 120 seconds for pronunciation. The assessment request timeout defaults to 11 minutes. AbortSignal cancels the client request; it does not refund quota or guarantee server inference cancellation. There is no automatic retry.
 
-## 4. Chọn dịch vụ
+## 5. Read the assessment
 
-- `serviceType="realtime"`: microphone, text tạm khi nói, kết quả cuối kèm WAV PCM16 mono 16 kHz.
-- `serviceType="upload"`: chọn file audio, trả transcript và chính File đầu vào, giữ tên/định dạng.
-- Không đặt `serviceType`: hiện cả hai cách. `uploadEnabled=false` ẩn upload.
-- `initialLanguage`: `en` (Anh), `ja` (Nhật), `ko` (Hàn), `zh` (Trung), `vi` (Việt, mặc định).
+| Field | Use |
+| --- | --- |
+| phoneme_similarity / phoneme_error_rate | Edit-based phoneme comparison, not an official grade |
+| comparisons | match/substitution/deletion/insertion; expected/observed tokens and approximate seconds |
+| observed_phonemes | Recognized tokens and approximate times |
+| breakdown | Optional criteria, errors, signal and limitations |
+| acoustic_frames / psd_frequencies_hz | Formants, pitch, intensity and spectral data |
+| warnings | Interpretation and model limitations |
 
-Ví dụ upload: thay `serviceType="realtime"` bằng `serviceType="upload"`. Callback không đổi.
+breakdown may be absent or null with older services. Each criterion has score (0–100 or null), status (estimated/unavailable), method and reason. Display unavailable as "Unavailable", never zero. Display methods/reasons/limitations alongside estimates. Missing sounds can have null timestamps; counts refer to phonemes, not words.
 
-## 5. Kết quả trả về
+Accuracy = 100*M/(M+S+I); completeness = 100*(N-D)/N, with matches/substitutions/omissions/insertions M/S/D/I and reference count N. Completeness includes substitutions as covered. Similarity = 100*max(0, 1-(S+D+I)/N) and differs from accuracy. Fluency is an acoustic energy-continuity proxy affected by noise/intentional pauses. Prosody has pitch measurements without a score. Overall pronunciation is the harmonic mean of Accuracy and Completeness. Vocabulary, grammar and topic scores are unavailable. calibrated=false; approximate timing is not forced alignment. Do not use these diagnostics as educational grades, Azure scores or pass/fail thresholds.
 
-`completed` nhận `SpeakingResult`:
+## 6. Existing transcription component
 
-| Trường | Kiểu / ý nghĩa |
-| --- | --- |
-| `text` | String nhận dạng cuối; rỗng khi không có lời nói |
-| `audio` | File, dùng createObjectURL/FormData/arrayBuffer; realtime có tên speaking.wav |
-| `language` | en/ja/ko/zh/vi |
-| `serviceType` | realtime/upload |
-| `status` | succeeded/no_speech; các metadata gốc vẫn được giữ |
-| `result` | Transcript chi tiết từ server nếu có |
+Use serviceType="realtime" for microphone transcription; serviceType="upload" for audio-file transcription. Omitting serviceType displays both; [uploadEnabled]="false" hides upload. initialLanguage supports en/ja/ko/zh/vi (default vi).
 
-File realtime chứa âm thanh người dùng vừa nói, đã chuẩn hóa cho nhận dạng; không phải giọng AI đọc text. File không tự được lưu vĩnh viễn lên S3 hoặc cấp URL tải công khai. Ứng dụng sở hữu File sau callback, tự lưu nếu cần. Revoke object URL khi thay file/rời trang như ví dụ để tránh giữ RAM. Hủy/lỗi không phát callback thành công.
+completed emits SpeakingResult with text, audio (File), language, serviceType, status and optional detailed result. Realtime audio is WAV PCM16 mono at 16 kHz; upload preserves the selected file. An empty transcript may indicate no_speech. failed emits an Error; cancellation/failure does not emit successful audio. Use object URLs for playback/download and revoke them when no longer needed. Use FormData to store audio; files are not automatically persisted to permanent storage.
 
-## 6. Giới hạn và lỗi
+## 7. Quotas and troubleshooting
 
-Dịch vụ public tự cấp phiên ngắn hạn. Mặc định server giới hạn 5 lượt/IP/ngày và 100 lượt/ngày cho mỗi instance, tính theo UTC; hạn mức có thể được FSEL điều chỉnh. Một phiên cấp mới tính một lượt kể cả khi nhận dạng thất bại. Người dùng cùng mạng có thể chung IP. Realtime tối đa 5 phút; buffer PCM tối đa khoảng 9,6 MB trước khi tạo WAV. Upload UI tối đa 25 MiB, server có thể giới hạn thấp hơn; chờ job tối đa 10 phút. Không tự reconnect/replay audio sau mất mạng. Rời màn ngừng thu/polling; job đã upload có thể còn chạy trên server.
+Basic quota defaults to 5 sessions per IP/day and 100 per instance/day (UTC), subject to operator changes. New sessions consume quota even on processing failure. Application-key quota is managed by FSEL. Realtime buffers approximately 9.6 MB PCM; upload UI accepts up to 25 MiB and polls up to 10 minutes. Leaving the component stops capture/polling, although accepted server jobs may continue. There is no automatic reconnect/replay.
 
-`failed` nhận Error; lỗi dịch vụ có `code`/`status` qua SpeakingError. QUOTA_EXCEEDED/429: hết lượt, chờ ngày mới. 503: dịch vụ/model chưa sẵn sàng. 404: server chưa triển khai phiên bản dịch vụ public. Microphone denied: bật quyền site và dùng HTTPS/localhost. Mạng/CSP: cho phép kết nối, worklet tới dịch vụ FSEL theo chính sách ứng dụng. Server phải chạy bản hỗ trợ public SDK trước khi dùng 0.3.
+Handle SpeakingError.code/status/message: INVALID_REFERENCE/INVALID_AUDIO for input, INVALID_APP_KEY/401 for key issues, QUOTA_EXCEEDED/429 for quota, 415 for unsupported formats, 422 for validation/no recognized phonemes, 404 for missing functionality and 503 for service/model readiness. Check browser microphone permissions and application network/CSP policies for capture/connection failures.
 
-API thấp của 0.2 vẫn có sẵn cho tích hợp tùy chỉnh; không cần dùng trong luồng trên. Microphone thiết bị và khả năng truy cập mạng cần kiểm tra trong ứng dụng triển khai thực tế.
+The bundle installs clients; it does not deploy models or prove hosted readiness. Physical microphone/playback and real learner scoring require separate device/service verification.
 
 
-## Application key
+## Overall pronunciation output (0.6.0)
 
-Pass the application key provided by FSEL as `appKey`. The SDK handles service
-connections automatically. Quotas and key status are managed by the service.
-App keys identify an application and are visible in browser/mobile applications.
+Use `result.overall?.score` for the overall chart.
+It is a local estimate, the harmonic mean of unrounded Accuracy and Completeness:
+`2*A*C/(A+C)`, or 0 if A+C=0. Fluency and Prosody are excluded. This is not an
+Azure or calibrated educational grade. `phoneme_similarity` is a separate legacy
+edit-distance diagnostic and can be zero while the overall score is positive.
 
-```ts
-provideSpeakingApp({ appKey: environment.speakingAppKey });
+The overall object includes `version=local-accuracy-completeness-v1`, `scale=100`,
+`calibrated=false`, `status`, `method`, `reason`, `components` and
+`excluded_components` (Flutter: `excludedComponents`).
+Render null/unavailable scores as unavailable; preserve valid zero values.
+An older server can omit `overall`; the SDK never computes a replacement score.
+`breakdown.pronunciation` mirrors the overall criterion for compatibility.
+The server must be upgraded as well as the SDK.
+
+```json
+{"overall":{"score":50,"status":"estimated","method":"accuracy_completeness_hmean: 2*A*C/(A+C); zero if A+C=0","reason":null,"version":"local-accuracy-completeness-v1","scale":100,"calibrated":false,"components":["accuracy","completeness"],"excluded_components":["fluency","prosody"]}}
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hoanghong/speaking-angular",
-  "version": "0.4.3",
-  "description": "Ready-to-use online speaking: five languages, microphone realtime and audio upload",
+  "version": "0.6.0",
+  "description": "Angular 18 SDK for speech transcription, audio upload and versioned local pronunciation assessment with typed overall and component scores.",
   "type": "module",
   "peerDependencies": {
     "@angular/common": ">=18 <19",
@@ -11,13 +11,19 @@
   "sideEffects": false,
   "license": "MIT",
   "dependencies": {
-    "@hoanghong/speaking-core": "^0.4.3",
+    "@hoanghong/speaking-core": "^0.6.0",
     "tslib": "^2.3.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
+  "keywords": [
+    "speech",
+    "pronunciation-assessment",
+    "speech-to-text",
+    "sdk"
+  ],
   "module": "fesm2022/hoanghong-speaking-angular.mjs",
   "typings": "index.d.ts",
   "exports": {