@convbased/sdk 0.1.0

package/dist/cjs/upload.js

@@ -0,0 +1,87 @@
+"use strict";
+// Audio upload helpers shared by TTS (reference voice) and file inference
+// (source audio). Two steps mirror Convbased-Web: ask the GraphQL service for
+// a presigned PUT (`requestAudioUpload`), then PUT the bytes straight to object
+// storage. The returned COS `key` is what you hand to `submitTts` /
+// `startTask`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestAudioUpload = requestAudioUpload;
+exports.putToPresigned = putToPresigned;
+exports.uploadAudio = uploadAudio;
+const graphql_js_1 = require("./graphql.js");
+const REQUEST_AUDIO_UPLOAD = /* GraphQL */ `
+	mutation RequestAudioUpload($input: RequestUploadInput!) {
+		requestAudioUpload(input: $input) {
+			key
+			upload_url
+			method
+			expires_in
+			headers {
+				name
+				value
+			}
+			bucket
+			region
+			url
+		}
+	}
+`;
+/** Ask the service for a presigned PUT for an audio file. */
+async function requestAudioUpload(args) {
+    const data = await (0, graphql_js_1.graphqlRequest)({
+        graphqlUrl: args.graphqlUrl,
+        apiKey: args.apiKey,
+        accessToken: args.accessToken,
+        signal: args.signal,
+        query: REQUEST_AUDIO_UPLOAD,
+        variables: {
+            input: {
+                filename: args.filename,
+                content_type: args.contentType,
+                size: args.size,
+            },
+        },
+    });
+    return data.requestAudioUpload;
+}
+/** PUT raw bytes to a presigned upload target. */
+async function putToPresigned(presigned, body, signal) {
+    const headers = {};
+    for (const h of presigned.headers ?? []) {
+        if (h?.name)
+            headers[h.name] = h.value;
+    }
+    const res = await fetch(presigned.upload_url, {
+        method: presigned.method || "PUT",
+        headers,
+        body: body,
+        signal,
+    });
+    if (!res.ok) {
+        throw new Error(`Audio upload failed: HTTP ${res.status} ${res.statusText}`);
+    }
+}
+/**
+ * Upload an audio `Blob`/`File` end-to-end (presign + PUT) and resolve the COS
+ * `key`. Filename and content type are taken from the `File` when available;
+ * override via `opts` when uploading a bare `Blob`.
+ */
+async function uploadAudio(args) {
+    const maybeFile = args.file;
+    const filename = args.filename ?? maybeFile.name ?? "audio.wav";
+    const contentType = args.contentType ||
+        args.file.type ||
+        "application/octet-stream";
+    const presigned = await requestAudioUpload({
+        graphqlUrl: args.graphqlUrl,
+        apiKey: args.apiKey,
+        accessToken: args.accessToken,
+        signal: args.signal,
+        filename,
+        contentType,
+        size: args.file.size,
+    });
+    await putToPresigned(presigned, args.file, args.signal);
+    return { key: presigned.key };
+}
+//# sourceMappingURL=upload.js.map

package/dist/cjs/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../src/upload.ts"],"names":[],"mappings":";AAAA,0EAA0E;AAC1E,8EAA8E;AAC9E,gFAAgF;AAChF,oEAAoE;AACpE,eAAe;;AA6Cf,gDAwBC;AAGD,wCAoBC;AAOD,kCA4BC;AA7HD,6CAAgE;AAwBhE,MAAM,oBAAoB,GAAG,aAAa,CAAC;;;;;;;;;;;;;;;;CAgB1C,CAAC;AAEF,6DAA6D;AACtD,KAAK,UAAU,kBAAkB,CACvC,IAMC;IAED,MAAM,IAAI,GAAG,MAAM,IAAA,2BAAc,EAA0C;QAC1E,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,oBAAoB;QAC3B,SAAS,EAAE;YACV,KAAK,EAAE;gBACN,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,YAAY,EAAE,IAAI,CAAC,WAAW;gBAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;aACf;SACD;KACD,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,kBAAkB,CAAC;AAChC,CAAC;AAED,kDAAkD;AAC3C,KAAK,UAAU,cAAc,CACnC,SAA0B,EAC1B,IAA0C,EAC1C,MAAoB;IAEpB,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACzC,IAAI,CAAC,EAAE,IAAI;YAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;IACxC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,SAAS,CAAC,UAAU,EAAE;QAC7C,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,KAAK;QACjC,OAAO;QACP,IAAI,EAAE,IAAgB;QACtB,MAAM;KACN,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACd,6BAA6B,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,EAAE,CAC3D,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,WAAW,CAChC,IAMC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,IAAY,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,SAAS,CAAC,IAAI,IAAI,WAAW,CAAC;IAChE,MAAM,WAAW,GAChB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,IAAI,CAAC,IAAI;QACd,0BAA0B,CAAC;IAE5B,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC;QAC1C,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,QAAQ;QACR,WAAW;QACX,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI;KACpB,CAAC,CAAC;IAEH,MAAM,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACxD,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,GAAG,EAAE,CAAC;AAC/B,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,169 @@
+import { TypedEmitter } from "./events.js";
+import { type ConnectionState, type ConnectionStats, type ConnectOptions, type ConvbasedClientOptions, type FileInferencePreferences, type RTCPreferences, type ServerMessageEvent, type TaskStatus } from "./types.js";
+export interface TaskAckEvent {
+    taskId: string;
+    status: "queued" | "started";
+    queuePosition?: number;
+    code?: number;
+}
+export interface TaskProgressEvent {
+    taskId: string;
+    /** Progress in [0, 1]. */
+    progress: number;
+    code?: number;
+}
+export interface TaskFinishedEvent {
+    taskId: string;
+    status: TaskStatus;
+    /** COS key of the converted audio, on success. */
+    resultKey?: string;
+    /** Presigned download URL of the converted audio, on success. */
+    downloadUrl?: string;
+    /** Server-reported error, on failure. */
+    error?: string;
+    code?: number;
+}
+export interface StartTaskOptions {
+    /** COS key of the source audio to convert (upload via `uploadAudio`). */
+    audioKey: string;
+    /** Optional client-supplied task id; one is generated when omitted. */
+    taskId?: string;
+    /** Base name for the generated output file. Default `"output"`. */
+    generateName?: string;
+    /** Output container format. Default `"wav"`. */
+    format?: string;
+    /** Per-task conversion parameters. */
+    preferences?: FileInferencePreferences;
+}
+export interface RunFileInferenceOptions extends Omit<StartTaskOptions, "audioKey"> {
+    /** COS key of an already-uploaded source audio. Provide this or `audio`. */
+    audioKey?: string;
+    /** A source-audio `Blob`/`File` to upload first. Provide this or `audioKey`. */
+    audio?: Blob;
+    /** Give up waiting after this many ms. Default 300_000 (5 min). */
+    timeoutMs?: number;
+    /** Abort the wait (and stop the task). */
+    signal?: AbortSignal;
+    /** Called on `task_progress` frames. */
+    onProgress?: (event: TaskProgressEvent) => void;
+    /** Called on the `task_ack` frame. */
+    onAck?: (event: TaskAckEvent) => void;
+}
+type ClientEvents = {
+    state: {
+        state: ConnectionState;
+        previous: ConnectionState;
+    };
+    message: ServerMessageEvent;
+    ready: {
+        code: number;
+        message?: string;
+    };
+    track: {
+        stream: MediaStream;
+        track: MediaStreamTrack;
+    };
+    error: Error;
+    closed: {
+        code?: number;
+        reason?: string;
+    };
+    taskAck: TaskAckEvent;
+    taskProgress: TaskProgressEvent;
+    taskFinished: TaskFinishedEvent;
+};
+/**
+ * Real-time voice conversion client. Mirrors the flow used by Convbased-Web:
+ *
+ *  1. Open WebSocket to `${signalingUrl}/signaling/ws?api_key=…`.
+ *  2. Capture the microphone (or accept a user-provided `MediaStream`).
+ *  3. Build an `RTCPeerConnection`, attach the mic track, mangle the offer's
+ *     Opus parameters, and send `{type: "offer", sdp, preferences}` over the
+ *     signaling socket.
+ *  4. Apply the `answer` and `ice_candidate` messages from the server, fire
+ *     local ICE candidates back over signaling.
+ *  5. When the server sends `{code: SERVICE_READY}` the processed track is
+ *     emitted via the `track` event — wire it to an `<audio>` element to hear
+ *     converted audio.
+ *
+ * The client is single-use: call `connect()` once, then `disconnect()` to
+ * tear everything down. Create a fresh instance for a new session.
+ */
+export declare class ConvbasedClient extends TypedEmitter<ClientEvents> {
+    private readonly opts;
+    private readonly logger;
+    private state;
+    private signaling;
+    private pc;
+    private localStream;
+    private convertedStream;
+    private serviceReadyTimer;
+    private offerInFlight;
+    constructor(options: ConvbasedClientOptions);
+    getState(): ConnectionState;
+    /** The converted (voice-changed) audio stream returned from the inference node. */
+    getConvertedStream(): MediaStream | null;
+    getPeerConnection(): RTCPeerConnection | null;
+    /**
+     * Open the signaling socket, capture audio, and run WebRTC negotiation.
+     * Resolves when the server emits SERVICE_READY (audio is flowing both ways).
+     * Rejects on auth failures, signaling errors, or negotiation timeouts.
+     */
+    connect(opts: ConnectOptions): Promise<void>;
+    /**
+     * Send a runtime config update to the inference node. Equivalent to the
+     * pitch / formant / RMS sliders in Convbased-Web — only the fields you set
+     * are forwarded.
+     */
+    updateConfig(preferences: Partial<RTCPreferences>): void;
+    /**
+     * Upload a source-audio `Blob`/`File` and resolve its COS key, ready to pass
+     * to `startTask` / `runFileInference`. Requires `graphqlUrl` (the default
+     * production endpoint, or a self-hosted override — not `false`).
+     */
+    uploadAudio(file: Blob, opts?: {
+        filename?: string;
+        contentType?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        key: string;
+    }>;
+    /**
+     * Submit a file-inference task over the signaling channel and return its
+     * task id. The client must be `connected`. Results arrive asynchronously via
+     * the `taskAck` / `taskProgress` / `taskFinished` events — use
+     * `runFileInference` for a promise-based wrapper.
+     */
+    startTask(opts: StartTaskOptions): string;
+    /** Cancel a file-inference task. Omit `taskId` to stop the current one. */
+    stopTask(taskId?: string): void;
+    /**
+     * Promise-based file inference: (optionally upload the source audio,) start
+     * the task, and resolve with the `taskFinished` event on success. Rejects on
+     * task failure/cancellation, timeout, signaling close, or `signal` abort.
+     */
+    runFileInference(opts: RunFileInferenceOptions): Promise<TaskFinishedEvent>;
+    /** Mute / unmute the local mic by toggling the captured audio track. */
+    setMuted(muted: boolean): void;
+    /** Replace the local input stream (mic) with a different `MediaStream` (hot-swap). */
+    replaceLocalStream(newStream: MediaStream): Promise<void>;
+    /** Snapshot of jitter / loss / RTT (sampled from `RTCPeerConnection.getStats`). */
+    getStats(): Promise<ConnectionStats | null>;
+    /** Gracefully end the session — notifies the server, closes the PC. */
+    disconnect(): Promise<void>;
+    private openSignaling;
+    private resolveIceServers;
+    private openPeer;
+    private acquireLocalStream;
+    private waitForServiceReady;
+    private clearServiceReadyTimer;
+    private handleSignalingMessage;
+    private applyAnswer;
+    private applyRemoteCandidate;
+    private handleSignalingClose;
+    private tearDownPeer;
+    private stopTracks;
+    private setState;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAE7B,KAAK,cAAc,EAGnB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,WAAW,CAAC,EAAE,wBAAwB,CAAC;CACvC;AAED,MAAM,WAAW,uBAChB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC;IAC1C,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wCAAwC;IACxC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;CACtC;AAED,KAAK,YAAY,GAAG;IACnB,KAAK,EAAE;QAAE,KAAK,EAAE,eAAe,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,CAAC;IAC7D,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1C,KAAK,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,gBAAgB,CAAA;KAAE,CAAC;IACxD,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,EAAE,iBAAiB,CAAC;IAChC,YAAY,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAgB,SAAQ,YAAY,CAAC,YAAY,CAAC;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAWnB;IACF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0D;IAEjF,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,EAAE,CAAkC;IAC5C,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,eAAe,CAA4B;IACnD,OAAO,CAAC,iBAAiB,CAA8C;IACvE,OAAO,CAAC,aAAa,CAAS;gBAElB,OAAO,EAAE,sBAAsB;IA8B3C,QAAQ,IAAI,eAAe;IAI3B,mFAAmF;IACnF,kBAAkB,IAAI,WAAW,GAAG,IAAI;IAIxC,iBAAiB,IAAI,iBAAiB,GAAG,IAAI;IAI7C;;;;OAIG;IACG,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BlD;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI;IAaxD;;;;OAIG;IACG,WAAW,CAChB,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACtE,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAiB3B;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM;IAwBzC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAO/B;;;;OAIG;IACG,gBAAgB,CACrB,IAAI,EAAE,uBAAuB,GAC3B,OAAO,CAAC,iBAAiB,CAAC;IA+F7B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAK9B,sFAAsF;IAChF,kBAAkB,CAAC,SAAS,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/D,mFAAmF;IAC7E,QAAQ,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAsBjD,uEAAuE;IACjE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YA4BnB,aAAa;YAiBb,iBAAiB;YAoBjB,QAAQ;YAqER,kBAAkB;IAmBhC,OAAO,CAAC,mBAAmB;IAiC3B,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,sBAAsB;YAmHhB,WAAW;YAaX,oBAAoB;IAWlC,OAAO,CAAC,oBAAoB;IAuB5B,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,QAAQ;CAMhB"}