@supertone/supertone 0.1.0

package/examples/custom_voices/edit_custom_voice.ts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Example: Edit Custom Voice
+ *
+ * This example demonstrates how to update a custom voice's name and description.
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+const CUSTOM_VOICE_ID =
+	process.env.CUSTOM_VOICE_ID || "your-custom-voice-id-here";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	if (CUSTOM_VOICE_ID === "your-custom-voice-id-here") {
+		console.error("❌ Please set CUSTOM_VOICE_ID in .env");
+		console.error("   Run list_custom_voices.ts to get voice IDs");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		// New metadata
+		const timestamp = new Date().toLocaleString();
+		const newName = `Updated Voice ${timestamp}`;
+		const newDescription = `Voice updated at ${timestamp}`;
+
+		console.log("✏️  Updating custom voice...");
+		console.log(`   Voice ID: ${CUSTOM_VOICE_ID}`);
+		console.log(`   New name: ${newName}`);
+		console.log(`   New description: ${newDescription}`);
+
+		// Edit custom voice
+		const response = await client.customVoices.editCustomVoice({
+			voiceId: CUSTOM_VOICE_ID,
+			updateClonedVoiceRequest: {
+				name: newName,
+				description: newDescription,
+			},
+		});
+
+		// Display results
+		console.log("\n✅ Custom voice updated successfully!");
+		console.log(`   Name: ${response.name}`);
+		console.log(`   Description: ${response.description}`);
+
+		console.log("\n💡 Verify changes:");
+		console.log(`   npx tsx examples/custom_voices/get_custom_voice.ts`);
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/custom_voices/get_custom_voice.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Example: Get Custom Voice Details
+ *
+ * This example demonstrates how to retrieve detailed information about a custom voice.
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+const CUSTOM_VOICE_ID =
+	process.env.CUSTOM_VOICE_ID || "your-custom-voice-id-here";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	if (CUSTOM_VOICE_ID === "your-custom-voice-id-here") {
+		console.error("❌ Please set CUSTOM_VOICE_ID in .env");
+		console.error("   Run list_custom_voices.ts to get voice IDs");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		console.log(`🔍 Fetching custom voice details...`);
+		console.log(`   Voice ID: ${CUSTOM_VOICE_ID}`);
+
+		// Get custom voice details
+		const response = await client.customVoices.getCustomVoice({
+			voiceId: CUSTOM_VOICE_ID,
+		});
+
+		// Display results
+		console.log("\n✅ Custom Voice Details:");
+		console.log(`   Name: ${response.name}`);
+		console.log(`   ID: ${response.voiceId}`);
+		console.log(`   Description: ${response.description || "No description"}`);
+
+		console.log("\n💡 Use this voice in TTS examples:");
+		console.log(
+			`   VOICE_ID=${response.voiceId} npx tsx examples/text_to_speech/create_speech.ts`
+		);
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+
+		if (error.message.includes("404") || error.message.includes("not found")) {
+			console.error("\n💡 Voice ID not found. Try:");
+			console.error("   npx tsx examples/custom_voices/list_custom_voices.ts");
+		}
+
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/custom_voices/list_custom_voices.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Example: List Custom Voices
+ *
+ * This example demonstrates how to list your custom cloned voices.
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		console.log("🎨 Fetching custom voice list...");
+
+		// List custom voices
+		const response = await client.customVoices.listCustomVoices({
+			pageSize: 10,
+		});
+
+		// Display results
+		console.log("\n✅ Custom Voice List Retrieved:");
+		console.log(`   Total custom voices: ${response.total}`);
+		console.log(`   Showing: ${response.items?.length || 0} voices`);
+
+		if (response.items && response.items.length > 0) {
+			console.log("\n🎤 Your Custom Voices:");
+			for (const voice of response.items) {
+				console.log(`\n   ${voice.name}`);
+				console.log(`      ID: ${voice.voiceId}`);
+				console.log(
+					`      Description: ${voice.description || "No description"}`
+				);
+			}
+
+			// Save first voice ID for use in other examples
+			const firstVoiceId = response.items[0]?.voiceId;
+			if (firstVoiceId) {
+				console.log(
+					`\n💡 Tip: Use custom voice ID "${firstVoiceId}" in TTS examples`
+				);
+			}
+		} else {
+			console.log("\n📝 No custom voices found");
+			console.log("   💡 Create a custom voice using create_cloned_voice.ts");
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/custom_voices/search_custom_voices.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Example: Search Custom Voices
+ *
+ * This example demonstrates how to search for custom voices by name.
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+
+// Search query (can be partial name)
+const SEARCH_QUERY = process.env.SEARCH_QUERY || "Custom";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		console.log(`🔍 Searching for custom voices...`);
+		console.log(`   Query: "${SEARCH_QUERY}"`);
+
+		// Search custom voices
+		const response = await client.customVoices.searchCustomVoices({
+			name: SEARCH_QUERY,
+			pageSize: 10,
+		});
+
+		// Display results
+		console.log("\n✅ Search Results:");
+		console.log(`   Found: ${response.items?.length || 0} matching voices`);
+
+		if (response.items && response.items.length > 0) {
+			console.log("\n🎤 Matching Custom Voices:");
+			for (const voice of response.items) {
+				console.log(`\n   ${voice.name}`);
+				console.log(`      ID: ${voice.voiceId}`);
+				console.log(
+					`      Description: ${voice.description || "No description"}`
+				);
+			}
+
+			// Save first voice ID for use in other examples
+			const firstVoiceId = response.items[0]?.voiceId;
+			if (firstVoiceId) {
+				console.log(`\n💡 Use this voice:`);
+				console.log(
+					`   CUSTOM_VOICE_ID=${firstVoiceId} npx tsx examples/custom_voices/get_custom_voice.ts`
+				);
+			}
+		} else {
+			console.log("\n📝 No custom voices found matching the query");
+			console.log(`   💡 Try different search terms or create a new voice`);
+		}
+
+		console.log(`\n💡 Tip: Change search query with:`);
+		console.log(
+			`   SEARCH_QUERY="your-query" npx tsx examples/custom_voices/search_custom_voices.ts`
+		);
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "supertone-examples",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build:parent": "cd .. && npm i && npm run build && cd -",
+    "build:examples": "npm i",
+    "build": "npm run build:parent && npm run build:examples"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "dotenv": "^16.4.5",
+    "tsx": "^4.19.2"
+  },
+  "dependencies": {
+    "supertone": "file:.."
+  }
+}

package/examples/textToSpeechCreateSpeech.example.ts

@@ -0,0 +1,32 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import dotenv from "dotenv";
+dotenv.config();
+/**
+ * Example usage of the supertone SDK
+ *
+ * To run this example from the examples directory:
+ * npm run build && npx tsx textToSpeechCreateSpeech.example.ts
+ */
+
+import { Supertone } from "supertone";
+
+const supertone = new Supertone({
+  apiKey: "<YOUR_API_KEY_HERE>",
+});
+
+async function main() {
+  const result = await supertone.createSpeech({
+    voiceId: "<id>",
+    apiConvertTextToSpeechUsingCharacterRequest: {
+      text: "<value>",
+      language: "ja",
+    },
+  });
+
+  console.log(result);
+}
+
+main().catch(console.error);

package/examples/text_to_speech/create_speech.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Example: Basic Text-to-Speech Conversion
+ *
+ * This example demonstrates how to convert text to speech and save it as an audio file.
+ * ⚠️ This consumes API credits!
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as models from "../../src/models/index.js";
+import * as fs from "fs";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+const VOICE_ID = process.env.VOICE_ID || "your-voice-id-here";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	if (VOICE_ID === "your-voice-id-here") {
+		console.error("❌ Please set VOICE_ID in .env or run list_voices.ts first");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		const text = "Hello! This is a test of the Supertone text-to-speech API.";
+		console.log("🎤 Creating speech...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log(`   Format: WAV`);
+		console.log("   ⚠️ This will consume credits!");
+
+		// Create speech
+		const response = await client.textToSpeech.createSpeech({
+			voiceId: VOICE_ID,
+			apiConvertTextToSpeechUsingCharacterRequest: {
+				text: text,
+				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+				outputFormat:
+					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+				style: "neutral",
+				model: "sona_speech_1",
+			},
+		});
+
+		// Save the audio file
+		if (response.result) {
+			const outputFile = "output_speech.wav";
+
+			// Handle different response types
+			if (response.result instanceof Uint8Array) {
+				fs.writeFileSync(outputFile, response.result);
+			} else if (
+				typeof response.result === "object" &&
+				"getReader" in response.result
+			) {
+				// ReadableStream
+				const reader = (
+					response.result as ReadableStream<Uint8Array>
+				).getReader();
+				const chunks: Uint8Array[] = [];
+
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					if (value) chunks.push(value);
+				}
+
+				const audioData = Buffer.concat(chunks);
+				fs.writeFileSync(outputFile, audioData);
+			}
+
+			console.log(`\n✅ Speech created successfully!`);
+			console.log(`   💾 Saved to: ${outputFile}`);
+			console.log(`   📊 File size: ${fs.statSync(outputFile).size} bytes`);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/create_speech_long_text.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Example: TTS with Long Text (Auto-Chunking)
+ *
+ * This example demonstrates how the SDK automatically handles long text (300+ chars)
+ * by chunking and merging audio seamlessly.
+ * ⚠️ This consumes API credits!
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as models from "../../src/models/index.js";
+import * as fs from "fs";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+const VOICE_ID = process.env.VOICE_ID || "your-voice-id-here";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	if (VOICE_ID === "your-voice-id-here") {
+		console.error("❌ Please set VOICE_ID in .env or run list_voices.ts first");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		// Long text (400+ characters)
+		const longText = `
+    Real-time streaming text-to-speech technology plays a crucial role in modern AI applications.
+    It is an indispensable technology especially in conversational services, live broadcasting, and real-time translation services.
+    Through the auto-chunking feature, long texts are naturally divided into multiple small segments for processing.
+    Each segment is intelligently segmented considering sentence and word boundaries, enabling natural speech generation.
+    Now users don't need to worry about text length, as the SDK automatically handles everything seamlessly.
+    `.trim();
+
+		console.log("🎤 Creating speech with auto-chunking...");
+		console.log(`   Text length: ${longText.length} characters (exceeds 300)`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log("   ✨ SDK will automatically chunk and merge");
+		console.log("   ⚠️  This will consume credits!");
+
+		// Create speech - SDK handles chunking automatically
+		const response = await client.textToSpeech.createSpeech({
+			voiceId: VOICE_ID,
+			apiConvertTextToSpeechUsingCharacterRequest: {
+				text: longText,
+				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+				outputFormat:
+					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+				style: "neutral",
+				model: "sona_speech_1",
+			},
+		});
+
+		// Save the audio file
+		if (response.result) {
+			const outputFile = "output_long_text_speech.wav";
+
+			// Handle ReadableStream response
+			if (
+				typeof response.result === "object" &&
+				"getReader" in response.result
+			) {
+				const reader = (
+					response.result as ReadableStream<Uint8Array>
+				).getReader();
+				const chunks: Uint8Array[] = [];
+
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					if (value) chunks.push(value);
+				}
+
+				const audioData = Buffer.concat(chunks);
+				fs.writeFileSync(outputFile, audioData);
+			}
+
+			console.log(`\n✅ Long text speech created successfully!`);
+			console.log(`   💾 Saved to: ${outputFile}`);
+			console.log(`   📊 File size: ${fs.statSync(outputFile).size} bytes`);
+			console.log(`   🎯 Text was automatically chunked and audio merged!`);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/create_speech_with_phonemes.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Example: TTS with Phoneme Information
+ *
+ * This example demonstrates how to get phoneme timing data along with audio.
+ * Useful for lip-sync animation, subtitles, and speech analysis.
+ * ⚠️ This consumes API credits!
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as models from "../../src/models/index.js";
+import * as fs from "fs";
+import * as dotenv from "dotenv";
+import * as path from "path";
+import { fileURLToPath } from "url";
+
+// Load environment variables
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+dotenv.config({ path: path.join(__dirname, "../.env") });
+
+const API_KEY = process.env.SUPERTONE_API_KEY;
+const VOICE_ID = process.env.VOICE_ID || "your-voice-id-here";
+
+async function main() {
+	if (!API_KEY) {
+		console.error("❌ SUPERTONE_API_KEY not found in .env file");
+		process.exit(1);
+	}
+
+	if (VOICE_ID === "your-voice-id-here") {
+		console.error("❌ Please set VOICE_ID in .env or run list_voices.ts first");
+		process.exit(1);
+	}
+
+	try {
+		// Initialize the client
+		const client = new Supertone({ apiKey: API_KEY });
+
+		const text = "Hello world! This is a phoneme timing test.";
+		console.log("🔤 Creating speech with phoneme data...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log("   ⚠️  This will consume credits!");
+
+		// Create speech with phonemes
+		const response = await client.textToSpeech.createSpeech({
+			voiceId: VOICE_ID,
+			apiConvertTextToSpeechUsingCharacterRequest: {
+				text: text,
+				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+				outputFormat:
+					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+				style: "neutral",
+				model: "sona_speech_1",
+				includePhonemes: true, // Request phoneme data
+			},
+		});
+
+		// Handle response with phonemes
+		if (response.result) {
+			if (
+				typeof response.result === "object" &&
+				"audioBase64" in response.result
+			) {
+				// Response includes both audio and phonemes
+				const result = response.result as any;
+
+				// Decode and save audio
+				const audioBase64 = result.audioBase64;
+				const binaryString = atob(audioBase64);
+				const bytes = new Uint8Array(binaryString.length);
+				for (let i = 0; i < binaryString.length; i++) {
+					bytes[i] = binaryString.charCodeAt(i);
+				}
+
+				const audioFile = "output_with_phonemes.wav";
+				fs.writeFileSync(audioFile, bytes);
+				console.log(`\n✅ Speech with phonemes created!`);
+				console.log(`   💾 Audio saved to: ${audioFile}`);
+
+				// Display phoneme data
+				if (result.phonemes) {
+					const phonemes = result.phonemes;
+					console.log(`\n📊 Phoneme Data:`);
+					console.log(`   Symbols count: ${phonemes.symbols?.length || 0}`);
+					console.log(
+						`   Durations count: ${phonemes.durations_seconds?.length || 0}`
+					);
+					console.log(
+						`   Start times count: ${phonemes.start_times_seconds?.length || 0}`
+					);
+
+					if (phonemes.symbols && phonemes.symbols.length > 0) {
+						console.log(`\n   First 10 phonemes:`);
+						for (let i = 0; i < Math.min(10, phonemes.symbols.length); i++) {
+							const symbol = phonemes.symbols[i];
+							const duration = phonemes.durations_seconds?.[i];
+							const startTime = phonemes.start_times_seconds?.[i];
+							console.log(
+								`      [${i}] "${symbol}" - start: ${startTime?.toFixed(
+									3
+								)}s, duration: ${duration?.toFixed(3)}s`
+							);
+						}
+					}
+
+					// Save phoneme data to JSON
+					const phonemeFile = "phoneme_data.json";
+					fs.writeFileSync(phonemeFile, JSON.stringify(phonemes, null, 2));
+					console.log(`\n   💾 Phoneme data saved to: ${phonemeFile}`);
+				}
+			}
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+