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:

Input	Without AutoTag	With AutoTag
`555-123-4567`	”five five five dash one two three dash four five six seven"	"five five five one two three four five six seven”
`$1,500`	”dollar-one-comma-five…"	"one thousand five hundred dollars”
`14:30`	”fourteen-colon-thirty"	"two thirty PM”

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.

Language tier	Support	Official codes / accepted aliases
Korean and English	Full patterns	`ko`, `kor`, `en`, `eng`
Japanese and Simplified Chinese	Core TTS patterns	`ja`, `jpn`, `zh`, `zho`
Traditional Han-script voices	Core TTS patterns	`zh-TW`, `nan`, `yue`
Other SSFM v3.0 languages	Common TTS patterns (31)	Official ISO 639-3 codes below

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.

Full support for English text preprocessing with proper number reading, currency formatting, and more.

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.'

Core Japanese TTS patterns, including irregular time and counter readings, contextual identifiers, and scripture references.

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

autoTag('受付は14時から19時まで、全部で6件です。', { language: 'ja' });
// → '受付はじゅうよじからじゅうくじまで、全部でろっけんです。'

autoTag('注文番号はZX-407、ヨハネ3:16を確認してください。', { language: 'ja' });
// → '注文番号はZ・X、よん・ゼロ・なな、ヨハネさんしょうじゅうろくせつを確認してください。'

Core Simplified Chinese TTS patterns, including identifiers, flight numbers, units, and scripture references.

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

autoTag('订单编号是ZX-407，请读约翰福音3:16。', { language: 'zh' });
// → '订单编号是Z·X、四·零·七，请读约翰福音三章十六节。'

Traditional Chinese input with Taiwan phone, postal, currency, measurement, and identifier readings.

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

autoTag('客服時間是6–9點，費用是NT$12,800。', { language: 'zh-TW' });
// → '客服時間是六點到九點，費用是一萬二千八百新臺幣。'

autoTag('訂單編號是ZX-407，請讀約翰福音3:16。', { language: 'zh-TW' });
// → '訂單編號是Z·X、四·零·七，請讀約翰福音三章十六節。'

Common patterns use the requested language’s locale-specific number reading.

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

autoTag('Total 1,234.5 and 72.5%.', { language: 'spa' });
// → 'Total mil doscientos treinta y cuatro punto cinco and setenta y dos punto cinco%.'

All 37 official language codes are available in the JavaScript/TypeScript and browser package. Python, Java, and C/C++ currently expose Korean and English entry points.

Installation

JavaScript/TypeScript
Python
Java
C/C++

Install the public npm package:

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' });

Install the public PyPI package:

pip install typecast-autotag

from typecast_autotag import auto_tag_en, manual_tag_en, auto_tag_with_manual_en

result = auto_tag_en('Call 555-123-4567.')
# → 'Call five five five, one two three, four five six seven.'

Add the Maven Central artifact to your project:

<dependency>
    <groupId>com.neosapience</groupId>
    <artifactId>typecast-autotag</artifactId>
    <version>1.13.0</version>
</dependency>

implementation "com.neosapience:typecast-autotag:1.13.0"

import ai.typecast.autotag.TypecastAutotag;

String result = TypecastAutotag.autoTag("Call 555-123-4567.", "en");
// → "Call five five five, one two three, four five six seven."

Either grab a pre-built native binary from GitHub Releases, or build from source:

git clone https://github.com/neosapience/typecast-autotag.git
cd typecast-autotag
pnpm install
pnpm c-binding:build-all-multiarch
# Headers + libraries land under c-binding/build/

#include "typecast_autotag.h"

char* result = typecast_auto_tag_english("Call 555-123-4567.");
// → "Call five five five one two three four five six seven."

typecast_free(result);

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.'

Manual tags are processed first, then auto-tags are applied to the remaining text.

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)

Tag	Description	Example
`phone`	Phone numbers	`555-123-4567`
`datetime`	Date and time	`2024-01-15T14:30`
`time`	Time	`2:30 PM`
`date`	Date	`January 15, 2024`
`money`	Currency	`$1,500`
`year`	Year	`year 2024`
`month`	Month	`January`
`day`	Day	`the 15th`
`order`	Ordinal	`1st place`
`point`	Points/scores	`95 points`
`ratio`	Ratio/percent	`50%`, `1:2`
`weight`	Weight	`5kg`, `100lb`
`distance`	Distance	`5km`, `100m`
`temperature`	Temperature	`25°C`, `-5°F`
`volume`	Volume	`500ml`, `2L`
`dataCapacity`	Data size	`100GB`, `50Mbps`

Manual-Only Tags

Tag	Description	Syntax	Output
`name`	Language-specific name handling	`name(김철수)`	`김 . 철 . 수`
`digits`	Digit-by-digit	`digits(1234)`	`one two three four`

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

Language	Version	Install path	Text languages
Node.js	≥18	`@neosapience/typecast-autotag` from npm	All 37 official codes + `ko`, `en`, `ja`, `zh`, `zh-TW` aliases
Browser	Modern	`@neosapience/typecast-autotag` ESM/UMD bundle	All 37 official codes + `ko`, `en`, `ja`, `zh`, `zh-TW` aliases
Python	≥3.8	`typecast-autotag` from PyPI	`ko`, `en`
Java	≥8	`com.neosapience:typecast-autotag` from Maven Central	`ko`, `en`
C/C++	Any	Pre-built binary from Releases or `pnpm c-binding:build-all-multiarch`	`ko`, `en`

Server Platforms

Platform	Status
Linux	Supported (CentOS 6.9+, Amazon Linux 2+, Ubuntu, Debian)
macOS	Supported (Intel & Apple Silicon)
Windows	Supported (Windows 10+)

Architectures

Architecture	Status
x86_64 (AMD64)	Supported
x86 (32-bit)	Supported
arm64 (AArch64)	Supported
armv7 (32-bit ARM)	Supported

GET STARTED

SDKs

INTEGRATIONS

Overview

npm Package

PyPI Package

Maven Central

GitHub Repository

Why AutoTag?

Language Support

Installation

Quick Start

Auto-Tagging

Manual-Tagging

Combined Usage

Supported Tags

Auto-Tags (Automatically Detected)

Manual-Only Tags

AICC Use Case

Integration with Typecast TTS

Platform Support

Development Languages

Server Platforms

Architectures

Next Steps

Quickstart

SDK Documentation

​Overview

npm Package

PyPI Package

Maven Central

GitHub Repository

​Why AutoTag?

​Language Support

​Installation

​Quick Start

​Auto-Tagging

​Manual-Tagging

​Combined Usage

​Supported Tags

​Auto-Tags (Automatically Detected)

​Manual-Only Tags

​AICC Use Case

​Integration with Typecast TTS

​Platform Support

​Development Languages

​Server Platforms

​Architectures

​Next Steps

Quickstart

SDK Documentation

Overview

Why AutoTag?

Language Support

Installation

Quick Start

Auto-Tagging

Manual-Tagging

Combined Usage

Supported Tags

Auto-Tags (Automatically Detected)

Manual-Only Tags

AICC Use Case

Integration with Typecast TTS

Platform Support

Development Languages

Server Platforms

Architectures

Next Steps