@hoanghong/speaking-angular 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 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.
+
 ## 0.4.2
 
 - Simplify public integration documentation; no runtime changes.

package/README.md

@@ -5,15 +5,15 @@ Component nhận dạng lời nói online dùng ngay. Chỉ cài package, chọn
 ## 1. Cài đặt
 
 ```bash
-npm install ./vendor/hoanghong-speaking-core-0.4.2.tgz ./vendor/hoanghong-speaking-angular-0.4.2.tgz
+npm install ./vendor/hoanghong-speaking-core-0.5.0.tgz ./vendor/hoanghong-speaking-angular-0.5.0.tgz
 ```
 
 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.
 
-Bản 0.4.2 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.2 lên registry. Các tính năng nhận dạng cũ vẫn dùng được.
+Bản 0.5.0 là bộ cài test local: giải nén ZIP và copy hai tarball vào `vendor/` trước.
+Chưa publish 0.5.0 lên registry. Các tính năng nhận dạng cũ vẫn dùng được.
 
-## Đánh giá phát âm tiếng Anh Mỹ (0.4.2)
+## Đánh giá phát âm tiếng Anh Mỹ (0.5.0)
 
 Thêm `SpeakingService` vào `providers` của component dùng để test, import từ
 `@hoanghong/speaking-angular`, rồi gọi trong class component:
@@ -40,10 +40,9 @@ Thêm `signal: controller.signal` để hủy request. Hàm reject khi lỗi; UI
 Kết quả có timestamp, âm thiếu/thừa/thay thế, formant/pitch/intensity/PSD và warnings.
 
 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. Endpoint public `/sdk/v1/pronunciation-assessments` và model phải
+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.
-Test server riêng qua `provideSpeakingGateway({baseUrl: 'https://YOUR_TEST_GATEWAY'})`;
-gateway phải chuyển tiếp endpoint và giữ service credential ở backend, không đưa vào app.
+Không đưa service credential vào ứng dụng.
 
 ## 2. Thêm component — ví dụ đầy đủ
 
@@ -158,17 +157,36 @@ Dịch vụ public tự cấp phiên ngắn hạn. Mặc định server giới h
 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ế.
 
 
-## Application key and service URL
+## Application key
 
-Pass the application key provided by FSEL as `appKey`. Quotas and key status are
-managed by the service. App keys identify an application and are visible in
-browser/mobile applications.
-
-The default service is https://ai-service.fsel.edu.vn/sdk. For a private deployment,
-set `baseUrl` to the absolute /sdk endpoint supplied by your service operator.
+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.
 
 ```ts
-provideSpeakingApp({ appKey: environment.speakingAppKey,
-  baseUrl: environment.speakingServiceUrl });
-// Local: speakingServiceUrl = 'http://127.0.0.1:8001/sdk'
+provideSpeakingApp({ appKey: environment.speakingAppKey });
 ```
+
+
+## Multi-criteria pronunciation diagnostics (0.5.0)
+
+Optional `breakdown` contains accuracy, completeness, fluency, prosody, pronunciation,
+vocabulary, grammar and topic. Each has score (0–100 or null), status
+(estimated/unavailable), method and reason. These are local diagnostics, not Azure
+scores or calibrated grades. Older services may omit breakdown.
+
+- Accuracy = 100 * matches / (matches + substitutions + insertions), at phoneme level.
+- Completeness = 100 * (reference phonemes - omissions) / reference phonemes.
+  Substitutions count as covered; this is coverage, not correctness.
+- Fluency is an energy continuity proxy = 100 * (1 - internal pause seconds / active span).
+  20 ms RMS windows, threshold=max(0.005, 0.1*peak RMS), internal gaps >=250 ms.
+  Excludes leading/trailing silence; requires >=2 s audio and >=1 s active span.
+  Noise may inflate the value and intentional pauses may lower it; this is not VAD/native fluency.
+- Prosody has no score. Pitch P90-P10 and standard deviation (semitones) are reported
+  with >=20 voiced frames and >=2 s audio. Variation does not imply correct intonation.
+- Overall pronunciation and content scores remain null: no calibrated composite,
+  stress model, transcript/grammar evaluator or topic evaluator is configured.
+
+errors counts phoneme matches/substitutions/omissions/insertions. signal.pauses are
+acoustic intervals, not linguistic unexpected/missing breaks. Consult limitations
+and version=local-diagnostics-v1 before interpreting estimates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoanghong/speaking-angular",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Ready-to-use online speaking: five languages, microphone realtime and audio upload",
   "type": "module",
   "peerDependencies": {
@@ -11,7 +11,7 @@
   "sideEffects": false,
   "license": "MIT",
   "dependencies": {
-    "@hoanghong/speaking-core": "^0.4.2",
+    "@hoanghong/speaking-core": "^0.5.0",
     "tslib": "^2.3.0"
   },
   "publishConfig": {