@hoanghong/speaking-core 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hoanghong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @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.
+
+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.
+
+## 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' });
+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 unsubscribe = client.onEvent(event => {
+  if (event.type === 'partial') transcript.textContent = event.text;
+  if (event.type === 'clientError') { transcript.textContent = event.error.message; idle(); }
+});
+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 });
+```
+
+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.
+
+## 4. Ví dụ upload đầy đủ
+
+```js
+import { BatchSpeakingClient, createSpeakingGateway } from '@hoanghong/speaking-core';
+
+const batch = new BatchSpeakingClient(createSpeakingGateway().batch);
+export async function transcribeFile(file, signal) {
+  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;
+  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');
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    job = await batch.getResult(job.job_id, signal);
+  }
+  if (job.error) throw new Error(job.error.message);
+  return job;
+}
+// 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
+
+`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.
+
+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.
+
+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.

package/assets/pcm-worklet.js

@@ -0,0 +1,52 @@
+// Streaming sample-rate conversion with fractional carry between render quanta.
+// Averaging provides a simple anti-alias filter; no sample loss at noninteger ratios.
+class FselPcm16 extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this.ratio = sampleRate / 16000;
+    this.weight = 0; this.sum = 0;
+    this.samples = []; this.running = true; this.energy = 0;
+    this.port.onmessage = ({ data }) => {
+      if (data.type !== 'flush') return;
+      this.running = false;
+      if (this.weight > 0) this.samples.push(this.sum / this.weight);
+      this.weight = 0; this.sum = 0;
+      this.emit();
+      this.port.postMessage({ type: 'flushed' });
+    };
+  }
+  emit() {
+    if (!this.samples.length) return;
+    const buffer = new ArrayBuffer(this.samples.length * 2);
+    const view = new DataView(buffer);
+    let energy = 0;
+    this.samples.forEach((value, index) => {
+      const clamped = Math.max(-1, Math.min(1, value));
+      view.setInt16(index * 2, Math.round(clamped * (clamped < 0 ? 32768 : 32767)), true);
+      energy += clamped * clamped;
+    });
+    this.port.postMessage({ type: 'pcm', buffer, level: Math.sqrt(energy / this.samples.length) }, [buffer]);
+    this.samples = [];
+  }
+  process(inputs) {
+    if (!this.running) return true;
+    const channels = inputs[0];
+    if (!channels?.length) return true;
+    for (let i = 0; i < channels[0].length; i++) {
+      let value = 0;
+      for (const channel of channels) value += channel[i] / channels.length;
+      let remaining = 1;
+      while (remaining > 1e-9) {
+        const take = Math.min(remaining, this.ratio - this.weight);
+        this.sum += value * take; this.weight += take; remaining -= take;
+        if (this.weight >= this.ratio - 1e-9) {
+          this.samples.push(this.sum / this.ratio);
+          this.weight = 0; this.sum = 0;
+          if (this.samples.length >= 3200) this.emit();
+        }
+      }
+    }
+    return true;
+  }
+}
+registerProcessor('fsel-pcm16', FselPcm16);

package/dist/batch.d.ts

@@ -0,0 +1,16 @@
+import { AudioProfile, Job, Language } from './contracts.js';
+export interface BatchOptions {
+    baseUrl: string;
+    /** User/gateway auth only. Never distribute an ASR service credential to an app. */
+    headers: () => Promise<HeadersInit>;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class BatchSpeakingClient {
+    private readonly options;
+    private readonly request;
+    constructor(options: BatchOptions);
+    private call;
+    submitAudio(audio: Blob, language: Language, idempotencyKey: string, audioProfile?: AudioProfile, filename?: string, signal?: AbortSignal): Promise<Job>;
+    getResult(jobId: string, signal?: AbortSignal): Promise<Job>;
+    cancelJob(jobId: string): Promise<Job>;
+}

package/dist/batch.js

@@ -0,0 +1,39 @@
+import { SpeakingError } from './contracts.js';
+export class BatchSpeakingClient {
+    options;
+    request;
+    constructor(options) {
+        this.options = options;
+        this.request = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async call(path, init) {
+        const response = await this.request(this.options.baseUrl.replace(/\/$/, '') + path, init);
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new SpeakingError(error.code ?? 'HTTP_ERROR', error.message ?? 'Speaking request failed', response.status);
+        }
+        return response.json();
+    }
+    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');
+        const form = new FormData();
+        form.append('file', audio, filename);
+        form.append('language', language);
+        form.append('audio_profile', audioProfile);
+        const headers = new Headers(await this.options.headers());
+        headers.delete('Content-Type');
+        headers.set('Idempotency-Key', idempotencyKey);
+        return this.call('/v1/transcription-jobs', { method: 'POST', headers, body: form, signal });
+    }
+    async getResult(jobId, signal) {
+        return this.call('/v1/transcription-jobs/' + encodeURIComponent(jobId), {
+            headers: await this.options.headers(), signal,
+        });
+    }
+    async cancelJob(jobId) {
+        return this.call('/v1/transcription-jobs/' + encodeURIComponent(jobId), {
+            method: 'DELETE', headers: await this.options.headers(),
+        });
+    }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,107 @@
+export type Language = 'en' | 'ja' | 'ko' | 'zh' | 'vi';
+export type AudioProfile = 'short_answer' | 'passage';
+export type SpeakingState = 'idle' | 'connecting' | 'recording' | 'stopping' | 'stopped' | 'cancelled' | 'failed';
+export interface Transcript {
+    text: string;
+    audio_duration_seconds: number;
+    timestamp_granularity: 'none' | 'segment' | 'word';
+    segments: Array<{
+        text: string;
+        start: number | null;
+        end: number | null;
+        words: Array<{
+            word: string;
+            start: number;
+            end: number;
+            probability?: number | null;
+        }>;
+    }>;
+    timing: {
+        queue_ms: number;
+        decode_ms: number;
+        inference_ms: number;
+    };
+}
+export interface Job {
+    job_id: string;
+    status: 'queued' | 'running' | 'cancelling' | 'cancelled' | 'succeeded' | 'no_speech' | 'failed';
+    language: Language;
+    audio_profile: AudioProfile;
+    model_id: string;
+    model_revision: string;
+    runtime: string;
+    execution_profile: string;
+    config_hash: string;
+    result: Transcript | null;
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+    } | null;
+}
+export interface StartOptions {
+    language: Language;
+    audioProfile?: AudioProfile;
+    correlationId?: string;
+}
+export interface RealtimeFinal {
+    type: 'final';
+    session_id: string;
+    status: 'succeeded' | 'no_speech';
+    language: Language;
+    audio_profile: AudioProfile;
+    correlation_id: string | null;
+    model_id: string;
+    model_revision: string;
+    runtime: string;
+    execution_profile: string;
+    config_hash: string;
+    last_seq: number;
+    total_bytes: number;
+    result: Transcript | null;
+}
+export interface Started {
+    type: 'started';
+    protocol_version: 1;
+    session_id: string;
+    audio_format: 'pcm_s16le';
+    sample_rate: 16000;
+    channels: 1;
+    max_chunk_bytes: number;
+    max_audio_seconds: number;
+}
+export type ServerEvent = Started | RealtimeFinal | {
+    type: 'ack';
+    session_id: string;
+    last_seq: number;
+    total_bytes: number;
+} | {
+    type: 'partial';
+    session_id: string;
+    text: string;
+    last_seq: number;
+} | {
+    type: 'stopped' | 'cancelled';
+    session_id: string;
+} | {
+    type: 'error';
+    code: string;
+    message: string;
+    request_id: string;
+    session_id: string;
+};
+export type SpeakingEvent = ServerEvent | {
+    type: 'state';
+    state: SpeakingState;
+} | {
+    type: 'audioLevel';
+    level: number;
+} | {
+    type: 'clientError';
+    error: SpeakingError;
+};
+export declare class SpeakingError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    constructor(code: string, message: string, status?: number | undefined);
+}

package/dist/contracts.js

@@ -0,0 +1,10 @@
+export class SpeakingError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'SpeakingError';
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,16 @@
+import { BatchOptions } from './batch.js';
+import { MicrophoneOptions } from './microphone.js';
+import { RealtimeOptions } from './realtime.js';
+export interface SpeakingGatewayOptions {
+    /** Application gateway, e.g. /api/speaking. It must relay /v1 HTTP + WebSocket. */
+    baseUrl?: string;
+    /** Optional short-lived application auth. Never embed the ASR service token. */
+    headers?: () => Promise<HeadersInit>;
+    workletUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+export declare function createSpeakingGateway(options?: SpeakingGatewayOptions): {
+    batch: BatchOptions;
+    realtime: RealtimeOptions;
+    microphone: MicrophoneOptions;
+};

package/dist/gateway.js

@@ -0,0 +1,35 @@
+import { SpeakingError } from './contracts.js';
+export function createSpeakingGateway(options = {}) {
+    const origin = typeof location === 'undefined' ? undefined : location.origin;
+    const url = new URL(options.baseUrl ?? '/api/speaking', origin);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+        throw new SpeakingError('INVALID_CONFIG', 'Use an HTTP(S) gateway URL without credentials, query or hash');
+    }
+    const baseUrl = url.href.replace(/\/$/, '');
+    const headers = options.headers ?? (async () => ({}));
+    const request = options.fetch ?? globalThis.fetch.bind(globalThis);
+    const socket = new URL(baseUrl + '/v1/realtime');
+    socket.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return {
+        batch: { baseUrl, headers, fetch: request },
+        realtime: {
+            websocketUrl: socket.href,
+            ticketProvider: async (start) => {
+                const auth = new Headers(await headers());
+                auth.set('Content-Type', 'application/json');
+                const response = await request(baseUrl + '/v1/realtime-tickets', {
+                    method: 'POST', headers: auth, credentials: 'same-origin',
+                    body: JSON.stringify({ language: start.language, audio_profile: start.audioProfile ?? 'short_answer' }),
+                });
+                const decoded = await response.json().catch(() => ({}));
+                const body = decoded && typeof decoded === 'object' ? decoded : {};
+                if (!response.ok)
+                    throw new SpeakingError(body.code ?? 'HTTP_ERROR', body.message ?? 'Cannot create speaking ticket', response.status);
+                if (typeof body.ticket !== 'string' || !body.ticket)
+                    throw new SpeakingError('INVALID_RESPONSE', 'Gateway returned no ticket');
+                return body.ticket;
+            },
+        },
+        microphone: { workletUrl: options.workletUrl ?? 'assets/speaking/pcm-worklet.js' },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './batch.js';
+export * from './realtime.js';
+export * from './microphone.js';
+export * from './gateway.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './batch.js';
+export * from './realtime.js';
+export * from './microphone.js';
+export * from './gateway.js';

package/dist/microphone.d.ts

@@ -0,0 +1,27 @@
+import { RealtimeSpeakingClient } from './realtime.js';
+import { RealtimeFinal, 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;
+}
+export declare class SpeakingMicrophone {
+    readonly client: RealtimeSpeakingClient;
+    private readonly options;
+    private stream?;
+    private context?;
+    private source?;
+    private worklet?;
+    private sends;
+    private audioError?;
+    private flush?;
+    private unsubscribe?;
+    private starting;
+    private generation;
+    private stopPromise?;
+    constructor(client: RealtimeSpeakingClient, options: MicrophoneOptions);
+    start(options: StartOptions): Promise<void>;
+    stop(): Promise<RealtimeFinal>;
+    private release;
+    cancel(): Promise<void>;
+    dispose(): Promise<void>;
+}

package/dist/microphone.js

@@ -0,0 +1,139 @@
+import { SpeakingError } from './contracts.js';
+export class SpeakingMicrophone {
+    client;
+    options;
+    stream;
+    context;
+    source;
+    worklet;
+    sends = Promise.resolve();
+    audioError;
+    flush;
+    unsubscribe;
+    starting = false;
+    generation = 0;
+    stopPromise;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+    }
+    async start(options) {
+        if (this.starting || this.stream)
+            throw new SpeakingError('INVALID_STATE', 'Microphone is already active');
+        const generation = ++this.generation;
+        this.starting = true;
+        this.stopPromise = undefined;
+        this.audioError = undefined;
+        this.sends = Promise.resolve();
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({
+                audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
+            });
+            if (generation !== this.generation) {
+                stream.getTracks().forEach(track => track.stop());
+                throw new SpeakingError('CANCELLED', 'Microphone start cancelled');
+            }
+            this.stream = stream;
+            this.context = new AudioContext();
+            await this.context.resume();
+            await this.context.audioWorklet.addModule(this.options.workletUrl);
+            if (generation !== this.generation)
+                throw new SpeakingError('CANCELLED', 'Microphone start cancelled');
+            await this.client.start(options);
+            if (generation !== this.generation)
+                throw new SpeakingError('CANCELLED', 'Microphone start cancelled');
+            this.unsubscribe = this.client.onEvent(event => {
+                if (generation !== this.generation)
+                    return;
+                if (event.type === 'clientError') {
+                    this.audioError = event.error;
+                    void this.release();
+                }
+            });
+            this.worklet = new AudioWorkletNode(this.context, 'fsel-pcm16');
+            this.worklet.port.onmessage = ({ data }) => {
+                if (generation !== this.generation)
+                    return;
+                if (data.type === 'pcm') {
+                    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));
+                    this.sends = Promise.all([this.sends, pending]).then(() => { }).catch(error => {
+                        if (generation !== this.generation)
+                            return;
+                        this.audioError = error instanceof SpeakingError ? error : new SpeakingError('AUDIO_FAILED', 'Audio capture failed');
+                        void this.release();
+                    });
+                }
+                else if (data.type === 'flushed')
+                    this.flush?.();
+            };
+            this.source = this.context.createMediaStreamSource(stream);
+            this.source.connect(this.worklet);
+            this.worklet.connect(this.context.destination);
+        }
+        catch (error) {
+            this.client.cancel();
+            await this.release();
+            throw error;
+        }
+        finally {
+            this.starting = false;
+        }
+    }
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        this.stopPromise = (async () => {
+            const generation = this.generation;
+            if (!this.worklet || this.client.state !== 'recording')
+                throw this.audioError ?? new SpeakingError('INVALID_STATE', 'Microphone is not recording');
+            this.source?.disconnect();
+            this.stream?.getTracks().forEach(track => track.stop());
+            try {
+                await new Promise((resolve, reject) => {
+                    const done = () => { clearTimeout(timer); if (this.flush === done)
+                        this.flush = undefined; resolve(); };
+                    const timer = setTimeout(() => { if (this.flush === done)
+                        this.flush = undefined; reject(new SpeakingError('TIMEOUT', 'Microphone flush timed out')); }, 2000);
+                    this.flush = done;
+                    this.worklet.port.postMessage({ type: 'flush' });
+                });
+                if (generation !== this.generation)
+                    throw new SpeakingError('CANCELLED', 'Microphone session changed');
+                await this.sends;
+                if (generation !== this.generation)
+                    throw new SpeakingError('CANCELLED', 'Microphone session changed');
+                if (this.audioError)
+                    throw this.audioError;
+                return await this.client.stop();
+            }
+            catch (error) {
+                if (generation === this.generation)
+                    this.client.cancel();
+                throw error;
+            }
+            finally {
+                if (generation === this.generation)
+                    await this.release();
+            }
+        })();
+        return this.stopPromise;
+    }
+    async release() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        this.source?.disconnect();
+        this.source = undefined;
+        this.worklet?.disconnect();
+        this.worklet = undefined;
+        this.stream?.getTracks().forEach(track => track.stop());
+        this.stream = undefined;
+        const context = this.context;
+        this.context = undefined;
+        if (context && context.state !== 'closed')
+            await context.close();
+    }
+    async cancel() { ++this.generation; this.client.cancel(); await this.release(); }
+    async dispose() { await this.cancel(); this.client.dispose(); }
+}

package/dist/realtime.d.ts

@@ -0,0 +1,42 @@
+import { RealtimeFinal, 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. */
+    ticketProvider: (options: StartOptions) => Promise<string>;
+    socketFactory?: (url: string) => WebSocket;
+    startTimeoutMs?: number;
+    ticketTimeoutMs?: number;
+    ackTimeoutMs?: number;
+    maxQueuedBytes?: number;
+}
+export declare class RealtimeSpeakingClient {
+    private readonly options;
+    state: SpeakingState;
+    private socket?;
+    private listeners;
+    private waiters;
+    private queue;
+    private queuedBytes;
+    private seq;
+    private bytes;
+    private started?;
+    private final?;
+    private failure?;
+    private stopPromise?;
+    private generation;
+    private cancelTicket?;
+    constructor(options: RealtimeOptions);
+    onEvent(listener: (event: SpeakingEvent) => void): () => void;
+    private emit;
+    private setState;
+    audioLevel(level: number): void;
+    private wait;
+    private rejectWaiters;
+    private fail;
+    private acquireTicket;
+    start(options: StartOptions): Promise<Started>;
+    pushAudio(pcm: Uint8Array): Promise<void>;
+    stop(): Promise<RealtimeFinal>;
+    cancel(): void;
+    dispose(): void;
+}

package/dist/realtime.js

@@ -0,0 +1,269 @@
+import { SpeakingError } from './contracts.js';
+export class RealtimeSpeakingClient {
+    options;
+    state = 'idle';
+    socket;
+    listeners = new Set();
+    waiters = new Set();
+    queue = Promise.resolve();
+    queuedBytes = 0;
+    seq = 0;
+    bytes = 0;
+    started;
+    final;
+    failure;
+    stopPromise;
+    generation = 0;
+    cancelTicket;
+    constructor(options) {
+        this.options = options;
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch { /* Consumer callbacks must not break transport cleanup. */ }
+        }
+    }
+    setState(state) {
+        this.state = state;
+        this.emit({ type: 'state', state });
+    }
+    audioLevel(level) { this.emit({ type: 'audioLevel', level }); }
+    wait(type, timeout) {
+        return new Promise((resolve, reject) => {
+            const waiter = { type, resolve, reject, timer: setTimeout(() => {
+                    this.waiters.delete(waiter);
+                    const error = new SpeakingError('TIMEOUT', 'Speaking connection timed out');
+                    reject(error);
+                    this.fail(error);
+                }, timeout) };
+            this.waiters.add(waiter);
+        });
+    }
+    rejectWaiters(error) {
+        for (const waiter of this.waiters) {
+            clearTimeout(waiter.timer);
+            waiter.reject(error);
+        }
+        this.waiters.clear();
+    }
+    fail(error) {
+        if (['failed', 'cancelled', 'stopped'].includes(this.state))
+            return;
+        this.failure = error;
+        this.setState('failed');
+        this.rejectWaiters(error);
+        this.socket?.close();
+        this.emit({ type: 'clientError', error });
+    }
+    async acquireTicket(options) {
+        let timer;
+        let cancel;
+        try {
+            return await Promise.race([
+                this.options.ticketProvider(options),
+                new Promise((_, reject) => {
+                    cancel = () => reject(new SpeakingError('CANCELLED', 'Ticket request cancelled'));
+                    this.cancelTicket = cancel;
+                    timer = setTimeout(() => reject(new SpeakingError('TIMEOUT', 'Ticket request timed out')), this.options.ticketTimeoutMs ?? 30000);
+                }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+            if (this.cancelTicket === cancel)
+                this.cancelTicket = undefined;
+        }
+    }
+    async start(options) {
+        if (['connecting', 'recording', 'stopping'].includes(this.state)) {
+            throw new SpeakingError('INVALID_STATE', 'Speaking session is already active');
+        }
+        const generation = ++this.generation;
+        this.seq = 0;
+        this.bytes = 0;
+        this.queuedBytes = 0;
+        this.final = undefined;
+        this.failure = undefined;
+        this.stopPromise = undefined;
+        this.queue = Promise.resolve();
+        this.setState('connecting');
+        try {
+            const ticket = await this.acquireTicket(options);
+            if (generation !== this.generation || this.state !== 'connecting') {
+                throw new SpeakingError('CANCELLED', 'Speaking start was cancelled');
+            }
+            const socket = (this.options.socketFactory ?? (url => new WebSocket(url)))(this.options.websocketUrl);
+            this.socket = socket;
+            const ready = this.wait('started', this.options.startTimeoutMs ?? 210000);
+            socket.onopen = () => socket.send(JSON.stringify({ type: 'authenticate', protocol_version: 1, ticket }));
+            socket.onmessage = event => {
+                if (generation !== this.generation)
+                    return;
+                try {
+                    const message = JSON.parse(String(event.data));
+                    const allowed = ['started', 'ack', 'partial', 'final', 'stopped', 'cancelled', 'error'];
+                    if (!allowed.includes(message.type))
+                        throw new Error('Unknown event');
+                    if (message.type === 'error') {
+                        this.emit(message);
+                        this.fail(new SpeakingError(message.code, message.message));
+                        return;
+                    }
+                    if (message.type === 'final')
+                        this.final = message;
+                    if (message.type === 'stopped') {
+                        if (!this.final || this.final.last_seq !== this.seq || this.final.total_bytes !== this.bytes) {
+                            throw new Error('Incomplete final result');
+                        }
+                        this.setState('stopped');
+                    }
+                    for (const waiter of this.waiters) {
+                        if (waiter.type === message.type) {
+                            clearTimeout(waiter.timer);
+                            this.waiters.delete(waiter);
+                            waiter.resolve(message);
+                        }
+                    }
+                    this.emit(message);
+                }
+                catch {
+                    this.fail(new SpeakingError('PROTOCOL_ERROR', 'Invalid speaking event'));
+                }
+            };
+            socket.onerror = () => {
+                if (generation === this.generation)
+                    this.fail(new SpeakingError('CONNECTION_LOST', 'Speaking connection failed'));
+            };
+            socket.onclose = () => {
+                if (generation === this.generation && !['stopped', 'cancelled', 'failed'].includes(this.state)) {
+                    this.fail(new SpeakingError('CONNECTION_LOST', 'Speaking connection closed before completion'));
+                }
+            };
+            const started = await ready;
+            if (generation !== this.generation || this.state !== 'connecting') {
+                throw new SpeakingError('CANCELLED', 'Speaking start was cancelled');
+            }
+            if (started.protocol_version !== 1 || started.sample_rate !== 16000 || started.channels !== 1 ||
+                started.audio_format !== 'pcm_s16le' || !Number.isInteger(started.max_chunk_bytes) ||
+                started.max_chunk_bytes < 2 || started.max_chunk_bytes % 2 ||
+                !Number.isInteger(started.max_audio_seconds) || started.max_audio_seconds < 1) {
+                throw new SpeakingError('PROTOCOL_ERROR', 'Unsupported speaking audio contract');
+            }
+            this.started = started;
+            this.setState('recording');
+            return started;
+        }
+        catch (error) {
+            if (generation === this.generation)
+                this.fail(error instanceof SpeakingError ? error :
+                    new SpeakingError('START_FAILED', 'Could not start speaking session'));
+            throw error;
+        }
+    }
+    pushAudio(pcm) {
+        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)) {
+            const error = new SpeakingError('BACKPRESSURE', 'Speaking connection cannot keep up with audio');
+            this.fail(error);
+            return Promise.reject(error);
+        }
+        const owned = pcm.slice();
+        const generation = this.generation;
+        this.queuedBytes += owned.length;
+        const operation = this.queue.then(async () => {
+            if (generation !== this.generation)
+                throw new SpeakingError('CANCELLED', 'Session changed');
+            if (this.failure)
+                throw this.failure;
+            const max = this.started.max_chunk_bytes;
+            for (let offset = 0; offset < owned.length; offset += max) {
+                const chunk = owned.subarray(offset, offset + max);
+                if (this.bytes + chunk.length > this.started.max_audio_seconds * 32000) {
+                    throw new SpeakingError('AUDIO_TOO_LONG', 'Speaking duration limit reached');
+                }
+                const frame = new Uint8Array(4 + chunk.length);
+                new DataView(frame.buffer).setUint32(0, this.seq + 1, false);
+                frame.set(chunk, 4);
+                const ack = this.wait('ack', this.options.ackTimeoutMs ?? 15000);
+                try {
+                    this.socket.send(frame);
+                }
+                catch {
+                    this.fail(new SpeakingError('CONNECTION_LOST', 'Could not send speaking audio'));
+                }
+                const received = await ack;
+                if (generation !== this.generation)
+                    throw new SpeakingError('CANCELLED', 'Session changed');
+                if (received.type !== 'ack' || received.last_seq !== this.seq + 1 || received.total_bytes !== this.bytes + chunk.length) {
+                    throw new SpeakingError('PROTOCOL_ERROR', 'Audio acknowledgement does not match');
+                }
+                this.seq++;
+                this.bytes += chunk.length;
+            }
+        }).catch(error => {
+            if (generation === this.generation)
+                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.queue = operation.catch(() => { });
+        return operation;
+    }
+    stop() {
+        if (this.stopPromise)
+            return this.stopPromise;
+        if (this.state !== 'recording')
+            return Promise.reject(this.failure ?? new SpeakingError('INVALID_STATE', 'No active speaking session'));
+        const generation = this.generation;
+        this.setState('stopping');
+        this.stopPromise = (async () => {
+            await this.queue;
+            if (generation !== this.generation)
+                throw new SpeakingError('CANCELLED', 'Session changed');
+            if (this.failure)
+                throw this.failure;
+            const stopped = this.wait('stopped', this.options.ackTimeoutMs ?? 15000);
+            try {
+                this.socket.send(JSON.stringify({ type: 'stop', last_seq: this.seq, total_bytes: this.bytes }));
+            }
+            catch {
+                this.fail(new SpeakingError('CONNECTION_LOST', 'Could not finalize speaking'));
+            }
+            await stopped;
+            if (generation !== this.generation)
+                throw new SpeakingError('CANCELLED', 'Session changed');
+            if (!this.final || this.final.last_seq !== this.seq || this.final.total_bytes !== this.bytes) {
+                const error = new SpeakingError('INCOMPLETE_AUDIO', 'Final transcript does not match audio');
+                this.fail(error);
+                throw error;
+            }
+            this.setState('stopped');
+            this.socket?.close();
+            return this.final;
+        })();
+        return this.stopPromise;
+    }
+    cancel() {
+        ++this.generation;
+        this.cancelTicket?.();
+        this.setState('cancelled');
+        this.rejectWaiters(new SpeakingError('CANCELLED', 'Speaking session cancelled'));
+        try {
+            if (this.socket?.readyState === 1)
+                this.socket.send(JSON.stringify({ type: 'cancel' }));
+        }
+        finally {
+            this.socket?.close();
+        }
+    }
+    dispose() { this.cancel(); this.listeners.clear(); }
+}

package/package.json

@@ -1,6 +1,36 @@
-{
-  "name": "@hoanghong/speaking-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@hoanghong/speaking-core",
+  "version": "0.2.0",
+  "description": "Online speaking SDK: gateway configuration, realtime microphone and audio upload",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./pcm-worklet.js": "./assets/pcm-worklet.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "~5.5.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}