Autotag SDK

Overview

Typecast AutoTag is a text preprocessing SDK that converts structured data (phone numbers, dates, times, amounts, etc.) into TTS-friendly formats for voice applications.

npm Package

@neosapience/typecast-autotag

PyPI Package

typecast-autotag

Maven Central

com.neosapience:typecast-autotag

GitHub Repository

Source, issues, and native binaries

Why AutoTag?

When building voice applications, raw text often doesn't translate well to natural speech:

AutoTag automatically detects these patterns and converts them to natural speech, improving the user experience in voice applications.

Language Support

The JavaScript and browser package accepts every SSFM v3.0 TTS language.

Official SSFM v3.0 language codes (37): ara, ben, bul, ces, dan, deu, ell, eng, fin, fra, hin, hrv, hun, ind, ita, jpn, kor, msa, nan, nld, nor, pan, pol, por, ron, rus, slk, spa, swe, tam, tgl, tha, tur, ukr, vie, yue, zho.

The five extra accepted values are aliases or a locale tag, not additional official languages: ko → kor, en → eng, ja → jpn, zh → zho, and zh-TW → Traditional Chinese.

For the 31 languages without a dedicated rule module, AutoTag handles datetime, date, time, money, phone, percentage, range, unit, serial, and number patterns. It applies locale-specific date order, month and currency names, decimal separators, 12/24-hour conventions, and common native digit scripts. The nan and yue codes reuse the Traditional Chinese pattern pipeline while retaining their own TTS voice selection.

import { autoTag } from '@neosapience/typecast-autotag';

autoTag('Call me at 555-123-4567.', { language: 'en' });
// → 'Call me at five five five one two three four five six seven.'

autoTag('Total is $1,500.', { language: 'en' });
// → 'Total is one thousand five hundred dollars.'

Installation

pnpm add @neosapience/typecast-autotag

# or
npm install @neosapience/typecast-autotag
yarn add @neosapience/typecast-autotag

import { autoTag } from '@neosapience/typecast-autotag';

autoTag('Call me at 555-123-4567.', { language: 'en' });

Quick Start

Auto-Tagging

Automatically detect and convert patterns in your text:

import { autoTag } from '@neosapience/typecast-autotag';

// Phone numbers
autoTag('Call 555-123-4567', { language: 'en' });
// → 'Call five five five one two three four five six seven'

// Dates and times
autoTag('Meeting at 2:30 PM on January 15, 2024', { language: 'en' });
// → 'Meeting at two thirty PM on January fifteenth, twenty twenty-four'

// Currency
autoTag('Total: $1,234.56', { language: 'en' });
// → 'Total: one thousand two hundred thirty-four dollars and fifty-six cents'

Manual-Tagging

Use explicit tag syntax for precise control:

import { manualTag } from '@neosapience/typecast-autotag';

// Read a verification code digit by digit
manualTag('Your code is digits(2048).', { language: 'en' });
// → 'Your code is two zero four eight.'

Combined Usage

Apply both auto and manual tags together:

import { autoTagWithManual } from '@neosapience/typecast-autotag';

autoTagWithManual('Code digits(2048), total $50.', { language: 'en' });
// → 'Code two zero four eight, total fifty dollars.'

Supported Tags

Tag availability varies by language. Use getSupportedAutoTags(language) for the exact runtime list. Japanese, Simplified Chinese, and Taiwan Mandarin additionally recognize regional postal codes, ranges, scores, fractions, units, email symbols, directions, contextual serial/account/flight identifiers, and scripture references.

Auto-Tags (Automatically Detected)

Manual-Only Tags

AICC Use Case

Perfect for AI Contact Center applications where natural speech is critical:

import { autoTagWithManual } from '@neosapience/typecast-autotag';

// Customer service script
const customerName = 'John Smith';
const orderNumber = '12345';
const deliveryDate = 'January 15, 2024';
const supportPhone = '1-800-555-1234';

const script = autoTagWithManual(`
  Hello, name(${customerName}).
  Your order number digits(${orderNumber}) will be delivered on ${deliveryDate}.
  For questions, please call ${supportPhone}.
`, { language: 'en' });

// Output:
// "Hello, John Smith.
//  Your order number one two three four five will be delivered on January fifteenth, twenty twenty-four.
//  For questions, please call one eight zero zero five five five one two three four."

Integration with Typecast TTS

Combine AutoTag with Typecast TTS API for the best voice experience:

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

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

// Preprocess text with AutoTag
const rawText = 'Your balance is $1,234.56. Call 555-123-4567 for support.';
const processedText = autoTagWithManual(rawText, { language: 'en' });

// Send to Typecast TTS
const audio = await client.textToSpeech({
    text: processedText,
    model: 'ssfm-v30',
    voice_id: 'tc_672c5f5ce59fac2a48faeaee'
});

Platform Support

Development Languages

Server Platforms

Architectures

Next Steps