@supertone/supertone 0.1.0

package/examples/text_to_speech/create_speech_with_voice_settings.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Example: TTS with Custom Voice Settings
+ *
+ * This example demonstrates how to adjust pitch, speed, and variance.
+ * ⚠️ 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 voice settings test. You can hear the adjusted pitch and speed.";
+
+		// Custom voice settings
+		const voiceSettings = {
+			pitchShift: 0.95, // Lower pitch (0.5 to 1.5)
+			pitchVariance: 1.1, // More variation (0.5 to 1.5)
+			speed: 0.9, // Slower speed (0.5 to 2.0)
+		};
+
+		console.log("🎛️  Creating speech with custom voice settings...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log(`   Settings:`);
+		console.log(`      Pitch shift: ${voiceSettings.pitchShift}`);
+		console.log(`      Pitch variance: ${voiceSettings.pitchVariance}`);
+		console.log(`      Speed: ${voiceSettings.speed}`);
+		console.log("   ⚠️  This will consume credits!");
+
+		// Create speech with voice settings
+		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",
+				voiceSettings: voiceSettings, // Apply custom settings
+			},
+		});
+
+		// Save the audio file
+		if (response.result) {
+			const outputFile = "output_with_voice_settings.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✅ Speech with voice settings created!`);
+			console.log(`   💾 Saved to: ${outputFile}`);
+			console.log(`   📊 File size: ${fs.statSync(outputFile).size} bytes`);
+			console.log(`   🎯 Listen to hear the customized voice!`);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/predict_duration.ts

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Example: Predict TTS Duration
+ *
+ * This example demonstrates how to predict audio duration without generating audio.
+ * Useful for resource planning and UI pre-calculations.
+ */
+
+import { Supertone } from "../../src/index.js";
+import * as models from "../../src/models/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 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 message for duration prediction. How long will this take?";
+		console.log("⏱️  Predicting TTS duration...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+
+		// Predict duration
+		const response = await client.textToSpeech.predictDuration({
+			voiceId: VOICE_ID,
+			predictTTSDurationUsingCharacterRequest: {
+				text: text,
+				language: models.PredictTTSDurationUsingCharacterRequestLanguage.En,
+			},
+		});
+
+		// Display result
+		console.log(`\n✅ Prediction complete!`);
+		console.log(`   📊 Estimated duration: ${response.duration} seconds`);
+		console.log(`   💡 This did NOT consume TTS credits (prediction only)`);
+
+		// Calculate additional info
+		const minutes = Math.floor(response.duration / 60);
+		const seconds = (response.duration % 60).toFixed(1);
+		console.log(`   📊 Formatted: ${minutes}m ${seconds}s`);
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/stream_speech.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * Example: Streaming Text-to-Speech
+ *
+ * This example demonstrates real-time streaming TTS for progressive playback.
+ * Useful for real-time applications where you want audio to start immediately.
+ * ⚠️ 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 =
+			"This is a streaming test. Audio chunks arrive progressively for real-time playback.";
+		console.log("📡 Starting streaming TTS...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log("   ⚠️  This will consume credits!");
+
+		// Stream speech
+		const response = await client.textToSpeech.streamSpeech({
+			voiceId: VOICE_ID,
+			apiConvertTextToSpeechUsingCharacterRequest: {
+				text: text,
+				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+				outputFormat:
+					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+				style: "neutral",
+				model: "sona_speech_1",
+			},
+		});
+
+		console.log("\n✅ Stream started!");
+		console.log("   📦 Receiving audio chunks...\n");
+
+		// Process streaming response
+		if (
+			response.result &&
+			typeof response.result === "object" &&
+			"getReader" in response.result
+		) {
+			const reader = (
+				response.result as ReadableStream<Uint8Array>
+			).getReader();
+			const chunks: Uint8Array[] = [];
+			let chunkCount = 0;
+			let totalBytes = 0;
+
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+
+				if (value) {
+					chunks.push(value);
+					chunkCount++;
+					totalBytes += value.length;
+
+					// Show progress (every 5 chunks or last chunk)
+					if (chunkCount % 5 === 0 || done) {
+						console.log(
+							`   📦 Chunk ${chunkCount}: ${value.length} bytes (total: ${totalBytes} bytes)`
+						);
+					}
+				}
+			}
+
+			// Save complete audio
+			const audioData = Buffer.concat(chunks);
+			const outputFile = "output_streamed_speech.wav";
+			fs.writeFileSync(outputFile, audioData);
+
+			console.log(`\n✅ Streaming complete!`);
+			console.log(`   💾 Saved to: ${outputFile}`);
+			console.log(`   📊 Total chunks: ${chunkCount}`);
+			console.log(`   📊 Total size: ${totalBytes} bytes`);
+			console.log(
+				`\n💡 Tip: In a real application, play chunks as they arrive for real-time audio!`
+			);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/stream_speech_long_text.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Example: Streaming TTS with Long Text (Auto-Chunking)
+ *
+ * This example demonstrates streaming TTS with long text (300+ chars).
+ * The SDK automatically chunks the text and streams audio sequentially.
+ * ⚠️ 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 (450+ 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.
+    The SDK handles all complexity automatically, so users can focus on building great applications.
+    `.trim();
+
+		console.log("📡 Starting long text streaming TTS...");
+		console.log(`   Text length: ${longText.length} characters (exceeds 300)`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log("   ✨ SDK automatically chunks and streams sequentially");
+		console.log("   ⚠️  This will consume credits!");
+
+		const startTime = Date.now();
+
+		// Stream speech - SDK handles chunking automatically
+		const response = await client.textToSpeech.streamSpeech({
+			voiceId: VOICE_ID,
+			apiConvertTextToSpeechUsingCharacterRequest: {
+				text: longText,
+				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+				outputFormat:
+					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+				style: "neutral",
+				model: "sona_speech_1",
+			},
+		});
+
+		const responseTime = Date.now() - startTime;
+		console.log(`\n✅ Stream started! (${responseTime}ms to first response)`);
+		console.log("   📦 Receiving audio chunks progressively...\n");
+
+		// Process streaming response
+		if (
+			response.result &&
+			typeof response.result === "object" &&
+			"getReader" in response.result
+		) {
+			const reader = (
+				response.result as ReadableStream<Uint8Array>
+			).getReader();
+			const chunks: Uint8Array[] = [];
+			let chunkCount = 0;
+			let totalBytes = 0;
+			let firstChunkTime = 0;
+
+			while (true) {
+				const { done, value } = await reader.read();
+				if (done) break;
+
+				if (value) {
+					if (chunkCount === 0) {
+						firstChunkTime = Date.now() - startTime;
+						console.log(
+							`   ⚡ First audio chunk received! (${firstChunkTime}ms total latency)`
+						);
+					}
+
+					chunks.push(value);
+					chunkCount++;
+					totalBytes += value.length;
+
+					// Show progress
+					if (chunkCount % 10 === 0) {
+						console.log(
+							`   📦 Received ${chunkCount} chunks, ${(
+								totalBytes / 1024
+							).toFixed(1)}KB`
+						);
+					}
+				}
+			}
+
+			// Save complete audio
+			const audioData = Buffer.concat(chunks);
+			const outputFile = "output_long_text_streamed.wav";
+			fs.writeFileSync(outputFile, audioData);
+
+			const totalTime = Date.now() - startTime;
+			console.log(`\n✅ Streaming complete!`);
+			console.log(`   💾 Saved to: ${outputFile}`);
+			console.log(`   📊 Statistics:`);
+			console.log(`      Total chunks: ${chunkCount}`);
+			console.log(`      Total size: ${(totalBytes / 1024).toFixed(1)}KB`);
+			console.log(`      Total time: ${totalTime}ms`);
+			console.log(`      First chunk latency: ${firstChunkTime}ms`);
+			console.log(
+				`\n🎯 Long text was automatically chunked and streamed seamlessly!`
+			);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/text_to_speech/stream_speech_with_phonemes.ts

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Example: Streaming TTS with Phoneme Information
+ *
+ * This example demonstrates streaming TTS with phoneme timing data.
+ * Note: Phoneme data is returned as JSON, not in streaming format.
+ * ⚠️ 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 streaming test with phoneme timing information.";
+		console.log("📡🔤 Starting streaming TTS with phonemes...");
+		console.log(`   Text: "${text}"`);
+		console.log(`   Voice ID: ${VOICE_ID}`);
+		console.log(
+			"   ℹ️  Note: Phoneme data comes as JSON, audio streams progressively"
+		);
+		console.log("   ⚠️  This will consume credits!");
+
+		const startTime = Date.now();
+
+		// Stream speech with phonemes
+		const response = await client.textToSpeech.streamSpeech({
+			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
+			},
+		});
+
+		const responseTime = Date.now() - startTime;
+		console.log(`\n✅ Response received! (${responseTime}ms)`);
+
+		// Process response
+		if (response.result) {
+			// Check if response contains phoneme data (JSON format)
+			if (
+				typeof response.result === "object" &&
+				"audioBase64" in response.result
+			) {
+				console.log("   📦 Response includes both audio and phoneme data\n");
+
+				const result = response.result as any;
+
+				// Decode 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);
+				}
+
+				// Save audio
+				const audioFile = "output_streamed_with_phonemes.wav";
+				fs.writeFileSync(audioFile, bytes);
+				console.log(`   💾 Audio saved to: ${audioFile}`);
+				console.log(`   📊 Audio size: ${(bytes.length / 1024).toFixed(1)}KB`);
+
+				// 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
+					const phonemeFile = "phoneme_data_streamed.json";
+					fs.writeFileSync(phonemeFile, JSON.stringify(phonemes, null, 2));
+					console.log(`\n   💾 Phoneme data saved to: ${phonemeFile}`);
+				}
+			} else if (
+				typeof response.result === "object" &&
+				"getReader" in response.result
+			) {
+				// Pure streaming (no phoneme data)
+				console.log("   ⚠️  No phoneme data in response (pure streaming mode)");
+
+				const reader = (
+					response.result as ReadableStream<Uint8Array>
+				).getReader();
+				const chunks: Uint8Array[] = [];
+				let chunkCount = 0;
+
+				while (true) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					if (value) {
+						chunks.push(value);
+						chunkCount++;
+					}
+				}
+
+				const audioData = Buffer.concat(chunks);
+				const audioFile = "output_streamed_no_phonemes.wav";
+				fs.writeFileSync(audioFile, audioData);
+				console.log(`   💾 Audio saved to: ${audioFile}`);
+				console.log(`   📊 Received ${chunkCount} chunks`);
+			}
+		}
+
+		const totalTime = Date.now() - startTime;
+		console.log(`\n✅ Complete! (Total: ${totalTime}ms)`);
+		console.log(`\n💡 Use cases for phoneme data:`);
+		console.log(`   • Lip-sync animation`);
+		console.log(`   • Subtitle generation`);
+		console.log(`   • Speech analysis`);
+		console.log(`   • Karaoke-style highlighting`);
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+