📞TTS가 전화번호·금액을 어색하게 읽는다면 – autotag 적용 가이드(API 연동)

 

AI 음성을 서비스에 붙여보면 텍스트 대부분은 자연스럽게 읽힙니다. 문제는 숫자와 기호를 읽어야할 때입니다. “50,000원”이 “오만영원”으로, “010-1234-5678″이 자리 구분 없이 흘러나오는 순간 안내가 어색해지죠.

더 좋은 목소리, 더 좋은 음질의 TTS를 도입해도 해결되지 않아요. 목소리가 아니라 숫자를 ‘읽는 방식’의 문제라서, TTS에 넣기 전에 텍스트를 한 번 정리해 주는 과정(전처리)이 필요합니다.

이 정리를 대신해 주는 도구가 타입캐스트의 오픈소스 SDK autotag입니다. 설치만 한 번 해 두면, 전화번호·금액·날짜가 사람이 읽는 방식으로 자동 정리되어 자연스러운 음성이 생성됩니다.

오늘은 TTS API를 한층 더 자연스럽게 사용하도록 만드는 autotag 설치부터 타입캐스트 API 연결까지 세 단계로 안내해드려요.

타입캐스트 API 무료로 시작하기 →

---

AI 목소리는 왜 숫자를 어색하게 읽을까요?

TTS는 입력된 글자를 그대로 소리로 옮깁니다. 그래서 “50000원”이라는 문자열은 “오만영원”처럼 글자 단위로 읽히죠. 사람이라면 “오만 원”으로 끊어 읽을 텍스트인데도요.

특히 한국어는 같은 숫자도 맥락마다 다르게 읽힙니다. 전화번호 “010”은 “공 일 공”, 금액은 “오만 원”, “3시 30분”은 “세 시 삼십 분”처럼 고유어와 한자어가 섞입니다. 게다가 서비스의 숫자는 DB에서 매번 다른 값이 들어오기 때문에 사람이 일일이 고칠 수 없죠. 규칙 기반으로 자동 정리하는 전처리 단계가 필요한 이유입니다.

어때요, 생각보다 차이가 크죠? 이제 방금 들은 차이를 직접 만들어 보겠습니다. autotag 설치부터 타입캐스트 API 연결까지, 세 단계면 충분합니다.

---

STEP 1. autotag 설치하기

autotag는 MIT 라이선스 오픈소스입니다. 따로 빌드할 필요 없이 JavaScript는 npm, Python은 pip로 바로 설치할 수 있습니다. 한국어와 영어를 지원합니다.

# JavaScript / TypeScript (Node.js 18 이상)
pnpm add @neosapience/typecast-autotag
# 또는: npm install @neosapience/typecast-autotag

# Python (3.8 이상)
pip install typecast-autotag

설치 후 함수를 가져옵니다.

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

---

STEP 2. autotag 적용하기

autotag로 텍스트를 정리하는 방식은 두 가지입니다. 형식이 분명한 값은 자동(autoTag)으로 처리하고, 읽는 방식이 갈리는 값만 직접(manualTag) 지정할 수 있어요.

방법 1자동으로 간편한 autoTag

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

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

타입캐스트 autotag가 자동 감지하는 패턴은 전화번호·날짜·시간·금액·비율·온도·용량 등 20여 가지입니다. 대부분의 동적 텍스트는 이 방식만으로 정리됩니다.

방법 2수동으로 세밀하게 manualTag

서비스에 따라 형태만으로는 읽는 방식이 달라지는 값도 있습니다. “1234”는 “천이백삼십사”로 읽을 수도, 주문번호처럼 “일 이 삼 사”로 읽을 수도 있죠. 사람 이름도 한 단어로 읽을지 글자마다 또박또박 읽을지는 의도에 달려 있습니다. 이렇게 읽는 방식이 갈리는 값은 manualTag로 직접 지정할 수 있어요.

manualTag('주문번호 digits(1234) 확인 부탁드립니다.', { language: 'ko' });
// → '주문번호 일 . 이 . 삼 . 사 확인 부탁드립니다.'

manualTag('안녕하세요, name(김철수)님.', { language: 'ko' });
// → '안녕하세요, 김 . 철 . 수님.'

수동 태그(manualTag)는 세 가지를 지원합니다.

태그	처리 방식	쓰는 곳
name()	이름을 글자별로 또박또박	고객명 안내
digits()	숫자를 자리별로	주문·카드·계좌번호
address()	한국어 주소 읽기	배송·방문 안내

---

STEP 3. 타입캐스트 API에 연결하기

마지막은 연결입니다. autotag로 정리한 텍스트를 기존 TTS 호출에 그대로 넘기기만 하면 음성이 나옵니다. 기존 코드는 손댈 필요 없이, 앞에 autotag 한 줄만 추가하면 끝이에요.

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

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

// 1) TTS에 넣기 전, 텍스트 정리 (수동 → 자동 순서로 처리)
const rawText = 'name(김철수)님, 주문번호 digits(1234) 상품이 50000원에 결제되었습니다.';
const processedText = autoTagWithManual(rawText, { language: 'ko' });

// 2) 정리된 텍스트로 음성 합성
const audio = await client.textToSpeech({
  text: processedText,
  model: 'ssfm-v30',
  voice_id: 'tc_xxxxxxxx'
});

자동/수동 태그를 한 번에 적용하고 싶으면 autoTagWithManual 한 줄로 처리해 보세요. 이제 ‘고객명’은 또박또박, ‘주문번호’는 자리별로, ‘금액’은 “오만 원”으로 정리된 음성이 생성될 거예요.

autotag GitHub 보기 → autotag 문서 보기 →

---

autotag, 어디에 적용하면 효과가 클까요?

autotag는 주문번호·고객명·금액처럼 값이 매번 바뀌는 텍스트를 음성으로 안내하는 서비스에서 효과가 큽니다. 사람이 미리 손볼 수 없는 텍스트일수록 자동 정리가 빛을 발하죠.