@hoanghong/speaking-core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.4.0
+
+- Add US English pronunciation assessment client: 120-second audio, reference passage, optional IPA tokens and uncalibrated phoneme diagnostics.
+- Share existing gateway/public application sessions; no service credentials in client apps.
+- Local test release; requires server pronunciation endpoint and model provisioning.
+
 # Changelog
 
 ## 0.3.0

package/README.md

@@ -1,6 +1,28 @@
 # @hoanghong/speaking-core
 
-SDK online cho người tự làm UI. Cài `npm install @hoanghong/speaking-core@^0.3.0`. 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.4.0 cài bằng `npm install ./vendor/hoanghong-speaking-core-0.4.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ỹ
+
+```ts
+import { PronunciationClient, createSpeakingService } from '@hoanghong/speaking-core';
+const pronunciation = new PronunciationClient(createSpeakingService().pronunciation);
+export async function assess(file: File) {
+  return pronunciation.assessAudio(file, {
+    referenceText: 'cat', expectedPhonemes: ['k', 'æ', 't'], filename: file.name,
+  });
+}
+```
+
+Audio tối đa 120 giây/25 MiB, reference tối đa 4096 ký tự; timeout client 11 phút.
+Đọc cả đoạn: thay referenceText bằng đoạn mẫu; bỏ expectedPhonemes khi server có eSpeak.
+Các âm tùy chọn là token vocabulary, không tách IPA theo ký tự. Mỗi lần gọi cấp phiên riêng,
+không tự retry. AbortSignal được hỗ trợ. Server phải triển khai endpoint/model phát âm;
+bộ cài này chưa xác nhận hosted endpoint đã sẵn sàng. Gateway riêng dùng cấu hình
+`createSpeakingGateway(...).pronunciation`, giữ credential của service ở backend.
+Response typed PronunciationAssessment: âm mẫu/nhận dạng, comparisons, timestamp ước lượng,
+formant/pitch/intensity/PSD và warnings. `calibrated=false`, không dùng similarity làm điểm
+phát âm chính thức. Các API realtime/upload dưới đây giữ nguyên.
 
 ## Kết nối tự động, không cấu hình URL/token
 

package/dist/gateway.d.ts

@@ -1,6 +1,7 @@
 import { BatchOptions } from './batch.js';
 import { MicrophoneOptions } from './microphone.js';
 import { RealtimeOptions } from './realtime.js';
+import { PronunciationOptions } from './pronunciation.js';
 export interface SpeakingGatewayOptions {
     /** Application gateway, e.g. /api/speaking. It must relay /v1 HTTP + WebSocket. */
     baseUrl?: string;
@@ -13,4 +14,5 @@ export declare function createSpeakingGateway(options?: SpeakingGatewayOptions):
     batch: BatchOptions;
     realtime: RealtimeOptions;
     microphone: MicrophoneOptions;
+    pronunciation: PronunciationOptions;
 };

package/dist/gateway.js

@@ -12,6 +12,7 @@ export function createSpeakingGateway(options = {}) {
     socket.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     return {
         batch: { baseUrl, headers, fetch: request },
+        pronunciation: { baseUrl, headers, fetch: request },
         realtime: {
             websocketUrl: socket.href,
             ticketProvider: async (start) => {

package/dist/index.d.ts

@@ -4,3 +4,4 @@ export * from './realtime.js';
 export * from './microphone.js';
 export * from './gateway.js';
 export * from './public-service.js';
+export * from './pronunciation.js';

package/dist/index.js

@@ -4,3 +4,4 @@ export * from './realtime.js';
 export * from './microphone.js';
 export * from './gateway.js';
 export * from './public-service.js';
+export * from './pronunciation.js';

package/dist/pronunciation.d.ts

@@ -0,0 +1,58 @@
+export interface PronunciationOptions {
+    baseUrl: string;
+    /** Short-lived app/gateway authentication; never embed a service credential. */
+    headers: () => Promise<HeadersInit>;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+}
+export interface PronunciationPhone {
+    phoneme: string;
+    start: number;
+    end: number;
+}
+export interface PronunciationComparison {
+    operation: 'match' | 'substitution' | 'deletion' | 'insertion';
+    expected: string | null;
+    observed: string | null;
+    start: number | null;
+    end: number | null;
+}
+export interface PronunciationAcousticFrame {
+    time: number;
+    formants_hz: Array<number | null>;
+    delta_formants_hz: Array<number | null>;
+    f2_minus_f1_hz: number | null;
+    pitch_hz: number | null;
+    intensity_db: number | null;
+    psd_power_per_hz: number[];
+}
+export interface PronunciationAssessment {
+    reference_text: string;
+    language: 'en-US';
+    expected_phonemes: string[];
+    observed_phonemes: PronunciationPhone[];
+    comparisons: PronunciationComparison[];
+    phoneme_error_rate: number;
+    phoneme_similarity: number;
+    calibrated: false;
+    timing_method: 'ctc_greedy_approximate';
+    duration: number;
+    acoustic_frames: PronunciationAcousticFrame[];
+    psd_frequencies_hz: number[];
+    model: string;
+    warnings: string[];
+}
+export interface AssessPronunciationOptions {
+    referenceText: string;
+    /** Vocabulary tokens, not individual IPA characters. Optional when server has eSpeak. */
+    expectedPhonemes?: string[];
+    filename?: string;
+    signal?: AbortSignal;
+}
+export declare class PronunciationClient {
+    private readonly options;
+    private readonly request;
+    constructor(options: PronunciationOptions);
+    /** US English, <=120 seconds and <=25 MiB. No automatic retries or duplicate quota charges. */
+    assessAudio(audio: Blob, options: AssessPronunciationOptions): Promise<PronunciationAssessment>;
+}

package/dist/pronunciation.js

@@ -0,0 +1,52 @@
+import { SpeakingError } from './contracts.js';
+export class PronunciationClient {
+    options;
+    request;
+    constructor(options) {
+        this.options = options;
+        this.request = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** US English, <=120 seconds and <=25 MiB. No automatic retries or duplicate quota charges. */
+    async assessAudio(audio, options) {
+        if (!options.referenceText.trim() || options.referenceText.length > 4096) {
+            throw new SpeakingError('INVALID_REFERENCE', 'Provide reference text of 1 to 4096 characters');
+        }
+        if (!audio.size || audio.size > 25 * 1024 * 1024) {
+            throw new SpeakingError('INVALID_AUDIO', 'Audio must be nonempty and at most 25 MiB');
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            abort();
+        else
+            options.signal?.addEventListener('abort', abort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.options.timeoutMs ?? 660_000);
+        try {
+            if (controller.signal.aborted)
+                throw new SpeakingError('CANCELLED', 'Assessment was cancelled');
+            const headers = new Headers(await this.options.headers());
+            headers.delete('Content-Type');
+            const form = new FormData();
+            form.append('file', audio, options.filename ?? 'recording.wav');
+            form.append('reference_text', options.referenceText);
+            form.append('language', 'en-US');
+            if (options.expectedPhonemes !== undefined) {
+                form.append('expected_phonemes', JSON.stringify(options.expectedPhonemes));
+            }
+            const response = await this.request(this.options.baseUrl.replace(/\/$/, '') + '/v1/pronunciation-assessments', { method: 'POST', credentials: 'same-origin', headers, body: form, signal: controller.signal });
+            const body = await response.json().catch(() => null);
+            if (!response.ok) {
+                throw new SpeakingError(body?.code ?? 'HTTP_ERROR', body?.message ?? 'Assessment failed', response.status);
+            }
+            if (!body || body.language !== 'en-US' || body.calibrated !== false ||
+                typeof body.phoneme_similarity !== 'number' || !Array.isArray(body.comparisons)) {
+                throw new SpeakingError('INVALID_RESPONSE', 'Invalid pronunciation assessment response');
+            }
+            return body;
+        }
+        finally {
+            clearTimeout(timer);
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+}

package/dist/public-service.d.ts

@@ -5,4 +5,5 @@ export declare function createSpeakingService(options?: {
     batch: import("./batch.js").BatchOptions;
     realtime: import("./realtime.js").RealtimeOptions;
     microphone: import("./microphone.js").MicrophoneOptions;
+    pronunciation: import("./pronunciation.js").PronunciationOptions;
 };

package/dist/public-service.js

@@ -37,5 +37,7 @@ export function createSpeakingService(options = {}) {
     };
     const realtime = createSpeakingGateway({ baseUrl: SERVICE, headers: async () => ({ Authorization: 'Bearer ' + await session() }) });
     config.realtime = realtime.realtime;
+    // Every synchronous assessment consumes its own short-lived, single-use session.
+    config.pronunciation.headers = async () => ({ Authorization: 'Bearer ' + await session() });
     return config;
 }

package/package.json

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