@hoanghong/speaking-core 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.4.2
+
+- Simplify public integration documentation; no runtime changes.
+
+# 0.4.1
+
+- Application keys support quota updates, 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.

package/README.md

@@ -1,6 +1,6 @@
 # @hoanghong/speaking-core
 
-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.
+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.
 
 ## Đánh giá phát âm tiếng Anh Mỹ
 
@@ -76,3 +76,17 @@ 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.
+
+
+## Application key and service URL
+
+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.
+
+```ts
+createSpeakingService({ appKey: 'YOUR_APP_KEY', baseUrl: 'https://your-service.example/sdk' });
+```

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

@@ -1,6 +1,7 @@
 /** 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;

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,7 @@ 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() });

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.4.0",
+  "version": "0.4.2",
   "description": "Online speaking SDK: gateway configuration, realtime microphone and audio upload",
   "type": "module",
   "main": "dist/index.js",