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

> 구조화된 텍스트를 TTS 애플리케이션에 자연스러운 음성 패턴으로 변환하는 텍스트 전처리 SDK

## 개요

**타입캐스트 오토태그**는 문장 속에 포함된 전화번호, 날짜, 시간, 금액 같은 복잡한 숫자나 기호를 TTS가 사람처럼 자연스럽게 읽을 수 있도록 미리 문장을 다듬어주는 텍스트 전처리 SDK입니다.

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

  <Card title="PyPI 패키지" 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 저장소" icon="github" href="https://github.com/neosapience/typecast-autotag">
    소스, 이슈, 네이티브 바이너리
  </Card>
</CardGroup>

## AutoTag를 사용해야 하는 이유

음성 애플리케이션을 구축할 때, 원본 텍스트는 자연스러운 음성으로 변환되기 어렵습니다:

| 입력              | AutoTag 없이                    | AutoTag 사용                                |
| --------------- | ----------------------------- | ----------------------------------------- |
| `010-1234-5678` | "영 일 영 다시 일 이 삼 사 다시 오 육 칠 팔" | "공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔" |
| `50000원`        | "오만영원"                        | "오만 원"                                    |
| `14:30`         | "십사콜론삼십"                      | "오후 두 시 삼십 분"                             |

AutoTag는 이러한 패턴을 자동으로 감지하고 자연스러운 음성으로 변환하여 음성 애플리케이션의 사용자 경험을 향상시킵니다.

## 언어 지원

<Tabs>
  <Tab title="한국어">
    자연스러운 숫자 읽기, 날짜/시간 포맷팅 등을 포함한 한국어 텍스트 전처리를 완벽하게 지원합니다.

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

    autoTag('전화번호는 010-1234-5678입니다.', { language: 'ko' });
    // → '전화번호는, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 입니다.'

    autoTag('총 금액은 50000원입니다.', { language: 'ko' });
    // → '총 금액은 오만 원 입니다.'
    ```
  </Tab>

  <Tab title="영어">
    적절한 숫자 읽기, 통화 포맷팅 등을 포함한 영어 텍스트 전처리를 완벽하게 지원합니다.

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

## 설치

<Tabs>
  <Tab title="JavaScript/TypeScript">
    공개 npm 패키지를 설치합니다:

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

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

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

    autoTag('전화번호는 010-1234-5678입니다.', { language: 'ko' });
    ```
  </Tab>

  <Tab title="Python">
    공개 PyPI 패키지를 설치합니다:

    ```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('전화번호는 010-1234-5678입니다.', language='ko')
    # → '전화번호는, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 입니다.'

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

  <Tab title="Java">
    Maven Central 아티팩트를 프로젝트에 추가합니다:

    ```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("전화번호는 010-1234-5678입니다.", "ko");
    // → "전화번호는, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 입니다."

    // 영어
    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++">
    [GitHub Releases](https://github.com/neosapience/typecast-autotag/releases)
    에서 미리 빌드된 네이티브 바이너리를 받거나 소스에서 빌드하세요.

    ```bash theme={null}
    git clone https://github.com/neosapience/typecast-autotag.git
    cd typecast-autotag
    pnpm install
    pnpm c-binding:build-all-multiarch
    # 헤더와 라이브러리가 c-binding/build/ 아래에 떨어집니다.
    ```

    ```c theme={null}
    #include "typecast_autotag.h"

    char* result = typecast_autotag_auto_tag(
        "전화번호는 010-1234-5678입니다.",
        "ko"
    );
    // → "전화번호는, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 입니다."

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

## 빠른 시작

### 자동 태깅

텍스트에서 패턴을 자동으로 감지하고 변환합니다:

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

// 전화번호
autoTag('전화번호는 010-1234-5678입니다.', { language: 'ko' });
// → '전화번호는, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 입니다.'

// 날짜와 시간
autoTag('회의는 14:30에 시작합니다.', { language: 'ko' });
// → '회의는 오후 두 시 삼십 분 에 시작합니다.'

// 금액
autoTag('총 금액은 50000원입니다.', { language: 'ko' });
// → '총 금액은 오만 원 입니다.'
```

### 수동 태깅

명시적인 태그 구문을 사용하여 정밀하게 제어합니다:

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

// 이름 철자 읽기 (글자별)
manualTag('안녕하세요, name(김철수)님.', { language: 'ko' });
// → '안녕하세요, 김 . 철 . 수님.'

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

### 조합 사용

자동 태그와 수동 태그를 함께 적용합니다:

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

autoTagWithManual('name(김철수)님, 010-1234-5678로 연락주세요.', { language: 'ko' });
// → '김 . 철 . 수님, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 로 연락주세요.'
```

<Note>수동 태그가 먼저 처리된 후 나머지 텍스트에 자동 태그가 적용됩니다.</Note>

## 지원 태그

### 자동 태그 (자동 감지)

| 태그             | 설명     | 한국어 예시             | 영어 예시              |
| -------------- | ------ | ------------------ | ------------------ |
| `phone`        | 전화번호   | `010-1234-5678`    | `555-123-4567`     |
| `datetime`     | 날짜와 시간 | `2024-01-15T14:30` | `2024-01-15T14:30` |
| `time`         | 시간     | `14:30`            | `2:30 PM`          |
| `date`         | 날짜     | `2024-01-15`       | `January 15, 2024` |
| `money`        | 금액     | `50000원`           | `$1,500`           |
| `year`         | 연도     | `2024년`            | `year 2024`        |
| `month`        | 월      | `12월`              | `January`          |
| `day`          | 일      | `25일`              | `the 15th`         |
| `order`        | 순서     | `3번째`              | `1st place`        |
| `point`        | 점수     | `95점`              | `95 points`        |
| `ratio`        | 비율/퍼센트 | `50%`, `1:2`       | `50%`, `1:2`       |
| `weight`       | 무게     | `5kg`              | `5kg`, `100lb`     |
| `distance`     | 거리     | `5km`              | `5km`, `100m`      |
| `temperature`  | 온도     | `25℃`              | `25°C`, `-5°F`     |
| `volume`       | 용량     | `500ml`            | `500ml`, `2L`      |
| `dataCapacity` | 데이터 용량 | `100GB`            | `100GB`, `50Mbps`  |

### 수동 전용 태그

| 태그        | 설명          | 구문                    | 출력              |
| --------- | ----------- | --------------------- | --------------- |
| `name`    | 이름 (글자별)    | `name(김철수)`           | `김 . 철 . 수`     |
| `digits`  | 숫자 (자리별)    | `digits(1234)`        | `일 . 이 . 삼 . 사` |
| `address` | 주소 (한국어 전용) | `address(102동 1101호)` | `백이동 천백일호`      |

## AICC 사용 사례

자연스러운 음성이 중요한 AI 컨택센터 애플리케이션에 완벽합니다:

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

// 고객 서비스 스크립트
const customerName = '김철수';
const orderNumber = '1234';
const deliveryDate = '2024년 1월 15일';
const supportPhone = '010-1234-5678';

const script = autoTagWithManual(`
  안녕하세요, name(${customerName})님.
  주문번호 ${orderNumber} 상품이 ${deliveryDate}에 배송될 예정입니다.
  문의사항은 ${supportPhone}으로 연락주세요.
`, { language: 'ko' });

// 출력:
// "안녕하세요, 김 . 철 . 수님.
//  주문번호 천이백삼십사 상품이 이천이십사년 일 월 십오 일 에 배송될 예정입니다.
//  문의사항은, 공 . 일 . 공, 일 . 이 . 삼 . 사, 오 . 육 . 칠 . 팔 으로 연락주세요."
```

## Typecast TTS와 연동

AutoTag를 Typecast TTS API와 결합하여 최상의 음성 경험을 제공하세요:

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

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

// AutoTag로 원본 텍스트 전처리
const rawText = '잔액은 1,234,567원입니다. 문의는 1588-1234로 전화주세요.';
const processedText = autoTagWithManual(rawText, { language: 'ko' });

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

## 플랫폼 지원

### 개발 언어

| 언어      | 버전     | 설치 경로                                                          |
| ------- | ------ | -------------------------------------------------------------- |
| Node.js | ≥18    | npm의 `@neosapience/typecast-autotag`                           |
| Browser | Modern | `@neosapience/typecast-autotag` ESM/UMD 번들                     |
| Python  | ≥3.8   | PyPI의 `typecast-autotag`                                       |
| Java    | ≥8     | Maven Central의 `com.neosapience:typecast-autotag`              |
| C/C++   | Any    | Releases 의 미리 빌드된 바이너리 또는 `pnpm c-binding:build-all-multiarch` |

### 서버 플랫폼

| 플랫폼     | 상태                                                |
| ------- | ------------------------------------------------- |
| Linux   | 지원 (CentOS 6.9+, Amazon Linux 2+, Ubuntu, Debian) |
| macOS   | 지원 (Intel & Apple Silicon)                        |
| Windows | 지원 (Windows 10+)                                  |

### 아키텍처

| 아키텍처             | 상태 |
| ---------------- | -- |
| x86\_64 (AMD64)  | 지원 |
| x86 (32비트)       | 지원 |
| arm64 (AArch64)  | 지원 |
| armv7 (32비트 ARM) | 지원 |

## 다음 단계

<CardGroup cols={2}>
  <Card title="빠른 시작" icon="bolt" href="/ko/quickstart">
    Typecast TTS API 시작하기
  </Card>

  <Card title="SDK 문서" icon="code" href="/ko/sdk/python">
    SDK 문서 살펴보기
  </Card>
</CardGroup>