Skip to main content
The official Node.js library for the Typecast API. Convert text to lifelike speech using AI-powered voices. Works with both Javascript and TypeScript. Full TypeScript types included. ESM & CommonJS supported. Works in Node.js 18+ and modern browsers. Node.js 16/17 users need to install isomorphic-fetch polyfill.

Package

Typecast Javascript/Typescript SDK

Source Code

Typecast Javascript/Typescript SDK Source Code

​
Installation

npm install @neosapience/typecast-js@latest
Make sure you have version 0.1.5 or higher installed. You can check your version with npm list @neosapience/typecast-js. If you have an older version, run npm update @neosapience/typecast-js to update.

​
Quick Start

import { TypecastClient } from '@neosapience/typecast-js';
import fs from 'fs';

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-v30",
    voice_id: "tc_672c5f5ce59fac2a48faeaee"
  });
  await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
  console.log(`Audio saved! Duration: ${audio.duration}s, Format: ${audio.format}`);
}

main();

​
Features

The Typecast Javascript/TypeScript SDK provides powerful features for text-to-speech conversion:
  • Multiple Voice Models: Support for ssfm-v30 (latest) and ssfm-v21 AI voice models
  • Multi-language Support: 37 languages including English, Korean, Spanish, Japanese, Chinese, and more
  • Emotion Control: Preset emotions (normal, happy, sad, angry, whisper, toneup, tonedown) or smart context-aware inference
  • Audio Customization: Control loudness (LUFS -70 to 0), pitch (-12 to +12 semitones), tempo (0.5x to 2.0x), and format (WAV/MP3)
  • Voice Discovery: V2 Voices API with filtering by model, gender, age, and use cases
  • TypeScript Support: Full type definitions included
  • Zero Dependencies: Uses native fetch API (works in Node.js 18+ and browsers)
  • Streaming: Real-time chunked audio delivery for low-latency playback

​
Configuration

Set your API key via environment variable or constructor: 
// Using environment variable
// export TYPECAST_API_KEY="your-api-key-here"
const client = new TypecastClient({
  apiKey: process.env.TYPECAST_API_KEY!
});

// Or pass directly
const client = new TypecastClient({
  apiKey: 'your-api-key-here'
});

​
Advanced Usage

​
Emotion Control (ssfm-v30)

ssfm-v30 offers two emotion control modes: Preset and Smart.
Let the AI infer emotion from context:
import { SmartPrompt } from '@neosapience/typecast-js';

const audio = await client.textToSpeech({
  text: "Everything is going to be okay.",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  prompt: {
    emotion_type: "smart",
    previous_text: "I just got the best news!",  // Optional context
    next_text: "I can't wait to celebrate!"      // Optional context
  } as SmartPrompt
});

​
Audio Customization

Control loudness, pitch, tempo, and output format: 
const response = await client.textToSpeech({
  text: "Customized audio output!",
  model: "ssfm-v30",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  output: {
    target_lufs: -14.0,   // Range: -70 to 0 (LUFS)
    audio_pitch: 2,       // Range: -12 to +12 semitones
    audio_tempo: 1.2,     // Range: 0.5x to 2.0x
    audio_format: "mp3"   // Options: wav, mp3
  }
});

​
Voice Discovery (V2 API)

List and filter available voices with enhanced metadata: 
// Get all voices
const voices = await client.getVoicesV2();

// Filter by criteria
const filtered = await client.getVoicesV2({
  model: 'ssfm-v30',
  gender: 'female',
  age: 'young_adult'
});

// Display voice info
voices.forEach(voice => {
  console.log(`ID: ${voice.voice_id}, Name: ${voice.voice_name}`);
  console.log(`Gender: ${voice.gender}, Age: ${voice.age}`);
  console.log(`Models: ${voice.models.map(m => m.version).join(', ')}`);
  console.log(`Use cases: ${voice.use_cases?.join(', ')}`);
});

​
Multilingual Content

The SDK supports 37 languages with automatic language detection: 
// Auto-detect language (recommended)
const audio = await client.textToSpeech({
  text: "こんにちは。お元気ですか。",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30"
});

// Or specify language explicitly
const koreanAudio = await client.textToSpeech({
  text: "안녕하세요. 반갑습니다.",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  language: "kor"  // ISO 639-3 language code
});

await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));

​
Streaming

Stream audio chunks in real-time for low-latency playback: 
// Node 18+ (built-in fetch). Pipe stream to ffplay for real-time playback.
// Prerequisite: ffmpeg (brew/choco/apt install ffmpeg)
import { spawn } from "node:child_process";
import { TypecastClient } from '@neosapience/typecast-js';

const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });

const ffplay = spawn(
    "ffplay",
    ["-autoexit", "-nodisp", "-loglevel", "error", "-i", "pipe:0"],
    { stdio: ["pipe", "ignore", "ignore"] },
);

const stream = await client.textToSpeechStream({
    text: "Stream this text as audio in real time.",
    model: "ssfm-v30",
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    output: { audio_format: "wav" }
});

// ReadableStream — read chunks as they arrive
const reader = stream.getReader();
while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    ffplay.stdin.write(value);
}
ffplay.stdin.end();
await new Promise((resolve) => ffplay.on("close", resolve));
WAV streaming format: 32000 Hz, 16-bit, mono PCM. The first chunk includes a 44-byte WAV header (size = 0xFFFFFFFF); subsequent chunks are raw PCM only. For MP3: 320 kbps, 44100 Hz, each chunk is independently decodable. The streaming endpoint does not support volume or target_lufs.

​
Supported Languages

The SDK supports 37 languages with automatic language detection:
CodeLanguageCodeLanguageCodeLanguage
engEnglishjpnJapaneseukrUkrainian
korKoreanellGreekindIndonesian
spaSpanishtamTamildanDanish
deuGermantglTagalogsweSwedish
fraFrenchfinFinnishmsaMalay
itaItalianzhoChinesecesCzech
polPolishslkSlovakporPortuguese
nldDutcharaArabicbulBulgarian
rusRussianhrvCroatianronRomanian
benBengalihinHindihunHungarian
nanHokkiennorNorwegianpanPunjabi
thaThaiturTurkishvieVietnamese
yueCantonese
If not specified, the language will be automatically detected from the input text.

​
Error Handling

The SDK provides TypecastAPIError for handling API errors: 
import { TypecastClient, TypecastAPIError } from '@neosapience/typecast-js';

try {
  const audio = await client.textToSpeech({
    text: "Hello world",
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    model: "ssfm-v30"
  });
} catch (error) {
  if (error instanceof TypecastAPIError) {
    // TypecastAPIError exposes: statusCode, message, response
    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;
      case 429:
        console.error('Rate limit exceeded - please retry later');
        break;
      default:
        console.error(`API error (${error.statusCode}):`, error.message);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

​
TypeScript Support

This SDK is written in TypeScript and provides full type definitions: 
import type {
  TTSRequest,
  TTSResponse,
  TTSModel,
  LanguageCode,
  Prompt,
  PresetPrompt,
  SmartPrompt,
  Output,
  VoiceV2Response,
  VoicesV2Filter
} from '@neosapience/typecast-js';