voicekit-client 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 Official TypeScript/JavaScript wrapper for [VoiceKit](https://ttsapi.ru):
 neural speech synthesis, transcription, sentiment analysis, and batch operations.
 
-Zero runtime dependencies. Requires Node.js 18+ (global `fetch`).
+Requires Node.js 18+ (global `fetch`). WebSocket streaming uses the `ws` package.
 
 ## Install
 
@@ -96,6 +96,23 @@ const fxFile = await client.downloadAudioEffects(fxJob.job_id);
 await writeFile("voice_fx.mp3", fxFile);
 ```
 
+### Audio cleaning (Pro/Business)
+
+```js
+// Denoise + normalize an existing file as a background job
+const cleanJob = await client.cleanAudio("noisy.wav");     // one-click preset
+// or with options:
+// const cleanJob = await client.cleanAudio("noisy.wav", { options: { denoise: { strength: 0.8 } } });
+
+let cleanResult = await client.getAudioCleaningJob(cleanJob.job_id);
+while (!["completed", "failed"].includes(cleanResult.status)) {
+  await new Promise(r => setTimeout(r, 1000));
+  cleanResult = await client.getAudioCleaningJob(cleanJob.job_id);
+}
+const cleanFile = await client.downloadAudioCleaning(cleanJob.job_id);
+await writeFile("voice_clean.wav", cleanFile);
+```
+
 ### WebSocket streaming (Pro/Business)
 
 ```js
@@ -117,6 +134,25 @@ for await (const event of vad.events()) {
 vad.close();
 ```
 
+### Voice ID (Pro/Business)
+
+```js
+// Voice passport: language, gender, age, emotion, speaker embedding, AI-vs-human
+const passport = await client.voiceId("recording.wav");
+
+// Voice biometrics on your own profiles
+const profile = await client.enrollVoice("speaker.wav", "Alice");  // { profile_id: "voice_…" }
+
+const check = await client.verifyVoice("check.wav", profile.profile_id);
+// { profile_id: "voice_…", similarity: 0.81, verified: true, threshold: 0.7 }
+
+const match = await client.identifyVoice("check.wav");            // 1:N across your profiles
+// { best_match: {…}, matches: […], threshold: 0.7 }
+
+const profiles = await client.listVoiceProfiles();
+await client.deleteVoiceProfile(profile.profile_id);
+```
+
 ## Configuration
 
 | Option | Default | Description |

package/index.d.ts

@@ -35,6 +35,12 @@ export class VoiceKitClient {
   getTranscriptionJob(jobId: string): Promise<Record<string, unknown>>;
   subtitles(jobId: string, format?: "vtt" | "srt"): Promise<string>;
   vad(audio: AudioSource): Promise<Record<string, unknown>>;
+  voiceId(audio: AudioSource): Promise<VoiceIdResult>;
+  enrollVoice(audio: AudioSource, name?: string): Promise<Record<string, unknown>>;
+  verifyVoice(audio: AudioSource, profileId: string): Promise<VoiceVerificationResult>;
+  identifyVoice(audio: AudioSource, profileIds?: string[]): Promise<VoiceIdentificationResult>;
+  listVoiceProfiles(): Promise<Array<Record<string, unknown>>>;
+  deleteVoiceProfile(profileId: string): Promise<void>;
 
   analyze(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
   analyzeSync(audio: AudioSource, opts?: AudioOptions): Promise<Record<string, unknown>>;
@@ -67,6 +73,13 @@ export class VoiceKitClient {
   getVideoEffectsJob(jobId: string): Promise<Record<string, unknown>>;
   downloadVideoEffects(jobId: string): Promise<Uint8Array>;
 
+  cleanAudio(
+    audio: AudioSource,
+    opts?: AudioCleaningOptions,
+  ): Promise<Record<string, unknown>>;
+  getAudioCleaningJob(jobId: string): Promise<Record<string, unknown>>;
+  downloadAudioCleaning(jobId: string): Promise<Uint8Array>;
+
   batchSynthesize(items: Array<Record<string, unknown>>): Promise<Record<string, unknown>>;
   batchAnalyze(items: Array<Record<string, unknown>>): Promise<Record<string, unknown>>;
   getBatch(batchId: string): Promise<Record<string, unknown>>;
@@ -106,6 +119,56 @@ export interface VideoEffectsOptions {
   webhookUrl?: string;
 }
 
+export interface AudioCleaningOptions {
+  options?: Record<string, unknown>;
+  outputFormat?: "wav" | "mp3" | "ogg";
+  webhookUrl?: string;
+}
+
+export interface VoiceIdResult {
+  language: string;
+  language_confidence: number;
+  duration_seconds: number;
+  speech_ratio: number;
+  gender: string;
+  gender_confidence: number;
+  age_group: string;
+  age_confidence: number;
+  emotional_background: string;
+  emotions?: Record<string, number>;
+  ai_probability?: number;
+  fake_detection_available: boolean;
+  speaker_embedding?: number[];
+  nearest_voices: VoiceIdMatch[];
+  processing_time_ms: number;
+}
+
+export interface VoiceIdMatch {
+  voice_id: string;
+  similarity: number;
+}
+
+export interface VoiceVerificationResult {
+  profile_id: string;
+  similarity: number;
+  verified: boolean;
+  threshold: number;
+}
+
+export interface VoiceIdentificationResult {
+  best_match?: VoiceIdMatch;
+  matches: VoiceIdMatch[];
+  threshold: number;
+}
+
+export interface VoiceProfile {
+  profile_id: string;
+  name: string;
+  source: string;
+  clone_voice_id?: string;
+  created_at: string;
+}
+
 export interface SynthesisAsyncOptions {
   voice?: string;
   format?: "wav";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voicekit-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TypeScript/JavaScript SDK for VoiceKit (synthesis, transcription, analysis, moderation, batches).",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,7 +1,7 @@
 /**
  * Official JavaScript/TypeScript SDK for VoiceKit.
  *
- * Requires Node.js 18+ (global `fetch`, web streams). Zero runtime dependencies.
+ * Requires Node.js 18+ (global `fetch`, web streams). WebSocket streaming uses the `ws` package.
  *
  * @example
  * import { VoiceKitClient } from "voicekit-client";
@@ -227,6 +227,67 @@ export class VoiceKitClient {
     return this.#postForm("/v1/vad", audio, {});
   }
 
+  /**
+   * Analyze a voice recording and return a voice passport (language, gender,
+   * age group, emotional background, speaker embedding and an AI-vs-human
+   * probability — beta, null when the detector is not configured).
+   * @param {AudioSource} audio
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  voiceId(audio) {
+    return this.#postForm("/v1/voice-id", audio, {});
+  }
+
+  /**
+   * Enroll an audio clip as a reusable voice profile (voiceprint).
+   * @param {AudioSource} audio
+   * @param {string} [name]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  enrollVoice(audio, name) {
+    return this.#postForm("/v1/voice-id/enroll", audio, { name });
+  }
+
+  /**
+   * Verify an audio clip against an enrolled profile (1:1).
+   * @param {AudioSource} audio
+   * @param {string} profileId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  verifyVoice(audio, profileId) {
+    return this.#postForm("/v1/voice-id/verify", audio, { profile_id: profileId });
+  }
+
+  /**
+   * Identify the closest matching profile for an audio clip (1:N).
+   * @param {AudioSource} audio
+   * @param {string[]} [profileIds]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  identifyVoice(audio, profileIds) {
+    const data = profileIds && profileIds.length
+      ? { profile_ids: profileIds.join(",") }
+      : {};
+    return this.#postForm("/v1/voice-id/identify", audio, data);
+  }
+
+  /**
+   * List the caller's enrolled voice profiles.
+   * @returns {Promise<Array<Record<string, unknown>>>}
+   */
+  listVoiceProfiles() {
+    return this.#getJson("/v1/voice-id/profiles");
+  }
+
+  /**
+   * Delete an enrolled voice profile by id.
+   * @param {string} profileId
+   * @returns {Promise<void>}
+   */
+  async deleteVoiceProfile(profileId) {
+    await this.#request(`/v1/voice-id/profiles/${profileId}`, { method: "DELETE" });
+  }
+
   // ──────────────────────── Analysis ─────────────────────────────────
 
   /**
@@ -375,6 +436,46 @@ export class VoiceKitClient {
     return new Uint8Array(await response.arrayBuffer());
   }
 
+  // ──────────────────────── Audio cleaning ───────────────────────────
+
+  /**
+   * Start an async audio-cleaning job; poll with `getAudioCleaningJob()`.
+   * With no `options` the one-click preset (denoise + normalize) is applied.
+   * @param {AudioSource} audio
+   * @param {{ options?: Record<string, unknown>, outputFormat?: string, webhookUrl?: string }} [opts]
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  async cleanAudio(audio, opts = {}) {
+    const { options, outputFormat = "wav", webhookUrl } = opts;
+    const { data, filename } = await audioToParts(audio);
+    const form = new FormData();
+    form.append("audio", new Blob([data], { type: "audio/wav" }), filename);
+    form.append("output_format", outputFormat);
+    if (options) form.append("options", JSON.stringify(options));
+    const query = webhookUrl ? `?webhookUrl=${encodeURIComponent(webhookUrl)}` : "";
+    const response = await this.#request(`/v1/audio/clean${query}`, { method: "POST", form });
+    return response.json();
+  }
+
+  /**
+   * Poll an audio-cleaning job; returns the manifest when completed.
+   * @param {string} jobId
+   * @returns {Promise<Record<string, unknown>>}
+   */
+  getAudioCleaningJob(jobId) {
+    return this.#getJson(`/v1/audio/clean/${jobId}`);
+  }
+
+  /**
+   * Download the cleaned audio for a completed audio-cleaning job.
+   * @param {string} jobId
+   * @returns {Promise<Uint8Array>}
+   */
+  async downloadAudioCleaning(jobId) {
+    const response = await this.#request(`/v1/audio/clean/${jobId}/audio`);
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
   // ──────────────────────── Batch ────────────────────────────────────
 
   /**