@vocalstack/js-sdk 2.0.0-alpha.0 → 2.0.0-alpha.2

package/README.md

@@ -4,6 +4,8 @@ The VocalStack speech API for Node (20 or newer) and browsers: one client,
 `VocalStack`, with one group per resource, typed from the API's one OpenAPI
 document (`/v1/openapi.json`, generated into `@vocalstack/contract`).
 
+Read more about the [VocalStack JavaScript SDK](https://vocalstack.com/#developers) and our other SDKs on the [VocalStack website](https://vocalstack.com/).
+
 ```ts
 import { VocalStack } from '@vocalstack/js-sdk';
 
@@ -21,14 +23,17 @@ const srt = await (await vs.recordings.export(job.recordingId, 'srt')).text();
 
 ## Install
 
-Not on npm yet. The API serves its own builds to every account: [https://api.vocalstack.com/docs/guides/quickstart.md](https://api.vocalstack.com/docs/guides/quickstart.md) has the install command for the current build (it sends your API key to that host only).
+```sh
+npm install @vocalstack/js-sdk
+```
 
 ## Guides
 
 - [Quickstart](https://github.com/vocalstack/js-sdk/blob/main/docs/quickstart.md): An API key, the SDK, and your first transcript in a dozen lines.
 - [Transcribe a file](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-file.md): Upload a file, wait for its job, read the transcript and export it. Asynchronous; nothing to keep open.
-- [Transcribe a link](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL or a YouTube video, then transcribes it like a file. Asynchronous, with a fetch phase first.
+- [Transcribe a link](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-link.md): The server fetches a public URL, a YouTube video or a recording on a video or audio site, then transcribes it like a file. Asynchronous, with a fetch phase first.
 - [Transcribe a batch of files](https://github.com/vocalstack/js-sdk/blob/main/docs/transcribe-a-batch.md): Send many files or links as one batch, start it once, and read every transcript when it is done. Cheaper than one transcription per file.
+- [Search your transcriptions](https://github.com/vocalstack/js-sdk/blob/main/docs/search-transcriptions.md): Find transcriptions by words in their name or link, site, language, kind, tag and date, keep the shared ones, and play each with its share code.
 - [Stream a microphone](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-microphone.md): Live audio in, transcript events out, over one WebSocket. Drafts replace the live tail; commits append.
 - [Stream a file at full speed](https://github.com/vocalstack/js-sdk/blob/main/docs/stream-a-file.md): Send a file's bytes through a realtime session and read the transcript as fast as the server makes it. Nothing is stored.
 - [Go live](https://github.com/vocalstack/js-sdk/blob/main/docs/go-live.md): Publish live audio to a stored transcription, and put it on a broadcast link listeners open. Control is HTTP; audio is one WebSocket.

package/SKILL.md

@@ -33,11 +33,8 @@ npm init -y && npm pkg set type=module   # in a new folder: the programs below a
 npm i @vocalstack/js-sdk                    # Node 20 or newer
 ```
 
-Before the package is published, any account installs
-the private build its environment serves: the API reference's Install section
-(`<base>/docs`, or Developers -> API reference in the app) and `<base>/sdk/latest`
-give the exact commands, which send `VOCALSTACK_API_KEY` to that host only.
-Or install it from a clone of https://github.com/vocalstack/js-sdk. Build it
+To run code newer than the npm release, install it from a clone of
+https://github.com/vocalstack/js-sdk. Build it
 first (`npm run build` also builds the bundled `contract/` package):
 
 ```sh
@@ -105,7 +102,7 @@ const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: pr
 
 const tx = await vs.transcriptions.create({
   file: process.argv[2], // a path (mp3, wav, flac, ogg, m4a, mp4 ...), a Blob or bytes
-  settings: { spokenLanguage: 'en', speakerLabels: 'on' }, // both optional; speakerLabels: 'off' (default) | 'auto' | 'on'
+  settings: { spokenLanguage: 'en', speakerLabels: 'on' }, // both optional; speakerLabels: 'auto' (default) | 'on' | 'off'
   // Off unless asked for: settings.summary, settings.title, settings.summaryTranslations,
   // settings.voice (spoken translations), and shareLink: true (a public share link).
 });
@@ -182,6 +179,16 @@ for (const h of hits) {
 }
 ```
 
+By meaning, in any language, even with none of the words (vector search). Each
+hit's `passage` is its whole paragraph: give the passages to your own model as
+context to answer questions about what was said (RAG). Pay as you go counts 60
+an hour (`allowance`); Premium and Enterprise have no limit.
+
+```js
+const { hits: found } = await vs.search.vector('how much does housing cost');
+for (const h of found) console.log(h.similarity.toFixed(2), h.passage.mediaStart, h.passage.text);
+```
+
 ## 6. A batch of files
 
 Many files at once cost less as a batch: one create, one minimum charge for

package/dist/errors.d.ts

@@ -1,6 +1,4 @@
 import type { ErrorCode } from '@vocalstack/contract';
-/** The OAuth errors `vs.connect.token()` raises (RFC 6749 §5.2): the token
- * endpoint answers `400 { error, error_description }`, not the envelope. */
 export type ConnectTokenErrorCode = 'invalid_request' | 'invalid_grant' | 'unsupported_grant_type';
 export interface VocalStackErrorOptions {
     retryable?: boolean;
@@ -9,32 +7,16 @@ export interface VocalStackErrorOptions {
     headers?: Headers;
     requestId?: string;
 }
-/** Every failure this SDK surfaces: an HTTP error envelope, a socket
- * `error` frame, or one the transport synthesizes (`capacity_exceeded`). */
 export declare class VocalStackError extends Error {
-    /** The envelope's code; on `vs.connect.token()`, the OAuth `error`. */
     readonly code: ErrorCode | ConnectTokenErrorCode;
     readonly retryable: boolean;
-    /** HTTP status, when the error came from an HTTP response. */
     readonly status?: number;
-    /** The envelope's `data.details`: for example `{ balance, required,
-     * plan, topUpUrl }` on `insufficient_credit`, code suggestions on a
-     * link conflict, `{ recordingId, takeover: true }` when another device
-     * is recording. */
     readonly details?: unknown;
-    /** The response headers (`Retry-After`, `RateLimit-*`,
-     * `WWW-Authenticate`), when the error came from an HTTP response. */
     readonly headers?: Headers;
-    /** The request's id (the envelope's `requestId`, else the `X-Request-Id`
-     * header): quote it when reporting a failure. */
     readonly requestId?: string;
     constructor(code: ErrorCode | ConnectTokenErrorCode, message: string, opts?: VocalStackErrorOptions);
-    /** Seconds the server asked the caller to wait (`Retry-After`), if it said. */
     get retryAfter(): number | undefined;
 }
 export declare function capacityExceeded(message: string): VocalStackError;
 export declare function fromEnvelope(body: unknown, status?: number, headers?: Headers): VocalStackError;
-/** A token endpoint's `400 { error, error_description }` (RFC 6749 §5.2) as
- * a `VocalStackError` whose `code` is the `error`; any other answer goes
- * through the envelope. */
 export declare function fromOAuth(body: unknown, status?: number, headers?: Headers): VocalStackError;

package/dist/errors.js

@@ -1,21 +1,9 @@
-/** Every failure this SDK surfaces: an HTTP error envelope, a socket
- * `error` frame, or one the transport synthesizes (`capacity_exceeded`). */
 export class VocalStackError extends Error {
-    /** The envelope's code; on `vs.connect.token()`, the OAuth `error`. */
     code;
     retryable;
-    /** HTTP status, when the error came from an HTTP response. */
     status;
-    /** The envelope's `data.details`: for example `{ balance, required,
-     * plan, topUpUrl }` on `insufficient_credit`, code suggestions on a
-     * link conflict, `{ recordingId, takeover: true }` when another device
-     * is recording. */
     details;
-    /** The response headers (`Retry-After`, `RateLimit-*`,
-     * `WWW-Authenticate`), when the error came from an HTTP response. */
     headers;
-    /** The request's id (the envelope's `requestId`, else the `X-Request-Id`
-     * header): quote it when reporting a failure. */
     requestId;
     constructor(code, message, opts = {}) {
         super(message);
@@ -27,7 +15,6 @@ export class VocalStackError extends Error {
         this.headers = opts.headers;
         this.requestId = opts.requestId;
     }
-    /** Seconds the server asked the caller to wait (`Retry-After`), if it said. */
     get retryAfter() {
         const v = this.headers?.get('retry-after');
         if (v == null || v === '')
@@ -44,8 +31,6 @@ export function capacityExceeded(message) {
 }
 export function fromEnvelope(body, status, headers) {
     const b = body;
-    // The envelope names the request; a header the page cannot read across
-    // origins (when it is not exposed) is the fallback.
     const requestId = (b && typeof b.requestId === 'string' ? b.requestId : undefined) ?? headers?.get('x-request-id') ?? undefined;
     if (b && typeof b.code === 'string') {
         return new VocalStackError(b.code, b.message ?? b.code, {
@@ -58,9 +43,6 @@ export function fromEnvelope(body, status, headers) {
     }
     return new VocalStackError('internal', `unexpected error (status ${status})`, { status, headers, requestId });
 }
-/** A token endpoint's `400 { error, error_description }` (RFC 6749 §5.2) as
- * a `VocalStackError` whose `code` is the `error`; any other answer goes
- * through the envelope. */
 export function fromOAuth(body, status, headers) {
     const b = body;
     if (status === 400 && b && typeof b.error === 'string') {

package/dist/http.d.ts

@@ -1,75 +1,43 @@
 export type Query = Record<string, string | number | boolean | undefined | null>;
 export interface ClientOptions {
-    /** API origin; `https://api.vocalstack.com` when absent. */
     baseUrl?: string;
-    /** An API key (`vs_key_…`), on a server: keys are refused from web
-     * pages.  Absent (and no `token`) = anonymous (a listener). */
     apiKey?: string;
-    /** In a browser instead: a signed-in person's access token or a
-     * short-lived browser token (`vs_bt_…`), or a getter so a refreshed one
-     * is picked up per request.  Not with `apiKey`. */
     token?: string | (() => string | undefined | null | Promise<string | undefined | null>);
-    /** Act for an organization the user belongs to (`X-Acting-Principal`). */
     actingPrincipal?: string;
-    /** A stable per-device id (correlation only, `X-Device-Id`). */
     deviceId?: string;
     fetch?: typeof fetch;
-    /** How often a `429 rate_limited`, or a `503 unavailable` on a call that
-     * is safe to repeat (GET, HEAD, DELETE, or one with an `Idempotency-Key`),
-     * is retried after its `Retry-After` (at most 60 s each).  Default 2; 0
-     * turns it off. */
     maxRetries?: number;
-    /** Default deadline for a realtime socket to report ready, in ms. */
     readyDeadlineMs?: number;
 }
-/** Per-call options every method takes last. */
 export interface CallOptions {
-    /** Sent as `Idempotency-Key` on the creates that honour it. */
     idempotencyKey?: string;
     signal?: AbortSignal;
 }
-/** How a listener reads something that is not theirs: a private
- * broadcast's listener token, or a share link's code. */
 export interface ReadAs {
     listenerToken?: string;
     shareCode?: string;
 }
-/** A listener-side read's query: the wire spells both as the options do
- * (`?listenerToken=`, `?shareCode=`), so this only picks them out. */
 export declare function listenerQuery(as: ReadAs | undefined): Query;
 export interface RequestInit2 extends CallOptions {
     query?: Query;
     body?: unknown;
     headers?: Record<string, string>;
-    /** Send no credential even when the client has one. */
     anonymous?: boolean;
-    /** Never retry, whatever the answer (a single-use code). */
     noRetry?: boolean;
-    /** Read a 400 as OAuth's `{ error, error_description }`. */
     oauthErrors?: boolean;
 }
 export declare const DEFAULT_BASE_URL = "https://api.vocalstack.com";
 export declare function qs(q: Query | undefined): string;
 export declare const seg: (s: string | number) => string;
-/** Whether a failed call is retried after its `Retry-After` (up to
- * `maxRetries` times): `429 rate_limited` always (nothing ran), and
- * `503 unavailable` (the database is waking) only when repeating the call
- * cannot do the work twice: GET, HEAD and DELETE, or a call carrying an
- * `Idempotency-Key`. */
 export declare function retries(status: number, code: string, method: string, idempotencyKey?: string): boolean;
-/** The one HTTP path every resource method goes through. */
 export declare class Transport {
     #private;
     readonly baseUrl: string;
     readonly opts: ClientOptions;
     constructor(opts: ClientOptions);
-    /** What goes in `Authorization: Bearer`: the API key, else the token. */
     bearer(): Promise<string | undefined>;
     url(path: string, query?: Query): string;
     wsUrl(path: string, query?: Query): string;
-    /** The raw response, after error mapping.  Redirects are not followed
-     * (`redirect: 'manual'`), so a 302 comes back as itself. */
     raw(method: string, path: string, init?: RequestInit2): Promise<Response>;
-    /** A JSON call; an empty body resolves to `undefined`. */
     json<T>(method: string, path: string, init?: RequestInit2): Promise<T>;
 }

package/dist/http.js

@@ -1,6 +1,4 @@
-import { fromEnvelope, fromOAuth } from './errors.js';
-/** A listener-side read's query: the wire spells both as the options do
- * (`?listenerToken=`, `?shareCode=`), so this only picks them out. */
+import { VocalStackError, fromEnvelope, fromOAuth } from './errors.js';
 export function listenerQuery(as) {
     return { listenerToken: as?.listenerToken, shareCode: as?.shareCode };
 }
@@ -18,13 +16,7 @@ export function qs(q) {
 }
 export const seg = (s) => encodeURIComponent(String(s));
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** The wait before retrying `503 unavailable` when it names none. */
 const UNAVAILABLE_WAIT_S = 2;
-/** Whether a failed call is retried after its `Retry-After` (up to
- * `maxRetries` times): `429 rate_limited` always (nothing ran), and
- * `503 unavailable` (the database is waking) only when repeating the call
- * cannot do the work twice: GET, HEAD and DELETE, or a call carrying an
- * `Idempotency-Key`. */
 export function retries(status, code, method, idempotencyKey) {
     if (status === 429)
         return true;
@@ -33,7 +25,6 @@ export function retries(status, code, method, idempotencyKey) {
     const m = method.toUpperCase();
     return m === 'GET' || m === 'HEAD' || m === 'DELETE' || !!idempotencyKey;
 }
-/** The one HTTP path every resource method goes through. */
 export class Transport {
     baseUrl;
     opts;
@@ -45,7 +36,6 @@ export class Transport {
         this.opts = opts;
         this.#fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
     }
-    /** What goes in `Authorization: Bearer`: the API key, else the token. */
     async bearer() {
         if (this.opts.apiKey)
             return this.opts.apiKey;
@@ -59,8 +49,6 @@ export class Transport {
     wsUrl(path, query) {
         return `${this.baseUrl.replace(/^http/, 'ws')}${path}${qs(query)}`;
     }
-    /** The raw response, after error mapping.  Redirects are not followed
-     * (`redirect: 'manual'`), so a 302 comes back as itself. */
     async raw(method, path, init = {}) {
         const headers = { accept: 'application/json', ...init.headers };
         const form = typeof FormData !== 'undefined' && init.body instanceof FormData;
@@ -81,13 +69,23 @@ export class Transport {
         const body = init.body === undefined ? undefined : form ? init.body : urlencoded ? String(init.body) : JSON.stringify(init.body);
         const maxRetries = init.noRetry ? 0 : (this.opts.maxRetries ?? 2);
         for (let attempt = 0;; attempt++) {
-            const res = await this.#fetch(this.url(path, init.query), {
-                method,
-                headers,
-                body,
-                redirect: 'manual',
-                signal: init.signal,
-            });
+            let res;
+            try {
+                res = await this.#fetch(this.url(path, init.query), {
+                    method,
+                    headers,
+                    body,
+                    redirect: 'manual',
+                    signal: init.signal,
+                });
+            }
+            catch (e) {
+                if (e?.name === 'AbortError')
+                    throw e;
+                const err = new VocalStackError('unavailable', 'could not reach the VocalStack API', { retryable: true });
+                err.cause = e;
+                throw err;
+            }
             if (res.ok || (res.status >= 300 && res.status < 400))
                 return res;
             const text = await res.text().catch(() => '');
@@ -100,8 +98,6 @@ export class Transport {
             }
             const err = (init.oauthErrors ? fromOAuth : fromEnvelope)(json, res.status, res.headers);
             if (retries(res.status, err.code, method, init.idempotencyKey) && attempt < maxRetries) {
-                // `unavailable` (a waking database) asks for Retry-After: 2; a
-                // missing header means the same.
                 const wait = err.retryAfter ?? (err.code === 'unavailable' ? UNAVAILABLE_WAIT_S : undefined);
                 if (wait !== undefined && wait <= 60) {
                     await sleep(wait * 1000);
@@ -111,12 +107,18 @@ export class Transport {
             throw err;
         }
     }
-    /** A JSON call; an empty body resolves to `undefined`. */
     async json(method, path, init = {}) {
         const res = await this.raw(method, path, init);
         if (res.status >= 300 && res.status < 400)
             return { location: res.headers.get('location') };
         const text = await res.text();
-        return (text ? JSON.parse(text) : undefined);
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new VocalStackError('internal', 'the API answered with a body that is not JSON', { status: res.status, headers: res.headers, requestId: res.headers.get('x-request-id') ?? undefined });
+        }
     }
 }

package/dist/index.d.ts

@@ -1,22 +1,6 @@
-/**
- * The VocalStack SDK: one client, `VocalStack`, grouped by resource.
- *
- *   import { VocalStack } from '@vocalstack/js-sdk';
- *   const vs = new VocalStack({ apiKey: process.env.VOCALSTACK_API_KEY });
- *
- *   const tx = await vs.transcriptions.createFromUrl('https://example.com/talk.mp3');
- *   const job = await vs.jobs.wait(tx.job!.recordingId);
- *   const { sentences } = await vs.recordings.transcript(job.recordingId);
- *
- * What is what (the API's glossary): a realtime session is a signed token
- * plus one socket, nothing stored (`vs.realtime`); a broadcast is the link
- * listeners open; a transcription is a file, link, microphone or stream
- * transcribed and stored; a recording is one take inside either; a job is
- * a file or link recording's transcription work.
- */
 import { type ClientOptions } from './http.js';
 import { Realtime } from './realtime.js';
-import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Transcriptions, Voices } from './resources.js';
+import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices } from './resources.js';
 export type { ClientOptions, CallOptions, ReadAs, Query } from './http.js';
 export { DEFAULT_BASE_URL } from './http.js';
 export { VocalStackError } from './errors.js';
@@ -29,8 +13,9 @@ export type { ConnectOptions, TranscribeOptions, RealtimeTranscript } from './re
 export { Subscription } from './subscription.js';
 export type { SubscribeOptions, SubscriptionEvent } from './subscription.js';
 export type { WsLike } from './ws.js';
-export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Transcriptions, Voices, } from './resources.js';
-export type { AddBatchFileInput, ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
+export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export type { AudioKind, MediaAuth, MediaFormat, RenderVoice, VoicesChoice } from './resources.js';
+export type { AddBatchFileInput, ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, TranscriptionFilters, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
 export type * from '@vocalstack/contract';
 export type VocalStackOptions = ClientOptions;
 export declare class VocalStack {
@@ -43,6 +28,7 @@ export declare class VocalStack {
     readonly jobs: Jobs;
     readonly corrections: Corrections;
     readonly shareLinks: ShareLinks;
+    readonly tags: Tags;
     readonly voices: Voices;
     readonly search: Search;
     readonly me: MeApi;

package/dist/index.js

@@ -1,28 +1,12 @@
-/**
- * The VocalStack SDK: one client, `VocalStack`, grouped by resource.
- *
- *   import { VocalStack } from '@vocalstack/js-sdk';
- *   const vs = new VocalStack({ apiKey: process.env.VOCALSTACK_API_KEY });
- *
- *   const tx = await vs.transcriptions.createFromUrl('https://example.com/talk.mp3');
- *   const job = await vs.jobs.wait(tx.job!.recordingId);
- *   const { sentences } = await vs.recordings.transcript(job.recordingId);
- *
- * What is what (the API's glossary): a realtime session is a signed token
- * plus one socket, nothing stored (`vs.realtime`); a broadcast is the link
- * listeners open; a transcription is a file, link, microphone or stream
- * transcribed and stored; a recording is one take inside either; a job is
- * a file or link recording's transcription work.
- */
 import { Transport } from './http.js';
 import { Realtime } from './realtime.js';
-import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Transcriptions, Voices, } from './resources.js';
+import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, } from './resources.js';
 export { DEFAULT_BASE_URL } from './http.js';
 export { VocalStackError } from './errors.js';
 export { RealtimeSession } from './realtime.js';
 export { Realtime, applySentence } from './realtime.js';
 export { Subscription } from './subscription.js';
-export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Transcriptions, Voices, } from './resources.js';
+export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
 export class VocalStack {
     baseUrl;
     realtime;
@@ -33,6 +17,7 @@ export class VocalStack {
     jobs;
     corrections;
     shareLinks;
+    tags;
     voices;
     search;
     me;
@@ -53,6 +38,7 @@ export class VocalStack {
         this.jobs = new Jobs(t);
         this.corrections = new Corrections(t);
         this.shareLinks = new ShareLinks(t);
+        this.tags = new Tags(t);
         this.voices = new Voices(t);
         this.search = new Search(t);
         this.me = new MeApi(t);

package/dist/mic.d.ts

@@ -1,51 +1,16 @@
 import type { RealtimeSession } from './realtime.js';
-/** Why capture stopped producing audio (see `MicCaptureOptions.onStall`). */
-export type MicStallReason = 
-/** The input track ended: device unplugged, headset switched, permission revoked. */
-'track_ended'
-/** The track is muted by the OS/hardware (no samples until it unmutes). */
- | 'track_muted'
-/** The AudioContext was suspended (phone call, screen lock, route change). */
- | 'context_suspended'
-/** The AudioContext was closed underneath us. */
- | 'context_closed'
-/** Seconds of exact-zero samples: a silently denied or hardware-muted mic. */
- | 'silent';
+export type MicStallReason = 'track_ended' | 'track_muted' | 'context_suspended' | 'context_closed' | 'silent';
 export interface MicCaptureOptions {
     chunkSeconds?: number;
     sampleRate?: number;
     audio?: MediaTrackConstraints;
-    /**
-     * Called every ~0.5s with (pcm, wall): cumulative output samples
-     * produced and seconds since capture start.  Wire it to
-     * `session.sendClock` so the server can detect capture loss (a
-     * suspended context or dead track produces no samples while wall
-     * time advances) and mark the transcript with honest gaps.  Driven
-     * by a timer, not by sample arrival, so it keeps reporting while
-     * capture is stalled — that is the case it exists for.
-     */
     onClock?: (pcm: number, wall: number) => void;
-    /**
-     * Capture stopped producing audio.  Recovery is attempted
-     * automatically (context resume, track re-acquire); `onRecover`
-     * fires when samples flow again.  Use it to show a "microphone
-     * lost" state instead of "Listening".
-     */
     onStall?: (reason: MicStallReason) => void;
-    /** Audio is flowing again after a stall. */
     onRecover?: () => void;
-    /**
-     * Exact-zero run length (seconds) that flags a silently denied or
-     * hardware-muted mic (real mics always carry a noise floor).  Default
-     * 3; 0 disables.
-     */
     silentSeconds?: number;
 }
-/** The input device the capture is reading, as the browser reports it. */
 export interface MicDevice {
-    /** The device's name, e.g. "MacBook Pro Microphone" ("" before permission is granted). */
     label: string;
-    /** Its native rate (the capture resamples to `sampleRate`). */
     sampleRate?: number;
     channelCount?: number;
     noiseSuppression?: boolean;
@@ -54,20 +19,7 @@ export interface MicDevice {
 export interface MicCapture {
     stop(): Promise<void>;
     readonly sampleRate: number;
-    /** The microphone being read now (a re-acquired track may be another one). */
     readonly device: MicDevice;
-    /** Hold the capture open but stop sending what the microphone hears.
-     *
-     *  A side conversation should not have to end the session, and pausing
-     *  is not the same thing: pausing closes the stream and the listeners
-     *  lose it. Muting keeps every listener connected and the recording
-     *  running, and simply says nothing.
-     *
-     *  Muted chunks are emitted as SILENCE rather than dropped. The server
-     *  measures media time by the audio it receives, so dropping would
-     *  compress the timeline and every later timestamp would be wrong;
-     *  silence keeps the clock honest and transcribes to nothing, which is
-     *  exactly what happened. */
     setMuted(muted: boolean): void;
     readonly muted: boolean;
 }

package/dist/mic.js

@@ -1,7 +1,3 @@
-// The worklet runs on the browser's realtime audio thread and does one
-// allocation-light thing: post every 128-frame block to the main thread.
-// MessagePort queues are unbounded and never overwrite, so a busy main
-// thread (a big transcript re-render) delivers audio late, never drops it.
 const WORKLET_SOURCE = `
 class PCMProcessor extends AudioWorkletProcessor {
   process(inputs) {
@@ -15,9 +11,7 @@ class PCMProcessor extends AudioWorkletProcessor {
 }
 registerProcessor('pcm-processor', PCMProcessor);
 `;
-/** Retry cadence for context resume / track re-acquire while stalled. */
 const RECOVER_MS = 1000;
-/** Capture clock heartbeat cadence. */
 const CLOCK_MS = 500;
 export async function captureMicrophone(onChunk, opts = {}) {
     if (typeof navigator === 'undefined' || !navigator.mediaDevices) {
@@ -32,10 +26,6 @@ export async function captureMicrophone(onChunk, opts = {}) {
     };
     let muted = false;
     let media = await navigator.mediaDevices.getUserMedia({ audio: constraints });
-    // Ask for the target rate directly: Chrome/Firefox/Safari 14.1+ then
-    // resample on the audio thread and our converter is a pass-through.
-    // Browsers that refuse the option fall back to the default rate and the
-    // linear-interpolation resampler below.
     let ctx;
     try {
         ctx = new AudioContext({ sampleRate: targetRate });
@@ -58,15 +48,11 @@ export async function captureMicrophone(onChunk, opts = {}) {
     let buffered = [];
     let readPos = 0;
     let pending = null;
-    // Capture clock: cumulative resampled output samples vs wall time.
     const t0 = performance.now();
     let outSamples = 0;
-    // Zero-run detector state (input-rate samples).
     const silentLimit = Math.round((opts.silentSeconds ?? 3) * inputRate);
     let zeroRun = 0;
     let silentFlagged = false;
-    // Stall bookkeeping: one active reason at a time; `onRecover` fires
-    // once when it clears.
     let stopped = false;
     let stall = null;
     let recoverTimer = null;
@@ -130,27 +116,21 @@ export async function captureMicrophone(onChunk, opts = {}) {
         }
         if (out.length) {
             outSamples += out.length;
-            // Samples flowing again clears a track/context stall; the silent
-            // stall clears only on a nonzero sample (handled above).
             if (stall !== null && stall !== 'silent')
                 clearStall();
             pending = pending ? concat(pending, out) : Float32Array.from(out);
             while (pending.length >= chunkSamples) {
                 const chunk = pending.slice(0, chunkSamples);
-                // Silence, not nothing: see `MicCapture.setMuted`.
                 onChunk(muted ? new Float32Array(chunk.length) : chunk);
                 pending = pending.slice(chunkSamples);
             }
         }
     };
-    // Heartbeat on a timer so a stalled capture is still reported: pcm
-    // stops while wall advances, and the server declares the gap.
     const clockTimer = opts.onClock
         ? setInterval(() => {
             opts.onClock?.(outSamples, (performance.now() - t0) / 1000);
         }, CLOCK_MS)
         : null;
-    // --- recovery -------------------------------------------------------
     const scheduleRecover = (fn) => {
         if (stopped || recoverTimer)
             return;
@@ -185,7 +165,6 @@ export async function captureMicrophone(onChunk, opts = {}) {
             source = ctx.createMediaStreamSource(media);
             source.connect(node);
             watchTracks(media);
-            // `onRecover` fires from the first delivered block.
         })
             .catch(() => scheduleRecover(reacquireTrack));
     };
@@ -201,7 +180,6 @@ export async function captureMicrophone(onChunk, opts = {}) {
                 if (!stopped)
                     setStall('track_muted');
             });
-            // `unmute` needs no handler: the next block clears the stall.
         }
     };
     watchTracks(media);