@hoanghong/speaking-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,12 +1,22 @@
-# 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.
+# 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,56 @@
 # @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. 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.
 
-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.
+## Kết nối tự động, không cấu hình URL/token
 
-## 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>
-```
-
-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' });
+```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/index.d.ts

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

package/dist/index.js

@@ -3,3 +3,4 @@ export * from './batch.js';
 export * from './realtime.js';
 export * from './microphone.js';
 export * from './gateway.js';
+export * from './public-service.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/public-service.d.ts

@@ -0,0 +1,8 @@
+/** 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;
+};

package/dist/public-service.js

@@ -0,0 +1,41 @@
+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;
+    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.3.0",
   "description": "Online speaking SDK: gateway configuration, realtime microphone and audio upload",
   "type": "module",
   "main": "dist/index.js",