@hoanghong/speaking-core 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# 0.4.1
+
+- CMS-managed application keys share PostgreSQL quota, rotation and revocation.
+- Optional public-service baseUrl for private deployments and local integration.
+- Includes microphone selection and realtime audio backpressure fixes (web SDK).
+
+## 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.1 cài bằng `npm install ./vendor/hoanghong-speaking-core-0.4.1.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
 
@@ -54,3 +76,19 @@ createSpeakingGateway và các constructor cấu hình thủ công cũ vẫn đ
 ## Key ứng dụng
 
 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.
+
+
+## CMS application keys (0.4.1)
+
+Create an application key in CMS > API Keys, then pass it as `appKey`.
+The CMS backend and SDK endpoint must share the same PostgreSQL DATABASE_URL.
+Quota changes, key rotation and disabling are enforced by the backend. Existing
+sessions are also checked against key state. App keys identify quota; they do not
+grant CMS administrator access and are visible in browser/mobile applications.
+
+The hosted default remains https://ai-service.fsel.edu.vn/sdk. A custom deployment
+can set `baseUrl` to its absolute /sdk endpoint (never /admin/api).
+
+```ts
+createSpeakingService({ appKey: 'KEY_FROM_CMS', baseUrl: 'https://your-service.example/sdk' });
+```

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/microphone.d.ts

@@ -3,6 +3,12 @@ import { RecordedSpeakingFinal, StartOptions } from './contracts.js';
 export interface MicrophoneOptions {
     /** Host the packaged pcm-worklet.js with your app's normal CSP; no inline/blob worker. */
     workletUrl: string;
+    /** Select the same device as the host application's microphone diagnostic. */
+    deviceId?: string;
+    /** Disable processing when a driver/browser suppresses speech unexpectedly. */
+    echoCancellation?: boolean;
+    noiseSuppression?: boolean;
+    autoGainControl?: boolean;
 }
 export declare class SpeakingMicrophone {
     readonly client: RealtimeSpeakingClient;

package/dist/microphone.js

@@ -30,7 +30,13 @@ export class SpeakingMicrophone {
         this.recording.clear();
         try {
             const stream = await navigator.mediaDevices.getUserMedia({
-                audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
+                audio: {
+                    channelCount: 1,
+                    ...(this.options.deviceId ? { deviceId: { exact: this.options.deviceId } } : {}),
+                    echoCancellation: this.options.echoCancellation ?? true,
+                    noiseSuppression: this.options.noiseSuppression ?? true,
+                    autoGainControl: this.options.autoGainControl ?? true,
+                },
             });
             if (generation !== this.generation) {
                 stream.getTracks().forEach(track => track.stop());

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

@@ -1,8 +1,10 @@
 /** Hosted public service. The SDK handles short-lived capabilities internally. */
 export declare function createSpeakingService(options?: {
     appKey?: string;
+    baseUrl?: string;
 }): {
     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

@@ -5,9 +5,20 @@ const SERVICE = 'https://ai-service.fsel.edu.vn/sdk';
 export function createSpeakingService(options = {}) {
     if (options.appKey !== undefined && !options.appKey.trim())
         throw new SpeakingError('INVALID_CONFIG', 'Application key cannot be empty');
+    let endpoint;
+    try {
+        endpoint = new URL(options.baseUrl ?? SERVICE);
+    }
+    catch {
+        throw new SpeakingError('INVALID_CONFIG', 'Use an absolute HTTP(S) service URL');
+    }
+    if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+        throw new SpeakingError('INVALID_CONFIG', 'Use an HTTP(S) service URL without credentials, query or fragment');
+    }
+    const service = endpoint.href.replace(/\/$/, '');
     const request = globalThis.fetch.bind(globalThis);
     const session = async () => {
-        const response = await request(SERVICE + '/session', {
+        const response = await request(service + '/session', {
             method: 'POST', credentials: 'omit',
             headers: options.appKey ? { 'X-Speaking-Key': options.appKey } : undefined,
         });
@@ -21,13 +32,13 @@ export function createSpeakingService(options = {}) {
     let token;
     let previousKey;
     const config = createSpeakingGateway({
-        baseUrl: SERVICE,
+        baseUrl: service,
         headers: async () => {
             if (!token)
                 throw new SpeakingError('INVALID_STATE', 'Submit audio before reading a public job');
             return { Authorization: 'Bearer ' + token };
         },
-        workletUrl: SERVICE + '/pcm-worklet.js',
+        workletUrl: service + '/pcm-worklet.js',
     });
     config.batch.beforeSubmit = async (key) => {
         if (!token || key !== previousKey) {
@@ -35,7 +46,9 @@ export function createSpeakingService(options = {}) {
             previousKey = key;
         }
     };
-    const realtime = createSpeakingGateway({ baseUrl: SERVICE, headers: async () => ({ Authorization: 'Bearer ' + await session() }) });
+    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/dist/realtime.d.ts

@@ -17,6 +17,7 @@ export declare class RealtimeSpeakingClient {
     private waiters;
     private queue;
     private queuedBytes;
+    private pendingAudio;
     private seq;
     private bytes;
     private started?;

package/dist/realtime.js

@@ -7,6 +7,7 @@ export class RealtimeSpeakingClient {
     waiters = new Set();
     queue = Promise.resolve();
     queuedBytes = 0;
+    pendingAudio = [];
     seq = 0;
     bytes = 0;
     started;
@@ -90,6 +91,7 @@ export class RealtimeSpeakingClient {
         this.seq = 0;
         this.bytes = 0;
         this.queuedBytes = 0;
+        this.pendingAudio = [];
         this.final = undefined;
         this.failure = undefined;
         this.stopPromise = undefined;
@@ -172,19 +174,31 @@ export class RealtimeSpeakingClient {
         if (this.state !== 'recording' || !pcm.length || pcm.length % 2) {
             return Promise.reject(new SpeakingError('INVALID_AUDIO', 'An active session and PCM16 samples are required'));
         }
-        if (this.queuedBytes + pcm.length > (this.options.maxQueuedBytes ?? 64000)) {
+        if (this.queuedBytes + pcm.length > (this.options.maxQueuedBytes ?? 320000)) {
             const error = new SpeakingError('BACKPRESSURE', 'Speaking connection cannot keep up with audio');
             this.fail(error);
             return Promise.reject(error);
         }
-        const owned = pcm.slice();
+        this.pendingAudio.push(pcm.slice());
         const generation = this.generation;
-        this.queuedBytes += owned.length;
+        this.queuedBytes += pcm.length;
+        let consumed = 0;
         const operation = this.queue.then(async () => {
             if (generation !== this.generation)
                 throw new SpeakingError('CANCELLED', 'Session changed');
             if (this.failure)
                 throw this.failure;
+            if (!this.pendingAudio.length)
+                return;
+            const chunks = this.pendingAudio;
+            this.pendingAudio = [];
+            consumed = chunks.reduce((size, chunk) => size + chunk.length, 0);
+            const owned = new Uint8Array(consumed);
+            let at = 0;
+            for (const chunk of chunks) {
+                owned.set(chunk, at);
+                at += chunk.length;
+            }
             const max = this.started.max_chunk_bytes;
             for (let offset = 0; offset < owned.length; offset += max) {
                 const chunk = owned.subarray(offset, offset + max);
@@ -215,7 +229,7 @@ export class RealtimeSpeakingClient {
                 this.fail(error instanceof SpeakingError ? error : new SpeakingError('CONNECTION_LOST', 'Speaking audio failed'));
             throw error;
         }).finally(() => { if (generation === this.generation)
-            this.queuedBytes -= owned.length; });
+            this.queuedBytes -= consumed; });
         this.queue = operation.catch(() => { });
         return operation;
     }

package/package.json

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