@supertone/supertone 0.1.0

package/examples/text_to_speech/stream_speech_with_voice_settings.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * Example: Streaming TTS with Custom Voice Settings
+ *
+ * This example demonstrates streaming TTS with custom pitch, speed, and variance.
+ * Useful for creating varied voice outputs in real-time applications.
+ * ⚠️ 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 streaming test with custom voice settings. Notice the adjusted pitch and speed.";
+
+		// Custom voice settings
+		const voiceSettings = {
+			pitchShift: 1.15, // Higher pitch (0.5 to 1.5)
+			pitchVariance: 0.9, // Less variation (0.5 to 1.5)
+			speed: 1.2, // Faster speed (0.5 to 2.0)
+		};
+
+		console.log("📡🎛️  Starting streaming TTS with 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!");
+
+		const startTime = Date.now();
+
+		// Stream speech with voice settings
+		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",
+				voiceSettings: voiceSettings, // Apply custom settings
+			},
+		});
+
+		const responseTime = Date.now() - startTime;
+		console.log(`\n✅ Stream started! (${responseTime}ms to first response)`);
+		console.log("   📦 Receiving audio chunks with customized voice...\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 % 5 === 0) {
+						console.log(
+							`   📦 Chunk ${chunkCount}: ${(totalBytes / 1024).toFixed(
+								1
+							)}KB received`
+						);
+					}
+				}
+			}
+
+			// Save complete audio
+			const audioData = Buffer.concat(chunks);
+			const outputFile = "output_streamed_with_voice_settings.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🎯 Listen to hear the customized voice with adjusted settings!`
+			);
+
+			console.log(`\n💡 Voice Settings Use Cases:`);
+			console.log(`   • Character voices (high/low pitch)`);
+			console.log(`   • Emotional expression (variance)`);
+			console.log(`   • Accessibility (speed adjustment)`);
+			console.log(`   • Audio book narration (pacing)`);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/usage/get_credit_balance.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * Example: Get Credit Balance
+ *
+ * This example demonstrates how to check your remaining credit balance.
+ */
+
+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 });
+
+		// Get credit balance
+		console.log("💰 Fetching credit balance...");
+		const response = await client.usage.getCreditBalance();
+
+		// Display results
+		console.log("\n✅ Credit Balance Retrieved:");
+		console.log(`   Balance: ${response.balance} credits`);
+
+		if (response.balance < 100) {
+			console.log("\n⚠️  Low credit balance! Consider topping up.");
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/usage/get_usage.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Example: Get Usage Analytics
+ *
+ * This example demonstrates how to retrieve usage analytics for a time period.
+ */
+
+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 });
+
+		// Set time period (last 7 days)
+		const endTime = new Date();
+		const startTime = new Date(endTime.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+		console.log("📊 Fetching usage analytics...");
+		console.log(
+			`   Period: ${startTime.toISOString().split("T")[0]} to ${
+				endTime.toISOString().split("T")[0]
+			}`
+		);
+
+		// Get usage data
+		const response = await client.usage.getUsage({
+			startTime: startTime.toISOString(),
+			endTime: endTime.toISOString(),
+		});
+
+		// Display results
+		console.log("\n✅ Usage Data Retrieved:");
+		console.log(`   Total buckets: ${response.total}`);
+		console.log(`   Data buckets: ${response.data?.length || 0}`);
+
+		if (response.data && response.data.length > 0) {
+			console.log("\n📅 Recent Usage:");
+			for (const bucket of response.data.slice(0, 3)) {
+				console.log(`   ${bucket.startingAt} - ${bucket.endingAt}`);
+				if (bucket.results) {
+					const totalMinutes = bucket.results.reduce(
+						(sum, r) => sum + (r.minutesUsed || 0),
+						0
+					);
+					console.log(`      Usage: ${totalMinutes.toFixed(2)} minutes`);
+				}
+			}
+		} else {
+			console.log("\n📝 No usage records for this period");
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/usage/get_voice_usage.ts

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Example: Get Voice Usage Statistics
+ *
+ * This example demonstrates how to retrieve per-voice usage statistics.
+ */
+
+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 });
+
+		// Set date range (last 7 days)
+		const endDate = new Date();
+		const startDate = new Date(endDate.getTime() - 7 * 24 * 60 * 60 * 1000);
+
+		console.log("🎤 Fetching voice usage statistics...");
+		console.log(
+			`   Period: ${startDate.toISOString().split("T")[0]} to ${
+				endDate.toISOString().split("T")[0]
+			}`
+		);
+
+		// Get voice usage
+		const response = await client.usage.getVoiceUsage({
+			startDate: startDate.toISOString().split("T")[0],
+			endDate: endDate.toISOString().split("T")[0],
+		});
+
+		// Display results
+		console.log("\n✅ Voice Usage Retrieved:");
+		console.log(`   Total voices used: ${response.usages?.length || 0}`);
+
+		if (response.usages && response.usages.length > 0) {
+			console.log("\n🎤 Top Voices:");
+			for (const usage of response.usages.slice(0, 5)) {
+				const voiceName =
+					usage.name || `Voice ${usage.voiceId?.substring(0, 8)}`;
+				console.log(`   ${voiceName}`);
+				console.log(
+					`      Usage: ${usage.totalMinutesUsed?.toFixed(2)} minutes`
+				);
+				console.log(`      ID: ${usage.voiceId}`);
+				if (usage.language) {
+					console.log(`      Language: ${usage.language}`);
+				}
+			}
+		} else {
+			console.log("\n📝 No voice usage records for this period");
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/voices/get_voice.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Example: Get Voice Details
+ *
+ * This example demonstrates how to get detailed information about a specific 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;
+
+// Replace with an actual voice ID (get it from list_voices.ts)
+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 });
+
+		console.log(`🔍 Fetching voice details for ID: ${VOICE_ID}...`);
+
+		// Get voice details
+		const response = await client.voices.getVoice({ voiceId: VOICE_ID });
+
+		// Display results
+		console.log("\n✅ Voice Details:");
+		console.log(`   Name: ${response.name}`);
+		console.log(`   ID: ${response.voiceId}`);
+		console.log(`   Language: ${response.language}`);
+		console.log(`   Gender: ${response.gender}`);
+		if (response.description) {
+			console.log(`   Description: ${response.description}`);
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/voices/list_voices.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Example: List Available Voices
+ *
+ * This example demonstrates how to list all available 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 voice list...");
+
+		// List voices (first page, 10 items)
+		const response = await client.voices.listVoices({ pageSize: 10 });
+
+		// Display results
+		console.log("\n✅ Voice List Retrieved:");
+		console.log(`   Total voices: ${response.total}`);
+		console.log(`   Showing: ${response.items?.length || 0} voices`);
+
+		if (response.items && response.items.length > 0) {
+			console.log("\n🎤 Available Voices:");
+			for (const voice of response.items) {
+				console.log(`\n   ${voice.name}`);
+				console.log(`      ID: ${voice.voiceId}`);
+				console.log(`      Language: ${voice.language}`);
+				console.log(`      Gender: ${voice.gender}`);
+				if (voice.description) {
+					console.log(
+						`      Description: ${voice.description.substring(0, 60)}...`
+					);
+				}
+			}
+
+			// Save first voice ID for potential use in other examples
+			const firstVoiceId = response.items[0]?.voiceId;
+			if (firstVoiceId) {
+				console.log(`\n💡 Tip: Use voice ID "${firstVoiceId}" in TTS examples`);
+			}
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/examples/voices/search_voices.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * Example: Search Voices
+ *
+ * This example demonstrates how to search for voices by language and gender.
+ */
+
+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("🔍 Searching for female English voices...");
+
+		// Search voices
+		const response = await client.voices.searchVoices({
+			language: "en",
+			gender: "female",
+			pageSize: 10,
+		});
+
+		// Display results
+		console.log("\n✅ Search Results:");
+		console.log(`   Found: ${response.items?.length || 0} voices`);
+
+		if (response.items && response.items.length > 0) {
+			console.log("\n🎤 Matching Voices:");
+			for (const voice of response.items) {
+				console.log(`\n   ${voice.name}`);
+				console.log(`      ID: ${voice.voiceId}`);
+				console.log(`      Language: ${voice.language}`);
+				console.log(`      Gender: ${voice.gender}`);
+			}
+		} else {
+			console.log("\n📝 No voices found matching the criteria");
+		}
+	} catch (error: any) {
+		console.error("❌ Error:", error.message);
+		process.exit(1);
+	}
+}
+
+main();
+

package/jsr.json

@@ -0,0 +1,27 @@
+
+
+{
+  "name": "supertone",
+  "version": "0.1.0",
+  "exports": {
+    ".": "./src/index.ts",    
+    "./models/errors": "./src/models/errors/index.ts",    
+    "./models": "./src/models/index.ts",    
+    "./models/operations": "./src/models/operations/index.ts",
+    "./lib/config": "./src/lib/config.ts",
+    "./lib/http": "./src/lib/http.ts",
+    "./lib/retries": "./src/lib/retries.ts",
+    "./lib/sdks": "./src/lib/sdks.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "publish": {
+    "include": [
+      "LICENSE",
+      "README.md",
+      "RUNTIMES.md",
+      "USAGE.md",
+      "jsr.json",
+      "src/**/*.ts"
+    ]
+  }
+}