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

> Transform structured text into natural speech patterns for TTS applications.

## 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="box" 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>

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

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

    ```typescript theme={null}
    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>
</Tabs>

## Installation

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

    ```bash theme={null}
    pnpm add @neosapience/typecast-autotag

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

    ```typescript theme={null}
    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 theme={null}
    pip install typecast-autotag
    ```

    ```python theme={null}
    from typecast_autotag import auto_tag, manual_tag, auto_tag_with_manual

    result = auto_tag('Call 555-123-4567.', language='en')
    # → 'Call five five five, one two three, four five six seven.'
    ```
  </Tab>

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

    ```xml theme={null}
    <dependency>
        <groupId>com.neosapience</groupId>
        <artifactId>typecast-autotag</artifactId>
        <version>1.8.1</version>
    </dependency>
    ```

    ```gradle theme={null}
    implementation "com.neosapience:typecast-autotag:1.8.1"
    ```

    ```java theme={null}
    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 theme={null}
    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 theme={null}
    #include "typecast_autotag.h"

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

    typecast_autotag_free(result);
    ```
  </Tab>
</Tabs>

## Quick Start

### Auto-Tagging

Automatically detect and convert patterns in your text:

```typescript theme={null}
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 theme={null}
import { manualTag } from '@neosapience/typecast-autotag';

// Name spelling (character by character)
manualTag('Hello, name(John).', { language: 'en' });
// → 'Hello, J O H N.'
```

### Combined Usage

Apply both auto and manual tags together:

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

autoTagWithManual('name(John), call 555-123-4567.', { language: 'en' });
// → 'J O H N, call five five five, one two three, four five six seven.'
```

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

## Supported Tags

### 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`   | Name (char-by-char) | `name(John)`   | `J O H N`            |
| `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 theme={null}
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, J O H N S M I T H.
//  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 theme={null}
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                                                           |
| -------- | ------- | ---------------------------------------------------------------------- |
| Node.js  | ≥18     | `@neosapience/typecast-autotag` from npm                               |
| Browser  | Modern  | `@neosapience/typecast-autotag` ESM/UMD bundle                         |
| Python   | ≥3.8    | `typecast-autotag` from PyPI                                           |
| Java     | ≥8      | `com.neosapience:typecast-autotag` from Maven Central                  |
| C/C++    | Any     | Pre-built binary from Releases or `pnpm c-binding:build-all-multiarch` |

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