@hoanghong/speaking-core 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,12 +1,28 @@
-# Changelog
-
-## 0.2.0
-
-- Add createSpeakingGateway for shared HTTP/WebSocket/ticket configuration.
-- Validate gateway URLs and malformed ticket responses.
-- Add complete microphone/upload examples and gateway/asset setup instructions.
-- Preserve existing low-level 0.1 APIs.
-
-## 0.1.0
-
-- Initial batch, realtime and browser microphone 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
+
+- Per-application keys with server-managed quota; appKey setup without a service URL.
+
+- Hosted public service configuration with automatic short-lived sessions and quota errors.
+- Select realtime/upload using serviceType; no URL or token setup for hosted use.
+- Completed callback includes text and audio: recorded PCM as WAV, or original uploaded file.
+- Bounded five-minute recording buffer and preserved final residual audio.
+
+
+## 0.2.0
+
+- Add createSpeakingGateway for shared HTTP/WebSocket/ticket configuration.
+- Validate gateway URLs and malformed ticket responses.
+- Add complete microphone/upload examples and gateway/asset setup instructions.
+- Preserve existing low-level 0.1 APIs.
+
+## 0.1.0
+
+- Initial batch, realtime and browser microphone SDK.

package/README.md

@@ -1,120 +1,78 @@
 # @hoanghong/speaking-core
 
-TypeScript SDK cho FSEL ASR online: batch upload, WebSocket realtime, microphone AudioWorklet. MIT. Ngôn ngữ `en`, `ja`, `ko`, `zh`, `vi`. Không chứa model hoặc service credential.
+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.
 
-Muốn UI dùng ngay: cài [@hoanghong/speaking-angular](https://www.npmjs.com/package/@hoanghong/speaking-angular). Flutter dùng [fsel_speaking](https://pub.dev/packages/fsel_speaking). Core dành cho người tự thiết kế giao diện browser.
+## Đánh giá phát âm tiếng Anh Mỹ
 
-## 1. Cài đặt
-
-```bash
-npm install @hoanghong/speaking-core@^0.2.0
-```
-
-Cần browser có WebSocket, AudioWorklet, getUserMedia, HTTPS hoặc localhost. Node >=18 dùng cho tooling/batch; microphone chỉ chạy trong browser. Thư viện là ESM.
-
-## 2. Chuẩn bị gateway và asset
-
-Backend ứng dụng cung cấp prefix như `/api/speaking`, xác thực người dùng và relay giao thức FSEL ASR tới server. Chỉ backend giữ service token. Không nhúng khóa S3/service token vào bundle. Địa chỉ gateway quan sát được qua Network; không thể giấu URL mạng trong SDK. Package không kèm server ASR hoặc tài khoản miễn phí; server phải có weights cho ngôn ngữ được chọn.
-
-
-Gateway forward `POST /v1/realtime-tickets`, `WS /v1/realtime`, `POST /v1/transcription-jobs`, `GET/DELETE /v1/transcription-jobs/{id}` sau khi bỏ prefix. Bảo vệ route bằng đăng nhập, quyền sở hữu job và quota; không mở relay công khai dùng service token.
-
-Copy `node_modules/@hoanghong/speaking-core/assets/pcm-worklet.js` sang static asset `assets/speaking/pcm-worklet.js`. Với Angular thêm vào `angular.json` assets:
-
-```json
-{"glob":"pcm-worklet.js","input":"node_modules/@hoanghong/speaking-core/assets","output":"assets/speaking"}
-```
-
-Với bundler khác, dùng chức năng copy static assets tương ứng; URL phải trả JavaScript. Không dùng một HTML fallback làm worklet.
-
-## 3. Ví dụ microphone đầy đủ
-
-HTML của trang:
-
-```html
-<button id="start">Bắt đầu</button>
-<button id="stop" disabled>Dừng</button>
-<button id="cancel" disabled>Hủy</button>
-<pre id="transcript" aria-live="polite"></pre>
+```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,
+  });
+}
 ```
 
-Module JavaScript/TypeScript được bundler xử lý sau khi DOM đã có:
-
-```js
-import {
-  createSpeakingGateway, RealtimeSpeakingClient, SpeakingMicrophone,
-} from '@hoanghong/speaking-core';
-
-const config = createSpeakingGateway({ baseUrl: '/api/speaking' });
+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
+
+```ts
+import { createSpeakingService, RealtimeSpeakingClient, SpeakingMicrophone } from '@hoanghong/speaking-core';
+const config = createSpeakingService();
 const client = new RealtimeSpeakingClient(config.realtime);
-const microphone = new SpeakingMicrophone(client, config.microphone);
-const start = document.querySelector('#start');
-const stop = document.querySelector('#stop');
-const cancel = document.querySelector('#cancel');
-const transcript = document.querySelector('#transcript');
-function idle() { start.disabled = false; stop.disabled = true; cancel.disabled = true; }
+const mic = new SpeakingMicrophone(client, config.microphone);
 const unsubscribe = client.onEvent(event => {
-  if (event.type === 'partial') transcript.textContent = event.text;
-  if (event.type === 'clientError') { transcript.textContent = event.error.message; idle(); }
+  if (event.type === 'partial') console.log(event.text);
+  if (event.type === 'clientError') console.error(event.error);
 });
-start.onclick = async () => {
-  start.disabled = true;
-  transcript.textContent = 'Đang chuẩn bị…';
-  try {
-    await microphone.start({ language: 'vi' });
-    transcript.textContent = 'Đang nghe…';
-    stop.disabled = false; cancel.disabled = false;
-  } catch (error) { transcript.textContent = String(error); idle(); }
-};
-stop.onclick = async () => {
-  stop.disabled = true;
-  try {
-    const final = await microphone.stop();
-    transcript.textContent = final.result?.text ?? 'Không có lời nói.';
-  } catch (error) { transcript.textContent = String(error); }
-  finally { idle(); }
-};
-cancel.onclick = async () => {
-  try { await microphone.cancel(); transcript.textContent = 'Đã hủy.'; }
-  catch (error) { transcript.textContent = String(error); }
-  finally { idle(); }
-};
-window.addEventListener('pagehide', () => {
-  unsubscribe();
-  void microphone.dispose();
-}, { once: true });
+// Gọi từ handler nút bắt đầu; không tự ghi âm khi load trang:
+export async function start() { await mic.start({ language: 'vi' }); }
+export async function stop() {
+  const result = await mic.stop();
+  return { text: result.result?.text ?? '', audio: result.audio };
+}
+export async function cancel() { await mic.cancel(); }
+export async function dispose() { unsubscribe(); await mic.dispose(); }
 ```
 
-Không tự bắt đầu ghi âm khi load trang. Chờ quyền microphone và `start()` hoàn tất trước khi nói. Khi dùng trong SPA, gọi unsubscribe/dispose ở lifecycle unmount thay vì chỉ pagehide. Không tự reconnect/replay audio sau mất mạng.
+Audio là File WAV PCM16 mono 16 kHz, gồm phần audio cuối khi dừng. Dùng URL.createObjectURL để nghe/tải rồi revokeObjectURL; hoặc FormData để lưu. Cần browser AudioWorklet/getUserMedia và HTTPS/localhost. Public worklet được tải tự động; không copy asset. Gọi dispose ở lifecycle unmount.
 
-## 4. Ví dụ upload đầy đủ
+## Upload
 
-```js
-import { BatchSpeakingClient, createSpeakingGateway } from '@hoanghong/speaking-core';
-
-const batch = new BatchSpeakingClient(createSpeakingGateway().batch);
-export async function transcribeFile(file, signal) {
+```ts
+import { BatchSpeakingClient, createSpeakingService } from '@hoanghong/speaking-core';
+const batch = new BatchSpeakingClient(createSpeakingService().batch);
+export async function upload(file: File) {
   if (file.size > 25 * 1024 * 1024) throw new Error('File tối đa 25 MiB');
-  let job = await batch.submitAudio(file, 'vi', crypto.randomUUID(), 'short_answer', file.name, signal);
-  const deadline = Date.now() + 10 * 60 * 1000;
+  let job = await batch.submitAudio(file, 'vi', crypto.randomUUID(), 'short_answer', file.name);
+  const deadline = Date.now() + 600000;
   while (!['succeeded', 'no_speech', 'failed', 'cancelled'].includes(job.status)) {
-    if (Date.now() > deadline) throw new Error('Hết thời gian chờ; job có thể còn chạy');
-    if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+    if (Date.now() > deadline) throw new Error('Hết thời gian chờ');
     await new Promise(resolve => setTimeout(resolve, 1500));
-    job = await batch.getResult(job.job_id, signal);
+    job = await batch.getResult(job.job_id);
   }
   if (job.error) throw new Error(job.error.message);
-  return job;
+  if (job.status === 'cancelled') throw new Error('Đã hủy');
+  return { text: job.result?.text ?? '', audio: file, language: 'vi', serviceType: 'upload' };
 }
-// Truyền File lấy từ input[type=file] vào transcribeFile(file).
-// Chủ động hủy server job: await batch.cancelJob(jobId).
-// AbortSignal chỉ dừng request phía client, không tự hủy job trên server.
 ```
 
-## Cấu hình và xử lý lỗi
+Public client quản lý capability cho một job tại một thời điểm; tạo client/config riêng nếu xử lý nhiều job song song. Giữ client khi cần getResult/cancelJob cho job đó. Không chia sẻ capability hay serialize audio vào JSON.
+
+Ngôn ngữ en/ja/ko/zh/vi. Public service mặc định 5 phiên/IP/ngày, 100 phiên/ngày/instance (UTC); có thể được FSEL điều chỉnh. Mỗi phiên mới tính lượt kể cả khi lỗi; 429/QUOTA_EXCEEDED là hết lượt. SDK không tự retry/replay. Realtime tối đa 300 giây với buffer PCM 9,6 MB; dọn buffer khi lỗi/hủy. Upload không tự lưu vĩnh viễn file trên S3. Mạng/CSP cần cho phép truy cập dịch vụ FSEL. 404/503 có thể do server chưa triển khai public SDK/model. Cần server hỗ trợ bản 0.3 trước khi sử dụng.
 
-`createSpeakingGateway({baseUrl, headers, workletUrl, fetch})` trả ba nhóm `batch`, `realtime`, `microphone`. Mặc định base `/api/speaking`, worklet `assets/speaking/pcm-worklet.js`. Relative base dùng origin trang hiện tại; ngoài browser truyền URL HTTP(S) tuyệt đối. HTTPS tự dùng WSS. Không truyền base có userinfo/query/hash. `headers` là callback Promise trả HeadersInit, dùng auth của người dùng ứng dụng nếu cần, không dùng service token dài hạn. Cùng origin sử dụng cookie của ứng dụng; auth khác origin/CORS cần backend cấu hình tương ứng.
+createSpeakingGateway và các constructor cấu hình thủ công cũ vẫn được giữ cho nhu cầu nâng cao; không cần dùng trong luồng public trên.
 
-Realtime ticket được xin tự động qua POST JSON `language`/`audio_profile`; ticket dùng để authenticate WebSocket. SDK xử lý queue audio có giới hạn, ACK, stop/final flush; microphone thu PCM mono 16 kHz. Realtime tối đa 300 giây theo server. Các constructor cấu hình thủ công 0.1 vẫn dùng được.
+## Key ứng dụng
 
-401/403: kiểm tra auth ứng dụng/gateway. 404: prefix/rewrite/asset. 503: model hoặc tài nguyên server. Worklet MIME/404: kiểm tra copy asset. Microphone denied: quyền và HTTPS. WS timeout: proxy Upgrade/WSS và timeout. `SpeakingError` có `code`, `message`, `status` khi có HTTP status. Không log credential hoặc ticket.
+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.

package/dist/audio.d.ts

@@ -0,0 +1,9 @@
+/** Five minutes of mono PCM16 at 16 kHz; bounded independently of server limits. */
+export declare const MAX_RECORDING_BYTES: number;
+export declare class SpeakingAudioBuffer {
+    private chunks;
+    private size;
+    append(pcm: Uint8Array): void;
+    file(): File;
+    clear(): void;
+}

package/dist/audio.js

@@ -0,0 +1,36 @@
+import { SpeakingError } from './contracts.js';
+/** Five minutes of mono PCM16 at 16 kHz; bounded independently of server limits. */
+export const MAX_RECORDING_BYTES = 16000 * 2 * 300;
+export class SpeakingAudioBuffer {
+    chunks = [];
+    size = 0;
+    append(pcm) {
+        if (pcm.byteLength % 2)
+            throw new SpeakingError('INCOMPLETE_AUDIO', 'PCM16 requires complete samples');
+        if (this.size + pcm.byteLength > MAX_RECORDING_BYTES)
+            throw new SpeakingError('AUDIO_TOO_LONG', 'Recording exceeds five minutes');
+        this.chunks.push(pcm.slice());
+        this.size += pcm.byteLength;
+    }
+    file() {
+        const header = new ArrayBuffer(44);
+        const view = new DataView(header);
+        const text = (at, value) => { for (let i = 0; i < value.length; ++i)
+            view.setUint8(at + i, value.charCodeAt(i)); };
+        text(0, 'RIFF');
+        view.setUint32(4, 36 + this.size, true);
+        text(8, 'WAVE');
+        text(12, 'fmt ');
+        view.setUint32(16, 16, true);
+        view.setUint16(20, 1, true);
+        view.setUint16(22, 1, true);
+        view.setUint32(24, 16000, true);
+        view.setUint32(28, 32000, true);
+        view.setUint16(32, 2, true);
+        view.setUint16(34, 16, true);
+        text(36, 'data');
+        view.setUint32(40, this.size, true);
+        return new File([header, ...this.chunks], 'speaking.wav', { type: 'audio/wav' });
+    }
+    clear() { this.chunks = []; this.size = 0; }
+}

package/dist/batch.d.ts

@@ -4,6 +4,7 @@ export interface BatchOptions {
     /** User/gateway auth only. Never distribute an ASR service credential to an app. */
     headers: () => Promise<HeadersInit>;
     fetch?: typeof globalThis.fetch;
+    beforeSubmit?: (idempotencyKey: string) => Promise<void>;
 }
 export declare class BatchSpeakingClient {
     private readonly options;

package/dist/batch.js

@@ -17,6 +17,7 @@ export class BatchSpeakingClient {
     async submitAudio(audio, language, idempotencyKey, audioProfile = 'short_answer', filename = 'recording.wav', signal) {
         if (!idempotencyKey.trim())
             throw new SpeakingError('INVALID_REQUEST', 'An idempotency key is required');
+        await this.options.beforeSubmit?.(idempotencyKey);
         const form = new FormData();
         form.append('file', audio, filename);
         form.append('language', language);

package/dist/contracts.d.ts

@@ -1,4 +1,14 @@
 export type Language = 'en' | 'ja' | 'ko' | 'zh' | 'vi';
+export type SpeakingServiceType = 'realtime' | 'upload';
+export type SpeakingResult = (RealtimeFinal | Job) & {
+    text: string;
+    audio: File;
+    language: Language;
+    serviceType: SpeakingServiceType;
+};
+export type RecordedSpeakingFinal = RealtimeFinal & {
+    audio: File;
+};
 export type AudioProfile = 'short_answer' | 'passage';
 export type SpeakingState = 'idle' | 'connecting' | 'recording' | 'stopping' | 'stopped' | 'cancelled' | 'failed';
 export interface Transcript {

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

@@ -3,3 +3,5 @@ export * from './batch.js';
 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

@@ -3,3 +3,5 @@ export * from './batch.js';
 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

@@ -1,5 +1,5 @@
 import { RealtimeSpeakingClient } from './realtime.js';
-import { RealtimeFinal, StartOptions } from './contracts.js';
+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;
@@ -18,9 +18,10 @@ export declare class SpeakingMicrophone {
     private starting;
     private generation;
     private stopPromise?;
+    private readonly recording;
     constructor(client: RealtimeSpeakingClient, options: MicrophoneOptions);
     start(options: StartOptions): Promise<void>;
-    stop(): Promise<RealtimeFinal>;
+    stop(): Promise<RecordedSpeakingFinal>;
     private release;
     cancel(): Promise<void>;
     dispose(): Promise<void>;

package/dist/microphone.js

@@ -1,4 +1,5 @@
 import { SpeakingError } from './contracts.js';
+import { SpeakingAudioBuffer } from './audio.js';
 export class SpeakingMicrophone {
     client;
     options;
@@ -13,6 +14,7 @@ export class SpeakingMicrophone {
     starting = false;
     generation = 0;
     stopPromise;
+    recording = new SpeakingAudioBuffer();
     constructor(client, options) {
         this.client = client;
         this.options = options;
@@ -25,6 +27,7 @@ export class SpeakingMicrophone {
         this.stopPromise = undefined;
         this.audioError = undefined;
         this.sends = Promise.resolve();
+        this.recording.clear();
         try {
             const stream = await navigator.mediaDevices.getUserMedia({
                 audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
@@ -55,6 +58,15 @@ export class SpeakingMicrophone {
                 if (generation !== this.generation)
                     return;
                 if (data.type === 'pcm') {
+                    try {
+                        this.recording.append(new Uint8Array(data.buffer));
+                    }
+                    catch (error) {
+                        this.audioError = error;
+                        this.client.audioFailed(this.audioError);
+                        void this.release();
+                        return;
+                    }
                     this.client.audioLevel(data.level);
                     // Enqueue immediately to let the transport enforce a bounded audio backlog.
                     const pending = this.client.pushAudio(new Uint8Array(data.buffer));
@@ -106,7 +118,10 @@ export class SpeakingMicrophone {
                     throw new SpeakingError('CANCELLED', 'Microphone session changed');
                 if (this.audioError)
                     throw this.audioError;
-                return await this.client.stop();
+                const result = await this.client.stop();
+                if (generation !== this.generation)
+                    throw new SpeakingError('CANCELLED', 'Microphone session changed');
+                return { ...result, audio: this.recording.file() };
             }
             catch (error) {
                 if (generation === this.generation)
@@ -121,6 +136,7 @@ export class SpeakingMicrophone {
         return this.stopPromise;
     }
     async release() {
+        this.recording.clear();
         this.unsubscribe?.();
         this.unsubscribe = undefined;
         this.source?.disconnect();

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

@@ -0,0 +1,9 @@
+/** Hosted public service. The SDK handles short-lived capabilities internally. */
+export declare function createSpeakingService(options?: {
+    appKey?: 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

@@ -0,0 +1,43 @@
+import { createSpeakingGateway } from './gateway.js';
+import { SpeakingError } from './contracts.js';
+const SERVICE = 'https://ai-service.fsel.edu.vn/sdk';
+/** Hosted public service. The SDK handles short-lived capabilities internally. */
+export function createSpeakingService(options = {}) {
+    if (options.appKey !== undefined && !options.appKey.trim())
+        throw new SpeakingError('INVALID_CONFIG', 'Application key cannot be empty');
+    const request = globalThis.fetch.bind(globalThis);
+    const session = async () => {
+        const response = await request(SERVICE + '/session', {
+            method: 'POST', credentials: 'omit',
+            headers: options.appKey ? { 'X-Speaking-Key': options.appKey } : undefined,
+        });
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok)
+            throw new SpeakingError(body?.code ?? 'HTTP_ERROR', body?.message ?? 'Speaking service unavailable', response.status);
+        if (typeof body?.access_token !== 'string' || !body.access_token)
+            throw new SpeakingError('INVALID_RESPONSE', 'Speaking session unavailable');
+        return body.access_token;
+    };
+    let token;
+    let previousKey;
+    const config = createSpeakingGateway({
+        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',
+    });
+    config.batch.beforeSubmit = async (key) => {
+        if (!token || key !== previousKey) {
+            token = await session();
+            previousKey = key;
+        }
+    };
+    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

@@ -1,4 +1,4 @@
-import { RealtimeFinal, SpeakingEvent, SpeakingState, Started, StartOptions } from './contracts.js';
+import { RealtimeFinal, SpeakingError, SpeakingEvent, SpeakingState, Started, StartOptions } from './contracts.js';
 export interface RealtimeOptions {
     websocketUrl: string;
     /** Ask an authenticated application backend for a fresh single-use ticket per start. */
@@ -30,6 +30,7 @@ export declare class RealtimeSpeakingClient {
     private emit;
     private setState;
     audioLevel(level: number): void;
+    audioFailed(error: SpeakingError): void;
     private wait;
     private rejectWaiters;
     private fail;

package/dist/realtime.js

@@ -35,6 +35,7 @@ export class RealtimeSpeakingClient {
         this.emit({ type: 'state', state });
     }
     audioLevel(level) { this.emit({ type: 'audioLevel', level }); }
+    audioFailed(error) { this.fail(error); }
     wait(type, timeout) {
         return new Promise((resolve, reject) => {
             const waiter = { type, resolve, reject, timer: setTimeout(() => {

package/package.json

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