@hoanghong/speaking-core 0.0.0-stage → 0.1.0

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,19 @@
-# 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 batch ASR và realtime WebSocket v1. Không nhúng model hay service credential.
+
+Exports: `BatchSpeakingClient`, `RealtimeSpeakingClient`, `SpeakingMicrophone`, contracts và errors.
+Microphone dùng AudioWorklet; copy asset `assets/pcm-worklet.js` vào app và truyền `workletUrl`.
+
+```bash
+npm ci
+npm test
+npm pack
+```
+
+Realtime `ticketProvider` gọi backend ứng dụng để lấy ticket một lần, không gọi private ASR ticket API
+bằng service token trong browser. Batch `headers` cung cấp token người dùng cho gateway.
+`stop()` chờ ACK toàn bộ audio; `SpeakingMicrophone.stop()` flush phần PCM cuối trước finalize.
+Mất mạng/quá backlog trả lỗi rõ ràng, không tự reconnect/resume hay fallback.
+
+Hướng dẫn cấu hình, ví dụ và contract: `docs/realtime-and-sdk.md` ở repository root.

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

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

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './contracts.js';
+export * from './batch.js';
+export * from './realtime.js';
+export * from './microphone.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,35 @@
-{
-  "name": "@hoanghong/speaking-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@hoanghong/speaking-core",
+  "version": "0.1.0",
+  "description": "FSEL batch and native realtime speaking SDK for browsers",
+  "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"
+  ],
+  "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/"
+  }
+}