Voice Design

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });
// Access this API via: client.textToVoice

/**
 * Create voice previews from a text prompt
 * @param request - Voice design prompt and output format
 * @param requestOptions - Optional request configuration
 * @returns Voice previews with generated_voice_id and audio samples
 * @throws UnprocessableEntityError if request fails
 */
client.textToVoice.createPreviews(
  request: VoiceDesignRequest,
  requestOptions?: RequestOptions
): HttpResponsePromise<VoiceDesignPreviewResponse>;

interface VoiceDesignRequest {
  /** Output audio format */
  outputFormat?: string;
  /** Text description of desired voice characteristics */
  voiceDescription: string;
  /** Additional voice parameters */
  gender?: "male" | "female" | "neutral";
  age?: "young" | "middle_aged" | "old";
  accent?: string;
  accentStrength?: number;
}

/**
 * @param request - Voice design prompt and settings
 * @param requestOptions - Optional request configuration
 * @returns Voice preview with generated_voice_id
 * @throws UnprocessableEntityError if request fails
 */
client.textToVoice.design(
  request: VoiceDesignRequestModel,
  requestOptions?: RequestOptions
): HttpResponsePromise<VoiceDesignPreviewResponse>;

interface VoiceDesignRequestModel {
  /** Text description of desired voice characteristics */
  text: string;
  /** Voice gender (optional) */
  gender?: "male" | "female" | "neutral";
  /** Voice age (optional) */
  age?: "young" | "middle_aged" | "old";
  /** Voice accent (optional) */
  accent?: string;
  /** Accent strength (0.3 to 2.0) */
  accent_strength?: number;
}

interface VoiceDesignPreviewResponse {
  /** Temporary voice ID for previewing */
  generated_voice_id: string;
  /** Preview audio samples */
  previews: PreviewAudio[];
}

interface PreviewAudio {
  /** Preview audio URL */
  audio_url: string;
  /** Sample text used */
  text: string;
}

/**
 * @param request - Voice name and preview ID
 * @param requestOptions - Optional request configuration
 * @returns Created voice with permanent voice_id
 * @throws UnprocessableEntityError if request fails
 */
client.textToVoice.create(
  request: BodyCreateANewVoiceFromVoicePreviewV1TextToVoicePost,
  requestOptions?: RequestOptions
): HttpResponsePromise<Voice>;

interface BodyCreateANewVoiceFromVoicePreviewV1TextToVoicePost {
  /** Name for the voice */
  voice_name: string;
  /** Generated voice ID from preview */
  generated_voice_id: string;
  /** Voice description */
  voice_description?: string;
  /** Voice labels/tags */
  labels?: Record<string, string>;
}

/**
 * @param voice_id - ID of voice to remix
 * @param request - Remix instructions
 * @param requestOptions - Optional request configuration
 * @returns Remixed voice preview
 * @throws UnprocessableEntityError if request fails
 */
client.textToVoice.remix(
  voice_id: string,
  request: VoiceRemixRequestModel,
  requestOptions?: RequestOptions
): HttpResponsePromise<VoiceDesignPreviewResponse>;

interface VoiceRemixRequestModel {
  /** Text description of desired modifications */
  text: string;
  /** Gender modification (optional) */
  gender?: "male" | "female" | "neutral";
  /** Age modification (optional) */
  age?: "young" | "middle_aged" | "old";
  /** Accent modification (optional) */
  accent?: string;
  /** Accent strength (0.3 to 2.0) */
  accent_strength?: number;
}

/**
 * Stream a voice preview created via design endpoint
 * @param generated_voice_id - Generated voice ID from preview
 * @param requestOptions - Optional request configuration
 * @returns Audio stream
 * @throws UnprocessableEntityError if request fails
 */
client.textToVoice.preview.stream(
  generated_voice_id: string,
  requestOptions?: RequestOptions
): HttpResponsePromise<ReadableStream<Uint8Array>>;

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({ apiKey: "your-api-key" });

// Design a voice from text description
const voiceDesign = await client.textToVoice.design({
  text: "A warm and friendly female voice with a slight British accent, middle-aged, professional but approachable",
  gender: "female",
  age: "middle_aged",
  accent: "british",
  accent_strength: 1.2,
});

console.log("Generated voice ID:", voiceDesign.generated_voice_id);

// Listen to previews
for (const preview of voiceDesign.previews) {
  console.log("Preview text:", preview.text);
  console.log("Preview URL:", preview.audio_url);
}

// After previewing, save the voice to your library
const savedVoice = await client.textToVoice.create({
  voice_name: "Professional British Female",
  generated_voice_id: voiceDesign.generated_voice_id,
  voice_description: "Warm, professional British female voice for corporate content",
  labels: {
    use_case: "corporate",
    accent: "british",
    gender: "female",
  },
});

console.log("Voice saved with ID:", savedVoice.voice_id);

// Now use the voice for text-to-speech
const audio = await client.textToSpeech.convert(savedVoice.voice_id, {
  text: "Welcome to our company presentation.",
});

// Simple voice design with minimal parameters
const maleVoice = await client.textToVoice.design({
  text: "Deep male voice with an American accent",
  gender: "male",
});

const femaleVoice = await client.textToVoice.design({
  text: "Young energetic female voice",
  gender: "female",
  age: "young",
});

// Modify an existing voice
const remixed = await client.textToVoice.remix("original-voice-id", {
  text: "Make the voice sound older and more authoritative",
  age: "old",
});

// Preview the remixed voice
console.log("Remixed voice ID:", remixed.generated_voice_id);

// Save if satisfied
const savedRemix = await client.textToVoice.create({
  voice_name: "Authoritative Variant",
  generated_voice_id: remixed.generated_voice_id,
});

// Stream the pre-generated preview audio
const previewAudio = await client.textToVoice.preview.stream(
  voiceDesign.generated_voice_id
);

// Save preview to file
import { writeFile } from "fs/promises";

const chunks: Uint8Array[] = [];
for await (const chunk of previewAudio) {
  chunks.push(chunk);
}
await writeFile("voice_preview.mp3", Buffer.concat(chunks));

// To hear custom text, save the voice first then use text-to-speech
const savedVoice = await client.textToVoice.create({
  voice_name: "My Designed Voice",
  generated_voice_id: voiceDesign.generated_voice_id,
});

// Now generate audio with custom text
const customAudio = await client.textToSpeech.convert(savedVoice.voice_id, {
  text: "This is a custom preview of the designed voice with any text you want.",
});

// Save to file
const chunks: Uint8Array[] = [];
for await (const chunk of customAudio) {
  chunks.push(chunk);
}
await writeFile("custom_voice_audio.mp3", Buffer.concat(chunks));

// Try different accents for the same voice
const accents = ["british", "american", "australian", "irish"];

for (const accent of accents) {
  const design = await client.textToVoice.design({
    text: `Friendly female voice with ${accent} accent`,
    gender: "female",
    accent,
    accent_strength: 1.5,
  });

  console.log(`${accent} voice:`, design.generated_voice_id);
  // Test each preview...
}

// Design voices for different character types
async function designCharacterVoice(
  characterType: string,
  description: string
): Promise<string> {
  const design = await client.textToVoice.design({
    text: description,
  });

  const voice = await client.textToVoice.create({
    voice_name: characterType,
    generated_voice_id: design.generated_voice_id,
    labels: { character_type: characterType },
  });

  return voice.voice_id;
}

// Create voices for different characters
const heroVoice = await designCharacterVoice(
  "Hero",
  "Strong, confident male voice, brave and determined"
);

const villainVoice = await designCharacterVoice(
  "Villain",
  "Sinister male voice, cold and calculating"
);

const narratorVoice = await designCharacterVoice(
  "Narrator",
  "Warm, storytelling voice with gravitas"
);

// Create age variations of the same base voice
const baseDescription = "Friendly male voice with American accent";

const youngVoice = await client.textToVoice.design({
  text: `${baseDescription}, young and energetic`,
  gender: "male",
  age: "young",
});

const middleAgedVoice = await client.textToVoice.design({
  text: `${baseDescription}, mature and experienced`,
  gender: "male",
  age: "middle_aged",
});

const oldVoice = await client.textToVoice.design({
  text: `${baseDescription}, elderly and wise`,
  gender: "male",
  age: "old",
});

// Create a gallery of professional voices
interface VoiceProfile {
  name: string;
  description: string;
  gender: "male" | "female";
  age: "young" | "middle_aged" | "old";
  accent?: string;
}

const profiles: VoiceProfile[] = [
  {
    name: "Corporate Executive",
    description: "Authoritative, confident, professional",
    gender: "male",
    age: "middle_aged",
    accent: "american",
  },
  {
    name: "Customer Service",
    description: "Friendly, helpful, warm and approachable",
    gender: "female",
    age: "young",
    accent: "american",
  },
  {
    name: "Documentary Narrator",
    description: "Clear, articulate, engaging storyteller",
    gender: "male",
    age: "middle_aged",
    accent: "british",
  },
];

for (const profile of profiles) {
  const design = await client.textToVoice.design({
    text: profile.description,
    gender: profile.gender,
    age: profile.age,
    accent: profile.accent,
  });

  const voice = await client.textToVoice.create({
    voice_name: profile.name,
    generated_voice_id: design.generated_voice_id,
    voice_description: profile.description,
  });

  console.log(`Created ${profile.name}:`, voice.voice_id);
}

// Iteratively refine voice design
async function refineVoiceDesign(
  initialDescription: string,
  iterations: string[]
): Promise<string> {
  // Start with initial design
  let currentDesign = await client.textToVoice.design({
    text: initialDescription,
  });

  console.log("Initial design:", currentDesign.generated_voice_id);

  // Apply refinements
  for (const refinement of iterations) {
    // Save current design
    const tempVoice = await client.textToVoice.create({
      voice_name: `Temp ${Date.now()}`,
      generated_voice_id: currentDesign.generated_voice_id,
    });

    // Remix with refinement
    currentDesign = await client.textToVoice.remix(tempVoice.voice_id, {
      text: refinement,
    });

    console.log("After refinement:", refinement);
  }

  // Save final version
  const finalVoice = await client.textToVoice.create({
    voice_name: "Refined Voice",
    generated_voice_id: currentDesign.generated_voice_id,
  });

  return finalVoice.voice_id;
}

const voiceId = await refineVoiceDesign(
  "Casual male voice",
  [
    "Make it more professional",
    "Add a slight British accent",
    "Make it sound more authoritative",
  ]
);