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.
Installation
npm install @neosapience/typecast-js@latest
pnpm add @neosapience/typecast-js@latest
yarn add @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
TypeScript (ESM)
Javascript (CommonJS)
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();
const { TypecastClient } = require('@neosapience/typecast-js');
const fs = require('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 volume (0-200), 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)
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
});
Explicitly set emotion with preset values:import { PresetPrompt } from '@neosapience/typecast-js';
const audio = await client.textToSpeech({
text: "I am so excited to show you these features!",
voice_id: "tc_672c5f5ce59fac2a48faeaee",
model: "ssfm-v30",
prompt: {
emotion_type: "preset",
emotion_preset: "happy", // normal, happy, sad, angry, whisper, toneup, tonedown
emotion_intensity: 1.5 // Range: 0.0 to 2.0
} as PresetPrompt
});
Audio Customization
Control volume, pitch, tempo, and output format:
const audio = await client.textToSpeech({
text: "Customized audio output!",
voice_id: "tc_672c5f5ce59fac2a48faeaee",
model: "ssfm-v30",
output: {
volume: 120, // Range: 0 to 200 (default: 100)
audio_pitch: 2, // Range: -12 to +12 semitones
audio_tempo: 1.2, // Range: 0.5x to 2.0x
audio_format: "mp3" // Options: wav, mp3
},
seed: 42 // For reproducible results
});
await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
console.log(`Duration: ${audio.duration}s, Format: ${audio.format}`);
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));
Supported Languages
The SDK supports 37 languages with automatic language detection:
| Code | Language | Code | Language | Code | Language |
|---|
eng | English | jpn | Japanese | ukr | Ukrainian |
kor | Korean | ell | Greek | ind | Indonesian |
spa | Spanish | tam | Tamil | dan | Danish |
deu | German | tgl | Tagalog | swe | Swedish |
fra | French | fin | Finnish | msa | Malay |
ita | Italian | zho | Chinese | ces | Czech |
pol | Polish | slk | Slovak | por | Portuguese |
nld | Dutch | ara | Arabic | bul | Bulgarian |
rus | Russian | hrv | Croatian | ron | Romanian |
ben | Bengali | hin | Hindi | hun | Hungarian |
nan | Hokkien | nor | Norwegian | pan | Punjabi |
tha | Thai | tur | Turkish | vie | Vietnamese |
yue | Cantonese | | | | |
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';
