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

package/README.md

@@ -32,7 +32,6 @@ npm install @vocalstack/js-sdk
 - [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, 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.
@@ -53,9 +52,8 @@ npm install @vocalstack/js-sdk
 | transcription | a file, link, microphone or stream, transcribed and stored (`live: true` for a microphone or stream) | `vs.transcriptions` |
 | recording | one take inside a broadcast or a transcription | `vs.recordings` |
 | job | a file or link recording's transcription work | `vs.jobs` |
-| batch | many files transcribed together, for less than one transcription each | `vs.batches` |
 
-The other groups: `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+The other groups: `vs.corrections`, `vs.shareLinks`, `vs.speakers`, `vs.voices`,
 `vs.search`, `vs.me`, `vs.languages`, `vs.rtmp`, `vs.events`, `vs.meta`.
 Method names follow the document's `operationId`s (`broadcasts.startRecording`
 is `POST /v1/broadcasts/{id}/recordings`); lists return arrays.
@@ -129,7 +127,7 @@ Browser microphone capture ships as `@vocalstack/js-sdk/mic`
 ## Binary answers
 
 `recordings.export`, `recordings.clip`, `recordings.voiceClip`, `jobs.preview`,
-`voices.preview`, `voices.clonePreview` and `voices.sample` return the
+`voices.preview`, `speakers.voicePreview` and `speakers.sample` return the
 `Response` itself: `.text()`, `.arrayBuffer()` or stream it.
 `recordings.audioUrl` returns the signed media URL.
 

package/SKILL.md

@@ -19,9 +19,6 @@ one group per resource: `vs.transcriptions`, `vs.jobs`, `vs.recordings`,
 - A **job** is a file or link recording's transcription work:
   `vs.jobs.wait(recordingId)` polls it until it is `done` or `failed`
   (`{ onProgress: (job) => … }` sees each read: `job.state`, `job.progress.pct`).
-- A **batch** is many files transcribed together for less than one
-  transcription each: `vs.batches.create()`, `addFile`/`addUrl` per file,
-  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -189,28 +186,6 @@ 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
-the whole batch. Its files get transcripts, exports and speaker labels (when
-`settings.speakerLabels` asks), never a summary, title, share link or voices.
-
-```js
-import { VocalStack } from '@vocalstack/js-sdk';
-const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
-
-const batch = await vs.batches.create({ name: 'Interviews', settings: { spokenLanguage: 'en' } });
-for (const path of process.argv.slice(2)) await vs.batches.addFile(batch.id, { file: path }); // or addUrl(batch.id, url)
-await vs.batches.start(batch.id);
-const done = await vs.batches.wait(batch.id); // done (or stopped); check done.counts.failed
-for (const tx of done.files ?? []) {
-  if (tx.job?.state !== 'done') continue;
-  const { sentences } = await vs.recordings.transcript(tx.job.recordingId);
-  console.log(tx.name, sentences.map((s) => s.text).join(' '));
-}
-// vs.batches.export(batch.id, 'srt') is every finished transcript in one zip.
-```
-
 ## Errors
 
 A failed call throws `VocalStackError` with `code`, `message`, `status`,
@@ -248,8 +223,7 @@ try {
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `listShareLinks`, `createShareLink`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audioUrl`, `subscribe` for a
-  live transcript feed), `vs.batches` (`create`, `addFile`, `addUrl`, `start`,
-  `wait`, `get`, `list`, `export`, `stop`, `delete`), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+  live transcript feed), `vs.corrections`, `vs.shareLinks`, `vs.speakers`, `vs.voices`,
   `vs.broadcasts`, `vs.me` (`get`, `usage`), `vs.languages`,
   `vs.rtmp`, `vs.events`, `vs.meta`. Each method is named after its operation
   in the OpenAPI document (`transcriptions.create` is `POST /v1/transcriptions`).

package/dist/index.d.ts

@@ -1,21 +1,21 @@
 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, Tags, Transcriptions, Voices } from './resources.js';
+import { Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Speakers, 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';
 export type { ConnectTokenErrorCode, VocalStackErrorOptions } from './errors.js';
 export { RealtimeSession } from './realtime.js';
-export type { ConnectParams, SessionEvent } from './realtime.js';
+export type { ConnectParams, QueuedInfo, SessionEvent } from './realtime.js';
 export type { FileInput } from './file.js';
 export { Realtime, applySentence } from './realtime.js';
 export type { ConnectOptions, TranscribeOptions, RealtimeTranscript } from './realtime.js';
 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, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export { Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Speakers, 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 { 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 {
@@ -23,12 +23,12 @@ export declare class VocalStack {
     readonly realtime: Realtime;
     readonly broadcasts: Broadcasts;
     readonly transcriptions: Transcriptions;
-    readonly batches: Batches;
     readonly recordings: Recordings;
     readonly jobs: Jobs;
     readonly corrections: Corrections;
     readonly shareLinks: ShareLinks;
     readonly tags: Tags;
+    readonly speakers: Speakers;
     readonly voices: Voices;
     readonly search: Search;
     readonly me: MeApi;

package/dist/index.js

@@ -1,23 +1,23 @@
 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, Tags, Transcriptions, Voices, } from './resources.js';
+import { Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Speakers, 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, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export { Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Speakers, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
 export class VocalStack {
     baseUrl;
     realtime;
     broadcasts;
     transcriptions;
-    batches;
     recordings;
     jobs;
     corrections;
     shareLinks;
     tags;
+    speakers;
     voices;
     search;
     me;
@@ -33,12 +33,12 @@ export class VocalStack {
         this.realtime = new Realtime(t);
         this.broadcasts = new Broadcasts(t);
         this.transcriptions = new Transcriptions(t);
-        this.batches = new Batches(t);
         this.recordings = new Recordings(t);
         this.jobs = new Jobs(t);
         this.corrections = new Corrections(t);
         this.shareLinks = new ShareLinks(t);
         this.tags = new Tags(t);
+        this.speakers = new Speakers(t);
         this.voices = new Voices(t);
         this.search = new Search(t);
         this.me = new MeApi(t);

package/dist/realtime.d.ts

@@ -11,8 +11,12 @@ export interface ConnectParams {
     options?: SessionOptions;
     readyDeadlineMs?: number;
     onLoading?(stage: 'download' | 'model'): void;
+    onQueued?(queued: QueuedInfo): void;
     onFrame?(frame: ServerFrame): void;
 }
+export type QueuedInfo = Omit<Extract<ServerFrame, {
+    type: 'session.queued';
+}>, 'type'>;
 export declare function engineLost(closeCode?: number): VocalStackError;
 export declare function upgradeRefused(status: number | undefined, body: string): VocalStackError;
 export declare const RESTART_CLOSE = 1012;
@@ -41,6 +45,7 @@ export declare class RealtimeSession implements AsyncIterable<SessionEvent> {
 }
 export interface ConnectOptions {
     onLoading?(stage: 'download' | 'model'): void;
+    onQueued?(queued: QueuedInfo): void;
     onFrame?(frame: ServerFrame): void;
     readyDeadlineMs?: number;
 }

package/dist/realtime.js

@@ -29,7 +29,7 @@ export function upgradeRefused(status, body) {
 export const RESTART_CLOSE = 1012;
 const RESTART_TRIES = 3;
 const MAX_PENDING_BYTES = 4 * 1024 * 1024;
-async function openReady(url, deadlineMs, onLoading, onFrame, attach) {
+async function openReady(url, deadlineMs, onLoading, onQueued, onFrame, attach) {
     const ws = await openWebSocket(url);
     ws.binaryType = 'arraybuffer';
     await new Promise((resolve, reject) => {
@@ -77,6 +77,10 @@ async function openReady(url, deadlineMs, onLoading, onFrame, attach) {
             if (frame.type === 'session.loading') {
                 onLoading?.(frame.stage);
             }
+            else if (frame.type === 'session.queued') {
+                const { type: _type, ...queued } = frame;
+                onQueued?.(queued);
+            }
             else if (frame.type === 'session.ready') {
                 if (!settled) {
                     settled = true;
@@ -142,7 +146,7 @@ export class RealtimeSession {
         const deadlineMs = params.readyDeadlineMs ?? DEFAULT_READY_DEADLINE_MS;
         const early = [];
         let session;
-        await openReady(params.streamUrl, deadlineMs, params.onLoading, (f) => early.push(f), (ws) => {
+        await openReady(params.streamUrl, deadlineMs, params.onLoading, params.onQueued, (f) => early.push(f), (ws) => {
             const s = new RealtimeSession(params.sessionId, ws, params);
             for (const f of early)
                 s.#frame(f);
@@ -160,7 +164,7 @@ export class RealtimeSession {
             if (this.#closedByUs)
                 break;
             try {
-                await openReady(this.#params.streamUrl, deadlineMs, this.#params.onLoading, (f) => this.#frame(f), (ws) => {
+                await openReady(this.#params.streamUrl, deadlineMs, this.#params.onLoading, this.#params.onQueued, (f) => this.#frame(f), (ws) => {
                     this.#ws = ws;
                     this.#reconnecting = false;
                     this.#listen();
@@ -389,6 +393,7 @@ export class Realtime {
             options,
             readyDeadlineMs: connect.readyDeadlineMs ?? this.#t.opts.readyDeadlineMs,
             onLoading: connect.onLoading,
+            onQueued: connect.onQueued,
             onFrame: connect.onFrame,
         });
     }

package/dist/resources.d.ts

@@ -1,4 +1,4 @@
-import type { AppStreamKey, AudioSourceCheck, Batch, BatchPage, AutoTopUpSettings, AutoTopUpView, BillingDetails, BillingView, CheckPromoCode, CheckoutView, CreateCheckout, LowBalanceAlertSettings, LowBalanceAlertView, PaymentDocument, PaymentMethodList, PaymentPage, PortalLink, PromoCodeView, SetInterval, SubscriptionView, YearlyOptIn, UsageChargePage, UsageReport, Broadcast, Correction, CorrectionBatch, CorrectionPage, CreateAppStreamKey, CreateAudioSource, CreateBatch, CreateLiveTranscription, CreateBroadcast, CreateShareLink, CreateTag, CreateTranscription, CreateVoiceFromSpeaker, CreatedAppStreamKey, ChargePage, ExportFormat, ClientApp, ClientPolicy, Health, LanguageLists, LedgerPage, LinkProbe, PatchVoice, PlanList, PublishGrant, Recording, RecordingEvent, RecordingEvents, RecordingPage, RetranscribeLine, RtmpStatus, SearchResults, VectorResults, SettingsPatch, ShareLink, SharedTranscript, StartRecording, StartJob, SummaryStatus, Tag, TagTranscriptions, Transcription, TranscriptionJob, TranscriptionPage, TranscriptSnapshot, UpdateBroadcast, UpdateTag, UpdateTranscription, UpdateShareLink, UploadRecording, Voice, VoiceCatalogue, VoiceTrack, ManyResult } from '@vocalstack/contract';
+import type { AppStreamKey, AudioSourceCheck, AutoTopUpSettings, AutoTopUpView, BillingDetails, BillingView, CheckPromoCode, CheckoutView, CreateCheckout, LowBalanceAlertSettings, LowBalanceAlertView, PaymentDocument, PaymentMethodList, PaymentPage, PortalLink, PromoCodeView, SetInterval, SubscriptionView, YearlyOptIn, UsageChargePage, UsageReport, Broadcast, Correction, CorrectionBatch, CorrectionPage, CreateAppStreamKey, CreateAudioSource, CreateLiveTranscription, CreateBroadcast, CreateShareLink, CreateTag, CreateTranscription, CreateSpeaker, CreateSpeakerFromAppearance, CreatedAppStreamKey, ChargePage, ExportFormat, ClientApp, ClientPolicy, Health, LanguageLists, LedgerPage, LinkProbe, PatchSpeaker, PlanList, PublishGrant, Recording, RecordingEvent, RecordingEvents, RecordingPage, RetranscribeLine, RtmpStatus, SearchResults, VectorResults, SettingsPatch, ShareLink, SharedTranscript, StartRecording, StartJob, SummaryStatus, Tag, TagTranscriptions, Transcription, TranscriptionJob, TranscriptionPage, TranscriptSnapshot, UpdateBroadcast, UpdateTag, UpdateTranscription, UpdateShareLink, UploadRecording, Speaker, VoiceCatalogue, VoiceTrack, ManyResult } from '@vocalstack/contract';
 import { Transport, type CallOptions, type ReadAs } from './http.js';
 import { RealtimeSession, type ConnectOptions } from './realtime.js';
 import { Subscription, type SubscribeOptions } from './subscription.js';
@@ -72,30 +72,7 @@ export declare class Transcriptions extends ParentResource<Transcription, Update
     probe(url: string): Promise<LinkProbe>;
     attachBroadcast(id: string, broadcastId: string): Promise<Transcription>;
     detachBroadcast(id: string, broadcastId: string): Promise<Transcription>;
-}
-export type AddBatchFileInput = Pick<CreateTranscription, 'url' | 'name' | 'startS' | 'endS' | 'durationS'> & {
-    file?: Upload;
-    fileName?: string;
-};
-export declare class Batches {
-    #private;
-    constructor(t: Transport);
-    create(req?: CreateBatch, call?: CallOptions): Promise<Batch>;
-    list(): Promise<Batch[]>;
-    listPage(opts?: PageOptions): Promise<BatchPage>;
-    get(id: string): Promise<Batch>;
-    delete(id: string): Promise<void>;
-    addFile(id: string, req: AddBatchFileInput, call?: CallOptions): Promise<Transcription>;
-    addUrl(id: string, url: string, opts?: Omit<AddBatchFileInput, 'url' | 'file' | 'fileName'>, call?: CallOptions): Promise<Transcription>;
-    start(id: string, call?: CallOptions): Promise<Batch>;
-    export(id: string, format: ExportFormat): Promise<Response>;
-    stop(id: string): Promise<Batch>;
-    wait(id: string, opts?: {
-        intervalMs?: number;
-        timeoutMs?: number;
-        signal?: AbortSignal;
-        onProgress?(batch: Batch): void;
-    }): Promise<Batch>;
+    nameAppearance(id: string, appearance: number, name: string | null): Promise<void>;
 }
 export declare class Recordings {
     #private;
@@ -170,7 +147,6 @@ export declare class Recordings {
         token: string;
         expiresAt: string;
     }>;
-    nameSpeaker(id: string, speaker: number, name: string | null): Promise<void>;
     events(id: string, opts?: {
         after?: number;
         limit?: number;
@@ -237,33 +213,39 @@ export declare class Tags {
     delete(id: string): Promise<void>;
     tagTranscriptions(id: string, req: TagTranscriptions): Promise<Tag>;
 }
-export declare class Voices {
+export declare class Speakers {
     #private;
     constructor(t: Transport);
     list(opts?: {
         lifecycle?: 'active' | 'archived';
-    }): Promise<Voice[]>;
-    get(id: string): Promise<Voice>;
-    archive(id: string): Promise<Voice>;
-    restore(id: string): Promise<Voice>;
+    }): Promise<Speaker[]>;
+    get(id: string): Promise<Speaker>;
+    archive(id: string): Promise<Speaker>;
+    restore(id: string): Promise<Speaker>;
     archiveMany(ids: string[]): Promise<ManyResult>;
     restoreMany(ids: string[]): Promise<ManyResult>;
     deleteMany(ids: string[]): Promise<ManyResult>;
-    create(req: {
-        name: string;
+    create(req: CreateSpeaker & {
         sample?: Upload;
-        sampleUrl?: string;
         fileName?: string;
-        gender?: 'male' | 'female';
-        color?: string;
-        draft?: boolean;
-    }, call?: CallOptions): Promise<Voice>;
-    createFromSpeaker(req: Omit<CreateVoiceFromSpeaker, 'consent'>, call?: CallOptions): Promise<Voice>;
+    }, call?: CallOptions): Promise<Speaker>;
+    createFromAppearance(req: CreateSpeakerFromAppearance, call?: CallOptions): Promise<Speaker>;
     setConsent(id: string, consent: 'granted' | 'refused', opts?: {
         name?: string;
-    }): Promise<Voice>;
-    update(id: string, patch: PatchVoice): Promise<Voice>;
+    }): Promise<Speaker>;
+    update(id: string, patch: PatchSpeaker): Promise<Speaker>;
     delete(id: string): Promise<void>;
+    voicePreview(id: string, opts?: {
+        lang?: string;
+        format?: 'ogg' | 'caf';
+        recording?: string;
+        asOwner?: boolean;
+    } & ReadAs): Promise<Response>;
+    sample(id: string): Promise<Response>;
+}
+export declare class Voices {
+    #private;
+    constructor(t: Transport);
     available(lang: string, opts?: {
         recording?: string;
         asOwner?: boolean;
@@ -271,13 +253,6 @@ export declare class Voices {
     preview(voice: string, lang: string, opts?: {
         format?: 'ogg' | 'caf';
     }): Promise<Response>;
-    clonePreview(id: string, opts?: {
-        lang?: string;
-        format?: 'ogg' | 'caf';
-        recording?: string;
-        asOwner?: boolean;
-    } & ReadAs): Promise<Response>;
-    sample(id: string): Promise<Response>;
 }
 export interface SearchOptions extends Omit<TranscriptionFilters, 'lifecycle' | 'q' | 'broadcast'> {
     broadcasts?: string[];

package/dist/resources.js

@@ -152,71 +152,8 @@ export class Transcriptions extends ParentResource {
     detachBroadcast(id, broadcastId) {
         return this.t.json('DELETE', this.p(id, `/broadcasts/${seg(broadcastId)}`));
     }
-}
-export class Batches {
-    #t;
-    constructor(t) {
-        this.#t = t;
-    }
-    #p(id, rest = '') {
-        return `/v1/batches/${seg(id)}${rest}`;
-    }
-    create(req = {}, call = {}) {
-        return this.#t.json('POST', '/v1/batches', { body: req, ...call });
-    }
-    list() {
-        return allPages(async (cursor) => {
-            const r = await this.listPage({ cursor });
-            return { items: r.batches, nextCursor: r.nextCursor };
-        });
-    }
-    listPage(opts = {}) {
-        return this.#t.json('GET', '/v1/batches', { query: { cursor: opts.cursor, limit: opts.limit } });
-    }
-    get(id) {
-        return this.#t.json('GET', this.#p(id));
-    }
-    async delete(id) {
-        await this.#t.json('DELETE', this.#p(id));
-    }
-    async addFile(id, req, call = {}) {
-        const { file, fileName, ...options } = req;
-        if (file === undefined)
-            return this.#t.json('POST', this.#p(id, '/files'), { body: options, ...call });
-        const { blob, name } = await toBlob(file);
-        const fd = new FormData();
-        fd.append('options', JSON.stringify(options));
-        fd.append('file', blob, fileName ?? name ?? 'upload');
-        return this.#t.json('POST', this.#p(id, '/files'), { body: fd, ...call });
-    }
-    addUrl(id, url, opts = {}, call = {}) {
-        return this.addFile(id, { ...opts, url }, call);
-    }
-    start(id, call = {}) {
-        return this.#t.json('POST', this.#p(id, '/start'), call);
-    }
-    export(id, format) {
-        return this.#t.raw('GET', this.#p(id, '/export'), { headers: { accept: '*/*' }, query: { format } });
-    }
-    stop(id) {
-        return this.#t.json('POST', this.#p(id, '/stop'));
-    }
-    async wait(id, opts = {}) {
-        const interval = opts.intervalMs ?? 5000;
-        const deadline = opts.timeoutMs ? Date.now() + opts.timeoutMs : Infinity;
-        for (;;) {
-            const batch = await this.get(id);
-            opts.onProgress?.(batch);
-            if ((batch.state === 'done' || batch.state === 'stopped') && batch.finishedAt)
-                return batch;
-            if (batch.state === 'open')
-                throw new VocalStackError('invalid_state', 'the batch is open: start it before waiting for it');
-            if (Date.now() + interval > deadline)
-                throw new VocalStackError('timeout', `batch still ${batch.state} after ${opts.timeoutMs} ms`, { retryable: true });
-            if (opts.signal?.aborted)
-                throw opts.signal.reason ?? new Error('aborted');
-            await new Promise((r) => setTimeout(r, interval));
-        }
+    async nameAppearance(id, appearance, name) {
+        await this.t.json('PUT', this.p(id, `/appearances/${seg(appearance)}`), { body: { name } });
     }
 }
 export class Recordings {
@@ -253,6 +190,7 @@ export class Recordings {
             streamUrl: grant.streamUrl,
             readyDeadlineMs: opts.readyDeadlineMs ?? this.#t.opts.readyDeadlineMs,
             onLoading: opts.onLoading,
+            onQueued: opts.onQueued,
             onFrame: opts.onFrame,
         });
     }
@@ -343,9 +281,6 @@ export class Recordings {
     mediaToken(id) {
         return this.#t.json('GET', this.#p(id, '/media-token'));
     }
-    async nameSpeaker(id, speaker, name) {
-        await this.#t.json('PUT', this.#p(id, `/speakers/${seg(speaker)}`), { body: { name } });
-    }
     events(id, opts = {}) {
         return allPages(async (cursor) => {
             const r = await this.eventsPage(id, cursor ? { cursor, limit: opts.limit } : { after: opts.after, limit: opts.limit });
@@ -482,54 +417,70 @@ export class Tags {
         return this.#t.json('POST', `/v1/tags/${seg(id)}/transcriptions`, { body: req });
     }
 }
-export class Voices {
+export class Speakers {
     #t;
     constructor(t) {
         this.#t = t;
     }
     async list(opts = {}) {
-        const r = await this.#t.json('GET', '/v1/voices', { query: { lifecycle: opts.lifecycle } });
-        return r.voices ?? [];
+        const r = await this.#t.json('GET', '/v1/speakers', { query: { lifecycle: opts.lifecycle } });
+        return r.speakers ?? [];
     }
     get(id) {
-        return this.#t.json('GET', `/v1/voices/${seg(id)}`);
+        return this.#t.json('GET', `/v1/speakers/${seg(id)}`);
     }
     archive(id) {
-        return this.#t.json('POST', `/v1/voices/${seg(id)}/archive`);
+        return this.#t.json('POST', `/v1/speakers/${seg(id)}/archive`);
     }
     restore(id) {
-        return this.#t.json('POST', `/v1/voices/${seg(id)}/restore`);
+        return this.#t.json('POST', `/v1/speakers/${seg(id)}/restore`);
     }
     archiveMany(ids) {
-        return this.#t.json('POST', '/v1/voices/archive', { body: { ids } });
+        return this.#t.json('POST', '/v1/speakers/archive', { body: { ids } });
     }
     restoreMany(ids) {
-        return this.#t.json('POST', '/v1/voices/restore', { body: { ids } });
+        return this.#t.json('POST', '/v1/speakers/restore', { body: { ids } });
     }
     deleteMany(ids) {
-        return this.#t.json('POST', '/v1/voices/delete', { body: { ids } });
+        return this.#t.json('POST', '/v1/speakers/delete', { body: { ids } });
     }
     async create(req, call = {}) {
         const { sample, fileName, ...meta } = req;
         const form = new FormData();
-        form.append('meta', JSON.stringify({ consent: !meta.draft, ...meta }));
+        form.append('meta', JSON.stringify(meta));
         if (sample !== undefined) {
             const { blob, name } = await toBlob(sample);
             form.append('sample', blob, fileName ?? name ?? 'sample.webm');
         }
-        return this.#t.json('POST', '/v1/voices', { body: form, ...call });
+        return this.#t.json('POST', '/v1/speakers', { body: form, ...call });
     }
-    createFromSpeaker(req, call = {}) {
-        return this.#t.json('POST', '/v1/voices/from-speaker', { body: { consent: true, ...req }, ...call });
+    createFromAppearance(req, call = {}) {
+        return this.#t.json('POST', '/v1/speakers/from-appearance', { body: req, ...call });
     }
     setConsent(id, consent, opts = {}) {
-        return this.#t.json('POST', `/v1/voices/${seg(id)}/consent`, { body: { consent, ...opts } });
+        return this.#t.json('POST', `/v1/speakers/${seg(id)}/consent`, { body: { consent, ...opts } });
     }
     update(id, patch) {
-        return this.#t.json('PATCH', `/v1/voices/${seg(id)}`, { body: patch });
+        return this.#t.json('PATCH', `/v1/speakers/${seg(id)}`, { body: patch });
     }
     async delete(id) {
-        await this.#t.json('DELETE', `/v1/voices/${seg(id)}`);
+        await this.#t.json('DELETE', `/v1/speakers/${seg(id)}`);
+    }
+    voicePreview(id, opts = {}) {
+        return this.#t.raw('GET', `/v1/speakers/${seg(id)}/preview`, {
+            headers: { accept: '*/*' },
+            query: { ...listenerQuery(opts), lang: opts.lang, format: opts.format, recording: opts.recording },
+            anonymous: opts.asOwner === false,
+        });
+    }
+    sample(id) {
+        return this.#t.raw('GET', `/v1/speakers/${seg(id)}/sample`, { headers: { accept: '*/*' } });
+    }
+}
+export class Voices {
+    #t;
+    constructor(t) {
+        this.#t = t;
     }
     available(lang, opts = {}) {
         return this.#t.json('GET', '/v1/voices/available', {
@@ -540,16 +491,6 @@ export class Voices {
     preview(voice, lang, opts = {}) {
         return this.#t.raw('GET', '/v1/voices/preview', { headers: { accept: '*/*' }, query: { voice, lang, format: opts.format } });
     }
-    clonePreview(id, opts = {}) {
-        return this.#t.raw('GET', `/v1/voices/${seg(id)}/preview`, {
-            headers: { accept: '*/*' },
-            query: { ...listenerQuery(opts), lang: opts.lang, format: opts.format, recording: opts.recording },
-            anonymous: opts.asOwner === false,
-        });
-    }
-    sample(id) {
-        return this.#t.raw('GET', `/v1/voices/${seg(id)}/sample`, { headers: { accept: '*/*' } });
-    }
 }
 export class Search {
     #t;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vocalstack/js-sdk",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.4",
   "description": "VocalStack speech API SDK for Node and browsers: one client (VocalStack) grouped by resource, typed from the generated contract, with realtime WebSocket streaming.",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
-    "@vocalstack/contract": "1.0.0-alpha.2",
+    "@vocalstack/contract": "1.0.0-alpha.4",
     "ws": "^8.18.0"
   },
   "devDependencies": {

package/skills/vocalstack/SKILL.md

@@ -19,9 +19,6 @@ one group per resource: `vs.transcriptions`, `vs.jobs`, `vs.recordings`,
 - A **job** is a file or link recording's transcription work:
   `vs.jobs.wait(recordingId)` polls it until it is `done` or `failed`
   (`{ onProgress: (job) => … }` sees each read: `job.state`, `job.progress.pct`).
-- A **batch** is many files transcribed together for less than one
-  transcription each: `vs.batches.create()`, `addFile`/`addUrl` per file,
-  `start`, then `wait` (section 6).
 - A **broadcast** is a link listeners open to follow a live recording.
 - A **realtime session** (`vs.realtime`) is a socket you stream audio into and
   read the transcript from. Nothing is stored. "Session" means only this.
@@ -189,28 +186,6 @@ 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
-the whole batch. Its files get transcripts, exports and speaker labels (when
-`settings.speakerLabels` asks), never a summary, title, share link or voices.
-
-```js
-import { VocalStack } from '@vocalstack/js-sdk';
-const vs = new VocalStack({ baseUrl: process.env.VOCALSTACK_BASE_URL, apiKey: process.env.VOCALSTACK_API_KEY });
-
-const batch = await vs.batches.create({ name: 'Interviews', settings: { spokenLanguage: 'en' } });
-for (const path of process.argv.slice(2)) await vs.batches.addFile(batch.id, { file: path }); // or addUrl(batch.id, url)
-await vs.batches.start(batch.id);
-const done = await vs.batches.wait(batch.id); // done (or stopped); check done.counts.failed
-for (const tx of done.files ?? []) {
-  if (tx.job?.state !== 'done') continue;
-  const { sentences } = await vs.recordings.transcript(tx.job.recordingId);
-  console.log(tx.name, sentences.map((s) => s.text).join(' '));
-}
-// vs.batches.export(batch.id, 'srt') is every finished transcript in one zip.
-```
-
 ## Errors
 
 A failed call throws `VocalStackError` with `code`, `message`, `status`,
@@ -248,8 +223,7 @@ try {
 - The other groups: `vs.transcriptions` (`list`, `get`, `update`, `archive`,
   `restore`, `purge`, `listShareLinks`, `createShareLink`), `vs.recordings`
   (`get`, `summarize`, `summary`, `translation`, `audioUrl`, `subscribe` for a
-  live transcript feed), `vs.batches` (`create`, `addFile`, `addUrl`, `start`,
-  `wait`, `get`, `list`, `export`, `stop`, `delete`), `vs.corrections`, `vs.shareLinks`, `vs.voices`,
+  live transcript feed), `vs.corrections`, `vs.shareLinks`, `vs.speakers`, `vs.voices`,
   `vs.broadcasts`, `vs.me` (`get`, `usage`), `vs.languages`,
   `vs.rtmp`, `vs.events`, `vs.meta`. Each method is named after its operation
   in the OpenAPI document (`transcriptions.create` is `POST /v1/transcriptions`).