> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

<CardGroup cols={2}>
<Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@neosapience/typecast-autotag">
@neosapience/typecast-autotag
</Card>

<Card title="PyPI Package" icon="python" href="https://pypi.org/project/typecast-autotag/">
typecast-autotag
</Card>

<Card title="Maven Central" icon="java" href="https://central.sonatype.com/artifact/com.neosapience/typecast-autotag">
com.neosapience:typecast-autotag
</Card>

<Card title="GitHub Repository" icon="github" href="https://github.com/neosapience/typecast-autotag">
Source, issues, and native binaries
</Card>
</CardGroup>

<Note>
**typecast-autotag 3.0.0** requires Python 3.11 or later; verified on **3.11–3.13**. This applies to the Python package.
</Note>

<Accordion title="Compatibility and migration for older Python versions">
**Python 3.8, 3.9, and 3.10 are no longer supported because they have reached end of life (EOL).** The last compatible Autotag Python package is **1.13.0** for Python 3.8/3.9 and **2.0.1** for Python 3.10. Upgrade Python, then run `python -m pip install --upgrade typecast-autotag`. To temporarily keep Python 3.10, pin `python -m pip install "typecast-autotag==2.0.1"`; for Python 3.8/3.9, use `typecast-autotag==1.13.0`. An older package pin does not restore EOL security support. This change applies to the Python package, independently of the JavaScript and Java package versions.
</Accordion>

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

<Tabs>
  <Tab title="English">
    Full support for English text preprocessing with proper number reading, currency formatting, and more.

    ```typescript
    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.'
    ```
  </Tab>

  <Tab title="Korean">
    Full support for Korean text preprocessing with natural number reading, date/time formatting, and more.
  </Tab>

  <Tab title="Japanese">
    Core Japanese TTS patterns, including irregular time and counter readings, contextual identifiers, and scripture references.

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

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

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

  <Tab title="Simplified Chinese">
    Core Simplified Chinese TTS patterns, including identifiers, flight numbers, units, and scripture references.

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

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

  <Tab title="Taiwan Mandarin">
    Traditional Chinese input with Taiwan phone, postal, currency, measurement, and identifier readings.

    ```typescript
    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、四·零·七，請讀約翰福音三章十六節。'
    ```
  </Tab>

  <Tab title="Other SSFM languages">
    Common patterns use the requested language's locale-specific number reading.

    ```typescript
    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%.'
    ```
  </Tab>
</Tabs>

<Note>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.</Note>

## Installation

<Tabs>
  <Tab title="JavaScript/TypeScript">
    Install the public npm package:

    ```bash
    pnpm add @neosapience/typecast-autotag

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

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

    autoTag('Call me at 555-123-4567.', { language: 'en' });
    ```
  </Tab>

  <Tab title="Python">
    Install the public PyPI package:

    ```bash
    pip install typecast-autotag
    ```

    ```python
    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.'
    ```
  </Tab>

  <Tab title="Java">
    Add the Maven Central artifact to your project:

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

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

    ```java
    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."
    ```
  </Tab>

  <Tab title="C/C++">
    Either grab a pre-built native binary from
    [GitHub Releases](https://github.com/neosapience/typecast-autotag/releases),
    or build from source:

    ```bash
    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/
    ```

    ```c
    #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);
    ```
  </Tab>
</Tabs>

## Quick Start

### Auto-Tagging

Automatically detect and convert patterns in your text:

```typescript
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:

```typescript
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:

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

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

<Note>Manual tags are processed first, then auto-tags are applied to the remaining text.</Note>

## 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:

```typescript
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:

```typescript
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.11 | `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 |

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Get started with Typecast TTS API
  </Card>
  <Card title="SDK Documentation" icon="code" href="/sdk/python">
    Explore our SDK documentation
  </Card>
</CardGroup>