sonuslab

Official SonusLab SDK for audio clipping, text-to-speech, and voice cloning.

Install

npm install sonuslab
# or
pnpm add sonuslab
# or
bun add sonuslab

Requires Node.js 18+.

Quickstart

import { SonusLab } from "sonuslab";

const sonus = new SonusLab(process.env.SONUSLAB_API_KEY!);
// or with custom base URL:
// const sonus = new SonusLab({ apiKey: "...", baseUrl: "https://api.sonuslab.dev" });

Every call returns a discriminated Result. Narrow by checking error first — when error is non-null, the named data key is null, and vice versa.

const { clips, error } = await sonus.clips.list();
if (error) throw error;
console.log(clips.items);

Clips

Create and manage audio clips extracted from source media (e.g. YouTube URLs).

// Inspect a source URL before clipping
const { metadata, error } = await sonus.clips.getMetadata({
  url: "https://www.youtube.com/watch?v=...",
});

// Create a clip
const { clip } = await sonus.clips.create({
  url: "https://www.youtube.com/watch?v=...",
  start: 12.5,
  end: 24.0,
  name: "intro-hook",
});

// List, get, delete
const { clips } = await sonus.clips.list({ limit: 20 });
const { clip: one } = await sonus.clips.get("clip_123");
const { ok } = await sonus.clips.delete("clip_123");

Text-to-Speech

Generate speech with ElevenLabs or Fish providers.

const { sound, error } = await sonus.tts.generate({
  provider: "elevenlabs",
  voiceId: "voice_abc",
  text: "Hello from SonusLab.",
  modelId: "eleven_multilingual_v2",
  stability: 0.5,
  similarityBoost: 0.75,
});

// List available ElevenLabs voices
const { voices } = await sonus.tts.listVoices();

Voice Cloning

Clone a voice from an audio sample URL.

// Step 1: prepare and preview a sample
const { sample } = await sonus.voices.prepareSample({
  url: "https://example.com/sample.mp3",
});

// Step 2: create the voice clone
const { voice } = await sonus.voices.create({
  name: "my-voice",
  audio: sample!.audio,
  format: sample!.format,
  sampleRate: sample!.sampleRate,
});

// Manage clones
const { voices } = await sonus.voices.list();
const { ok } = await sonus.voices.delete("voice_123");

Error Handling

Failed requests resolve with error: SonusLabError — the promise does not reject.

import { SonusLabError } from "sonuslab";

const { clip, error } = await sonus.clips.get("missing");
if (error) {
  // error.status, error.body, error.message
  if (error.status === 404) {
    // handle not found
  }
  throw error;
}

Transient failures (408, 429, 5xx) retry automatically up to 2 times.

Cancellation

All methods accept an AbortSignal via the second argument:

const ac = new AbortController();
const promise = sonus.clips.list(undefined, { signal: ac.signal });
ac.abort();

License

MIT