@hoanghong/speaking-core 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

@@ -1,6 +1,6 @@
 # @hoanghong/speaking-core
 
-SDK online cho người tự làm UI. Bản test 0.4.2 cài bằng `npm install ./vendor/hoanghong-speaking-core-0.4.2.tgz` từ bộ ZIP, chưa publish registry. Angular dùng @hoanghong/speaking-angular với component có sẵn; Flutter dùng fsel_speaking. MIT.
+SDK online cho người tự làm UI. Bản test 0.5.0 cài bằng `npm install ./vendor/hoanghong-speaking-core-0.5.0.tgz` từ bộ ZIP, chưa publish registry. Angular dùng @hoanghong/speaking-angular với component có sẵn; Flutter dùng fsel_speaking. MIT.
 
 ## Đánh giá phát âm tiếng Anh Mỹ
 
@@ -78,15 +78,36 @@ createSpeakingGateway và các constructor cấu hình thủ công cũ vẫn đ
 Dùng `createSpeakingService({ appKey: "KEY_DUOC_FSEL_CAP" })` thay cho lời gọi không tham số. SDK gửi key khi cấp phiên; quota quản lý phía server, không có URL cần cấu hình. Key này là định danh ứng dụng có thể quan sát ở frontend, không có quyền quản trị. INVALID_APP_KEY/401 nghĩa là sai hoặc đã bị khóa; không tự fallback ẩn danh.
 
 
-## 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
-createSpeakingService({ appKey: 'YOUR_APP_KEY', baseUrl: 'https://your-service.example/sdk' });
+createSpeakingService({ appKey: 'YOUR_APP_KEY' });
 ```
+
+
+## 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/dist/pronunciation.d.ts

@@ -26,6 +26,47 @@ export interface PronunciationAcousticFrame {
     intensity_db: number | null;
     psd_power_per_hz: number[];
 }
+/** Local estimates, not Azure-equivalent or calibrated educational scores. */
+export interface PronunciationCriterion {
+    score: number | null;
+    status: 'estimated' | 'unavailable';
+    method: string;
+    reason: string | null;
+}
+export interface PronunciationBreakdown {
+    version: 'local-diagnostics-v1';
+    scope: 'scripted_phoneme_diagnostics';
+    calibrated: false;
+    accuracy: PronunciationCriterion;
+    completeness: PronunciationCriterion;
+    fluency: PronunciationCriterion;
+    prosody: PronunciationCriterion;
+    pronunciation: PronunciationCriterion;
+    vocabulary: PronunciationCriterion;
+    grammar: PronunciationCriterion;
+    topic: PronunciationCriterion;
+    errors: {
+        matches: number;
+        substitutions: number;
+        omissions: number;
+        insertions: number;
+    };
+    signal: {
+        speech_span_seconds: number;
+        internal_pause_seconds: number;
+        pause_ratio: number | null;
+        pauses: Array<{
+            start: number;
+            end: number;
+            duration: number;
+        }>;
+        energy_threshold: number;
+        pitch_range_semitones: number | null;
+        pitch_std_semitones: number | null;
+        voiced_frames: number;
+    };
+    limitations: string[];
+}
 export interface PronunciationAssessment {
     reference_text: string;
     language: 'en-US';
@@ -41,6 +82,8 @@ export interface PronunciationAssessment {
     psd_frequencies_hz: number[];
     model: string;
     warnings: string[];
+    /** Optional for compatibility with older service versions. */
+    breakdown?: PronunciationBreakdown | null;
 }
 export interface AssessPronunciationOptions {
     referenceText: string;

package/dist/pronunciation.js

@@ -42,6 +42,21 @@ export class PronunciationClient {
                 typeof body.phoneme_similarity !== 'number' || !Array.isArray(body.comparisons)) {
                 throw new SpeakingError('INVALID_RESPONSE', 'Invalid pronunciation assessment response');
             }
+            if (body.breakdown != null) {
+                const breakdown = body.breakdown;
+                const names = ['accuracy', 'completeness', 'fluency', 'prosody', 'pronunciation', 'vocabulary', 'grammar', 'topic'];
+                if (breakdown.version !== 'local-diagnostics-v1' || breakdown.calibrated !== false ||
+                    breakdown.scope !== 'scripted_phoneme_diagnostics' || !breakdown.signal || !breakdown.errors ||
+                    !Array.isArray(breakdown.limitations) || names.some(name => {
+                    const criterion = breakdown[name];
+                    return !criterion || typeof criterion.method !== 'string' ||
+                        (criterion.status !== 'estimated' && criterion.status !== 'unavailable') ||
+                        (criterion.status === 'unavailable' ? criterion.score !== null :
+                            typeof criterion.score !== 'number' || !Number.isFinite(criterion.score) || criterion.score < 0 || criterion.score > 100);
+                })) {
+                    throw new SpeakingError('INVALID_RESPONSE', 'Invalid pronunciation diagnostic breakdown');
+                }
+            }
             return body;
         }
         finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hoanghong/speaking-core",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Online speaking SDK: gateway configuration, realtime microphone and audio upload",
   "type": "module",
   "main": "dist/index.js",