@neosapience/typecast-js 0.1.3 → 0.1.4

package/README.md

@@ -7,7 +7,9 @@
 
 The official Node.js library for the [Typecast API](https://typecast.ai). Convert text to lifelike speech using AI-powered voices.
 
-Works with both JavaScript and TypeScript. TypeScript types included.
+Works with both JavaScript and TypeScript. Full TypeScript types included.
+
+ESM & CommonJS supported. This SDK targets Node.js environments only (browser usage is not supported).
 
 ## Installation
 
@@ -23,21 +25,18 @@ npm install @neosapience/typecast-js
 import { TypecastClient } from '@neosapience/typecast-js';
 import fs from 'fs';
 
-// Initialize client with API key
-const client = new TypecastClient({
-  apiKey: 'YOUR_API_KEY'
-});
-
-// Convert text to speech
-const audio = await client.textToSpeech({
-  text: "Hello there! I'm your friendly text-to-speech agent.",
-  model: "ssfm-v21",
-  voice_id: "tc_62a8975e695ad26f7fb514d1"
-});
+async function main() {
+  const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });
+  const audio = await client.textToSpeech({
+    text: "Hello there! I'm your friendly text-to-speech agent.",
+    model: "ssfm-v21",
+    voice_id: "tc_62a8975e695ad26f7fb514d1"
+  });
+  await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
+  console.log(`Audio saved! Duration: ${audio.duration}s, Format: ${audio.format}`);
+}
 
-// Save audio file
-await fs.promises.writeFile('output.wav', Buffer.from(audio.audioData));
-console.log(`Audio saved! Duration: ${audio.duration}s, Format: ${audio.format}`);
+main();
 ```
 
 ### JavaScript (CommonJS)
@@ -47,17 +46,13 @@ const { TypecastClient } = require('@neosapience/typecast-js');
 const fs = require('fs');
 
 async function main() {
-  const client = new TypecastClient({
-    apiKey: 'YOUR_API_KEY'
-  });
-
+  const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });
   const audio = await client.textToSpeech({
     text: "Hello there! I'm your friendly text-to-speech agent.",
     model: "ssfm-v21",
     voice_id: "tc_62a8975e695ad26f7fb514d1"
   });
-
-  await fs.promises.writeFile('output.wav', Buffer.from(audio.audioData));
+  await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
   console.log(`Audio saved! Duration: ${audio.duration}s, Format: ${audio.format}`);
 }
 
@@ -70,14 +65,14 @@ The client can be configured using environment variables or constructor options:
 
 ```typescript
 // Using environment variables
-// TYPECAST_API_KEY=your_api_key
-// TYPECAST_API_HOST=https://api.typecast.ai (optional)
-const client = new TypecastClient();
+// export TYPECAST_API_KEY=your_api_key
+const client = new TypecastClient({
+  apiKey: process.env.TYPECAST_API_KEY!
+});
 
-// Using constructor options
+// Or pass API key directly
 const client = new TypecastClient({
-  apiKey: 'your_api_key',
-  baseHost: 'https://api.typecast.ai' // optional
+  apiKey: 'your_api_key'
 });
 ```
 
@@ -114,10 +109,8 @@ const response = await client.textToSpeech({
 - **model** (required): Voice model (`ssfm-v21`)
 - **language** (optional): Language code (see supported languages below)
 - **prompt** (optional): Emotion and style settings
-  - `emotion_preset`: `'happy' | 'sad' | 'normal' | 'angry'` (default: `'normal'`)
+  - `emotion_preset`: Emotion type for the voice. Available options include `'happy' | 'sad' | 'normal' | 'angry' | 'tonemid' | 'toneup'` (default: `'normal'`). Note: Each voice supports different emotions - check the voice's `emotions` array using `getVoices()` to see which emotions are supported.
   - `emotion_intensity`: 0.0 - 2.0 (default: 1.0)
-  - `speed`: 0.5 - 2.0 (default: 1.0)
-  - `intonation`: -2 - 2 (default: 0)
 - **output** (optional): Audio output settings
   - `audio_format`: `'wav' | 'mp3'` (default: `'wav'`)
   - `volume`: 0 - 200 (default: 100)
@@ -129,6 +122,8 @@ const response = await client.textToSpeech({
 
 List all available voices, optionally filtered by model.
 
+**Signature:** `getVoices(model?: string): Promise<Voice[]>`
+
 ```typescript
 // Get all voices
 const voices = await client.getVoices();
@@ -142,15 +137,27 @@ voices.forEach(voice => {
 });
 ```
 
+For detailed Voice object fields, see the [API Reference](https://typecast.ai/docs/api-reference).
+
 ### Get Voice by ID
 
 Get information about a specific voice.
 
+**Signature:** `getVoiceById(voiceId: string, model?: string): Promise<Voice[]>`
+
 ```typescript
 const voiceInfo = await client.getVoiceById("tc_62a8975e695ad26f7fb514d1");
-console.log(voiceInfo);
+console.log(`Voice: ${voiceInfo[0].voice_name}`);
+console.log(`Model: ${voiceInfo[0].model}`);
+console.log(`Supported emotions: ${voiceInfo[0].emotions.join(', ')}`);
 ```
 
+**Voice Object Fields:**
+- `voice_id`: Unique identifier (format: `tc_*` or `uc_*`)
+- `voice_name`: Human-readable name of the voice
+- `model`: Voice model type (`ssfm-v21`)
+- `emotions`: Array of supported emotion presets for this voice
+
 ## Supported Languages
 
 The SDK supports 27 languages with automatic language detection:
@@ -171,6 +178,33 @@ If not specified, the language will be automatically detected from the input tex
 
 ## Advanced Examples
 
+### Working with Voice Emotions
+
+Each voice supports different emotion presets. Check which emotions a voice supports before using them:
+
+```typescript
+// Get voice information
+const voices = await client.getVoices("ssfm-v21");
+const myVoice = voices.find(v => v.voice_id === "tc_62a8975e695ad26f7fb514d1");
+
+console.log(`${myVoice.voice_name} supports: ${myVoice.emotions.join(', ')}`);
+// Example output: "Olivia supports: tonemid, toneup, normal, happy, sad, angry"
+
+// Use a supported emotion
+if (myVoice.emotions.includes('happy')) {
+  const audio = await client.textToSpeech({
+    text: "This voice supports the happy emotion!",
+    voice_id: myVoice.voice_id,
+    model: "ssfm-v21",
+    prompt: {
+      emotion_preset: "happy",
+      emotion_intensity: 1.5
+    }
+  });
+  // Save: await fs.promises.writeFile(`happy.${audio.format}`, Buffer.from(audio.audioData));
+}
+```
+
 ### Emotion Control
 
 ```typescript
@@ -181,10 +215,13 @@ const happyAudio = await client.textToSpeech({
   model: "ssfm-v21",
   prompt: {
     emotion_preset: "happy",
-    emotion_intensity: 1.8,
-    speed: 1.2
+    emotion_intensity: 1.8
+  },
+  output: {
+    audio_tempo: 1.2
   }
 });
+// Save: await fs.promises.writeFile(`happy.${happyAudio.format}`, Buffer.from(happyAudio.audioData));
 
 // Calm and professional voice
 const calmAudio = await client.textToSpeech({
@@ -193,10 +230,13 @@ const calmAudio = await client.textToSpeech({
   model: "ssfm-v21",
   prompt: {
     emotion_preset: "normal",
-    emotion_intensity: 0.8,
-    speed: 0.9
+    emotion_intensity: 0.8
+  },
+  output: {
+    audio_tempo: 0.9
   }
 });
+// Save: await fs.promises.writeFile(`calm.${calmAudio.format}`, Buffer.from(calmAudio.audioData));
 ```
 
 ### Audio Customization
@@ -214,6 +254,7 @@ const customAudio = await client.textToSpeech({
     audio_format: "mp3"
   }
 });
+// Save: await fs.promises.writeFile(`custom.${customAudio.format}`, Buffer.from(customAudio.audioData));
 ```
 
 ### Multilingual Content
@@ -226,6 +267,7 @@ const koreanAudio = await client.textToSpeech({
   model: "ssfm-v21",
   language: "kor"
 });
+// Save: await fs.promises.writeFile(`korean.${koreanAudio.format}`, Buffer.from(koreanAudio.audioData));
 
 // Japanese text
 const japaneseAudio = await client.textToSpeech({
@@ -234,6 +276,7 @@ const japaneseAudio = await client.textToSpeech({
   model: "ssfm-v21",
   language: "jpn"
 });
+// Save: await fs.promises.writeFile(`japanese.${japaneseAudio.format}`, Buffer.from(japaneseAudio.audioData));
 ```
 
 ### Error Handling
@@ -241,31 +284,38 @@ const japaneseAudio = await client.textToSpeech({
 ```typescript
 import { TypecastClient, TypecastAPIError } from '@neosapience/typecast-js';
 
-try {
-  const audio = await client.textToSpeech({
-    text: "Hello world",
-    voice_id: "tc_62a8975e695ad26f7fb514d1",
-    model: "ssfm-v21"
-  });
-} catch (error) {
-  if (error instanceof TypecastAPIError) {
-    switch (error.statusCode) {
-      case 401:
-        console.error('Invalid API key');
-        break;
-      case 402:
-        console.error('Insufficient credits');
-        break;
-      case 422:
-        console.error('Validation error:', error.response);
-        break;
-      default:
-        console.error(`API error (${error.statusCode}):`, error.message);
+async function main() {
+  const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });
+
+  try {
+    const audio = await client.textToSpeech({
+      text: "Hello world",
+      voice_id: "tc_62a8975e695ad26f7fb514d1",
+      model: "ssfm-v21"
+    });
+  } catch (error) {
+    if (error instanceof TypecastAPIError) {
+      // TypecastAPIError exposes: statusCode (number), message (string), response (unknown)
+      switch (error.statusCode) {
+        case 401:
+          console.error('Invalid API key');
+          break;
+        case 402:
+          console.error('Insufficient credits');
+          break;
+        case 422:
+          console.error('Validation error:', error.response);
+          break;
+        default:
+          console.error(`API error (${error.statusCode}):`, error.message);
+      }
+    } else {
+      console.error('Unexpected error:', error);
     }
-  } else {
-    console.error('Unexpected error:', error);
   }
 }
+
+main();
 ```
 
 ## TypeScript Support

package/lib/index.d.cts

@@ -36,7 +36,7 @@ type LanguageCode = 'eng' | 'kor' | 'jpn' | 'spa' | 'deu' | 'fra' | 'ita' | 'pol
  */
 interface Prompt {
     /** Emotion preset for the voice (default: 'normal') */
-    emotion_preset?: 'happy' | 'sad' | 'normal' | 'angry';
+    emotion_preset?: 'happy' | 'sad' | 'normal' | 'angry' | 'tonemid' | 'toneup';
     /**
      * Emotion intensity
      * @min 0.0
@@ -44,20 +44,6 @@ interface Prompt {
      * @default 1.0
      */
     emotion_intensity?: number;
-    /**
-     * Speech speed
-     * @min 0.5
-     * @max 2.0
-     * @default 1.0
-     */
-    speed?: number;
-    /**
-     * Intonation adjustment
-     * @min -2
-     * @max 2
-     * @default 0
-     */
-    intonation?: number;
 }
 /**
  * Audio output settings for controlling the final audio characteristics
@@ -127,7 +113,7 @@ interface TTSResponse {
 interface VoicesResponse {
     voice_id: string;
     voice_name: string;
-    model: string;
+    model: TTSModel;
     emotions: string[];
 }
 

package/lib/index.d.ts

@@ -36,7 +36,7 @@ type LanguageCode = 'eng' | 'kor' | 'jpn' | 'spa' | 'deu' | 'fra' | 'ita' | 'pol
  */
 interface Prompt {
     /** Emotion preset for the voice (default: 'normal') */
-    emotion_preset?: 'happy' | 'sad' | 'normal' | 'angry';
+    emotion_preset?: 'happy' | 'sad' | 'normal' | 'angry' | 'tonemid' | 'toneup';
     /**
      * Emotion intensity
      * @min 0.0
@@ -44,20 +44,6 @@ interface Prompt {
      * @default 1.0
      */
     emotion_intensity?: number;
-    /**
-     * Speech speed
-     * @min 0.5
-     * @max 2.0
-     * @default 1.0
-     */
-    speed?: number;
-    /**
-     * Intonation adjustment
-     * @min -2
-     * @max 2
-     * @default 0
-     */
-    intonation?: number;
 }
 /**
  * Audio output settings for controlling the final audio characteristics
@@ -127,7 +113,7 @@ interface TTSResponse {
 interface VoicesResponse {
     voice_id: string;
     voice_name: string;
-    model: string;
+    model: TTSModel;
     emotions: string[];
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neosapience/typecast-js",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "main": "./lib/index.cjs",
   "module": "./lib/index.js",